doc/www/sync.php

   1 <? include ("barry.inc"); ?>
   2
   3 <? createHeader("Syncing your BlackBerry with Evolution"); ?>
   4
   5 <? createSubHeader("Introduction"); ?>
   6
   7 <p>This document describes the steps needed to sync your Blackberry with
   8 Evolution, using OpenSync version 0.22 and the command line tool
   9 msynctool.  The concepts are similar with other Opensync plugins,
  10 and should be relatively straightforward to sync with other data sources.</p>
  11
  12
  13 <? createSubHeader("Overview"); ?>
  14
  15 <p>The first sync requires the following steps:
  16 <ul>
  17         <li>Run Evolution and make sure it has created its local databases</li>
  18         <li>Create a sync group with msynctool, and configure each member</li>
  19         <li>Shutdown Evolution servers</li>
  20         <li>Run the sync</li>
  21 </ul>
  22 </p>
  23
  24 <p>Future syncs only require the following steps:
  25 <ul>
  26         <li>Shutdown Evolution servers</li>
  27         <li>Run the sync</li>
  28 </ul>
  29 </p>
  30
  31
  32 <? createSubHeader("First Step"); ?>
  33
  34 <p>First step is to always make a backup of your data.  Use the GUI
  35 backup tool that comes with Barry, or the RIM Windows Desktop software,
  36 to make backups of your device data.</p>
  37
  38 <p>Remember that your device data is not the only database being operated
  39 on.  Your Evolution data is also at risk, should something go wrong.
  40 You should backup your Evolution data as well.
  41 See
  42 "<a href="http://ubuntu.wordpress.com/2005/12/03/how-to-backup-evolution/">How To Backup Evolution</a>" (external link)
  43 for step by step instructions on backing up your local Evolution data.</p>
  44
  45
  46 <? createSubHeader("Preparing Evolution"); ?>
  47
  48 <p>If you've never run Evolution before, start Evolution and follow its
  49 initial configuration dialogs.  Once it is running, click on each of the
  50 available section buttons.  These buttons include: Mail, Contacts,
  51 Calendars, Memos, and Tasks.  Clicking on each of these, causes Evolution
  52 to open and create the matching databases.</p>
  53
  54 <p>Each of these sections should have a "Personal" folder.  This is
  55 where data from your Blackberry will end up, and any data in these
  56 databases will be synced to your Blackberry as well.</p>
  57
  58 <p><b>Note:</b> Only Contacts and Calendar items are currently supported
  59 in the Barry Opensync 0.22 plugin.</p>
  60
  61
  62 <? createSubHeader("Preparing OpenSync"); ?>
  63
  64 <p>Opensync organizes its sync configurations in the form of groups.  Each
  65 group contains two or more member plugins that will be synchronized.</p>
  66
  67 <p>For example, using msynctool, you can create a group called EvoBarry
  68 which will sync your Blackberry and Evolution like this:</p>
  69
  70 <pre>
  71         msynctool --delgroup EvoBarry
  72         msynctool --addgroup EvoBarry
  73         msynctool --addmember EvoBarry evo2-sync
  74         msynctool --addmember EvoBarry barry-sync
  75         msynctool --configure EvoBarry 1
  76         msynctool --configure EvoBarry 2
  77         msynctool --showgroup EvoBarry
  78 </pre>
  79
  80 <p>Each configuration stage (1 and 2) will open an editor, where you can
  81 edit the member plugin's configuration file.  Evolution's plugin takes
  82 its configuration in the form of XML.  For example:</p>
  83
  84 <pre>
  85         &lt;config&gt;
  86            &lt;address_path&gt;file:///home/cdfrey/.evolution/addressbook/local/system&lt;/address_path&gt;
  87            &lt;calendar_path&gt;file:///home/cdfrey/.evolution/calendar/local/system&lt;/calendar_path&gt;
  88            &lt;tasks_path&gt;file:///home/cdfrey/.evolution/tasks/local/system&lt;/tasks_path&gt;
  89         &lt;config&gt;
  90 </pre>
  91
  92 <p>Barry's plugin member takes a simple text file.  The default configuration
  93 that comes with Barry is shown below:</p>
  94
  95 <pre>
  96         #
  97         # This is the default configuration file for the barry-sync opensync plugin.
  98         # Comments are preceded by a '#' mark at the beginning of a line.
  99         # The config format is a set of lines of <keyword> <values>.
 100         #
 101         # Keywords available:
 102         #
 103         # DebugMode        - If present, verbose USB debug output will be enabled
 104         #
 105         # Device           - If present, it is followed by the following values:
 106         #      PIN number    - PIN number of the device to sync with (in hex)
 107         #      sync calendar - 1 to sync calendar, 0 to skip
 108         #      sync contacts - 1 to sync contacts, 0 to skip
 109         #
 110         # Password secret  - If present, specifies the device's password in plaintext
 111         #
 112
 113         #DebugMode
 114
 115         Device 3009efe3 1 1
 116
 117         #Password secret
 118 </pre>
 119
 120 <p>Edit the device's PIN number, and save.  You're now ready to run your
 121 first sync.</p>
 122
 123
 124 <? createSubHeader("Syncing!"); ?>
 125
 126 <p>It is recommended that Evolution's backend servers be shutdown before
 127 the sync is performed.  Therefore, make sure you've closed Evolution,
 128 and run the following commands to sync, using the group you just configured:</p>
 129
 130 <pre>
 131         evolution --force-shutdown
 132         msynctool --sync EvoBarry
 133 </pre>
 134
 135 <p>Status messages will appear at each stage of the sync: each plugin
 136 fetches new records, the conflict resolution is performed by the Opensync
 137 engine, and new records are written to each plugin.</p>
 138
 139
 140 <? createSubHeader("Troubleshooting"); ?>
 141
 142 <p>There are a number of things that can go wrong during a sync:
 143 <ul>
 144         <li>One of the plugins may crash</li>
 145         <li>Opensync may hang, or take a long time, while processing conflicts</li>
 146         <li>Opensync may get confused and duplicate a lot of data</li>
 147 </ul>
 148 </p>
 149
 150 <p><b>If one of the plugins crash...</b></p>
 151
 152 <p>If one of the plugins crashes due to a segmentation fault, try to get
 153 a sequence of steps that can reproduce the crash every time.  At that
 154 point, enable core dumps, and run it again:</p>
 155
 156 <pre>
 157         ulimit -c unlimited
 158         msynctool --sync EvoBarry
 159 </pre>
 160
 161 <p>This will leave a core file somewhere on your filesystem.  In order
 162 to get a useful backtrace from it, you will need the debug packages
 163 for Barry and OpenSync.  The debug packages for Barry are available
 164 at the
 165 <a href="http://sourceforge.net/project/showfiles.php?group_id=153722">Sourceforge download page</a>.
 166 Debug packages for OpenSync should
 167 come with your distribution.</p>
 168
 169 <p>Once you have installed the matching debug packages, open the core
 170 dump file like this, which will tell you which program was running when
 171 the plugin crashed:</p>
 172
 173 <pre>
 174         gdb /bin/ls corefile
 175         [... lots of output ...]
 176         (gdb) quit
 177 </pre>
 178
 179 <p>As gdb loads, it will print the name of the program that crashed.
 180 Often this is /usr/lib/opensync/osplugin or something similar.
 181 Load gdb again with the correct program, and use the backtrace (bt)
 182 command:</p>
 183
 184 <pre>
 185         gdb /usr/lib/opensync/osplugin corefile
 186         [... lots of output ...]
 187         (gdb) bt
 188         [... useful output ...]
 189         (gdb) quit
 190 </pre>
 191
 192 <p>Paste the "useful ouput" above into an email and
 193 <?createLink("contact", "send it to us"); ?>.</p>
 194
 195
 196
 197 <p><b>If OpenSync hangs...</b></p>
 198
 199 <p>If the hang lasts only for about 30 seconds, then it is likely the
 200 USB conversation that is timing out.  Enable the <b>DebugMode</b>
 201 keyword in the Barry plugin configuration above, and send the last
 202 few screens of output to the
 203 <?createLink("contact", "mailing list"); ?>.</p>
 204
 205 <p>Otherwise, Opensync supports a detailed level of logging.  If you set
 206 the environment variable <b>OSYNC_TRACE</b> to the path of an empty
 207 directory, Opensync will write detailed logs for every thread
 208 used during the syncing process.  These logs quickly get out of
 209 hand, so delete them before each test run.</p>
 210
 211 <p>Some of these logs may contain private data, so before posting
 212 them on the mailing list, or on a website, you may wish to
 213 double check.  You can also
 214 <?createLink("contact", "email them privately"); ?>
 215 to the lead developer.</p>
 216
 217
 218 <p><b>If you get a load of duplicates...</b></p>
 219
 220 <p>If the sync has crashed, note that OpenSync will know this and attempt
 221 a slow-sync automatically the next time you run the sync.  If there is
 222 a mismatch in supported fields, this can cause duplicates to be created
 223 on one or possibly both sides of the sync.  For example, if your desktop
 224 software supports a Speed field, which the Blackberry does not, then
 225 with OpenSync 0.22, these records will look different, and duplicates will
 226 be created.</p>
 227
 228 <p>This bug should be <a href="http://www.opensync.org/ticket/636">fixed
 229 in the upcoming OpenSync 0.40.</a></p>
 230
 231 <p>In the meantime, it is much better to avoid slow-syncing, and re-create
 232 your sync configuration from scratch, as documented above.</p>
 233
 234 <p>If you know that one side is authoritative (for example, you may know
 235 that your Blackberry has the most up to date set of data), delete all
 236 the data from the opposite data source, reconfigure, and sync again.</p>
 237
 238 <p>If all else fails, restore your backups and start fresh.</p>
 239