.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents-montreal.org, 2009-06-14
.Dd June 14, 2009
.Dt SERIALCONSOLE 1
.Os NetBSD 1.4T
.Sh NAME
.Nm serialconsole
.Nd serial-line connection utility
.Sh SYNOPSIS
.Nm
.Op Fl flags Ar ...
.Sh DESCRIPTION
.Nm
is a serial-port communication tool designed for connecting to other
machines' serial consoles.  (In particular, it has features that are
particularly important for that use and is lacking some features of
little use there but of substantial importance for other uses.)
.Pp
.Nm
is built around a network server/client paradigm: one
.Nm
process talks with the serial line and acts as a network server; other
.Nm
processes act as network clients, mediating between the server process
and its users (humans, presumably).  Multiple clients can be run
against a single server; output is sent to all clients in parallel and
the input streams are merged by the server.
.Nm Ap s
options divide broadly into two classes, one set which are used for
server operation and another for client operation, though there are a
few, such as
.Fl port ,
which are used in each mode.  Each mode is described separately, with
options shared by both modes described twice, once for each mode.
.Pp
.Nm
can also provide access to other things, most notably a machine's own
console via a pseudo-terminal set to be the console (see
.Fl console )
and to network connections (see
.Fl net ;
this mode is designed for use with terminal servers that export their
serial lines as network connections).
.Sh SERVER MDOE
.Bl -tag -width indent
.It Fl daemon Ar tty-device
This causes
.Nm
to operate in server mode, talking to a serial line; the argument
specifies the underlying tty device.  The tty device is opened
immediately upon startup and kept open for the life of the daemon
process.
.It Fl console
This causes
.Nm
to operate in server mode, talking to the machine's console via a pty.
The pty pair is opened immediately, but it is set to be the console
only when there is at least one client connection.  Recap requests (see
below) are ignored in this mode.
.It Fl net Ar addr port
This causes
.Nm
to operate in server mode, talking to a TCP connection to address
.Ar addr ,
port
.Ar port .
The network connection is brought up immediately upon startup and kept
open for the life of the daemon process.  Break requests are ignored in
this mode.
.It Fl log Ar logfile
This keeps a log of all interaction with the serial line in
.Ar logfile .
This is quite detailed, including everything read from or written to
the serial line and certain other events such as break requests from
clients.  It is suitable for debugging problems by looking at exactly
what passed over the serial line, including things such as representing
nonprinting characters with escape sequences, but is not what you want
if you just want a transcript of what you saw; for that, try
.Fl script .
.It Fl script Ar logfile
This keeps a log of all output.  It does not record input per se,
though if it is echoed it will record the echo, nor does it record
special events such as speed changes or break requests.  It does,
however, provide a much more readable transcript than
.Fl log
for most purposes.
.It Fl speed Ar baudrate
Sets the underlying tty device's speed to
.Ar baudrate .
See also
.Fl lockspeed .
.It Fl addr Ar ip-addr
Listens for incoming connections on IP address
.Ar ip-addr .
This may be given multiple times to listen on multiple addresses.  The
argument may also be
.Sq any
or
.Sq all
to listen on all available addresses (by using
.Dv INADDR_ANY ) .
If this is not given at all, the default is to listen on 127.0.0.1.
.It Fl port Ar portnum
Specifies that
.Nm
is to listen for incoming connections on port
.Ar portnum
(on whatever address(es) are specified or defaulted; see
.Fl addr ) .
.It Fl lockspeed
Specifies that client requests to change the speed (see below) are to
be ignored.
.It Fl nodown
Specifies that client
.Dq down
requests (see below) are to be ignored.
.It Fl debug
Turns on various debugging support.  What, if anything, this controls
is not documented here; see the source code.
.El
.Sh CLIENT MODE
.Nm
operates in client mode whenever none of
.Fl daemon ,
.Fl console ,
or
.Fl net
is given.  Flags relevant to client mode are:
.Bl -tag -width indent
.It Fl addr Ar ip-addr
Specifies an address to try to contact the daemon at.  This may be
given multiple times;
.Nm
tries the addresses given, in order, until it connects successfully.
If no
.Fl addr
options are given, the default is 127.0.0.1.
.It Fl port Ar portnum
Specifies the port number on which
.Nm
is to contact the remote daemon (on whatever address(es) are specified
or defaulted; see
.Fl addr ) .
.It Fl esc Ar escchar
Specifies an escape character.  When this character is typed, the
client
.Nm
process reads the next character as a local command, rather than
sending it to the server as typed input.  See below for the local
commands supported.  The argument can be a single character, one of the
32 usual \&^-prefixed control characters,
.Sq sp
or
.Sq space
to specify a space character, or \&^?\& to indicate DEL.  The default
escape character is control-\&\].
.It Fl noesc
Specifies that no escape character is to be used.  In this mode, the
input connection is a full 8-bit-transparent input stream (or at least
can be; see
.Fl parity ) ,
but there is nothing that can be typed to get the attention of the
local
.Nm
process to issue commands such as disconnect requests.
.It Fl recap Ar N
Specifies that
.Nm
is to issue a recap request for the last
.Ar N
bytes of output immediately upon startup.  (See the local command
description below for more information on recap requests.)  NB: See
BUGS, below.
.It Fl captive
Disables the commands to exit, suspend, and run external programs (see
below), but nothing else.  Combined with
.Fl noesc ,
this is suitable for cases where you want to provide access to a serial
line without granting access to the local system.
.It Fl ro
Makes the
.Nm
instance read-only.  Input produces beeps rather than being sent to the
server.
.It Fl hex
Turns on hex mode (see below) immediately upon startup.
.It Fl parity Ar output-mode input-mode
Specifies parity interpretation and generation.  Each argument must be
a two-character string; the first character specifies what parity to
accept, the second, what parity to generate.  They usually will be the
same, but you can, for example, specify accepting even parity and
generating zero parity to strip the parity from even-parity data.  Each
character can be:
.Bl -tag -compact -width indent
.It n
None: on input, accept any parity; on output, do not modify the parity.
.It e
Even: on input, discard odd-parity data; on output, force even parity.
.It o
Odd: on input, discard even-parity data; on output, force odd parity.
.It 0
Zero: on input, discard data with the parity bit set; on output, clear
the parity bit.
.It 1
One: on input, discard data with the parity bit clear; on output, set
the parity bit.
.El
.Lp
.It Fl debug
Turns on various debugging support.  What, if anything, this controls
is not documented here; see the source code.
.El
.Sh LOCAL COMMANDS
When operating in client mode,
.Nm
has local command capability.  This is invoked by typing the escape
character (see the
.Fl esc
option).  The next character typed determines what
.Nm
does.  If it is the escape character again, the character is sent to
the server (this applies even if the escape character is one of the
characters listed below; in that case, the functionality below is not
accessible).  Otherwise, the character can be:
.Lp
.Bl -tag -compact -width indent
.It \&?
Print out a summary of the possible escapes.
.It \&#
Send a break request (see below) to the server.
.It \&
(Space.)  Do nothing - ignore the escape character and return to normal
communication.
.It \&%
Enter command mode (see below).
.It x
Accept two hexadecimal characters and
.Sq type
the character they form.  The resulting character is always treated as
typed input, even if it would normally do something else if it were
actually typed (for example, this is another way to
.Sq type
the escape character).
.It \&.
Exit
.\" Dammit, why doesn't ".Nm ." DTRT here?!
.Nm serialconsole .
(This is disabled if
.Fl captive
was given.)
.It z
Suspend
.Nm serialconsole .
(This is disabled if
.Fl captive
was given.)
.El
.Lp
Anything else produces a brief note suggesting use of \&?\& for help.
.Pp
Command mode (entered through the \&% escape) accepts lines of input
giving commands.  These can be:
.Bl -tag -width indent
.It \&?, help
Prints a brief summary of the commands available.
.It quit, exit
Exit
.Nm serialconsole .
(This is disabled if
.Fl captive
was given.)
.\" Without the \&, the entry line vanishes - is z magic to .It?
.It \&z, suspend
Suspend
.Nm serialconsole .
(This is disabled if
.Fl captive
was given.)
.It break
Generate a break request (like the \&# escape, above).  When the server
is talking to a real serial line, this will normally result in a break
condition on the serial line.
.It go, cont
Exit command mode, returning to normal communication.
.It recap Ar NNN
Request that the server repeat the last NNN characters of output.  If
the server has seen fewer than NNN characters of output since startup,
it will, of course, send only what it has.  NB: See BUGS, below.
.It speed Ar NNN
Request that the server change the serial-line speed to
.Ar NNN
baud.  The server may or may not pay attention to the request.
.It iparity Ar xy
Change the input parity setting.  See the
.Fl parity
option for details of the argument.
.It oparity Ar xy
Change the output parity setting.  See the
.Fl parity
option for details of the argument.
.It vis
Toggle vis mode.  When this is on, nonprinting characters are printed
as escape sequences.
.It hex
Toggle hex mode.  When this is on, all output is printed as
two-character hexadecimal, with a single space separating each octet
from the next.  This is suitable for looking at raw binary output.
.It run Ar commandline
Run
.Ar commandline
(which is passed to
.Pf \&$ Dv SHELL
with the
.Fl c
convention).  Its input and output will be connected to the serial line
(without any escape capability).  When the program exits, control is
returned to the user; in the meantime, input produces beeps and is not
sent anywhere.
.It down
Request that the server stop doing I/O on the undelrying serial line,
but hold it open (and thus maintain the settings, such as baud rate).
I/O is not performed in this state, but baudrate changes are, as a
convenient way to change the speed.
.Pp
The server may be configured to ignore
.Sq down
requests; see
.Fl nodown ,
above.
.It up
Cancel a previous
.Sq down ;
resume normal operation.
.El
.Sh BUGS
Completely IPv6-unaware.
.Pp
There is no way to listen on multiple ports, or to listen on different
ports on different addresses.
.Pp
Break requests use
.Xr tcsendbreak 3
on the server side, which can fail to generate a break condition when
running at very low baud rates.
.Pp
Recap requests asking for more than 65535 bytes of recap do not work
right; only the low 16 bits of the number are used.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .