Provided by: ipsvd_1.0.0-2_amd64 bug

NAME

       ipsvd-instruct - format of the ipsvd(8) instructions directory

DESCRIPTION

       The  internet  protocol  service  daemons,  ipsvd(7),  can  be  told  to  read  and follow
       instructions from a directory on incoming connections to the socket they listen on.

       For mostly static instructions or for performance reasons, it is possible to  compile  the
       instructions  from a directory into a constant database (cdb) with ipsvd-cdb(8) for faster
       lookup, and to tell ipsvd(7) to read the instructions from there.

MATCHING

       On each incoming connection, the ipsvd(7) matches the client's IP address against files in
       the instructions directory.  For example, the IP address a.b.c.d which reverse resolves to
       moa.bit.smarden.org is matched against the following files in the instructions  directory,
       in this order, first match wins:

       1.     a.b.c.d

       2.     a.b.c

       3.     a.b

       4.     a

       If the client's hostname has been successfully looked up in DNS:

       5.     moa.bit.smarden.org

       6.     bit.smarden.org

       7.     smarden.org

       8.     org

       And finally the catchall file ``0'' (zero):

       9.     0

       After  successfully  matching  a  client's IP address or hostname against the instructions
       directory, ipsvd(7) examines the file that matched the IP address or  hostname,  and  acts
       accordingly:

       1.     If neither the user's read permission, nor the user's execute permission is set for
              the file, the connection is closed immediately.

       2.     If the file has the user's execute permission set, ipsvd(7) reads the  contents  of
              the file and runs /bin/sh -c '<contents>' instead of the default program prog given
              at the command line for this connection.

       3.     If the file has the user's read permission set, ipsvd(7) reads the contents of  the
              file and interprets each line as an instruction for this connection (see below).

       If  the  client's  IP  address  or  hostname  doesn't  match  any file in the instructions
       directory, the default action is taken (the program prog is run to handle the connection).

INSTRUCTIONS

       If ipsvd(7) is given instructions for an incoming connection, it reads  the  corresponding
       file and interprets each line as follows.  The file may be empty, meaning that there is no
       special instruction.

       Empty lines and lines starting with ``#'' are ignored.

       +VAR=VALUE
              environment.  If the line starts with a plus (``+''), and the string following  the
              plus  contains  a  ``='',  ipsvd(7)  puts  the  string  following the plus into the
              environment before starting prog to handle the connection.  If the string following
              the plus doesn't contain a ``='', ipsvd(7) makes sure that the environment variable
              with the name string is not set.

       Cnum[:msg]
              concurrency.  If the line starts with a ``C'', and is followed by a number, the per
              host  concurrency  limit for the IP address that initiated the connection is set to
              this number.  If num is zero, per host concurrency limit is disabled.   If  num  is
              followed by ``:msg'', the message msg is written to this client if possible, if the
              per host concurrency limit is reached.

              msg may contain backslash-escaped characters as follows: ``\\'' is converted  to  a
              single  backslash,  ``\n''  is  converted  to  a  new line character, and ``\r'' is
              converted to a carriage return.

              On multiple concurrency instructions the last processed concurrency instruction  is
              considered.  Not all ipsvd(7)'s support per host concurrency.

       =hostname[:forward]
              check  hostname.   If  the line starts with a ``='', and is followed by a hostname,
              ipsvd(7) looks up the IP addresses for hostname in DNS and checks if  the  client's
              IP address matches one of these IP addresses.  If so, ipsvd(7) stops processing the
              instructions here and runs prog.  If hostname is  followed  a  colon  and  forward,
              ipsvd(7)  now  examines  the  file forward and acts accordingly, instead of running
              prog.  All check hostname instructions in forward are ignored.  If forward does not
              exist, the connection is closed.

              hostname may be ``0'' (zero), matching any IP address.

              Note:   Using  check  hostname  instructions  can  cause  significant  delay  while
              responding to connection attempts, caused by DNS lookups.

       If ipsvd(7) cannot interpret a line, it prints a warning, discards the line, and continues
       with the next instruction if any.

       After  processing all instructions, ipsvd(7) runs prog.  If the file contains at least one
       check hostname instruction, and none was successful, it closes the connection  instead  of
       running prog.

EXAMPLE INSTRUCTIONS

       +MEMORY=20000
              This  instruction  causes  the  environment  variable  ``MEMORY''  with  the  value
              ``20000'' to be available to the program prog that handles the connection.

       +DEBUG=
              This  instruction  adds  the  variable  ``DEBUG''  with  an  empty  value  to   the
              environment.

       +LOGNAME
              This  instructions  makes  sure  that the environment variable ``LOGNAME'' is unset
              when running prog.

       C16    Set the per host concurrency to 16.  A connection will be closed silently if  there
              are already 16 active connections from this client's IP address.

       =floyd.dyn.smarden.org:127.0.0.1
              Check  IP  address of the dynamic hostname floyd.dyn.smarden.org.  If one of the IP
              addresses floyd.dyn.smarden.org currently  resolves  to  matches  the  client's  IP
              address,  handle  the  connection  through  the  file 127.0.0.1 in the instructions
              directory.

SEE ALSO

       ipsvd(7), ipsvd-cdb(8), tcpsvd(8), sslsvd(8), udpsvd(8), sslio(8)

       http://smarden.org/ipsvd/

AUTHOR

       Gerrit Pape <pape@smarden.org>

                                                                                ipsvd-instruct(5)