HOSTS_OPTIONS(5)          OpenBSD Programmer's Manual         HOSTS_OPTIONS(5)

NAME
     hosts_options - tcp wrapper host access control language extensions

DESCRIPTION
     This document describes optional extensions to the language described in
     the hosts_access(5) document.

     The extensible language uses the following format:

           daemon_list : client_list : option : option ...

     The first two fields are described in the hosts_access(5) manual page.
     The remainder of the rules is a list of zero or more options.  Any ":"
     characters within options should be protected with a backslash.

     An option is of the form "keyword" or "keyword value".  Options are pro-
     cessed in the specified order.  Some options are subjected to %<letter>
     substitutions.  For the sake of backwards compatibility with earlier ver-
     sions, an "=" is permitted between keyword and value.

LOGGING
     severity mail.info

     severity notice     Change the severity level at which the event will be
                         logged.  Facility names (such as mail) are optional,
                         and are not supported on systems with older syslog
                         implementations.  The severity option can be used to
                         emphasize or to ignore specific events.

ACCESS CONTROL
     allow

     deny   Grant (deny) service.  These options must appear at the end of a
            rule.

     The allow and deny keywords make it possible to keep all access control
     rules within a single file, for example in the /etc/hosts.allow file.

     To permit access from specific hosts only:

           ALL: .friendly.domain: ALLOW
           ALL: ALL: DENY

     To permit access from all hosts except a few trouble makers:

           ALL: .bad.domain: DENY
           ALL: ALL: ALLOW

     Notice the leading dot on the domain name patterns.

RUNNING OTHER COMMANDS
     spawn shell_command  Execute, in a child process, the specified shell
                          command, after performing the %<letter> expansions
                          described in the hosts_access(5) manual page.  The
                          command is executed with stdin, stdout and stderr
                          connected to the null device, so that it won't mess
                          up the conversation with the client host.  Example:

                                spawn (/some/where/safe_finger -l @%h | \
                                        /usr/ucb/mail root) &

                          executes, in a background child process, the shell
                          command "safe_finger -l @%h | mail root" after re-
                          placing %h by the name or address of the remote
                          host.

                          The example uses the "safe_finger" command instead
                          of the regular "finger" command, to limit possible
                          damage from data sent by the finger server.  The
                          "safe_finger" command is part of the daemon wrapper
                          package; it is a wrapper around the regular finger
                          command that filters the data sent by the remote
                          host.

     twist shell_command  Replace the current process by an instance of the
                          specified shell command, after performing the %<let-
                          ter> expansions described in the hosts_access(5)
                          manual page.  Stdin, stdout and stderr are connected
                          to the client process.  This option must appear at
                          the end of a rule.

                          To send a customized bounce message to the client
                          instead of running the real ftp daemon:

                                ftpd : ... : twist /bin/echo 421 \
                                        Some bounce message

                          For an alternative way to talk to client processes,
                          see the banners option below.

                          To run /some/other/telnetd without polluting its
                          command-line array or its process environment:

                                telnetd : ... : twist PATH=/some/other; \
                                        exec in.telnetd

                          Warning:  in case of UDP services, do not twist to
                          commands that use the standard I/O or the read(2) or
                          write(2) routines to communicate with the client
                          process; UDP requires other I/O primitives.

NETWORK OPTIONS
     keepalive                 Causes the server to periodically send a mes-
                               sage to the client.  The connection is consid-
                               ered broken when the client does not respond.
                               The keepalive option can be useful when users
                               turn off their machine while it is still con-
                               nected to a server.  The keepalive option is
                               not useful for datagram (UDP) services.

     linger number_of_seconds  Specifies how long the kernel will try to de-
                               liver not-yet delivered data after the server
                               process closes a connection.

USERNAME LOOKUP
     rfc931 [ timeout_in_seconds ]  Look up the client user name with the RFC
                                    931 (TAP, IDENT, RFC 1413) protocol.  This
                                    option is silently ignored in case of ser-
                                    vices based on transports other than TCP.
                                    It requires that the client system runs an
                                    RFC 931 (IDENT, etc.) -compliant daemon,
                                    and may cause noticeable delays with con-
                                    nections from non-UNIX clients.  The time-
                                    out period is optional.  If no timeout is
                                    specified a compile-time defined default
                                    value is taken.

MISCELLANEOUS
     banners /some/directory  Look for a file in /some/directory with the same
                              name as the daemon process (for example telnetd
                              for the telnet service), and copy its contents
                              to the client.  Newline characters are replaced
                              by carriage-return newline, and %<letter> se-
                              quences are expanded (see the hosts_access(5)
                              manual page).

                              Warning: banners are supported for connection-
                              oriented (TCP) network services only.

     nice [ number ]          Change the nice value of the process (default
                              10).  Specify a positive value to spend more CPU
                              resources on other processes.

     setenv name value        Place a (name, value) pair into the process en-
                              vironment.  The value is subjected to %<letter>
                              expansions and may contain whitespace (but lead-
                              ing and trailing blanks are stripped off).

                              Warning: many network daemons reset their envi-
                              ronment before spawning a login or shell pro-
                              cess.

     umask 022                Like the umask command that is built into the
                              shell.  An umask of 022 prevents the creation of
                              files with group and world write permission.
                              The umask argument should be an octal number.

     user nobody

     user nobody.kmem         Assume the privileges of the "nobody" userid (or
                              user "nobody", group "kmem").  The first form is
                              useful with inetd implementations that run all
                              services with root privilege.  The second form
                              is useful for services that need special group
                              privileges only.

DIAGNOSTICS
     When a syntax error is found in an access control rule, the error is re-
     ported to the syslog daemon; further options will be ignored, and service
     is denied.

SEE ALSO
     hosts_access(5)

AUTHORS
           Wietse Venema (wietse@wzv.win.tue.nl)
           Department of Mathematics and Computing Science
           Eindhoven University of Technology
           Den Dolech 2, P.O. Box 513,
           5600 MB Eindhoven, The Netherlands

OpenBSD 4.7                      May 31, 2007                                3
