coldsync(8)

NAME

coldsync - synchronize files between a Palm and a worksta
tion.

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 de
vice and a workstation (see OVERVIEW, below). By default, it per
forms 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 infor; mation 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, be
low).
-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 upload
ed. If the argument is a directory, then all files in that direc
tory 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 as
sumed 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 DEVELOP
MENT 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 priv; ileges 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. Normal
ly, coldsync does not install databases if doing so would over
write 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 de; fault, full, and simple. (See the description of the protocol; option, below.)
-s Log errors and warnings through syslog(3). Mes
sages 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 ei; ther of the form facility or facility:level. This sets the de; bugging 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'' mes
sages, 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 in
stall 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 [gener
ic] 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 con
duits 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 any
thing 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. Con
duits 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-syn
chronized 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 con
duit 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 omit
ted, 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 omit
ted, 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 omit
ted, 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 lis
ten 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 num
ber, 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

tory 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 use
ful 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 de
faults 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-gener
ic; 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 every
thing 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 Prefer
ences'' 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 argu
ments 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 han
dles 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_CONDUIT
DIR):$(HOME)/.palm/conduits"; key: "this is the value";
}
The first two options are boolean; their values can be spec
ified as ``True'', ``False'', ``Yes'', or ``No''
install_first specifies whether new databases should be in
stalled before the main sync. It defaults to ``True''. ``in
stall_first: false'' is equivalent to specifying -z on the com
mand line, except that the command line takes precedence over the
configuration file.
force_install specifies whether new databases should be in
stalled 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_CON
DUIT_PATH). $(CS_CONDUITDIR) is the system-wide conduit directo
ry. 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''.
QuotingValues on the right side of a colon may be enclosed in dou
ble 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 omit; ted 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 men
tioned 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 develop
ment, 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 run
ning 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 copy
ing 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.

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 Vi
sors (and some Palm PDAs). This is because the Visor does not ap
pear 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 imple
mented. 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 cate
gory 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 on
ly be given one preference.
Probably many others.
BSD July 12, 1999

docs.sk

comprehensive documentation repository

See also

coldsync(8)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

OVERVIEW

CONFIGURATION FILE

ColdSync

THE PALMS FILE

WARNINGS

FILES

SEE ALSO

AUTHORS

DIAGNOSTICS

LIMITATIONS

BUGS