QuickPage(1)

NAME
QuickPage - SNPP client/server for sending messages to an alpha-numeric pager

SYNOPSIS
qpage [ -dhimQv ] [ -a [+][dd+]hhmm | -a YYMMDDHHMMSS ] [ -c coverage ] [ -C config ] [ -f from ] [ -l level ] [ -p pagerid ] [ -P pagerid ] [ -s server ] [ message ]

qpage [ -d ] -q interval

DESCRIPTION
QuickPage sends messages to a paging terminal using the SNPP and IXO (also known as TAP) protocols. It is normally used with no options other than a recipient and the message text, in which case the message is sent to the SNPP server where it is submitted to a page queue to be sent by a separate daemon process. Page groups and duty schedules are supported. Status notification messages indicating the success or failure of a page are sent via e-mail to submitters of high-priority (level 0) pages.

If no message is specified on the command line, the user is prompted for the message text. Characters are read from standard input until a line containing only a period is received. All occurrences of whitespace within the message text are reduced to a single space character.

Messages received by the QuickPage daemon that are longer than the maximum page length (see below) are split into multiple segments and sent as separate pages. Each message segment is prefixed with its segment number. The maximum number of segments a into which a message will be split is configurable. If a message exceeds this limit, the last allowed segment will be prefixed with 't', indicating that the message is truncated; otherwise, the last segment is prefixed with 'e' to indicate the end of the message. Messages that fit into a single page are not prefixed with segment numbers. All messages are prefixed with CALLerid information (see RFC-1861), if available.

OPTIONS
The following options are supported:

-a  Send the page at the specified time. A time specification prefixed with a plus sign (+) is added to the current time. The QuickPage daemon will not send any pages with a timestamp newer than the current time. This feature may be used to provide a simple alarm clock function for meeting reminders, etc. This option applies only to the pagerid(s) specified by the next -p option.

-c  Use a different coverage area or paging service. This option is only useful if the recipient has more than one pager and/or more than one paging service. This option applies only to the pagerid(s) specified by the next -p option.

-C  Specify an alternate configuration file.

-d  Debug mode. Very verbose and probably not interesting for the normal user. This option is provided for debugging purposes only.

-f  Specify who the page is from. This option specifies the argument to the SNPP CALLerid command. Every message segment will be prefixed with the value specified by this option. A null argument ( -f "") may be specified to suppress the message prefix. The default is the userid of the person running QuickPage.

-h  Help. Print a brief summary of the command line options.

-i  Use interactive mode. The page is sent immediately and summary messages are printed during the course of the transaction. This option may only be used on a machine with a physically attached modem. This option is intended for debugging purposes only. The -d option, when used in conjunction with this option, can be very effective in troubleshooting problems between the SNPP server and the remote paging terminal.

-l  Specify the service level for this page. The service level must be a number between 0 and 11, inclusive. The TME protocol specifies service level as follows:

        0 - Priority
        1 - Normal (default)
        2 - Five minutes
        3 - Fifteen minutes
        4 - One hour
        5 - Four hours
        6 - Twelve hours
        7 - Twenty Four hours
        8 - Carrier specific '1'
        9 - Carrier specific '2'
        10 - Carrier specific '3'
        11 - Carrier specific '4'

    With the exception of level zero, service levels have no meaning to QuickPage but they are accepted for compatibility with other programs. Pages submitted with service level zero cause e-mail to be sent to the submitter whenever a page succeeds or fails. Any service level specified by the user is passed on to the SNPP server. This option applies only to the pagerid(s) specified by the next -p option.

-m  This option tells QuickPage to read an e-mail message from standard input. A page is constructed by concatenating the From: header (XXX), the Subject: header (YYY), and lines from the message body (ZZZ) as follows:

        XXX (Subj: YYY) ZZZ ...

    Minimal support is provided for multipart MIME messages. The first part with a Content-Type: of text/plain will be processed. The remaining parts will be discarded. This will reduce the problems associated with people accidentally mailing binaries to their pagers.

    The X-sun-attachment type is not supported and should not be used. MIME is a documented standard. The X-sun-attachment type is neither documented nor standard. However, QuickPage will still use the From: and Subject: lines (but no message body) from such messages for those people who insist on using it anyway.

    A line starting with two dashes (--) in the message body (or in a MIME text part) is assumed to be the start of a signature and will cause QuickPage to stop processing the message at that point.

