COLDSYNC(8)

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 “N??o”

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.