Provided by: coldsync_3.0+pre3-2_i386 bug

NAME

     coldsync - synchronize files between a Palm and a workstation.

SYNOPSIS

     coldsync [options] [-ms]
     coldsync [options] -mI
     coldsync [options] -mb dir [database...]
     coldsync [options] -mr file|dir...
     coldsync [options] -md port
     coldsync -V
     coldsync -h

DESCRIPTION

     coldsync synchronizes databases between a Palm Computing device and a
     workstation (see OVERVIEW, below). By default, it performs a full sync,
     copying records from the Palm to the desktop and vice-versa until both
     contain the same set of records.

     In backup mode, coldsync downloads databases from the Palm to a user-
     specified directory on the workstation.

     In restore mode, coldsync uploads database files from the workstation to
     the Palm. This can be used either to restore files after a backup, or to
     install new databases on the Palm.

OPTIONS

   Modes
     -mI     Initialization mode. Before you can sync a Palm, you must
             initialize its user information. This may seem annoying, but it
             can prevent other annoyances (e.g., losing all of your
             information the next time you reset your Palm, or failing to work
             with HotSync). Note that backup and restore mode do not require
             that the Palm be initialized.

             In this mode, coldsync sets the user name and ID on the Palm from
             values specified in your .coldsyncrc.  If no values are specified
             there, the user name and ID default to your full name and user ID
             from /etc/passwd.  If the Palm already has non-default values
             that you haven’t explicitly overridden, coldsync will suggest
             what to add to your .coldsyncrc.

     -ms     Sync mode (or Standalone mode). This is the default mode, in
             which coldsync performs a full sync (see OVERVIEW, below).

     -mb     Backup mode, in which coldsync downloads databases from the Palm.
             The first argument is a directory in which to write the files.
             Any subsequent arguments are the names of databases to back up.
             If no databases are specified, coldsync does a full backup of the
             Palm.

     -mr     Restore mode (or Install mode), in which coldsync installs the
             files given as arguments on the Palm. Each argument is processed
             in turn; if it is a file, then that file is uploaded. If the
             argument is a directory, then all files in that directory will be
             uploaded (this is not recursive). If a database of the same name
             exists on the Palm, that database is deleted.

             Note that in this mode, files are uploaded as-is. No Install
             conduits are run.

     -md     Daemon mode. Use this mode when running coldsync as a getty
             replacement, or from /etc/inetd.conf.  This mode takes one
             argument, a port on which to listen. This can be either a full
             pathname to a device file (e.g., /dev/ugen0), a relative pathname
             (e.g., ugen0), in which case the given pathname is assumed to be
             relative to /dev, or the string “-” (a single dash), or meaning
             stdin and stdout.  The special string ’stdin’ also means stdin
             and stdout (useful with mgetty and modems).  ***PLEASE NOTE THIS
             FUNCTIONALITY IS DISABLED IN CURRENT DEVELOPMENT BUILDS (use
             config files with -f on the command line and specify the device
             there instead, using stdin instead of ’-’ if necessary)***

             ColdSync waits for a connection on the given port, reads the
             username and user ID from the Palm, and looks them up in
             /usr/local/etc/coldsync/palms.  If it finds a matching entry, it
             sets its UID to the appropriate user (relinquishing root
             privileges in the process) and runs a normal sync.

   Common Options
     -h       (Help) Print a usage message and exit.

     -V       Print version information and exit.

     -v       Increase verbosity. Use this option multiple times to increase
              verbosity still further.

     -f config_file
              Tells coldsync to read its configuration from config_file
              instead of ~/.coldsyncrc.

     -S       Force a slow sync. Don’t use this unless you know what you’re
              doing.

     -F       Force a fast sync. Don’t use this unless you know what you’re
              doing.

     -I       Install all databases in ~/.palm/install.  Normally, coldsync
              does not install databases if doing so would overwrite an
              existing database with a higher modification number. This flag
              overrides this behavior.

     -z       Install new databases (and run Install conduits) after the main
              sync.  Normally databases in ~/.palm/install are installed (and
              Install conduits run) before the main sync.

     -R       Consider read-only (ROM) databases when syncing or doing a
              backup or restore. Normally, these are ignored.

     -p device
              Specifies the device, e.g.  /dev/cuaa0 for serial connections,
              or /dev/ugen0 for USB connections, that the Palm is connected
              to. If not specified, this defaults to /dev/palm.

     -t type  Specifies the device type for the -f option. Legal values are
              serial, usb, and net.

     -P protocol
              Specifies the serial protocol. Legal values are default, full,
              and simple.  (See the description of the protocol option,
              below.)

     -s       Log errors and warnings through syslog(3).  Messages are logged
              to the LOCAL0 facility.

     -l logfile
              Log debugging messages to the file logfile.  logfile is created
              if it doesn’t exist, or appended to if it does. This option is
              more or less equivalent to the Bourne shell’s

                            coldsync 2>logfile
              but is intended for cases in which ColdSync is run without a
              shell, e.g., from inetd.

     -d debug
              Set debugging level. The argument debug can be either of the
              form facility or facility:level.  This sets the debugging level
              for the named facility. If the debugging level is not specified,
              it defaults to 1. Thus, -dmisc is equivalent to -dmisc:1.
              Facilities currently include SLP, CMP, PADP, DLP, DLPC, SYNC,
              PARSE, IO, MISC, and NET.  The level argument is an integer that
              specifies the verbosity of the output.  Unless you are a
              developer, you should probably never need to go above 5.

                            -d sync:5 -d misc:5
              is a good general-purpose debugging level. If you are having
              problems with your .coldsyncrc file,

                            -d sync:4
              will print a summary of what ColdSync thinks your configuration
              file contains.

