[pim/kmail] doc/kmail2: Updating chapter 7 of KMail documentation -- "troubleshooting"
David Bryant
null at kde.org
Wed Aug 18 23:18:50 BST 2021
Git commit 8d2ac17ab8e17077de1f27557f0b4dd76cc1be1f by David Bryant.
Committed on 18/08/2021 at 19:29.
Pushed by davidbryant into branch 'master'.
Updating chapter 7 of KMail documentation -- "troubleshooting"
M +428 -65 doc/kmail2/troubleshooting.docbook
https://invent.kde.org/pim/kmail/commit/8d2ac17ab8e17077de1f27557f0b4dd76cc1be1f
diff --git a/doc/kmail2/troubleshooting.docbook b/doc/kmail2/troubleshooting.docbook
index a7d3d5808..9342e4f30 100644
--- a/doc/kmail2/troubleshooting.docbook
+++ b/doc/kmail2/troubleshooting.docbook
@@ -3,40 +3,208 @@
<chapterinfo>
<authorgroup>
<author>
-<personname>
- <firstname>This chapter was converted from the KDE UserBase <ulink url="https://userbase.kde.org/Special:MyLanguage/KMail/FAQs_Hints_and_Tips">KMail/FAQs Hints and Tips</ulink> page.</firstname>
-<surname></surname>
-</personname>
- </author>
+ <personname>
+ <firstname>Portions of this chapter were converted from the KDE UserBase <ulink
+ url="https://userbase.kde.org/Special:MyLanguage/KMail/FAQs_Hints_and_Tips">KMail/FAQs Hints and Tips</ulink> page in 2012.</firstname>
+ </personname>
+</author>
+<author>
+&David.Bryant;
+&David.Bryant.mail;
+</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
- </authorgroup>
-<date>2012-07-28</date>
- <releaseinfo>&kde; SC 4.9</releaseinfo>
+</authorgroup>
+<date>2021-08-08</date>
+<releaseinfo>5.14.2 (Applications 20.04.2)</releaseinfo>
</chapterinfo>
<title>&kmail; Troubleshooting</title>
-<sect1 id="kmail2-doesnt-send-mail"><title>KMail doesn't send mail</title>
-<para>Some users find that mail does not go out, and it appears that &SMTP; is missing, even though the <guilabel>Settings</guilabel> page looks correct. It has been reported that this is cured by opening <application>akonadiconsole</application> and adding Mail Dispatcher Agent.
-</para>
-<para>If the computer was suddenly turned off in suspend mode (⪚ by a power cut) sometimes e-mails simply stay in the outbox without being sent, but no error message is generated either. This may be due to the fact that the Mail Dispatcher Agent is set to <quote>offline</quote> in the configuration file during suspend and is not changed back due to the crash. Edit the following file:
-</para>
-<para><filename>~/.config/akonadi/agent_config_akonadi_maildispatcher_agent</filename>
-</para>
-<para>and change
-</para>
-<para><screen>
-[Agent]
-Online=false</screen>
-</para>
-<para>to
-</para>
-<para><screen>
-[Agent]
-Online=true</screen>
-</para>
+<sect1 id="introduction-to-akonadi">
+<title>Introduction to &akonadi;</title>
+
+ <para>&kmail; has been under active development since 1997. A lot of bugs have cropped up over the years.
+ Many of these have been resolved. If you are curious about any of those old bugs, please see the <ulink
+ url="https://userbase.kde.org/Special:MyLanguage/KMail/FAQs_Hints_and_Tips">KMail/FAQs Hints and Tips</ulink>
+ in the &kde; UserBase Wiki. Or visit <ulink url="https://bugs.kde.org">&kde;'s main bug tracking page</ulink>
+ to learn about bugs of a more recent vintage.</para>
+
+ <para>At the present time (2021), many of the problems people are experiencing with &kmail; involve the &akonadi;
+ server. &akonadi; is an auxiliary program that functions as an intermediary between &kmail; (plus all the other &PIM;
+ applications) and a general purpose database daemon (most commonly "mysqld"). It also facilitates inter-process
+ communications among the various pieces of the &PIM; applications. Depending on the way your system is configured,
+ &akonadi; may be started during the bootup / login process. Or it may not start until you invoke a &PIM;
+ application program (like &kmail;, or &kaddressbook;, or &kontact;).</para>
+
+ <para> There are two application programs that permit one to interact with the &akonadi; server directly: <code>akonadictl</code>
+ (a terminal-oriented control program), and <code>akonadiconsole</code> (a GUI application). Here is a little information about
+ those two programs.</para>
+ <para> </para><!-- add whitespace -->
+
+ <sect2 id="intro-to-akonadictl">
+ <title>The Akonadictl Control Program</title>
+ <screenshot>
+ <screeninfo>&akonadi; status report</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="akonadictl.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>&akonadi; status report</phrase>
+ </textobject>
+ <caption>
+ <para>Akonadictl Status Report, 32 Agents Running</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ <para> </para><!-- add whitespace -->
+
+ <para>The preceding screenshot illustrates one of the commands one may use with the <code>akonadictl</code> program. Here
+ are all the commands <code>akonadictl</code> recognizes.</para>
+
+ <para><screen>~$ akonadictl start</screen> Starts the &akonadi; server.</para>
+ <para><screen>~$ akonadictl stop</screen> Stops the &akonadi; server.</para>
+ <para><screen>~$ akonadictl restart</screen> Stops the &akonadi; server, then launches it anew.</para>
+ <para><screen>~$ akonadictl status</screen> Produces the status report illustrated in the preceding screenshot.</para>
+ <para><screen>~$ akonadictl instances</screen> Lists the &akonadi; server instances (more than one can
+ be running at the same time).</para>
+ <para><screen>~$ akonadictl vacuum</screen> Cleans up &akonadi;'s storage, or at least tries to do that.</para>
+ <para><screen>~$ akonadictl fsck</screen> Performs a file consistency check. The output from this
+ command can be quite voluminous, especially if you have added your own folders to &kmail;. Use this
+ version of the command (piping the output through grep) to verify that your &akonadi; database is healthy,
+ without producing a lot of extraneous output.</para>
+ <para>
+
+<screen>~ $ akonadictl fsck 2>&1 | grep ^Found
+Found 0 external files.
+Found 0 external parts.
+Found no unreferenced external files.
+Found 0 parts to be moved to external files
+Found 0 parts to be moved to database
+Found 6 collections without RID.
+Found 0 items without RID.
+Found 0 dirty items.</screen> <!-- Can't indent here ... messes up the output. -->
+
+ RID stands for RemoteId, a named field in the mysql database tables. If there are more than 0 items
+ without RID, you have a minor problem that should be corrected. If there are more than 0 dirty items
+ you may have a major problem that <emphasis>must</emphasis> be corrected. See <link
+ linkend="resource-conflict-error">"Unable to Fetch Item ..."</link> and also <link
+ linkend="dealing-with-dirt">Correcting &kmail;'s "Dirty" Items</link>, below.
+ </para>
+ <para> </para><!-- add whitespace -->
+ </sect2>
+
+ <sect2 id="intro-to-akonadiconsole">
+ <title>The Akonadiconsole Program</title>
+ <screenshot>
+ <screeninfo>What akonadiconsole looks like</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="akonadiconsole.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>What akonadiconsole looks like</phrase>
+ </textobject>
+ <caption>
+ <para>Akonadiconsole in action</para>
+ </caption>
+ </mediaobject>
+ </screenshot>
+ <para> </para><!-- add whitespace -->
+
+ <para>The <code>akonadiconsole</code> program provides twelve different "windows" into the inner
+ workings of the &PIM; applications. Here is a brief summary of the available views.</para>
+
+ <variablelist>
+ <varlistentry id="ak-console-agents">
+ <term><guilabel>Agents</guilabel> tab.</term>
+ <listitem><para>Here you can see a list of the user agents (processors).</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-browser">
+ <term><guilabel>Browse</guilabel> tab.</term>
+ <listitem><para>This tab provides an overview of the various collections of data &akonadi;
+ is maintaining, organized as a hierarchical tree that shows how many items reside in each
+ collection.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-debugger">
+ <term><guilabel>Debugger</guilabel> tab.</term>
+ <listitem><para>Here you can turn debugging on and off, and view the debug message log.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-logging">
+ <term><guilabel>Logging</guilabel> tab.</term>
+ <listitem><para>This tab lets you view messages emitted by various &akonadi; components..</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-db-browser">
+ <term><guilabel>DB Browser</guilabel> tab.</term>
+ <listitem><para>Use this tab to peek inside the mysql database. There are many different tables.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-db-console">
+ <term><guilabel>DB Console</guilabel> tab.</term>
+ <listitem><para>Here you can query the mysql database.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-query">
+ <term><guilabel>Query Debugger</guilabel> tab.</term>
+ <listitem><para>Use this tab to turn database query debugging on and off. &kmail; queries the mysql
+ database many times in just a few seconds; output can be voluminous.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-tracker">
+ <term><guilabel>Job Tracker</guilabel> tab.</term>
+ <listitem><para>The &PIM; applications perform various functions by initiating "jobs". Use
+ this tab to toggle job tracking on and off.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-scheduler">
+ <term><guilabel>Resources Schedulers</guilabel> tab.</term>
+ <listitem><para>Here you can see which resources are needed when a particular &PIM; function is
+ invoked. You can see a list of all the &akonadi; resources in your system in the
+ <filename>~/.config/akonadi/</filename> directory.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-notif-monitor">
+ <term><guilabel>Notification Monitor</guilabel> tab.</term>
+ <listitem><para>Use this tab to monitor notifications sent by various &akonadi; resources.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-search">
+ <term><guilabel>Item Search</guilabel> tab.</term>
+ <listitem><para>This tab provides a generic search function. Searches can be restricted to Calendar, Contact,
+ Email, or Note.</para></listitem>
+ </varlistentry>
+
+ <varlistentry id="ak-console-monitors">
+ <term><guilabel>Monitors</guilabel> tab.</term>
+ <listitem><para>Here you can see a list of all the monitors running under &akonadi;, and also view
+ their properties. Agents, resources, and even some appliction programs are monitored.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ </sect2>
+
</sect1>
-<sect1 id="clean-start-after-a-failed-migration"><title>Clean start after a failed migration</title>
+
+<!-- <sect1 id="kmail2-doesnt-send-mail">
+<title>KMail doesn't send mail</title>
+ <para>Some users find that mail does not go out, and it appears that &SMTP; is missing, even though the
+ <guilabel>Settings</guilabel> page looks correct. It has been reported that this is cured by opening
+ <application>akonadiconsole</application> and adding Mail Dispatcher Agent.</para>ttps://bugs.kde.org/show_bug.cgi?id=283682
+ <para>If the computer was suddenly turned off in suspend mode (⪚ by a power cut) sometimes e-mails simply
+ stay in the outbox without being sent, but no error message is generated either. This may be due to the fact
+ that the Mail Dispatcher Agent is set to <quote>offline</quote> in the configuration file during suspend and
+ is not changed back due to the crash. Edit the following file:</para>
+ <para><filename>~/.config/akonadi/agent_config_akonadi_maildispatcher_agent</filename> and change</para>
+ <para><screen>[Agent] Online=false</screen></para>
+ <para>to</para>
+ <para><screen>[Agent] Online=true</screen></para>
+</sect1> --> <!-- This section removed 8/8/2021. -->
+
+<!-- <sect1 id="clean-start-after-a-failed-migration"><title>Clean start after a failed migration</title>
<para>In case migration from &kmail; 1 to &kmail; 2 fails or you have weird problems after it, you can try to do a clean import of your data, instead of migrating the existing settings. Be warned, this needs more manual setup, so do only if you are confident of setting up your &kmail; accounts again; it can generate a large amount of network traffic for &IMAP; resources.
</para>
<orderedlist>
@@ -72,7 +240,7 @@ Online=true</screen>
<para>Delete also the files starting with <emphasis>akonadi</emphasis> from <filename role="directory">~/.kde4/share/config</filename>
</para>
</listitem>
-<listitem>
+<listitem>ttps://bugs.kde.org/show_bug.cgi?id=283682
<para>Restart Akonadi server
</para>
<para><userinput><command>akonadictl start</command></userinput>
@@ -129,9 +297,9 @@ Online=true</screen>
</orderedlist>
<para>Hopefully after these steps, you will have a much nicer &kmail; experience.
</para>
-</sect1>
+</sect1> --> <!-- This section removed 8/8/2021. -->
-<sect1 id="local-folders-is-added-over-and-over"><title>Local Folders is added over and over</title>
+<!-- <sect1 id="local-folders-is-added-over-and-over"><title>Local Folders is added over and over</title>
<para>In some cases you might end up with a maildir account pointing to a certain place (like <filename>$HOME/Mail</filename>), but you still see a <guilabel>Local Folders</guilabel> folder in the folder list with Inbox/Outbox/Trash/Drafts/&etc; subfolders and &kmail; keeps putting mails there, especially sent mails.
</para>
<para>The problem is that certain folders are marked as special folders (system folders) and if you don't have them, &kmail; cannot operate correctly. That is the reason why it keeps re-creating that folder.
@@ -158,44 +326,239 @@ DefaultResourceId=akonadi_maildir_resource_0</userinput>
</para>
<para>If it keeps reappearing and the <guilabel>Mail Dispatcher Agent</guilabel> still crashes, you need to do one more thing in <application>akonadiconsole</application>. Go to the <guilabel>Browser</guilabel> tab, find the outbox you <emphasis>want</emphasis> to use, right click on it, select <guilabel>Folder Properties</guilabel>, <guilabel>Attributes</guilabel> tab, enter <userinput>SpecialCollectionAttribute</userinput> then click <guilabel>Add</guilabel>, double click on the <guilabel>Value</guilabel> near the <guilabel>SpecialCollectionAttribute</guilabel> and enter <userinput>outbox</userinput>. Add also another attribute, the attribute name has to be <guilabel>ENTITYDISPLAY</guilabel> and the value <userinput>("outbox" "mail-folder-outbox" "" ())</userinput> (just copy paste from here). Restart <application>akonadi</application> and now you should be able to remove completely the unneeded local folder account.
</para>
+</sect1> --> <!-- This section removed 8/8/2021. -->
+
+<sect1 id="unable-to-fetch-item-from-backend">
+<title>"Unable to Fetch Item from Backend" When Entering &IMAP; Folder</title>
+
+ <para>There are at least two possible reasons for this. Here are some workarounds.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Workaround 1</term>
+ <listitem>
+ <itemizedlist>
+ <listitem><para>edit <filename>~/.local/share/akonadi/mysql.conf</filename></para></listitem>
+ <listitem><para>Under the <guilabel>[mysql]</guilabel> section, add: <userinput>binlog_format=row</userinput></para></listitem>
+ </itemizedlist>
+ <para>If this does not work, try workaround 2 (below).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Workaround 2</term>
+ <listitem>
+ <para>This one is a matter of restarting so &kmail; can fetch those pesky items. Some possible steps include:</para>
+ <para>Use <keycombo>&Alt;<keycap>F2</keycap></keycombo> (&krunner;) or &konsole; to type <userinput><command>kquitapp
+ kmail</command></userinput> , then wait a minute, then <userinput><command>akonadictl stop</command></userinput> . Wait
+ a minute, type <userinput><command>akonadictl start</command></userinput> , wait a minute, then type <userinput>
+ <command>kmail</command></userinput> . This stops &kmail; (closing <emphasis>all</emphasis> windows), stops the &kmail;
+ backend, restarts the &kmail; backend, and restarts &kmail;. Having a working internet connection increases the chances
+ of success. Sometimes, you can also just do <userinput><command>kquitapp kmail</command></userinput> , wait a minute, and
+ then start &kmail; again. Often, a few restarts seem to be needed. It is unclear what causes this error, but on bad
+ network connections it is more likely to happen.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>See also <link linkend="your-mails-are-not-being-sent">the next topic</link> to learn how
+ <application>akonadiconsole</application> can be helpful.</para>
</sect1>
-<sect1 id="you-get-the-error-unable-to-fetch-item-from-backend-when-entering-imap-folder"><title>You get the error Unable to fetch item from backend when entering IMAP folder</title>
-<para>There are a number of possible reasons for this and it is something the &kmail; team hopes to tackle in time. Meanwhile, there are some workarounds:
-</para>
-<variablelist>
- <varlistentry>
- <term>Workaround 1</term>
- <listitem>
- <itemizedlist>
- <listitem><para>edit <filename>~/.local/share/akonadi/mysql.conf</filename></para></listitem>
- <listitem><para>Under the <guilabel>[mysql]</guilabel> section, add: <userinput>binlog_format=row</userinput></para></listitem>
- </itemizedlist>
- <para>If this does not work, try workaround 2 (below).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>Workaround 2</term>
- <listitem>
- <para>This one is mostly a matter of restarting so &kmail; can fetch those pesky items... Some possible steps:</para>
- <para>Use <keycombo>&Alt;<keycap>F2</keycap></keycombo> or &konsole; to type: <userinput><command>kquitapp kmail</command></userinput>, then wait a minute, then <userinput><command>akonadictl stop</command></userinput>, wait a minute, type <userinput><command>akonadictl start</command></userinput>, wait a minute, type <userinput><command>kmail</command></userinput>. This stops &kmail; (closing <emphasis>all</emphasis> windows), stops the &kmail; backend, starts the &kmail; backend, starts &kmail;. Having a working internet connection increases the chances of success. Sometimes, you can also just do <userinput><command>kquitapp kmail</command></userinput>, wait a minute, and start &kmail; again. Often, a few restarts seem to be needed. It is unclear what is the reason for this, but on bad network connections it is more likely to happen.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-<para>See also the below item for how <application>akonadiconsole</application> can be helpful.
-</para>
+<sect1 id="your-mails-are-not-being-sent">
+<title>Your Emails Are Not Being Sent, Without Error Messages</title>
+
+ <para>If &kmail; does not send mail without saying anything, the <quote>agent</quote> responsible for dispatching
+ messages may be stuck. Of course, you should first verify you have proper network connectivity so mail can be sent!</para>
+
+ <para>To remedy this, it might help to abort the current action and restart it. First, quit &kmail; by using &krunner;
+ (<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole; and typing: <userinput><command>kquitapp kmail</command></userinput> .
+ Note that a normal <keycombo>&Alt;<keycap>F4</keycap></keycombo> or <menuchoice><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem>
+ </menuchoice> does <emphasis>not</emphasis> do the trick! Wait a minute, then start &kmail; again. Now start
+ <application>akonadiconsole</application> using &krunner; (<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole;. Go to the
+ <guilabel>Mail Dispatcher Agent</guilabel> (under the <guilabel>Agents</guilabel> tab), do a right-click, and abort the current action.
+ You will most likely get some error messages popping up. Now go back to &kmail; and choose <menuchoice><guimenu>File</guimenu>
+ <guimenuitem>Send Queued Messages</guimenuitem></menuchoice>. Now it might work. If not, instead of aborting the current action,
+ try toggling the offline/online status of the <guilabel>Mail Dispatcher Agent</guilabel> (same context menu) or restarting things
+ as mentioned in workaround 2 of <link linkend="unable-to-fetch-item-from-backend"> the previous topic</link>.</para>
+
+ <para><note><para>akonadiconsole can be quite helpful for a number of situations because it shows all the <quote>agents</quote>,
+ the separate components of the &kmail; backend. You can stop and start them, put them in offline mode, abort ongoing actions &etc;.
+ It can be very helpful when &kmail; is acting cranky.</para></note></para>
+
+ <para>Sometimes the <guilabel>Mail Dispatcher Agent</guilabel> fails to function because the dbus daemon (a system-level
+ facility for inter-process communications) is not functioning correctly. Your best bet in this circumstance is simply to
+ reboot the system. The dbus daemon is one of the first processes started when you log in to the &kde; desktop, so it
+ cannot be easily stopped and restarted. The whole &plasma; environment depends on it.</para>
+
</sect1>
-<sect1 id="your-mails-are-not-being-sent-without-error-messages"><title>Your mails are not being sent, without error messages</title>
-<para>If &kmail; does not send mail without saying anything, the <quote>agent</quote> responsible for dispatching the messages can be stuck. Of course, you need to ensure you have proper network connectivity for mail to be sent!
-</para>
-<para>To remedy this, it might help to abort the current action and restart it. First, quit &kmail; by using &krunner; (<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole; and typing: <userinput><command>kquitapp kmail</command></userinput>. Note that a normal <keycombo>&Alt;<keycap>F4</keycap></keycombo> or <menuchoice><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem></menuchoice> does <emphasis>not</emphasis> do the trick! Wait a minute, then start &kmail; again. Now start <application>akonadiconsole</application> using &krunner; (<keycombo>&Alt;<keycap>F2</keycap></keycombo>) or &konsole;. Go to the <guilabel>Mail Dispatcher Agent</guilabel>, do a right-click and abort the current action. You will most likely get some error messages popping up.
- Go back to &kmail; and choose <menuchoice><guimenu>File</guimenu><guimenuitem>Send Queued Messages</guimenuitem></menuchoice>. Now it might work. If not, instead of aborting the current action, try toggling the offline/online status of the <guilabel>Mail Dispatcher Agent</guilabel> or restarting things as mentioned in workaround 2 of the problem above this one.
-</para>
-<para><note><para>akonadiconsole can be quite helpful for a number of situations as it shows all the <quote>agents</quote>, the separate components of the &kmail; backend. You can stop and start them, put them in offline mode, abort ongoing actions &etc; It can be very helpful when things get stuck.</para></note>
-</para>
+<sect1 id="resource-conflict-error">
+<title>"Unable to Fetch Item from Backend ... [LRCONFLICT]"</title>
+
+ <para>This problem is directly related to <ulink url="https://bugs.kde.org/show_bug.cgi?id=283682">&akonadi; bug #283682</ulink>,
+ which has been a thorn in the side of &kmail; since October, 2011. There is a timing / co-ordination problem with asynchronous
+ processing of message filters. Once in a while, a filter rule that moves messages to a different folder "hiccups", and produces
+ more than one database entry for a message that has been moved. When you try to open the second copy of such a message, the error
+ message "Unable to fetch item from backend ...[LRCONFLICT]" appears. Such phantom messages cannot be deleted or moved to trash
+ using &kmail;'s built-in functions. But you <emphasis>can</emphasis> get rid of them. Here's how you do it.</para>
+
+<procedure>
+ <step><para>First, exit the &kmail; program. This may not be necessary, but better safe than sorry.</para></step>
+
+ <step><para>You can learn how many corrupted messages are present by using <code>akonadictl</code>.
+<screen>~ $ akonadictl fsck 2>&1 | grep ^Found
+Found 6 external files.
+Found 6 external parts.
+Found no unreferenced external files.
+Found 0 parts to be moved to external files
+Found 0 parts to be moved to database
+Found 6 collections without RID.
+Found 9 items without RID.
+Found 0 dirty items.</screen> <!-- Can't indent here ... messes up the output. -->
+ In this instance, there are nine duplicated messages (without RID).</para>
+<para> </para><!-- add whitespace --></step>
+
+ <step><para>You need to know how to connect directly to the mysql server. Use the <code>ps</code> and
+ <code>grep</code> commands to do this.
+<screen>~ $ ps ux | grep mysql
+david 8788 0.2 0.9 3736292 153936 ? Sl 06:45 0:16 /usr/sbin/mysqld
+--defaults-file=/home/david/.local/share/akonadi/mysql.conf
+--datadir=/home/david/.local/share/akonadi/db_data/
+--socket=/run/user/1000/akonadi/mysql.socket
+--pid-file=/run/user/1000/akonadi/mysql.pid
+david 24275 0.0 0.0 8056 2144 pts/1 S+ 08:24 0:00 grep --colour=auto mysql</screen></para>
+<para> </para><!-- add whitespace --></step>
+
+ <step><para>Invoke the mysql server program using the socket information from step 3 and issue three mysql
+ commands, as illustrated below.
+<screen>~ $ mysql --socket=/run/user/1000/akonadi/mysql.socket <==
+Welcome to the MariaDB monitor. Commands end with ; or \g.
+Your MariaDB connection id is 114
+Server version: 10.5.10-MariaDB Source distribution
+
+Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
+
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+
+MariaDB [(none)]> use akonadi; <==
+Reading table information for completion of table and column names
+You can turn off this feature to get a quicker startup with -A
+
+Database changed
+MariaDB [akonadi]> delete from pimitemtable where remoteid is NULL; <==
+Query OK, 9 rows affected (0.003 sec)
+
+MariaDB [akonadi]> \q <==
+Bye</screen>
+ The three mysql commands are "use akonadi;", "delete from pimitemtable where remoteid is NULL;", and "\q". After you
+ say "mysql --socket= ..." you will be in a dialog with the mysql server (aka "MariaDB"), which provides a > prompt.
+ The entire dialog is presented here, for clarity. User input lines are marked with <== in the preceding
+ illustration.</para></step>
+
+</procedure>
+
+ <para>When you restart &kmail;, those pesky duplicate messages will be gone. They were merely phantoms caused by the NULL
+ pointers in the mysql database tables.</para>
+
</sect1>
+<sect1 id="cleaning-aux-storage">
+<title>Keeping &kmail;'s Auxiliary Storage Areas Clean</title>
+
+ <para>&kmail; stores data in several different places on your machine. Most of these places are inside the
+ <filename>~/.local/share/</filename> directory somewhere. For instance, on most Linux distros, your
+ <guilabel>Local Folders</guilabel> are in <filename>~/.local/share/local-mail/</filename> . &akonadi; stores
+ most of its data in <filename>~/.local/share/akonadi/</filename> .
+<screen>~ $ cd .local/share/akonadi
+~/.local/share/akonadi $ ls
+Akonadi.error db_data file_db_data mysql.conf socket-localhost-default
+Akonadi.error.old db_misc file_lost+found search_db
+</screen></para>
+
+ <para><filename>Akonadi.error</filename> and <filename>Akonadi.error.old</filename> are log files that are created
+ whenever &akonadi; stops and restarts. Text file <filename>mysql.conf</filename> is a configuration file for
+ the mysqld daemon that serves as &akonadi;'s backend. The two directories <filename>db_data</filename> and
+ <filename>search_db</filename> contain the actual mysql database tables. There are also a couple of mysql
+ log files in <filename>db_data</filename> that mignt be helpful if and when &akonadi; acts up.</para>
+
+ <para>The two directories <filename>file_db_data</filename> and <filename>file_lost+found</filename> contain auxiliary
+ data associated with asynchronous processing. &akonadi; does not automatically clean out the
+ <filename>file_lost+found</filename> directory, so you may wish to clean those files up manually from time to time
+ (⪚, with &dolphin;). &akonadi; does try to clean the <filename>file_db_data</filename> directory out after it has merged
+ everything into the main database files, but sometimes junk piles up in there. Use this command
+ <screen>find .local/share/akonadi/file_db_data/ -type f | xargs rm</screen> to fix this when it happens. (If the directory
+ <filename>file_db_data</filename> is already clean, the "find" command shown above will return an error.)</para>
+
+</sect1>
+
+<sect1 id="dealing-with-dirt">
+<title>Correcting &kmail;'s "Dirty" Items</title>
+
+ <para>This problem is directly related to <ulink url="https://bugs.kde.org/show_bug.cgi?id=436550">&akonadi; bug #436550</ulink>,
+ which was reported in April, 2021. It results from the "dirty" items occasionally found by <code>akonadictl fsck</code>.
+<screen>~ $ akonadictl fsck 2>&1 | grep ^Found
+Found 5 external files.
+Found 5 external parts.
+Found no unreferenced external files.
+Found 0 parts to be moved to external files
+Found 0 parts to be moved to database
+Found 6 collections without RID.
+Found 0 items without RID.
+Found 750 dirty items.</screen> <!-- Can't indent here ... messes up the output. -->
+ </para>
+
+ <para>The "dirty" flag on an item in pimitemtable (one of the tables in the &akonadi; database) is used to control certain
+ aspects of asynchronous processing. It is set true when there are operations pending for a particular email message. Most
+ of the time, the "dirty" flag is cleared one or two seconds later, when the once pending operation finishes up.</para>
+
+ <para>Occasionally, for reasons that are not entirely clear, the "dirty" flag can get set on dozens or even hundreds of
+ messages all at once, as illustrated above. When this happens, the automatic clearing mechanism gets stuck, and is unable
+ to repair itself automatically. The primary reason for a "dirty" item in this circumstance is that the field "remoteid"
+ is not set correctly, making retrieval of a "dirty" message impossible in &kmail;. The message still exists on the disk.
+ But &kmail; can't find it.</para>
+
+ <para>There ought to be a better way to correct this problem. If you think of a better way, please let the authors know about
+ it, so this documentation can be improved. The following procedure will at least correct the database errors. But it does
+ entail a lot of work.</para>
+
+ <procedure>
+ <step><para>Exit &kmail; and stop the &akonadi; server with a terminal command: <code>akonadictl stop</code> .</para></step>
+
+ <step><para>Make a backup copy of all your email messages. You may be able to use <ulink url="help:/pimdataexporter">PIM
+ Data Exporter</ulink> for this purpose. Or you may use &ark; to make an archive, or &dolphin; to make a second copy of
+ <filename>~/.local/share/local-mail/</filename> somewhere else on your hard disk. If you're adventurous, you might just
+ rename your local folders directory to something like <filename>local-mail-save</filename> . But it's safer to be sure
+ you have a backup copy of your messages before you proceed.</para></step>
+
+ <step><para>You should also make a backup copy of any filters you have created, and make sure you know how to restore any
+ custom <guilabel>Sent mail folder</guilabel>, <guilabel>Drafts folder</guilabel>, or <guilabel>Templates folder</guilabel>
+ entries associated with your &kmail; identities. The next step will remove all your personally customized mail folders,
+ and you will need to patch some stuff up after &akonadi; rebuilds its database tables.</para></step>
+
+ <step><para>Now delete all the folders inside of the directory <filename>local-mail</filename>, or rename that directory
+ to something like <filename>local-mail-save</filename> . Then start the &kmail; program. This will force &akonadi; to
+ erase all the database table entries associated with email messages. You will see your old folder names, briefly, but these
+ will disappear when &akonadi; finishes deleting all the "dirty" items (and all the clean ones, too).</para></step>
+
+ <step><para>Exit &kmail; and stop the &akonadi; server as explained in step 1, then restore the backup copy of your messages
+ (created in step 2) to the <filename>~/.local/share/local-mail/</filename> directory.</para></step>
+
+ <step><para>Start &kmail; up again, and force &akonadi; to re-sync the database. The easiest way to do this is to <menuchoice>
+ <shortcut><keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo></shortcut><guimenu>File</guimenu><guimenuitem>Check
+ Mail</guimenuitem></menuchoice>; &akonadi; automatically re-syncs all the folders when it fetches mail. This will take several
+ minutes to complete, depending on how many messages you have saved in your &kmail; folders. But when the process is complete
+ all the "dirty" items will be gone.</para></step>
+
+ <step><para>Finally, you will want to restore your mail filter rules backed up in step 3, and check that all the custom folder
+ items (<guilabel>Sent mail folder</guilabel>, &etc;) for your identities are set the way you want them. You will also need
+ to reset any custom folder properties you had set up, and you will probably have a bunch of spurious "Unread Message"
+ notifications to deal with. But your &akonadi; database tables will be all clean and shiny once again!</para></step>
+
+ </procedure>
+
+
+</sect1>
+
+
</chapter>
More information about the kde-doc-english
mailing list