-p  Specify the pagerid of the intended recipient. Multiple recipients may be specified by separating their pager IDs with commas, slashes, or colons (e.g. pagerid1,pagerid2,pagerid3). No spaces are permitted between recipients and separator characters. Any -a, -c, or -l options previously encountered on the command line are reset to their default values after this option is processed. This option may occur multiple times on the command line, each possibly preceded by different -a, -c, or -l options.

-P  Like -p but does not reset -a, -c, or -l options previously encountered on the command line.

-q  Start a QuickPage daemon process. This option causes QuickPage to detach itself from the controlling terminal and create two processes: one to listen for incoming SNPP connections and one for processing the page queue. This option also specifies the number of seconds QuickPage sleeps between queue runs. See the NOTES section below for more information.

-Q  Print the current contents of the page queue. This option may only be used on the QuickPage server.

-s  Specify the name(s) of the SNPP server(s). The hostnames used by a client to contact a server are determined by checking the following in this order:

        the -s option
        the environment variable SNPP_SERVER
        the contents of the compiled in filename
        the compiled in hostname

    Multiple hostnames are permitted by separating them with commas or colons. If multiple servers are used, it is assumed that they all have identical copies of the configuration file.

-v  Print the version of QuickPage and exit.

The QuickPage server requires a configuration file. This file is read once for each incoming SNPP connection and once for each queue run. The configuration file is made up of major and minor keyword=value pairs. Major keywords must start at the beginning of a line. Minor keywords must contain leading whitespace. All keywords must be immediately followed with an equal sign (=). Spaces are permitted between the equal sign and the value. Keywords may appear in any order with the following three exceptions:
    Minor keywords must be grouped together under their respective major keyword. Services must be defined before any pagers that reference them. Pagers must be defined before any groups that reference them.

The major keywords are:

    administrator
        The e-mail address of the QuickPage administrator. If defined, e-mail notification will be sent to the QuickPage administrator whenever a page fails (i.e. when maxtries has been exceeded). This address is also used in the Reply-To: header for status notification messages sent to users who submit high-priority pages.

    forcehostname
        (true, false, or @mailhost) Force the destination address to be qualified with a hostname when sending e-mail status notification to users. This option can be used when the QuickPage daemon is running on a machine that does not handle unqualified e-mail addresses correctly. If the value of this keyword starts with the '@' character, it will be appended as-is to unqualified e-mail addresses. If the value of this keyword is "true" then the submitter's hostname will be appended to such addresses. The default is false (do not append hostnames).

    identtimeout
        The number of seconds to wait for a reply before giving up on RFC-1413 queries. An integer less than or equal to zero disables ident functionality. The default is 10 seconds.

    snpptimeout
        The number of seconds to wait for an SNPP command before terminating the connection. The default is 60 seconds.

    queuedir
        The location of the page queue. There is no default queue directory; this option must be specified in the configuration file.

    service
        The start of a paging service definition. The argument to this keyword is the name of the paging service. If a service named default exists, the values of its minor keywords are used as defaults for all other service definitions. This keyword has the following minor keywords:

        device
            The name of the device the modem is physically connected to, such as /dev/cua/a. There is no default device; this option must be specified in the configuration file.

        dialcmd
            The command, including a phone number, that the modem should use to connect to the remote paging service. There is no default dial command; this option must be specified in the configuration file.

        password
            The password to use when logging into the remote paging service. The IXO specification defines the password as an optional six character alphanumeric string. The default is an empty string ("").

        baudrate
            The speed to use while talking to the modem. The default is 300 baud.

        parity
            The parity to use (even, odd, or none) while talking to the modem. The default is even.

        maxmsgsize
            The maximum number of characters allowed in a single page segment. The default is 80 characters.

        maxpages
            The maximum number of page segments to send when a message exceeds maxmsgsize. The value of this option must be between 1 and 9, inclusive. The default is 9 page segments.

        maxtries
            The number of times to attempt sending a page before giving up. If the modem is busy (i.e. tip or cu is currently using it) or if the modem returns BUSY in response to the dial command, the counter is not incremented. Thus a busy modem will cause QuickPage to retry the page forever. The default is 6.

        identfrom
            (true or false) This keyword specifies whether to use the ident response as the message prefix if no CALLerid SNPP command is received. The default is true.

        allowpid
            (true or false) This keyword specifies whether the QuickPage daemon will accept numeric pagerids for pagers not specified in the configuration file. The default service is used for such pagerids unless the user explicitly chooses a different service. The default for this keyword is false.

    pager
        The start of a pager definition. The argument to this keyword is the username associated with the pager. This username will be specified by the -p option on the command line when running QuickPage in client mode. This keyword has the following minor keywords:

        pagerid
            The pagerid sent to the remote paging service for this pager.

        service
            The default service to use for this pager.

    group
        The start of a group definition. The argument to this keyword is the name of a new page group. This keyword has the following minor keyword:

        member
            A member of this group. The member must have a valid pager entry before this group definition. An optional duty schedule (see below) may be specified. This keyword may appear multiple times within a single group.

