Akonadi and AddressBook: Difference between revisions

From KDE UserBase Wiki
(typography edit 2)
(Propose for deletion)
 
(25 intermediate revisions by 8 users not shown)
Line 1: Line 1:
{{Template:I18n/Language Navigation Bar|Akonadi_and_AddressBook}}
{{Proposed_deletion|All the information here is relevant to Akonadi and all the Akonadi-enabled apps rather than just KAddressbook (which was the only Akonadi-enabled app when this page was created). All the relevant content has been copied over to the [[Special:myLanguage/Akonadi|Akonadi]] page.}}
 
<languages />
<languages />
<translate>
<translate>
<!--T:31-->
{{Note|This article also applies to other applications that are using [[Special:myLanguage/Akonadi|Akonadi]], for example, KMail and KOrganizer.}}


<!--T:1-->
<!--T:1-->
''This information was provided by Tobias Koenig, '''KDE-PIM''' developer.''
''This information was provided by Tobias Koenig, '''KDE-PIM''' developer.''


<!--T:2-->
==Some Definitions== <!--T:2-->
==Some Definitions==


<!--T:3-->
<!--T:3-->
By ''real data'' we mean the data, like the contacts or events. These data are stored either on a groupware server or in local files. Where exactly depends on the resource you are using. E.g. the ''Personal Contacts'' resource stores its data under $HOME/.local/share/contacts while the ''VCard File'' resource (which is not recommended to use anyway [[Image:Face-smile.png|16px]]) stores its data under $HOME/.kde/share/apps/kabc/std.vcf.
;Real data
:By ''real data'' we mean the data, like the contacts or events. These data are stored either on a groupware server or in local files. Where exactly depends on the resource you are using. E.g. the ''Personal Contacts'' resource stores its data under ''$XDG_DATA_HOME/contacts''.


<!--T:4-->
<!--T:4-->
The ''cached data'' are copies of the real data that are kept in the database for faster access and offline caching. The database also keeps the ''meta data'' which are management data needed by '''Akonadi''' to work correctly.
;Cached data
:The ''cached data'' are copies of the real data that are kept in the database for faster access and offline caching. The database also keeps the ''meta data'' which are management data needed by '''Akonadi''' to work correctly.


<!--T:5-->
<!--T:5-->
The ''configuration data'' are the data that configure the '''Akonadi''' server and the individual resources. The configuration data for the server can be found under $HOME/.config/akonadi, the configuration for the resources are mostly stored under $HOME/.kde/share/config/akonadi_xyz_resourcerc# (xyz is name of resource and # its instance number).
;Configuration data
:The ''configuration data'' are the data that configure the '''Akonadi''' server and the individual resources. The general configuration data for the server can be found under ''$XDG_CONFIG_HOME/akonadi''. The configuration data for each indvidual resources are stored under ''$XDG_CONFIG_HOME/akonadi_xyz_resourcerc#'' ('''''xyz''''' is name of resource and '''''#''''' its instance number).


<!--T:6-->
<!--T:22-->
==Organising Backups==
:The '''Akonadi''' server configuration is a couple of files in ''$XDG_CONFIG_HOME/akonadi''. It contains which data sources and helper programs are active and will be started and watched (so they can be restarted on crashes) by one of '''Akonadi's''' server processes '''(akonadi_control)'''.


<!--T:7-->
<!--T:23-->
So now we need to decide what to back up.  If you want to backup the "real data", then it depends on the resources you have configured... if you use a groupware server, then the backup should be done there. For contacts, the files under $HOME/.local/share/contacts will normally be what you need.
:Each data source handler (called resources) or helper program (called agents) can have its own configuration although some agents or resources don't require configuration. The general rule is that for every entry in ''$XDG_CONFIG_HOME/akonadi/agentsrc'' there is a corresponding configuration file in ''$XDG_CONFIG_HOME''. For example, if the ''[Instances]'' section in ''agentrc'' contains an entry for ''akonadi_ical_resource_2'', there is also a config file called ''akonadi_ical_resource_2rc'' in the ''$XDG_CONFIG_HOME directory''.


<!--T:8-->
<!--T:24-->
The '''Akonadi''' tray icon offers you a backup and restore functionThat backs up the "cache data" which might not include all of your data!  It can be helpful if you want to clone a system 1:1, then you can copy the cached data together with the real data and the configuration, so you don't have to load the data again from the sources (e.g. groupware server).
:Depending on the type of data, such config files for resources will have filenames or directory names of where the data is stored.  Common locations are KDE's legacy default files, e.g. ''$HOME/.kde/share/apps/korganizer/std.ics''.  New default locations are files and directories in ''$XDG_DATA_HOME'', e.g. ''$XDG_DATA_HOME/contacts''.


<!--T:9-->
==Organising Backups== <!--T:6-->
==Examining your Resources==


<!--T:10-->
<!--T:7-->
'''KRunner''' offers you '''Akonadi Resource Configuration''', or you can access this through the '''Akonadi tray icon -> Configure'''. You may find several resources set up. You may find one labelled
So now we need to decide what to back up.  If you want to backup the "real data", then it depends on the resources you have configured... if you use a groupware server, then the backup should be done there. For contacts, the files under ''$XDG_DATA_HOME/contacts'' will normally be what you need.
 
