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 3/29/24)

     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 3/29/24)

     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 3/29/24)