Provided by: ipsvd_0.13.0-1_i386 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)