OVERVIEW

     To sync, run coldsync with the appropriate options. Place the Palm in its
     cradle and press the HotSync button. Your Palm will display the messages
     “Connecting with the desktop”, “Identifying user”, a series of
     “Synchronizing filename” messages, and finally “HotSync complete.” At
     this point, you can remove the Palm from its cradle and use it normally.

     Here’s a summary of what goes on when you sync:
     1.   coldsync starts, reads the .coldsyncrc file, and finds out which
          port it should listen on.
     2.   You press the HotSync button.
     3.   The Palm announces itself to coldsync.
     4.   coldsync queries the Palm to find out what databases it has, who
          owns it, etc.
     5.   If the -z flag was not given, coldsync runs Install conduits on any
          files in the install directory ( ~/.palm/install by default), then
          uploads to the Palm any files still in the install directory after
          the Install conduits have run.
     6.   coldsync runs the Fetch conduits, to create the desktop copies of
          the databases.
     7.   The main sync: coldsync runs the Sync conduits for all databases on
          the Palm. By default, coldsync only runs the [generic] conduit,
          which synchronizes the database on the Palm with a backup file on
          the workstation. This can be overridden, however.
     8.   If the -z option was given, coldsync runs Install conduits on any
          files in the install directory as mentioned in step 5, then installs
          any databases left in the install directory.
     9.   The main sync ends. The Palm displays the message “HotSync
          complete.” You may remove the Palm from its cradle.
     10.  coldsync runs the Dump conduits. These can export the updated
          databases to other formats.

     When possible, ColdSync (specifically, the [generic] Sync conduit) tries
     to be smart about how it syncs databases, and only transfers those
     records that have changed since the last sync. At the same time, it tries
     to be cautious, and never deletes anything that it isn’t sure should be
     deleted. For instance, if a record has changed both on the Palm and on
     the desktop, ColdSync will create two records, one with each version of
     the record, rather than risk deleting the wrong record.

     By itself, ColdSync is simply a fancy backup program. Conduits make it
     more useful. A conduit is simply a program that follows a certain
     protocol to read or write Palm database files.

     For instance, if you have a TODO file that you want to keep in sync with
     the Palm “ToDo” application, you could use a pair of conduits to do so: a
     Fetch conduit to convert your TODO file to a Palm database, and a Dump
     conduit to convert the newly-synchronized database back to a text file.
     If you’ll look back at the sequence of events, above, you’ll see how this
     works.

     Currently, the only conduit flavors are “Install”, “Fetch”, “Dump”, and
     “Sync”.  Others may be added in the future.

