Reset and recovery
A device keeps its identity, its trust list and its transfers in a state directory, and its keys in the key store of the operating system (or in a key file on a headless machine). If part of that is lost or damaged, easysync does not repair it silently. It refuses to start, says what is wrong, and names the remedy. This page explains the situations and the reset command.
What can go wrong #
| Situation | What easysync does | What to do |
|---|---|---|
| The database is fine, but the identity key is missing | Refuses to start | A full reset. The device gets a new identity that nobody trusts, so you pair it with every device again and revoke the old entry of this device on each of them. |
| The database is fine, but the key that protects it is missing | Refuses to start | A reset that keeps the identity, or restore the missing entry from a copy. |
| The database belongs to another device, or the key does not match it | Refuses to start | Restore the matching database or key, or reset. |
| The database is lost, the keys are intact | Starts with an empty trust list | Pair again. The other devices still trust this device. |
| The operating system's key store cannot be reached | Refuses to start | Start easysync inside your user session. A reset is not the remedy: it would destroy an identity that is fine. |
The reset command #
easysync resetThe reset runs offline: it never starts an engine, so it also works when the engine refuses to start. Stop the daemon or the app first; the reset takes the same lock as the engine.
There are two forms:
easysync resetis the full reset. The identity and the database go. The next start is the start of a new device with a new fingerprint and an empty trust list.easysync reset --keep-identityreplaces the key that protects the state and erases the state, the pairings, the relays and the settings. The identity and the fingerprint stay. It is a repair, not a security measure. The other devices still trust the key; they are told, mark the device as needing a new pairing, and stop dialling it until you pair again.
To see what would happen, and which check would refuse the reset, without changing anything:
easysync reset --dry-runAdd --yes to skip the question on the terminal, for scripts and containers.
What a reset removes and what it keeps #
It removes the identity and the key that protects the state (the identity only in the full form), the database with its peers, secrets, relays, settings, the clipboard clock and all transfer rows, and the unfinished .part files of incoming transfers. It keeps the files you already received, the files you were sending, config.toml and the state directory itself. When the key file is selected, it never touches the key store of the operating system.
Check which key store is selected before a reset. If the daemon on a server normally uses EASYSYNC_KEY_STORE=file and you run the command without it, the command can look at the wrong store.
A reset tells nobody #
A reset does not tell the other devices. If you reset because a device was lost or compromised, the old identity stays trusted on every device that paired with it. Revoke it there with easysync peer revoke <peer>.
Before you uninstall #
Uninstalling the desktop app never deletes the state directory or the entries of the key store. To remove a device completely, reset it first. On Android an uninstall removes the state and the keys of the app, and the device becomes a new device; on iOS the Keychain items may survive when you delete the app, while the state does not.