Settings Recovery - Using the 'folders', 'tags' and 'attributes' commands

These commands are intended to be used to recover from situations where the Akonadi database is lost or becomes corrupted and has to be recreated (see the "Backup" section in https://userbase.kde.org/Akonadi). By importing a PIM data backup or reimporting all the source data (local Maildir mail, contact VCF files etc) the database will be regenerated. No data will be lost, but the user's application configuration may be. In particular, settings such as:

• destination folder assignments for mail filters
• some folder display and expiry settings
• special folder assignments for identities
• folder assignments for POP/IMAP agents
• favourite folders and their display order

may change because they refer to internal Akonadi IDs as they were before.

Most of the above settings are stored in PIM application or agent configuration files, and are backed up and restored by the 'folders' command. Folder display options (e.g. a custom icon), the "Act on new mail in this folder" option in KMail, and expiry settings, are stored as collection attributes in the Akonadi database and are backed up and restored by the 'attributes' command.

The 'folders', 'tags' and 'attributes' subcommands of 'akonadiclient' attempt to automatically fix up these folder assignments and settings after the Akonadi database had had to be regenerated. Each command operates in three modes:

Backup akonadiclient folders -b ------ akonadiclient attributes -b akonadiclient tags -s

Each of these should be run when the current Akonadi database and application settings are known to be good. They do not change anything in the database or applications, but simply save lists of the current folders with their collection ID assignments, attributes and tags. These lists are saved to the "$XDG_DATA_HOME/akonadiclient" directory and are readable plain text files named "savedfolders.dat", "savedattributes.dat" and "savedtags.dat" respectively.

To ensure that this reflects the latest good state, these commands should be run whenever significant changes are made to the PIM resources: for example, adding a new Akonadi resource or online account, adding a tag, moving around or renaming folders, or changing folder display options.

The Akonadi server must be running when any of these commands are used; if it is not already running, then it will be automatically started.

Check akonadiclient folders -c ----- akonadiclient attributes -c

If the Akonadi database has had to be recreated, run each command in this mode. Again they will not change anything in the database or applications, but it checks the current folder structure, collection IDs and attributes against those saved as above. If any changes to configuration files are needed it will update them, but will save them to new files so as to not immediately overwrite their current settings.

When it has finished they will report whether any folder IDs or attributes have - if it reports "No folder IDs have changed", "No configuration changes are required" or "No collection attributes need to be restored" then there is nothing to do. Otherwise, they will display instructions on what to do next.

The Akonadi server must again be running when either of these commands are used.

Restore folders akonadiclient folders -r

If changes to folder IDs are necessary, then exit all running PIM applications and stop the Akonadi server ("akonadictl stop"). Then enable the dangerous akonadiclient actions by setting the environment variable:

AKONADICLIENT_DANGEROUS="enabled" export AKONADICLIENT_DANGEROUS

and then run the 'folders' command in this mode. It will recheck the integrity of the changes and files saved above, then update the application configuration with the new files. Then the server and PIM applications can be restarted; their settings and folder assignments should now be correct.

Assuming that the restore is successful, check the PIM application and account settings and then immediately run the command again in 'backup' mode to save the new folder assignments.

Restore attributes/tags akonadiclient attributes -r ----------------------- akonadiclient tags -r

If changes to collection attributes or tags are necessary, then run these commands in the same way. It is not necessary to exit any PIM applications or stop the Akonadi server in this case.

Due to the implementation of the Akonadi database, the 'tags' command can only restore the original tag assignments if there are no currently defined tags and never have been. So this can effectively only be used if the Akonadi database has had to be regenerated and the tags have all been lost.

Caution

These (and the 'akonadiclient' command in general) are powerful tools intended for use by those familiar with the Akonadi system and its maintenance. They do try to check the integrity of saved files and data before changing anything, but it is always possible that something could go wrong. You are recommended to back up the $XDG_CONFIG_HOME directory before running any command in 'check' or 'restore' mode.