RTELNET(8)

NAME
rtelnet - Annex reverse TELNET daemon

SYNOPSIS
rtelnet [ -abcdfhkmnoprstCDFOPRTV ] [ -l file ] [ -u user ]
[ -M mode ] annex port device-name

ARGUMENTS

-a  Select use of alternate pty set. If your system has both System V and Berkeley pseudo-terminals, then this option will select the use of the Berkeley instead of the System V ptys.

-b  Negotiate TELNET binary mode when communicating with the Annex. This is a useful option for terminal (getty(8)) connections. This option tells rtelnet to negotiate TELNET BINARY mode, and not to translate CR/LF sequences. CR will be sent as CR/NUL and translated back to CR by the Annex with this option enabled. (See also -t and -c options below.)

-c  Default to CBREAK mode on the pty to avoid cooked-mode line breaks (see tty(4)). Use of this option requires that the slave pty be kept open by rtelnet on System V compliant machines.

-d  Turn on socket-level debugging. This just sets the SO_DEBUG flag (or equivalent) on the created network connection -- the actual operation of this option depends on the underlying operating system.

-f  Enable the connect on the fly mode, where rtelnet opens the network connection when the slave pty is opened. This option causes rtelnet to wait for the pty to open before it attempts to create the connection to the Annex. This option is incompatible with any option that would keep the pty open, such as -o. The -m switch is usually also used with this mode to ensure that rtelnet will drop the connection when the slave device is not in use.

-h  Send a reset port RPC to the Annex when the slave pseudo device is closed. If this option is used, then the -m switch should also be specified. This option uses the same NETADM protocol used by na. This will currently only work on Annexes without an annex password parameter set, or with annex enable_security set to N.

-k  Periodically retry network connection. This option tests the connection to the Annex by attempting to reopen the same port every 20 seconds, when the connection is quiet. If this new connection succeeds, then the old connection must have become disconnected -- presumably by a reboot of the Annex -- and a new one is necessary. This is useful when the traffic is primarily from the Annex to the host and SO_KEEPALIVE is unimplemented, since writes from the host to the Annex will be able to detect a failed connection, but reads will not.

-l <file>
    Append log output to given file name. This option opens the requested file in append mode so that all error and debugging output is placed there once command line parsing is complete.

-m  Momentarily drop the network connection to the Annex when the slave pseudo-device is closed. This can be used to cause the Annex to drop DTR, (if the port control_lines parameter is set to modem_control or to both) which can be used to cause a dial-out modem to hang up when a program like tip exits.

-n  Never open slave side of pty. This option will prohibit some systems which require ioctl(2) calls to be made on the slave side from setting up default I/O modes. This is recommended for use when either -f or -m or both are specified.

-o  Hold slave side of pty open at all times. This is a useful option when detecting pty open/close isn't necessary. Since closing the slave pty causes the master pty to close (on most systems), there is a small timing window where, if the slave pty is closed and then rapidly reopened, the second open will fail because the rtelnet process hasn't had a chance to close and reopen the master pty. This most often occurs in scripts where one might use:

        echo "Some text" > /dev/mypty
        echo "Some more text" > /dev/mypty

        The second
        echo
        command may fail because the shell will open
        and close the pty too rapidly.  This option will keep the slave
        open at all times so that the master does not need to be
        recycled.

-p  Give process ID of child on standard output.  This is useful for
    logging the PIDs of all the
    rtelnets
    started on a system so that they can be removed quickly.  For example:

    rtelnet -pt myannex 1 /dev/port1 > rtlist
    rtelnet -pt myannex 2 /dev/port2 >> rtlist

    Now to cleanly terminate both connections, type:

    kill `cat rtlist`

-r  Remove the device
    device-name
    if it already exists and if it is not a regular file or directory.
    Without
    -r,
    rtelnet
    will exit with an error message if
    device-name
    already exists.

-s  Use a symbolic link instead of a hard link for the slave.  This
    option allows you to place the slave pty anywhere in the file
    system.  If this option isn't specified, then a hard link is
    created by default, and hard links cannot normally span across
    mounted devices.

-t  Use a transparent TCP connection to the indicated Annex.  This will
    cause the connection to be made through Annex ports in the 7000 range,
    rather than the 5000 range, and no
    TELNET
    option negotiation or CR/LF mapping will be used.  Use this option
    to create a fast, completely transparent data path.  (If used with
    -f option, the pty may not default to RAW mode.)

-u <user>
    This option will cause
    rtelnet
    to change its real UID to the given user.  This is useful with System V
    machines, where the owner of the slave pty granted is set to the user
    that requests it.  Without this option, System V will grant all ptys as
    "root," which may make some applications unusable.

-C  Don't try to fix cooked-mode pseudo terminal problems by inserting LF
    characters.  Ordinarily,
    rtelnet
    will attempt to avoid a problem in Unix pseudo terminals that causes the
    slave to lock up if it is in line-buffered ("cooked") mode and too many
    characters are written between line-feed characters.
    Rtelnet
    will do this insertion if it cannot determine the line mode or if it
    does find the line in "cooked" mode.  This option disables this action,
    and is useful with binary connections in applications where the mode of
    the slave pseudo terminal can be guaranteed to be unbuffered.

-D [ D ... ]
    Turns on verbose debugging output.  In this case,
    rtelnet
    does not fork off a daemon unless the
    -F
    switch is also used; instead, it displays TELNET option negotiation
    and all received data on the terminal where
    rtelnet
    was started.

