LISTEN(1) LISTEN(1)
NAME
listen, styxlisten, dial - network connections
SYNOPSIS
listen [ -Ats ] [ -a alg ]... [ -k keyfile ] [ -i
{initscript} ] addr command [ arg... ]
styxlisten [ -Ats ] [ -a alg ]... [ -k keyfile ] addr
command [ arg... ]
dial [ -A ] [ -a alg ] [ -k keyfile ] addr command [ arg...
]
DESCRIPTION
Listen waits for an incoming network connection on addr, (as
accepted by announce in dial(2)) and then invokes sh(1) to
run the associated command. If the -A option is specified,
no authentication or encryption will take place on the con-
nection; otherwise listen will attempt to authenticate the
party at the other end of the connection, allowing any given
alg to be used to encrypt and/or digest the connection's
data. If neither -A or any -a option is given, then listen
will allow any algorithm allowed by the local ssl(3) device.
If keyfile is specified, then that will be used as the
server's certificate; otherwise /usr/user/keyring/default
will be used.
If an initscript is provided, it is executed by each lis-
tener after announcing its network connection, with the
shell variable net set to the name of the corresponding net-
work directory (see dial(2)), before listening for incoming
calls. This can be used to change, or find out the charac-
teristics of an announced port (for instance to find out the
actual port number that has been announced).
By default, listen backgrounds itself (after checking that
the port announcement proceeded ok); giving it the -s option
causes it to run synchronously.
Listen currently makes available the whole of its current
name space visible to the command, which might be undesir-
able, and perhaps should be optional, with a new name space
constructed for an incoming call. The -t option declares
the command to be `trusted' giving it access to elements of
the current name space such as /mnt/keys on an authentica-
tion server. By default it has not got that access.
Styxlisten is similar to listen, except that it multiplexes
a single styx (see intro(5)) server between multiple
clients. Styxlisten starts its cmd only once; it assumes it
will serve styx messages through file descriptor 0 when
started. For each client that attaches to address, the
Page 1 Plan 9 (printed 10/27/25)
LISTEN(1) LISTEN(1)
command will see a new attach(5) message indicating the new
connection. Unless the -A option has been given, the uname
field in the attach message will be the name of the authen-
ticated user. When the command exits, the process listening
on address is stopped.
Dial is the complement of listen. It tries to make a connec-
tion to addr. If the -A option is given, no authentication
or encryption will take place; otherwise Inferno authentica-
tion and encryption will be performed as usual, using alg if
given, or a default algorithm otherwise. Keyfile is used
for the certificate if given, otherwise
/usr/user/keyring/addr, if it exists, and failing that,
/usr/user/keyring/default. Alg is used for the
encryption/digest algorithm on the connection. When the
connection is made, command is run in the context of that
connection, as described below.
For both dial and listen, when the command is run, $user is
set to the name of the authenticated user at the other end
of the connection (if authentication is being used), and
$net is set to the /net directory corresponding to the con-
nection. The standard input and output of the command is
redirected to the network connection (standard error is
unaffected).
EXAMPLES
Run a custom login daemon and an echo server that logs
incoming connections:
listen 'tcp!*!echo' {
echo connection from `{cat $net/remote} >[1=2]
echo user is $user >[1=2]
cat &
}
Dial up the above echo server:
dial tcp!somehost!echo {
echo made connection >[1=2]; echo hello; cat >[1=2]
}
Make the current name-space available to all:
styxlisten 'tcp!*!styx' export /
SOURCE
/appl/cmd/dial.b
/appl/cmd/listen.b
BUGS
The way that styxlisten is implemented means that the aname
Page 2 Plan 9 (printed 10/27/25)
LISTEN(1) LISTEN(1)
from the remote mount(2) request cannot be passed through to
the attach message seen by the command that has been started
by styxlisten.
SEE ALSO
dial(2), ssl(3), auth(6), svc(8)
Page 3 Plan 9 (printed 10/27/25)