CONFIGURATION FILE

     ColdSync reads its configuration from the file .coldsyncrc in the user’s
     home directory, or from the file specified with the -f command-line
     argument.

     The .coldsyncrc file contains listen, pda, options, and conduit
     directives.

   listen
     listen directives are of the following forms:

           listen serial {
                   device: /dev/palm;
                   protocol: default;
                   speed: 57600;
                   transient;
           }

           listen usb {                    # BSD only
                   device: /dev/ugen0;
           }

           listen net {
           }

           listen serial {
                   device: stdin;
                   nochangespeed;
           }

     listen serial is used for serial Palms, infrared syncing, and for
     Handspring Visors under Linux.

     The device directive specifies the device to use; if omitted, it defaults
     to /dev/palm.  The speed directive specifies the speed at which to sync,
     in bytes per second.  If omitted or set to 0, the speed defaults to the
     speed suggested by the Palm, or the fastest speed supported by the serial
     port, whichever is slower.

     The transient directive indicates that the device may not exist when
     ColdSync starts, but will be created later on, when the Palm connects to
     the workstation. Use this if you are using devfs.

     The nochangespeed directive indicates that the device is a modem, so
     ColdSync will not attempt to change the line speed and break the
     connection.

     listen usb is used to sync a Handspring Visor using native USB mode. This
     only works under *BSD.

     The device directive specifies the device to use. If omitted, it defaults
     to /dev/palm.

     listen net is used to listen for an incoming network HotSync connection.

     The protocol directive specifies the protocol stack to use over this
     connection.  Think of it this way: the listen line specifies whether
     you’re using a regular phone, a cell phone, or two tin cans and a string.
     The protocol option specifies which language you’ll be speaking.

     Legal values are default, full, simple, and net.  If omitted, the
     protocol option defaults to default.  Most of the time, default does the
     right thing. The main exception is for Palm m50x-es with USB cradles.
     Under Linux, use:

           listen serial {
                   protocol: simple;
           }
     Under {Free,Net}BSD, use

           listen usb {
                   protocol: full;
           }

     Currently, a configuration file should contain only one listen block. If
     more than one listen block is specified, only the first one will be used.

     If a device was specified on the command line with the -p option,
     ColdSync ignores the one specified in the configuration file. If no
     device was specified either on the command line or in the configuration
     file, ColdSync defaults to /dev/palm.

   pda
     pda directives are of the form

           pda "My Palm" {
                   snum: 10BX13C22K98-M;
                   directory: /folks/arensb/.palmIII;
                   username: "Gorko the Invincible";
                   userid: 1234;
                   default;
           }
     All of these lines are optional. You may also use palm as a synonym for
     pda.

     The PDA’s name, “My Palm” in this example, is currently unused and may be
     omitted.

     The snum line gives the Palm’s serial number. You can get this number by
     selecting “Info” from the Palm’s application launcher. In the above
     example, 10BX13C22K98 is the serial number, and the M after the dash is
     the checksum. If you omit the checksum, ColdSync will calculate it for
     you and suggest that you add it to your .coldsyncrc.

     You may also use the special value *Visor* to represent the (binary)
     string that all Handspring Visors return as their serial number. Since
     all Visors return the same “serial number”, it is not possible to
     differentiate between Visors this way, but it is possible to distinguish
     a Visor from other Palms.

     The directory line specifies the root of the tree where ColdSync will put
     its files. If this line is omitted, the directory defaults to ~/.palm.

     The username and userid entries allow you to specify the full name and
     user ID associated with this Palm. This can be useful if you have
     licensed applications whose license key depends on the user name. If the
     userid is omitted, it defaults to the UID under which ColdSync is run. If
     username is omitted, it defaults to the full name of the user running
     ColdSync, as returned by getpwuid().

     The default flag indicates that this a default PDA block. It will be used
     if no better match is found. Thus, if you specify

           pda {
                   directory: /folks/arensb/.palm-generic;
                   default;
           }

           pda {
                   snum: 10BX13C22K99;
                   directory: /folks/arensb/.palm-III;
           }

           pda {
                   snum: 0123456789AB;
           }
     ColdSync will use the directory /folks/arensb/.palm-III to sync the Palm
     with serial number 10BX13C22K99. It will use the directory
     /folks/arensb/.palm to sync the Palm with serial number 0123456789AB (the
     directory defaults to ~/.palm ). For any other Palm devices, ColdSync
     will use the directory /folks/arensb/.palm-generic.

     If you specify the serial number as the empty string,

                   snum: "";
     this refers to Palm devices without a serial number, e.g. the PalmPilot.
     Unfortunately, if you have several such devices, it is not possible to
     keep their contents separate through pda directives.

     You may specify both a serial number and the default flag. Since the
     serial number uniquely identifies a Palm, this is not terribly useful
     unless you specify the empty string as the serial number; this allows you
     to have one default for pre-3.0 Palms, and another default for all
     others.

   conduit
     conduit directives control the behavior of a conduit. The documentation
     for a conduit should specify the values to use here.

     conduit directives are of the form

           conduit <flavor-list> {
                   path: /path/to/conduit;
                   type: <creator>/<type>;
                   preference: <pref-creator>/<pref-id>;
                   <flags>;
               arguments:
                   <conduit-specific arguments>
           }
     where <flavor-list> is a comma-separated list of conduit flavors.
     Allowable conduit flavors are install, fetch, dump, and sync ( pre-fetch
     and post-dump are synonyms for fetch and dump, respectively);
     /path/to/conduit is the pathname of the conduit; <creator> is the
     database creator; <type> is the database type.  For instance:

           conduit fetch {
                   path: /usr/local/libexec/coldsync/addressbook-fetch;
                   type: addr/DATA;
           }
     The database creator and type should be specified in the documentation
     for each conduit. You may also use either the empty string ( "" ) or an
     asterisk ( * ) for the type or creator, to indicate a wildcard:
           type: addr/*;
     makes the conduit apply to all databases with creator addr,
           type: */DATA;
     makes the conduit apply to all databases with type DATA, and
           type: */*;
     makes the conduit apply to all databases. Only the last of these is
     generally useful.

     You may specify several type lines, e.g.,

           conduit fetch {
                   path: /usr/local/libexec/coldsync/very-generic;
                   type: addr/DATA;
                   type: memo/DATA;
                   type: graf/macr;
           }
     This conduit will match any of the three creator/type pairs.

     preference directives specify which preferences the conduit is interested
     in.  pref is a synonym for preference.

     Preferences are bits of configuration data stored in a pair of shared
     databases on the Palm. They include pretty much everything you can set
     through the “Prefs” application, but also things such as your signature
     from the “Mail” application.

     Preferences are stored in two databases: “Saved Preferences” and “Unsaved
     Preferences”.  If you know (and care) in which database a given
     preference is defined, you can specify it with the saved and unsaved
     keywords:

                   pref: saved mail/3;
                   pref: unsaved exps/1;

     If neither saved nor unsaved is specified, ColdSync will try them both.

     The following flags are defined for conduit blocks: default and final.

     The default flag indicates that this is a default conduit, and should be
     run only if no other matching conduit is specified later on. The default
     flag works in conjunction with the type specification:

           conduit dump {
                   path: /usr/bin/default-todo;
                   type: todo/*;
                   default;
           }
     only applies to databases with creator todo.  If two or more default
     conduits apply to a database, only the last one specified will be run.

     The final flag indicates that ColdSync should not consider any other
     conduits after this one. It works in conjunction with the type
     specification:

           conduit fetch {
                   path: /usr/bin/fetch-mail;
                   type: mail/DATA;
                   final;
           }

           conduit fetch {
                   path: /usr/bin/generic-fetch;
                   type: */*;
           }
     In this example, only /usr/bin/fetch-mail will be run for databases with
     creator mail and type DATA, even though the second conduit block also
     applies.

     A conduit block may also contain conduit-specific arguments, e.g.,

           conduit dump {
                   path: /usr/bin/send-mail
                   type: mail/DATA;
               arguments:
                   Sendmail: /usr/sbin/sendmail;
                   Signature: /home/arensb/.palm-signature;
                   DSN: return-receipt;
           }
     All of the lines following the arguments: line are passed to the conduit,
     and may be used to modify its behavior. These arguments are conduit-
     dependent, and thus will be described in the documentation for each
     conduit.

   Built-In Conduit
     Instead of a pathname to a program or script, you may also specify the
     string [generic] (with the brackets) to specify that you want to use the
     built-in generic conduit:

           conduit sync {
                   type: */*;
                   path: [generic];
                   default;
           }

     The generic conduit is a Sync conduit. By default, it handles every
     database unless that database has another Sync conduit specified. If you
     wish to run another Sync conduit on a database, you will need to specify
     explicitly in your .coldsyncrc whether you want it to run before or after
     the generic conduit, or whether the generic conduit should be run at all.

   options
     options directives are of the form

           option {
                   install_first:  true;
                   force_install:  no;
                   hostid: 0x1234abcd;

                   CS_CONDUIT_PATH: "$(CS_CONDUITDIR):$(HOME)/.palm/conduits";
                   key:  "this is the value";
           }
     The first two options are boolean; their values can be specified as
     “True”, “False”, “Yes”, or “No”

     install_first specifies whether new databases should be installed before
     the main sync. It defaults to “True”.  “install_first: false” is
     equivalent to specifying -z on the command line, except that the command
     line takes precedence over the configuration file.

     force_install specifies whether new databases should be installed even if
     they have the same modification number as the copy on the Palm. This
     defaults to “False”.  “force_install: true” is equivalent to specifying
     -I on the command line, except that the command line takes precedence
     over the configuration file.

     The hostid directive sets this host’s ID, for purposes of syncing. The
     host ID is a 32-bit integer, and may be specified in decimal
     (3232264158), octal (030052067736), or hexadecimal format (0xc0a86fde),
     using C-like syntax. If this directive is omitted, the host ID defaults
     to the host’s IPv4 address.

     All other options behave like shell variables, in that you may use them
     later on in the configuration file. In fact, if you do not set an option
     before you use it, coldsync will try to use your environment variables to
     set it. Options may only be used inside quoted strings.

     Two useful options are $(CS_CONDUITDIR) and $(CS_CONDUIT_PATH).
     $(CS_CONDUITDIR) is the system-wide conduit directory. It defaults to the
     directory to which the standard conduits were installed when ColdSync was
     installed.

     $(CS_CONDUIT_PATH) is a colon-separated path in which coldsync will look
     for conduits. If any element is empty, it will look in “the usual
     places”, which currently defaults to $(CS_CONDUITDIR).  Thus, if you set
     $(CS_CONDUIT_PATH) to /foo::/bar, coldsync will look for conduits in
     /foo, then in $(CS_CONDUITDIR), and finally in /bar.  If you set it it to
     /foo: then the last component is empty, so coldsync will first look in
     /foo, and then in “the usual places”.

   Quoting
     Values on the right side of a colon may be enclosed in double quotes.
     That is you can write either

                   path: /usr/bin/myconduit;
     or

                   path: "/usr/bin/myconduit";
     It is always safe to quote a value. The quotes may be omitted if the
     value does not contain whitespace or punctuation that might confuse the
     parser.

     If a string is enclosed in double quotes, it may contain standard escape
     characters, or option substitution, such as $(CS_CONDUITDIR). Options are
     set in the options section mentioned above.

     PDA names may also be quoted, subject to the same rules. That is, you may
     say

                   pda MyPalm {
     or

                   pda "My Palm" {
     but not

                   pda My Palm {

     Note: if you choose to quote the right-hand side of a type statement, you
     must quote both the creator and the type. That is, you may write

                   type: addr/DATA;
     or

                   type: "addr"/"DATA";
     but not

                   type: "addr/DATA";

THE PALMS FILE

     /usr/local/etc/coldsync/palms lists known Palms and their associated
     users. Each entry is on a single line, with fields separated by vertical
     bar (pipe) characters:

                   serial|username|userid|luser|name|conf_fname

           serial    The serial number of the Palm. The empty string or ’*’
                     will match any palm.

           username  The username on the Palm. The empty string or ’*’ will
                     match any palm.

           userid    The user ID on the Palm. The number ’0’ will match any
                     palm.

           luser     The local (Unix) username or UID to setuid() to.

           name      The Palm’s name in .coldsyncrc.

           conf_fname
                     Full pathname of a configuration file to use.

     name and conf_fname are optional, and may be omitted.

     Note, however, that the format of this is still in development, and may
     change in the future.

WARNINGS

   The Bargle Bug
     While you can choose any user ID you like for the Palm, you should avoid
     using 0 (this also means that you should avoid running ColdSync as root):
     if you do, you risk being bitten by the Bargle Bug.

     If you perform a hard reset of your Palm, or upgrade to a new one, you
     can lose all of your backup data: ColdSync doesn’t notice and assumes
     that you’ve chosen to delete everything on your Palm.

     To guard against this woeful fate, ColdSync requires the Palm to be
     initialized with a user name and userid.

   Upgrades
     Every so often, Palm announces a PalmOS upgrade. Some of these upgrades
     are simple and consist of a .prc file that you need to upload. It’s
     probably safe to apply this upgrade by copying the .prc file to
     ~/.palm/install and syncing.

     Other upgrades are more complex, and ColdSync can’t handle them. For
     these, you’ll need to follow Palm’s instructions.

FILES

     ~/.coldsyncrc    user’s configuration file.
     /usr/local/etc/coldsync/coldsync.conf
                      site-wide configuration file.
     /usr/local/etc/coldsync/palms
                      list of known Palms
     ~/.palm          The default root of the backup tree ( palmdir, below).
     palmdir/backup   contains backup files for the Palm.
     palmdir/backup/Attic
                      contains databases that have been deleted from the Palm.
     palmdir/archive  contains records deleted from the Palm, but with the
                      "Save archive on PC" box checked.
     palmdir/install  contains files to be installed at the next sync.

SEE ALSO

     pilot-xfer(1)

     Palm Database Files.

     ColdSync Conduits.

     http://usbvisor.sourceforge.net/Handspring-Visor-mini-HOWTO.  Explains
     how to sync a Handspring Visor under Linux.

AUTHORS

     Andrew Arensburger 〈arensb@ooblick.com〉
     Louis A. Mamakos 〈louie@TranSys.COM〉: USB support.
     And a cast of many.

DIAGNOSTICS

     Many and hopefully self-explanatory.

LIMITATIONS

     ColdSync does not detect the serial number on Handspring Visors (and some
     Palm PDAs). This is because the Visor does not appear to have a software-
     readable serial number. The pda block for a Visor should contain

                   snum: "*Visor*";

     Under Linux, ColdSync often spits out copious amounts of "Bad CRC"
     messages. This is due to Linux’s flaky serial driver.

     ColdSync does not deal with categories. This is due to the way the
     AppInfo block (which contains the categories) is implemented. However,
     conduits can deal with categories.

BUGS

     In the .coldsyncrc file, file and directory names must be specified as
     absolute pathnames.

     ColdSync does not sync .prc files. It makes a backup if there is isn’t
     one already, but that’s it.  If you upgrade from version 1.0 of an
     application to version 2.0, ColdSync will not back up the new version. In
     addition, most of the preferences in the Prefs application are saved in
     .prc files, so ColdSync does not maintain backups of them.

     There is as yet no tool for manipulating archive files.

     All network addresses are assumed to be IPv4 addresses.

     It appears that syncing with a machine other than that with which you
     normally sync might cause a database to lose its category information.

     Under FreeBSD, if you have both a Visor and another device plugged into
     the USB port, ColdSync might not be able to find the Visor correctly.

     If a conduit block contains several pref: lines, it will only be given
     one preference.

     Probably many others.