# $Id: README,v 1.31 2002/03/24 17:48:34 nemies Exp $
Sendpage (in Perl)

What this tool does
-------------------
Sendpage is designed to speak SNPP on one end and TAP (or UCP) on the
other.  It gets pages from the network via SNPP, and then uses a modem
or a direct serial connection to deliver the pages to a Paging Central
(or "paging terminal").  Sendpage requires, for modem use, that you know
your PC's access number (which is not usually advertised by your paging
provider), and you need to know the PINs of the pagers you want to deliver
pages to.  All of this information is known by your paging provider.
If you ARE a paging provider, your job is much easier.  ;)


Quick Start (for Linux)
-----------

   Requirements.

	- Net::SNPP (part of the libnet Perl module bundle)
	- Device::SerialPort version 0.12+  (or Win32::SerialPort, untested)
	- Mail::MailTools

   Installation.

	- run the following commands:

		perl Makefile.PL
		make
		make install

	- copy 'sendpage.cf' into /etc, and edit to your needs
	- copy 'email2page.conf' into /etc, and edit to your needs
	- copy 'snpp.conf' into /etc, and edit to your needs
	- if you use SysV-style init scripts, you can use "sendpage.init"
	  to start and stop sendpage.  Copy it to where you keep your rc
	  files.
	- create the user "sendpage"
	- figure out which group ID can write to your locks directory
	  (usually "uucp" can write in "/var/lock")
	- figure out which group ID can write to your modem device
	  (usually "tty" can write to "/dev/ttyS0")
	- make the queue area:

		mkdir -p /var/spool/sendpage
		chown sendpage /var/spool/sendpage
		chmod og-rwx /var/spool/sendpage

	- start the sendpage daemon as the root user (it will change
	  user id to 'sendpage'):

		sendpage -bd

	- go check your /var/log/messages for the syslog line saying
	  that sendpage started up:

		starting Queue Manager and SNPP listener (sendpage vX.X.X)

	- you can also use the "sendpage.init" file for SysV-style init
	  script control.	
	- make sure you have an entry in /etc/services for "snpp", which
	  should be port 444.

   Sending a page.

	- run the "snpp" command to send yourself a test page:

		snpp -d -f me@yourdomain.org -m 'hi there!' yourPIN@yourPC

	- if you want to write pages directly to the paging queue instead of
	  using SNPP, you can use "sendpage" itself, but you must be root:

		sendpage -f me@place.org -m 'hello again!' yourPIN@yourPC

	  the sendpage daemon must be running for this to actually be delivered.

	

Long Version
------------

Sendpage will be a fully-featured paging solution when it's done.
Right now, I'm interested in testing the new SNPP server.

Sendpage (the C program) was originally written in 1995 almost entirely
by Mark Fullmer.  Version "7" was when I became aware of it picked up
the code, since Mark didn't want to maintain it any more.  I developed
a "configure" script to make compiling easier, started working on merging
some features that other people had written, and stomping out a few bugs.
I released a series called "0.8", which still had a bunch of problems,
but seemed to mostly work for most people.  I haven't looked at the C
code in about a year, and it was getting rather dusty.  I was about to
work on porting it up to RedHat 6.1 and realized it would be easier to
redesign it from scratch.  I decided to use Perl because of all the great
modules I could use to help me get my job done.  And then I could spread
the blame around when things didn't work right.  ;)

And at this point I'd like to apologize here for my sloppy Perl modules.
I'm new to writing *modules* under Perl, so I fear that I'm violating
module and CPAN specs left and right.  I will try to correct any of these
problems as I learn about them.  My final goal is to produce a set of
modules that would be useful to any other packages that need to send
pages directly, and could be installed via CPAN. 

To get it started you'll need the following Perl modules installed:

	- a serial port module.  Either
		Device::SerialPort (for POSIX (unix))
			-or-
		Win32::SerialPort (for Windoze)
	- Mail::MailTools

