lib/libwrap/hosts_options.5

   1 .\"     $NetBSD: hosts_options.5,v 1.8 2002/10/01 19:38:46 wiz Exp $
   2 .\"
   3 .TH HOSTS_OPTIONS 5
   4 .SH NAME
   5 hosts_options \- host access control language extensions
   6 .SH DESCRIPTION
   7 This document describes optional extensions to the language described
   8 in the hosts_access(5) document.
   9 The extensions are enabled at program build time.
  10 For example, by editing the Makefile and turning on the
  11 PROCESS_OPTIONS compile-time option.
  12 .PP
  13 The extensible language uses the following format:
  14 .sp
  15 .ti +3
  16 daemon_list : client_list : option : option ...
  17 .PP
  18 The first two fields are described in the hosts_access(5) manual page.
  19 The remainder of the rules is a list of zero or more options.
  20 Any ":" characters within options should be protected with a backslash.
  21 .PP
  22 An option is of the form "keyword" or "keyword value".
  23 Options are processed in the specified order.
  24 Some options are subjected to
  25 %\*[Lt]letter\*[Gt] substitutions.
  26 For the sake of backwards compatibility with
  27 earlier versions, an "=" is permitted between keyword and value.
  28 .SH LOGGING
  29 .IP "severity mail.info"
  30 .IP "severity notice"
  31 Change the severity level at which the event will be logged.
  32 Facility names (such as mail) are optional, and are not supported on systems
  33 with older syslog implementations.
  34 The severity option can be used to emphasize or to ignore specific events.
  35 .SH ACCESS CONTROL
  36 .IP "allow"
  37 .IP "deny"
  38 Grant (deny) service.
  39 These options must appear at the end of a rule.
  40 .PP
  41 The \fIallow\fR and \fIdeny\fR keywords make it possible to keep all
  42 access control rules within a single file, for example in the
  43 \fIhosts.allow\fR file.
  44 .sp
  45 To permit access from specific hosts only:
  46 .sp
  47 .ne 2
  48 .ti +3
  49 ALL: .friendly.domain: ALLOW
  50 .ti +3
  51 ALL: ALL: DENY
  52 .sp
  53 To permit access from all hosts except a few trouble makers:
  54 .sp
  55 .ne 2
  56 .ti +3
  57 ALL: .bad.domain: DENY
  58 .ti +3
  59 ALL: ALL: ALLOW
  60 .sp
  61 Notice the leading dot on the domain name patterns.
  62 .SH RUNNING OTHER COMMANDS
  63 .IP "spawn shell_command"
  64 Execute, in a child process, the specified shell command, after
  65 performing the %\*[Lt]letter\*[Gt] expansions described in the hosts_access(5)
  66 manual page.
  67 The command is executed with stdin, stdout and stderr
  68 connected to the null device, so that it won\'t mess up the
  69 conversation with the client host.
  70 Example:
  71 .sp
  72 .nf
  73 .ti +3
  74 spawn (/some/where/safe_finger -l @%h | /usr/ucb/mail root) \*[Am]
  75 .fi
  76 .sp
  77 executes, in a background child process, the shell command "safe_finger
  78 -l @%h | mail root" after replacing %h by the name or address of the
  79 remote host.
  80 .sp
  81 The example uses the "safe_finger" command instead of the regular
  82 "finger" command, to limit possible damage from data sent by the finger server.
  83 The "safe_finger" command is part of the daemon wrapper
  84 package; it is a wrapper around the regular finger command that filters
  85 the data sent by the remote host.
  86 .IP "twist shell_command"
  87 Replace the current process by an instance of the specified shell
  88 command, after performing the %\*[Lt]letter\*[Gt] expansions described in the
  89 hosts_access(5) manual page.
  90 Stdin, stdout and stderr are connected to the client process.
  91 This option must appear at the end of a rule.
  92 .sp
  93 To send a customized bounce message to the client instead of
  94 running the real ftp daemon:
  95 .sp
  96 .nf
  97 .ti +3
  98 in.ftpd : ... : twist /bin/echo 421 Some bounce message
  99 .fi
 100 .sp
 101 For an alternative way to talk to client processes, see the
 102 \fIbanners\fR option below.
 103 .sp
 104 To run /some/other/in.telnetd without polluting its command-line
 105 array or its process environment:
 106 .sp
 107 .nf
 108 .ti +3
 109 in.telnetd : ... : twist PATH=/some/other; exec in.telnetd
 110 .fi
 111 .sp
 112 Warning:  in case of UDP services, do not twist to commands that use
 113 the standard I/O or the read(2)/write(2) routines to communicate with
 114 the client process; UDP requires other I/O primitives.
 115 .SH NETWORK OPTIONS
 116 .IP "keepalive"
 117 Causes the server to periodically send a message to the client.
 118 The connection is considered broken when the client does not respond.
 119 The keepalive option can be useful when users turn off their
 120 machine while it is still connected to a server.
 121 The keepalive option is not useful for datagram (UDP) services.
 122 .IP "linger number_of_seconds"
 123 Specifies how long the kernel will try to deliver not-yet delivered
 124 data after the server process closes a connection.
 125 .SH USERNAME LOOKUP
 126 .IP "rfc931 [ timeout_in_seconds ]"
 127 Look up the client user name with the RFC 931 (TAP, IDENT, RFC 1413)
 128 protocol.
 129 This option is silently ignored in case of services based on
 130 transports other than TCP.
 131 It requires that the client system runs an RFC 931 (IDENT, etc.)
 132 -compliant daemon, and may cause noticeable
 133 delays with connections from non-UNIX clients.
 134 The timeout period is optional.
 135 If no timeout is specified a compile-time defined default
 136 value is taken.
 137 .SH MISCELLANEOUS
 138 .IP "banners /some/directory"
 139 Look for a file in `/some/directory' with the same name as the daemon
 140 process (for example in.telnetd for the telnet service), and copy its
 141 contents to the client.
 142 Newline characters are replaced by carriage-return newline,
 143 and %\*[Lt]letter\*[Gt] sequences are expanded (see
 144 the hosts_access(5) manual page).
 145 .sp
 146 The tcp wrappers source code distribution provides a sample makefile
 147 (Banners.Makefile) for convenient banner maintenance.
 148 .sp
 149 Warning: banners are supported for connection-oriented (TCP) network
 150 services only.
 151 .IP "nice [ number ]"
 152 Change the nice value of the process (default 10).
 153 Specify a positive value to spend more CPU resources on other processes.
 154 .IP "setenv name value"
 155 Place a (name, value) pair into the process environment.
 156 The value is subjected to %\*[Lt]letter\*[Gt] expansions and
 157 may contain whitespace (but leading and trailing blanks are stripped off).
 158 .sp
 159 Warning: many network daemons reset their environment before spawning a
 160 login or shell process.
 161 .IP "umask 022"
 162 Like the umask command that is built into the shell.
 163 An umask of 022 prevents the creation of files with group
 164 and world write permission.
 165 The umask argument should be an octal number.
 166 .IP "user nobody"
 167 .IP "user nobody.kmem"
 168 Assume the privileges of the "nobody" userid (or user "nobody", group
 169 "kmem").
 170 The first form is useful with inetd implementations that run
 171 all services with root privilege.
 172 The second form is useful for services that need
 173 special group privileges only.
 174 .SH DIAGNOSTICS
 175 When a syntax error is found in an access control rule, the error
 176 is reported to the syslog daemon; further options will be ignored,
 177 and service is denied.
 178 .SH SEE ALSO
 179 hosts_access(3)
 180 hosts_access(5), the default access control language
 181 .SH AUTHOR
 182 .na
 183 .nf
 184 Wietse Venema (wietse@wzv.win.tue.nl)
 185 Department of Mathematics and Computing Science
 186 Eindhoven University of Technology
 187 Den Dolech 2, P.O. Box 513,
 188 5600 MB Eindhoven, The Netherlands
 189 \" @(#) hosts_options.5 1.10 94/12/28 17:42:28