README.modem

	Some notes on running ColdSync with a dialup modem

$Id$

INTRODUCTION:
=============

	If you're trying to run data collection or remote synchronisation 
for users with modems, you should first read README.daemon here and
make sure everything is working correctly with a local cradle (saves
a lot on phone calls), then read on.

	Coldsync doesn't talk directly to a modem, however it will talk to
stdin and stdout, so a tool like mgetty can be used to handle the modem.
This deals with the complexity of modem handling.


MGETTY CONFIGURATION:
=====================

I'll be assuming that you're using mgetty for nothing else.  If you want
to add fax support, remove the 'data-only' flag from the configuration
and go read how to set up faxing with mgetty.

I'm using ttyS1 under Linux for the serial port.  I assume changing the
serial port name will be sufficient for other unices, but let me know
if it doesn't (Bron Gondwana <brong@brong.net>).  File locations are as
on Debian (/etc/mgetty) - your documentation should tell you where to
find them.  I use mgetty+sendfax 1.1.27-Oct21 from Debian woody.

IMPORTANT - make sure you get the 'no-ask-login' bit right, as the palm
doesn't send 'login' packets.

-----------------------------
/etc/mgetty/mgetty.conf:
# don't ask for login
no-ask-login y

# SET THIS TO YOUR MODEM'S SERIAL PORT
port ttyS1
	data-only y
-----------------------------

You only need one line in login.conf, which will launch the shell script
owned by the palm user.  This allows you to alter the command line options
as the palm user
-----------------------------
/etc/mgetty/login.conf:
*       palmuser    -       /home/palmuser/bin/coldsync_modem.sh
-----------------------------

And of course a line in /etc/inittab, this may also be different for
different operating systems.

-----------------------------
/etc/inittab
T1:23:respawn:/sbin/mgetty ttyS1
-----------------------------


PALM USER HOME DIRECTORY:
=========================

I run with coldsync installed with a --prefix of /home/palmuser and
installed purely as the palm user with no mention of root anywhere
along the way.  You can also do this.

-----------------------------
/home/palmuser/bin/coldsync_modem.sh:
#!/bin/sh

/home/palmuser/bin/coldsync -md -f /home/palmuser/etc/modem.conf
-----------------------------

The modem.conf file needs to have the 'modem' keyword in a listen
block.  I do all the palm configuration through an /etc/palms with
custom config files.

-----------------------------
/home/palmuser/etc/modem.conf:
listen serial "mgetty" {
    device: stdin;
    nochangespeed;
}
-----------------------------

And the palms file (/etc/palms, /usr/local/etc/palms, 
/home/palmuser/etc/palms - you will know where it's been installed
- I hope).  You put one entry here per palm, with a separate directory.

-----------------------------
/home/palmuser/etc/palms:
*Visor*|brong|1234|palm|brong|/home/palm/etc/brong.userconf
*Visor*|example|4321|palm|example|/home/palm/etc/example.userconf
...
-----------------------------


PER USER CONFIG FILES:
======================

In my case I'm running two specific conduits and nothing else, because
these palms, so I'll give the example config for that.  These are all
autogenerated from a specification file giving the palm usernames
associated with each project (as is the palms file above).

-----------------------------
/home/palmuser/etc/example.userconf:
pda "example" {
    directory: /home/palm/lib/palms/example;
    username: example;
    userid: 4321;
    default;
}

conduit dump {
    path: /home/palm/bin/aaaa-conduit.pl;
    type: AAAA/DATA;
}

conduit dump {
    path: /home/palm/bin/bbbb-conduit.pl;
    type: BBBB/DATA;
}

conduit sync {
    type: AAAA/DATA;
    type: BBBB/DATA;
    path: [generic];
}

conduit sync {
    type: */*;
    default;
}

conduit dump {
    type: */*;
    default;
}

conduit fetch {
    type: */*;
    default;
}
-----------------------------


CONCLUSION:
===========

Coldsync combined with mgetty, custom built conduits and palm software is
a very powerful data collection tool.