-F  Force
    rtelnet
    to fork into background, even in debug mode.  This is usually used with
    the -l option (above) when doing long-term testing.

-M <mode>
    Set the default file modes for the slave pty to the octal number given.
    (See chmod(1) for a list of these modes.)

-O  Disable out-of-band telnet data (for pre-R7.0 Annexes).  For
    compatibility with older Annex operational code, the TELNET IAC DM
    signal, which is used to implement the output flush ioctl(2) system
    call, is disabled with this switch.

-P  Interpret the
    port
    argument as a TCP port (decimal 1 through 65535 or a service name).
    This can be used to establish a slave pty that links to the Annex
    Port Server (port 23), the VCLI (port 5000) or to rotaries
    in the 6000-range.

-R  Rename the slave pseudo terminal rather than linking the given name to
    it.  This option is provided for systems that assign meanings to the
    major and minor numbers of the pseudo terminal device, and which do not
    expect to see more than one device with the same numbers.  This is a
    dangerous option to use, since an abend of the system may leave some
    slave terminals in an unusable state.

-T  Truncate (rather than break) lines that would choke the pty in cooked
    mode.

-V  Display version information on standard output and exit.  This
    information is useful for Xylogics technical support so that they can
    precisely identify the version of software you are using.

annex
    The hostname or Internet address
    (in standard Internet dot separated notation)
    of the Annex.

port
    The serial port number on the Annex, or the TCP port number or TCP
    service name.  (See -P flag above.)

device-name
    name of psuedo device to create (usually in the /dev directory).

DESCRIPTION
Rtelnet is a modified version of the Berkeley telnetd program. It will create a pseudo-tty (pty) device on the host that is connected via TELNET or raw TCP to an Annex serial port. This allows UNIX programs such as tip(1C) and uucp(1C) to access serial devices attached to Annex ports. Rtelnet works like a telnet daemon program (telnetd) except in a reverse fashion; instead of accepting connections from other network machines, rtelnet makes connections to Annexes. Rtelnet creates a new file-like device (usually in /dev) that programs can open and use like a normal /dev/tty terminal.

Normally, rtelnet makes the connection to the Annex immediately. This ties the Annex port to exactly one host, which is useful for dedicated devices. On the other hand, this will not interact correctly with a port set to adaptive mode, which would normally be used for a dial-in/dial-out modem. Such a configuration should use the connect on the fly (-f) option. In that case, rtelnet will not make the connection immediately, but will instead wait until another process opens the slave device. When that happens, rtelnet will attempt to make the network connection. When the connection is established, data will flow normally. If the connection cannot be made, rtelnet will try again using an exponential backoff.

Rtelnet is designed as a core set of routines that should compile on all machines, and a set of machine-dependent files for various systems. See the accompanying release notes, and README and INTERN files for more information on the internals of rtelnet.

Example usage:

    A dial-out modem is attached to port 15 of an Annex named "modem-annex". To enable its use via tip on a 4BSD host:

    1.  Configure port 15 using na or local CLI admin to:

        "control_lines: modem_control"
        "         mode: slave"

    2.  Start up rtelnet to create the pseudo-device:

        rtelnet -rbm modem-annex 15 /dev/modem1

        Normally, this would be added to the system startup file
        (/etc/rc).

    3.  Create new system definition in /etc/remote specifying /dev/modem1
        as the tip (dv) device.  For example:

        dialer|generic dial-out: \
                :dv=/dev/modem1:cm=^M^JATe1^M^J:at=hayes:du:

FILES
/dev/ptmx		master pseudo-terminal clone device
/dev/pty[p-s][0-9a-f]	default list of master pseudo-terminals
/dev/tty[p-s][0-9a-f]	default list of slave pseudo-terminals

SEE ALSO
Annex Network Administrator's Guide

chmod(1), su(1), ln(1) and pty(4).

DIAGNOSTICS
Messages should be self-explanatory. Be sure to have the output of "rtelnet -V" handy if you need help from Annex support.

Debug messages take the form:

TYPE:pid:yyyymmddhhmmss: <message>

Where "TYPE" is one of:

INIT - Entry or exit message.
INFO - Informational message (from debugging code).
WARN - Warning message.
ERR  - Error message.
FATL - Fatal error message -- rtelnet aborted.

These tags indicate the severity and content of the message -- they are
not necessarily tied to the debug level flag.  (Although "ERR " and
"FATL" messages are usually sent out regardless of debug level.)

Using the -D switch, one may specify the debug level on start-up.
This number filters the output sent to the log file -- the higher the
level, the more verbose the output that is sent to the file.  Setting
level 2, for example, is accomplished by specifying -DD.  The
levels are roughly defined as:

0 - Unexpected system errors and fatal errors only.
1 - Exceptional conditions and entry / exit.
2 - I/O statistics and verbose TELNET protocol data.
3 - Flow control upcalls and system library calls.
4 - I/O selection and testing verification.
5 - Raw I/O dump
    (can be used to reconstruct a session).

While rtelnet is running, you may change these levels by issuing a
SIGUSR1 to increase the debug level, or SIGURG2 to set it back to zero.
For example, if the pid of the rtelnet process is 9654:

kill -USR2 9654

This would disable debugging on that copy of rtelnet without aborting
any current data transfer.