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