doc/www/sync.html

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