You can get these from http://cpan.perl.org/

And please check this out for POSIX people (lifted from the Device::SerialPort
docs):

	There are a small number of ioctl calls to handle the RTS and DTR
	outputs. Those require (from more or less traditional locations) the
	outputs from "h2ph" for ioctl.h and related files. If the module does
	not find the prerequisites, it disables the method calls that require
	them and sets "can_ioctl" false.
        	.../_h2ph_pre.ph        .../asm/termios.ph
        	.../asm/termbits.ph     .../asm/posix_types.ph
        	.../asm/ioctls.ph       .../asm/ioctl.ph
        	.../linux/posix_types.ph

This is important for hanging up the modem, etc.  POSIX users running
on Solaris, AIX, BSD or HPUX probably won't get version 0.07 working.  I
made a patch for Device::SerialPort, getting it to version 0.09, which can
be found at http://sendpage.cpoint.net/device-serialport/   Please use this
version instead of 0.07, and you shouldn't have any problems with your
modem.

If you choose to do the "make test", Solaris for me failed in a number
of places.  My output was:

Failed Test  Status Wstat Total Fail  Failed  List of failed
-------------------------------------------------------------------------------
t/test1.t                   173    8   4.62%  118, 121, 133, 141-142, 152-154
t/test3.t                   159    2   1.26%  107, 110

Half of the errors are with "pulse" commands taking too long.  The other
bugs are more serious, but shouldn't impact sendpage at all.  For now, you
can safely ignore those errors.  See the notes on compatibility below to
eliminate the timing errors under Solaris.

Now, build sendpage itself.  Right now, just do:
	cd sendpage-X.X.X
	perl Makefile.PL
	make
	make install

to install this package.  The important man page (sendpage's) is done.
The others are mostly just overviews.  I need to finish those.  If you
want to put the files somewhere besides where Perl wants to put them,
you can always create the Makefile is "perl Makefile.PL PREFIX=/usr/local"
or where ever you want the files to be forced to go.

Make sure you create a sendpage user, and identify the group who has
write access to /var/lock, and the group who has write access to your
modem device.

Once that's working, take a look at "sendpage.cf", and configure it for
your modem, paging central, etc.  Turn on the debugging if you're interested.
I'm going to eventually write a tool to convert old-style config files (and
perhaps even qpage and beepage config files) into the new-style config file.
Right now, this is not done.  Note that "sendpage.cf" needs to live in
/etc, or where ever you run "sendpage -C" with.  Please note, that you can
safely ignore any "Attempt to free unreferenced scalar." messages you get
while shutting down sendpage if you have debugging turned on.  This is just
Perl complaining about the paging centrals for some reason.

Also install and edit the "email2page.conf" file for the email-to-page
converting tool.  Documentation is in the conf file for that one right now.

And install and edit the "snpp.conf" file for the snpp's default
server.  Documentation is in the conf file for that one right now.

Now there is the "sendpage" daemon itself.  Run (as root) the command:
	sendpage -bd
to start up the daemon mode.  (Make sure that "sendpage" is in the PATH
for the root user.)  The SNPP server connections and Paging Centrals will
lose root privs when the fork, so that should be safe.  "sendpage -bs" will
stop sendpage.  The file "sendpage.init" has been included to run at as a
SysV-style init script, which takes "start" and "stop" arguments.  This
script assumes that sendpage is installed in /usr/local/bin, so be sure to
change it if you need to.

To put a page into the queue, run "snpp RECIP" where RECIP is either a 
valid alias "recip" section in /etc/sendpage.cf, or has the form PIN@PC,
where the PC is a valid "pc" section in /etc/sendpage.cf.  It will deliver
directly to the named PIN.  "snpp" will read from STDIN for the message,
unless you use the '-m' flag.  To use "snpp" from other networked machines,
you'll need to edit sendpage.cf to bind snpp to "0.0.0.0" or some other
network interface, and then use "snpp -s SERVER" from the remote client.
Be sure to read and set at least one "snpp-acl" line so that your remote
machine will have permission to connect to the SNPP server.