<!--T:11-->
''Address Book'' - No KDE address book plugin configured yet.
 
<!--T:12-->
That's the old compatibility bridge (possibly created by the migrator tool).
You should remove this one!
 
<!--T:13-->
''std.vcf'' - Ready
 
<!--T:14-->
This is the ''VCard File Resource'' which points to $HOME/.kde/share/apps/kabc/std.vcf per default.  It is not recommended that you use that one, as it doesn't share the benefit of '''Akonadi'''.


<!--T:15-->
To back up the entire ''Akonadi'' configuration, including which resources are active and their configuration, you can use the '''pimdataexporter''' tool. This, however doesn't back up the Akonadi database containing the cached data and, unfortunately, after restoring the configuration (using the '''pimdataexporter'' again), Akonadi will have to re-fetch all data again into its cache. This can cause configuration that points to actual mail folders or calendars to get broken and accidentally point to another folder.
''Personal Contacts'' - Offline


<!--T:16-->
'''After restoring configuration and syncing all data, it's vital to manually check all folder configuration, especially in KMail identities and make sure the folders are configured properly.'''
That's the preferred resource for your local contacts which points to
  $HOME/.local/share/contacts


<!--T:17-->
Note that this may say "Offline" when in fact you are using it.  This is a display bug, and can safely be ignored.


<!--T:18-->
== Related pages == <!--T:26-->
==And when more components use '''Akonadi'''?==


<!--T:19-->
<!--T:27-->
When the rest of the components move to '''Akonadi''', will all the data be under ~/.local/share?  That should make backup easy.  Well, contacts and mails are stored there now, I don't know what the plan for events/todos is, but it would make sense to store them there as well. We'll keep it in mind when discussion pops up!
*[[Special:myLanguage/Akonadi|Akonadi]]<br />
*[[Special:myLanguage/KAddressBook/index|KAddressBook]]


<!--T:20-->
<!--T:20-->
[[Category:System]]
[[Category:System]]
</translate>
</translate>

Latest revision as of 10:58, 4 December 2023

Pending Deletion

This page has been proposed for deletion for the following reason:
All the information here is relevant to Akonadi and all the Akonadi-enabled apps rather than just KAddressbook (which was the only Akonadi-enabled app when this page was created). All the relevant content has been copied over to the Akonadi page.
Please use the discussion section of this page to voice your opinion on this.

Note

This article also applies to other applications that are using Akonadi, for example, KMail and KOrganizer.


This information was provided by Tobias Koenig, KDE-PIM developer.

Some Definitions

Real data
By real data we mean the data, like the contacts or events. These data are stored either on a groupware server or in local files. Where exactly depends on the resource you are using. E.g. the Personal Contacts resource stores its data under $XDG_DATA_HOME/contacts.
Cached data
The cached data are copies of the real data that are kept in the database for faster access and offline caching. The database also keeps the meta data which are management data needed by Akonadi to work correctly.
Configuration data
The configuration data are the data that configure the Akonadi server and the individual resources. The general configuration data for the server can be found under $XDG_CONFIG_HOME/akonadi. The configuration data for each indvidual resources are stored under $XDG_CONFIG_HOME/akonadi_xyz_resourcerc# (xyz is name of resource and # its instance number).
The Akonadi server configuration is a couple of files in $XDG_CONFIG_HOME/akonadi. It contains which data sources and helper programs are active and will be started and watched (so they can be restarted on crashes) by one of Akonadi's server processes (akonadi_control).
Each data source handler (called resources) or helper program (called agents) can have its own configuration although some agents or resources don't require configuration. The general rule is that for every entry in $XDG_CONFIG_HOME/akonadi/agentsrc there is a corresponding configuration file in $XDG_CONFIG_HOME. For example, if the [Instances] section in agentrc contains an entry for akonadi_ical_resource_2, there is also a config file called akonadi_ical_resource_2rc in the $XDG_CONFIG_HOME directory.
Depending on the type of data, such config files for resources will have filenames or directory names of where the data is stored. Common locations are KDE's legacy default files, e.g. $HOME/.kde/share/apps/korganizer/std.ics. New default locations are files and directories in $XDG_DATA_HOME, e.g. $XDG_DATA_HOME/contacts.

Organising Backups

So now we need to decide what to back up. If you want to backup the "real data", then it depends on the resources you have configured... if you use a groupware server, then the backup should be done there. For contacts, the files under $XDG_DATA_HOME/contacts will normally be what you need.

To back up the entire Akonadi configuration, including which resources are active and their configuration, you can use the pimdataexporter' tool. This, however doesn't back up the Akonadi database containing the cached data and, unfortunately, after restoring the configuration (using the pimdataexporter again), Akonadi will have to re-fetch all data again into its cache. This can cause configuration that points to actual mail folders or calendars to get broken and accidentally point to another folder.

After restoring configuration and syncing all data, it's vital to manually check all folder configuration, especially in KMail identities and make sure the folders are configured properly.


Related pages