The default service, if present, must specify values for the device and dialcmd keywords. If there is no default service, all services must specify these values.

Member definitions within a page group have the syntax:
    member=name[/DayStart-End]
Where the square brackets indicate an optional duty schedule. The duty schedule has the same syntax as the Time parameter in the UUCP Systems file: Day is a list of case-sensitive weekday abbreviations (e.g. MoTuTh), Start is the start time (e.g. 800), and End is the end time (e.g. 1700). The word Any is synonymous with SuMoTuWeThFrSa. Midnight may be represented as either 0 or 2400. The time range must not span across midnight. A slash is required to separate the duty schedule from the member name. Multiple member definitions for the same person with different duty schedules are permitted (see the example below). Overlapping duty schedules for the same person within a group will not cause duplicate pages to be sent to that person. See the following example configuration file:
    #
    # QuickPage configuration file
    #
    identtimeout=10
    queuedir=/var/spool/qpage service=default
        device=/dev/cua/b
        dialcmd=ATDT482-1111
        baudrate=1200
        allowpid=yes
        maxtries=6
    # use the S7 modem register to set a connection timeout
    service=supercom
        dialcmd=ATS7=30DT482-9649
        maxmsgsize=80
        maxpages=9
    pager=tomiii
        pagerid=710
        service=supercom
    pager=tony
        pagerid=711
        service=supercom
    group=sysadmin
        member=tomiii/MoWeFr800-1700
        member=tony/TuTh800-1700
        member=tony/SaSu900-1600

NOTES
The order of the command line options is important. The -a, -c, and -l options must precede the pagerids they refer to.

The -p option resets -a, -c, and -l to their default values. If this behavior is not desired, use -P instead.

The QuickPage daemon runs as two separate processes. The child processes the pages in the page queue. If any pages remain in the queue at the end of a run (if the remote modem was busy, for example, or if a page is being held until a future time), the child sleeps for the time specified by the -q option and tries again. Otherwise the child goes to sleep until awakened by the parent.

The parent daemon process listens for incoming SNPP connections and forks an additional child process to handle each request. After a page is accepted, SIGUSR1 is sent to the sleeping child process causing it to start a queue run.

If the CALLerid information received by the QuickPage daemon contains the '@' character, it is truncated at that character before being prepended to messages. However, it is used as-is for the destination address when sending e-mail notification for high-priority recipients.

Due to limitations of SNPP, QuickPage has to derive e-mail notification addresses from the CALLerid information. Since the CALLerid information might be bogus, all e-mail notifications are sent using a null reverse path. This will prevent error messages from being generated by the mail system if a bogus address is used for e-mail notification.

If the server does not receive a CALLerid command (i.e. the -f flag contains a null argument), notification messages will not be sent, regardless of the specified service level.

When the -m flag is used to send a high-priority page, the status notification is sent to the return address in the original e-mail message unless overridden by the -f option.

The length of SNPP commands is limited only by the amount of memory available to QuickPage.

QuickPage uses a timeout of 255 seconds while waiting for a connection from the remote modem. This allows the administrator to specify an appropriate timeout by setting the modem's S7 register in the dial command.

The modem must control the CD (carrier-detect) line; otherwise, the on/off hook status of the modem cannot be determined. This is especially important if more than one paging service (phone number) is used since QuickPage must know when it's safe to send dial commands to the modem.

FILES
/etc/qpage.cf

SEE ALSO
RFC-1861

KNOWN BUGS
QuickPage cannot send a single e-mail message to multiple addresses. If such functionality is desired, a mailing list should be created for this purpose.

Pages are not queued on the client side. As a result, if no servers are available to the client at the time a page is submitted, an error message is printed and the page is discarded.

Please send bug reports to tomiii@mtu.edu.

AUTHOR
QuickPage was written by Thomas Dwyer III <tomiii@mtu.edu> and is provided to the internet community free of charge.

Copyright (c) 1995-1997 Thomas Dwyer III