summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJeroen van Meeuwen (Kolab Systems) <vanmeeuwen@kolabsys.com>2012-08-15 22:05:30 (GMT)
committerJeroen van Meeuwen (Kolab Systems) <vanmeeuwen@kolabsys.com>2012-08-15 22:05:30 (GMT)
commitcf03d34d89a5873ff08f13c3c4709b1d9c8a1c47 (patch)
tree2c1022b9039f701e8139a208a0787ad0649c4008
parenta39563d878d9b94505b31613a856b7569d44f28d (diff)
downloadkolab-docs-cf03d34d89a5873ff08f13c3c4709b1d9c8a1c47.tar.gz
Add documentation on Upgrading from Kolab 2 to Kolab 3
-rw-r--r--Administrator_Guide/en-US/Upgrading_from_Kolab_2_on_OpenPKG.xml214
-rwxr-xr-xAdministrator_Guide/en-US/part-Kolab_Server.xml2
-rw-r--r--Administrator_Guide/en-US/step-select-all-mailboxes.xml5
3 files changed, 137 insertions, 84 deletions
diff --git a/Administrator_Guide/en-US/Upgrading_from_Kolab_2_on_OpenPKG.xml b/Administrator_Guide/en-US/Upgrading_from_Kolab_2_on_OpenPKG.xml
index 4b342d6..d8ffaff 100644
--- a/Administrator_Guide/en-US/Upgrading_from_Kolab_2_on_OpenPKG.xml
+++ b/Administrator_Guide/en-US/Upgrading_from_Kolab_2_on_OpenPKG.xml
@@ -140,23 +140,32 @@ primary_mail = %(surname)s@%(domain)s
<para>
Now, users that are created will get a <literal>mail</literal> attribute value of "surname"@example.org assigned.
</para>
- <warning>
- <para>
- First adding user John Doe will give him a <literal>mail</literal> attribute value of <emphasis>doe@example.org</emphasis>, but should you have a Jane Doe as well, she would get <emphasis>doe2@example.org</emphasis>. It is therefore important to add users in order.
- </para>
-
- </warning>
+ <para>
+ First adding user John Doe will give him a <literal>mail</literal> attribute value of <emphasis>doe@example.org</emphasis>, but should you have a Jane Doe as well, she would get <emphasis>doe2@example.org</emphasis>. It is therefore important to add users in order.
+ </para>
</example>
- <procedure id="proc-Administrator_Guide-Upgrading_from_Kolab_2_on_OpenPKG-Migrate_the_Data_Through_Copying">
- <title>Migrate the Data Through Copying</title>
- <step>
- <para>
- Login to <literal>kolab3.example.org</literal> to execute the steps in this procedure.
- </para>
+ <section id="sect-Administrator_Guide-Upgrading_from_Kolab_2_on_OpenPKG-Migration_of_LDAP">
+ <title>Migration of LDAP</title>
+ <para>
+ This section has not been authored yet.
+ </para>
+ </section>
- </step>
- <!--
+ <section id="sect-Administrator_Guide-Upgrading_from_Kolab_2_on_OpenPKG-Migration_and_Upgrade_of_Data">
+ <title>Migration and Upgrade of Data</title>
+ <para>
+ The following procedure
+ </para>
+ <procedure id="proc-Administrator_Guide-Migration_and_Upgrade_of_Data-Migrate_the_Data_Through_Copying">
+ <title>Migrate the Data Through Copying</title>
+ <step>
+ <para>
+ Login to <literal>kolab3.example.org</literal> to execute the steps in this procedure.
+ </para>
+
+ </step>
+ <!--
It doesn't seem this step causes the annotations.{db,txt} to transfer 1:1
<step>
@@ -172,10 +181,10 @@ primary_mail = %(surname)s@%(domain)s
</step>
// --> <step>
- <para>
- Copy mailboxes.db and annotations.db. These files are located in <filename>/kolab/var/imapd/</filename> on your Kolab 2 server.
- </para>
- <para>
+ <para>
+ Copy mailboxes.db and annotations.db. These files are located in <filename>/kolab/var/imapd/</filename> on your Kolab 2 server.
+ </para>
+ <para>
<screen># <userinput>scp root@kolab2.example.org:/kolab/var/imapd/annotations.db \</userinput>
&gt; <userinput>/var/lib/imap/annotations.db</userinput>
@@ -184,28 +193,28 @@ primary_mail = %(surname)s@%(domain)s
&gt; <userinput>/var/lib/imap/mailboxes.db</userinput>
(...)</screen>
- </para>
+ </para>
- </step>
- <step>
- <para>
- Migrate the mail spool:
- </para>
- <para>
+ </step>
+ <step>
+ <para>
+ Migrate the mail spool:
+ </para>
+ <para>
<screen># <userinput>rsync -rltpHvz --progress --partial \</userinput>
&gt; <userinput>kolab2.example.org:/var/imapd/spool/ \</userinput>
&gt; <userinput>/var/spool/imap/</userinput>
(...)</screen>
- </para>
+ </para>
- </step>
- <step>
- <para>
- Migrate the seen and subscription databases:
- </para>
- <para>
+ </step>
+ <step>
+ <para>
+ Migrate the seen and subscription databases:
+ </para>
+ <para>
<screen># <userinput>rsync -rltpHvz --progress --partial \</userinput>
&gt; <userinput>kolab2.example.org:/var/imapd/domain/ \</userinput>
@@ -216,69 +225,69 @@ primary_mail = %(surname)s@%(domain)s
&gt; <userinput>/var/lib/imap/user/</userinput>
(...)</screen>
- </para>
+ </para>
- </step>
- <step>
- <para>
- Ensure the filesystem permissions are correct:
- </para>
- <para>
+ </step>
+ <step>
+ <para>
+ Ensure the filesystem permissions are correct:
+ </para>
+ <para>
<screen># <userinput>chown -R cyrus:mail /var/lib/imap/ /var/spool/imap/</userinput></screen>
- </para>
+ </para>
- </step>
- <step>
- <para>
- Ensure only the cyrus user can read and write, and the mail group can read the contents of either directory tree:
- </para>
- <para>
+ </step>
+ <step>
+ <para>
+ Ensure only the cyrus user can read and write, and the mail group can read the contents of either directory tree:
+ </para>
+ <para>
<screen># <userinput>find /var/lib/imap -type f -exec chmod 640 {} \;</userinput>
# <userinput>find /var/lib/imap -type d -exec chmod 750 {} \;</userinput>
# <userinput>find /var/spool/imap -type f -exec chmod 640 {} \;</userinput>
# <userinput>find /var/spool/imap -type d -exec chmod 750 {} \;</userinput></screen>
- </para>
+ </para>
- </step>
- <xi:include href="step-convert-seen-databases.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <step>
- <para>
- Stop the Kolab daemon:
- </para>
- <para>
+ </step>
+ <xi:include href="step-convert-seen-databases.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <step>
+ <para>
+ Stop the Kolab daemon:
+ </para>
+ <para>
<screen># <userinput>service kolabd stop</userinput></screen>
- </para>
+ </para>
- </step>
- <step>
- <para>
- Start the Cyrus IMAP service on <literal>kolab3.example.org</literal>:
- </para>
- <para>
+ </step>
+ <step>
+ <para>
+ Start the Cyrus IMAP service on <literal>kolab3.example.org</literal>:
+ </para>
+ <para>
<screen># <userinput>service cyrus-imapd start</userinput></screen>
- </para>
- <important>
- <para>
- Users should not yet be allowed to interact with the system at this point. We suggest closing access to the system through the firewall.
</para>
+ <important>
+ <para>
+ Users should not yet be allowed to interact with the system at this point. We suggest closing access to the system through the firewall.
+ </para>
- </important>
+ </important>
- </step>
- <xi:include href="step-select-all-mailboxes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <step>
- <para>
- Annotations...
- </para>
- <para>
+ </step>
+ <xi:include href="step-select-all-mailboxes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <step>
+ <para>
+ The annotations database may not have been upgraded correctly, causing some annotations to miss the first 4 characters of their value. The easiest way to fix the issue, that is known to work, is to get the annotation values as they were on the old (Kolab 2) IMAP server, and set them on the new (Kolab 3) IMAP server.
+ </para>
+ <para>
<screen># <userinput>kolab -c conf/kolab-kolab2.example.org.conf \</userinput>
&gt; <userinput>list-mailbox-metadata "user/john.doe/Calendar*@example.org"</userinput>
@@ -323,10 +332,10 @@ Folder user/john.doe/Calendar/Private@example.org
/shared/vendor/cmu/cyrus-imapd/size&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;305426
/shared/vendor/cmu/cyrus-imapd/sharedseen&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;false</screen>
- </para>
- <para>
- Fix'em:
- </para>
+ </para>
+ <para>
+ Fix'em:
+ </para>
<programlisting language="Bash">#!/bin/bash
@@ -373,13 +382,54 @@ for folder_search in user/*@example.org shared/*@example.org; do
done</programlisting>
- </step>
+ </step>
+ <step>
+ <para>
+ Upgrade all messages from Kolab Format version 2 to Kolab Format version 3 using <command>kolab-formatupgrade</command>. This command is run in two parts. The first will upgrade all mailbox contents in the personal namespace:
+ </para>
+ <para>
- </procedure>
+<screen># <userinput>kolab lm "user/%@example.org" | \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;<userinput>sed -e 's/user\///g' | \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;<userinput>while read user; do</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>kolab-formatupgrade \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--user cyrus-admin \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--password <replaceable>$password</replaceable> \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--proxyauth "${user}" \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--port 143 \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--encrypt TLS \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput><replaceable>localhost</replaceable></userinput>
+&gt;&nbsp;&nbsp;&nbsp;<userinput>done</userinput></screen>
- <para>
- find /var/spool/imap -type f -name "*." | sort | while read file ; do grep -l "X-Mailer: z-push-Kolab Backend" "$file" ; done
- </para>
+ </para>
+ <para>
+ The second part upgrades the contents of shared folders. Shared folders have no designated owners, and we can therefore not login as a designated user to upgrade the format.
+ </para>
+ <para>
+ As the user <literal>cyrus-admin</literal> normally does not have the necessary privileges to insert new messages into mail folders, so we're going to have to give out the rights first. We'll delete them again afterwards.
+ </para>
+ <para>
+
+<screen># <userinput>kolab sam shared/*@example.org cyrus-admin lrswiptexa</userinput>
+# <userinput>kolab lm shared/*@example.org | \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;<userinput>while read folder; do</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>kolab-formatupgrade \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--user cyrus-admin \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--password <replaceable>$password</replaceable> \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--port 143 \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--encrypt TLS \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput>--folder "${folder}" \</userinput>
+&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<userinput><replaceable>localhost</replaceable></userinput>
+&gt;&nbsp;&nbsp;&nbsp;<userinput>done</userinput>
+# <userinput>kolab dam shared/*@example.org cyrus-admin</userinput></screen>
+
+ </para>
+
+ </step>
+
+ </procedure>
+
+ </section>
</chapter>
diff --git a/Administrator_Guide/en-US/part-Kolab_Server.xml b/Administrator_Guide/en-US/part-Kolab_Server.xml
index ed2d342..9fbabcd 100755
--- a/Administrator_Guide/en-US/part-Kolab_Server.xml
+++ b/Administrator_Guide/en-US/part-Kolab_Server.xml
@@ -5,8 +5,8 @@
]>
<part id="part-Administrator_Guide-Kolab_Groupware_Server">
<title>Kolab Groupware Server</title>
- <!--
<xi:include href="Upgrading_from_Kolab_2_on_OpenPKG.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!--
<xi:include href="Upgrading_Accounts_from_Kolab_Format_version_2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Upgrading_Cyrus_IMAP_from_2.3_to_2.4.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
// --> <xi:include href="Verifying_the_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
diff --git a/Administrator_Guide/en-US/step-select-all-mailboxes.xml b/Administrator_Guide/en-US/step-select-all-mailboxes.xml
index 81715d1..4024c4f 100644
--- a/Administrator_Guide/en-US/step-select-all-mailboxes.xml
+++ b/Administrator_Guide/en-US/step-select-all-mailboxes.xml
@@ -7,9 +7,12 @@
<para>
Use the Cyrus IMAP administrator account to select all mailboxes, to make sure the format upgrade is not taking place while the user is attempting to login / select a mailbox.
</para>
+ <para>
+ Average sized mailboxes (those restricted with a reasonable quota such as 2GB) can take about 2 minutes to upgrade. A single folder can upgrade as fast as 5 seconds. Mailboxes that contain a lot of messages (such as a shared lists folder that also functions as an archive) can take up to 2-4 minutes to upgrade (approximately 40.000 messages).
+ </para>
<note>
<para>
- Optionally, enable full so-called telemetry logging:
+ Optionally, if errors are expected enable full so-called telemetry logging so that issues can be backtracked. On the IMAP server, issue the following commands:
</para>
<para>