-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 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.

-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.

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 .

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, 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 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 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.

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: makes the conduit apply to all databases with creator addr , makes the conduit apply to all databases with type DATA , and 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 application, but also things such as your signature from the application.

Preferences are stored in two databases: and 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.

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.

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 or

install_first specifies whether new databases should be installed before the main sync. It defaults to 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 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 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

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";

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.

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.