To force a queue run immediately, run (as root) "sendpage -q".  If you have
debugging turned on, it should be flooding your syslog with lots of fun
information while delivering the pages.

Look in the "docs" directory for various misc information files, including
the TAP specifications, the SNPP RFC, and a list of the known paging centrals
in the file "PagingCentrals.txt".  See if the PCs for your area are listed. 
If not, and you locate them, you should email them to me, and I'll update this
list.  There is also a searchable database of these available at the website
below.  For an example of how to set up sendpage as an email gateway, read
"sendmail.txt".  For an example of how to make a web page to send pages,
look at the "sendpage.php" PHP script.  Also in this directory is the
beginnings of my official "Sendpage Manual" in LyX format.

Logging
-------

By default, sendpage uses syslog facility "local6" to do it's reporting.
For debugging messages, it uses level "debug".  For general logging, it
uses the "info" level.  For myself, I wanted to keep my sendpage syslogs
out of my general syslog file ("/var/log/messages"), so my /etc/syslog.conf
looks like this:

*.info;mail.none;news.none;authpriv.none;local6.none  /var/log/messages 

local6.*                                              /var/log/sendpage
local6.=debug                                         /var/log/sendpage.debug
local6.info                                           /var/log/sendpage.info 

This way "messages" doesn't get anything from "local6" (sendpage), and I  
can watch the sendpage output in three ways: either everything going to  
local6 ("/var/log/sendpage"), JUST the stuff *at* the "debug" level
("/var/log/sendpage.debug"), or everything "info" and higher
("/var/log/sendpage.info").


Compatibility
-------------

Linux:	  This tool (and Device::SerialPort) was written and tested under
	  Linux.  There really shouldn't be any compatibility issues under
	  Linux.

Solaris:  Some headers under Solaris don't behave very well, so I had
	  to define "__sparc" explicitly in my patch to Device::SerialPort.
	  Also, under Solaris, many of the "make test" tests for
	  Device::SerialPort seem to hang and/or fail.  Most of these
	  seem safe to ignore as far as using sendpage with Device::SerialPort,
	  as the test failures seem to be with timings and/or flushes.
	  Most of that is unreliable anyway under Linux, so sendpage has
	  already worked around these bugs.

	  From the following URL:
	  http://www.stokely.com/unix.serial.port.resources/tutorials.html

		DTR Delay Problems: By default, Suns have a three second
		delay in toggling dtr. If your Sun has a zs serial port you
		can set the variable default_dtrlow to control the number of
		seconds of the delay. If the variable is set to zero, dtr
		can be toggled many times a second. For example, in
		/etc/system add the line "set zs:default_dtrlow=1" to have
		a 1 second delay.  

		If your workstation has an se serial port, the /etc/system
		line should be "set se:se_default_dtrlow = 1". However, in
		initial versions of the se driver, the delay was the value
		of (se_default_dtrlow + 1) seconds. If you have this version
		of the se driver, don't set the value to -1 in /etc/system or
		the port will hang on open. If you need to toggle dtr quickly,
		you can still set the value to -1 after the terminal is
		opened by using adb to set the variable manually.

		All this is Sun bugid 4230310, fixed by patch 105924-09 or
		higher. The patch makes se_default_dtrlow behave like
		default_dtrlow (i.e. setting se_default_dtrlow to 0 will allow
		rapid toggling of dtr instead of once per second). 

	  So, since I have zs serial ports on my Sun, I added the line:

		set zs:default_dtrlow=0

	  so I could toggle the DTR rapidly.

	  Also, I've seen trouble using Syslog correctly under Solaris.
	  Once again, this appears to be Perl's fault.  If it breaks
	  ("Your vendor has not defined the Sys::Syslog macro _PATH_LOG")
	  then just edit KeesLog.pm and remove the calls to "setlogsock".

AIX:	  Tested with 4.3.2, and works fine, some modem lines don't work.

*BSD:     Tested.  Carrier detection works after Sendpage 0.9.13.

HPUX:	  Untested so far...

SCO7:     Install notes from Pat Gunn:

          Removed system perl first (MUST happen before installing skunkperl
          or perl will become messed up)

          Then installed skunkperl from skunkware
          (stage.caldera.com/uw7/Packages/)
        
          In /usr/local/lib/perl5/site_perl/5.005/i386-svr4/_h2ph_pre.ph,
          comment out the line:
                 unless (defined &) { sub () { "" } }

          In /usr/local/lib/perl5/site_perl/5.005/i386-svr4/sys/types.ph,
          comment out the following lines:
                if( &model((defined(&lp64) ? &lp64 : 0))) {
                   unless(defined(&_INT64_T)) {
                       eval 'sub _INT64_T () {1;}' unless defined(&_INT64_T);
                   }
                   unless(defined(&_UINT64_T)) {
                       eval 'sub _UINT64_T () {1;}' unless defined(&_UINT64_T);
                   }
                   unless(defined(&_SIZE32_T)) {
                       eval 'sub _SIZE32_T () {1;}' unless defined(&_SIZE32_T);
                   }
                } else {
                   unless(defined(&_INT64_T)) {
                       eval 'sub _INT64_T () {1;}' unless defined(&_INT64_T);
                   }
                   unless(defined(&_UINT64_T)) {
                       eval 'sub _UINT64_T () {1;}' unless defined(&_UINT64_T);
                   }
                }

          Used CPAN module to upgrade prerequisites (didn't allow it to
          rebuild Perl itself. I have GCC and other gnu tools installed)

          Installed Device::Serialport (after these mods, it might work through
          CPAN, but you're better off doing it by hand so you can troubleshoot
          problems more easily)

          Installed sendpage.

          Created sendpage user, created /var/lock, set its group to uucp and
          changed its mode to 775, created sendpage spool directory, configured
          sendpage.conf and snpp.conf. Note that syslog does not appear to work
          with sendpage's logging component, so it's probably better to log to
          stderr. Change snpp.conf accordingly. It might be possible to fix
          this with some tinkering, but I'm not interested enough to take the
          time.

          The modem device on my system (serial port A) is /dev/term/00m,
          although I made a symlink to there from /dev/modem, and put
          /dev/modem in the configfile.


Porting Device::SerialPort
--------------------------
If you're trying to get Device::SerialPort to work on an untested platform,
please take a look at the top of the "SerialPort.pm" file, and examine the
paths where "termios.ph" is searched for.  Basically, SerialPort.pm needs
the following constants from a .ph file to operate correctly:

Must have these:
	TIOCM_RTS
	TIOCM_DTR
	TIOCMBIS
	TIOCMBIC
	TIOCMGET

Optional: I have only found these on OpenBSD (and are required for OpenBSD):
	TIOCSDTR
	TIOCCDTR

Optional: I have only found *both* of these under Linux:
	TIOCINQ
	TIOCOUTQ

Optional: I have only found this one under Linux:
	TIOCSERGETLSR

Once you get SerialPort.pm running happily (you can set $DEBUG=1 near the
top), try modifying (from the sendpage package) the script "modemtest"
to use your serial port with a modem attached.  This script will try to
examine all the possible settings for your vendor's serial port, and
will try to talk to the modem using Device::SerialPort.  If you can
get this script talking to the modem, sendpage should operate just fine.


Misc
----

The TODO file lists a large number of things I still want to have
working before the first "stable" release.

For further information, check out the sendpage web site at:
	http://sendpage.cpoint.net/

For CVS updates, check out the sourceforge project at:
	http://sourceforge.net/projects/sendpage



Thanks for using sendpage!


-Kees Cook
cook@cpoint.net

