1HOSTS_ACCESS(5)               File Formats Manual              HOSTS_ACCESS(5)
2
3
4

NAME

6       hosts_access - format of host access control files
7

DESCRIPTION

9       This  manual  page  describes  a simple access control language that is
10       based on client (host name/address, user  name),  and  server  (process
11       name,  host name/address) patterns.  Examples are given at the end. The
12       impatient reader is encouraged to skip to the EXAMPLES  section  for  a
13       quick introduction.
14
15       An  extended version of the access control language is described in the
16       hosts_options(5) document. The extensions  are  turned  on  at  program
17       build time by building with -DPROCESS_OPTIONS.
18
19       In the following text, daemon is the the process name of a network dae‐
20       mon process, and client is the name and/or address of a host requesting
21       service.  Network  daemon process names are specified in the inetd con‐
22       figuration file.
23

ACCESS CONTROL FILES

25       The access control software consults two files. The search stops at the
26       first match:
27
28       ·      Access  will  be  granted when a (daemon,client) pair matches an
29              entry in the /etc/hosts.allow file.
30
31       ·      Otherwise, access will be denied  when  a  (daemon,client)  pair
32              matches an entry in the /etc/hosts.deny file.
33
34       ·      Otherwise, access will be granted.
35
36       A  non-existing  access  control file is treated as if it were an empty
37       file. Thus, access control can be turned off  by  providing  no  access
38       control files.
39

ACCESS CONTROL RULES

41       Each access control file consists of zero or more lines of text.  These
42       lines are processed in order of appearance. The search terminates  when
43       a match is found.
44
45       ·      A  newline  character  is ignored when it is preceded by a back‐
46              slash character. This permits you to break up long lines so that
47              they are easier to edit.
48
49       ·      Blank  lines  or  lines  that  begin  with  a  `#´ character are
50              ignored.  This permits you to insert comments and whitespace  so
51              that the tables are easier to read.
52
53       ·      All  other  lines  should  satisfy  the following format, things
54              between [] being optional:
55
56                 daemon_list : client_list [ : shell_command ]
57
58       daemon_list is a list of one or more daemon process names (argv[0] val‐
59       ues) or wildcards (see below).
60
61       client_list  is  a list of one or more host names, host addresses, pat‐
62       terns or wildcards (see below) that will be matched against the  client
63       host name or address.
64
65       The  more  complex forms daemon@host and user@host are explained in the
66       sections on server endpoint patterns and on  client  username  lookups,
67       respectively.
68
69       List elements should be separated by blanks and/or commas.
70
71       With  the  exception  of  NIS (YP) netgroup lookups, all access control
72       checks are case insensitive.
73

PATTERNS

75       The access control language implements the following patterns:
76
77       ·      A string that begins with  a  `.´  character.  A  host  name  is
78              matched  if  the last components of its name match the specified
79              pattern.  For example, the pattern `.tue.nl´  matches  the  host
80              name `wzv.win.tue.nl´.
81
82       ·      A  string  that  ends  with  a  `.´ character. A host address is
83              matched if its first numeric fields match the given string.  For
84              example,  the pattern `131.155.´ matches the address of (almost)
85              every host on the Eindhoven University network (131.155.x.x).
86
87       ·      A string that begins with an `@´ character is treated as an  NIS
88              (formerly  YP)  netgroup name. A host name is matched if it is a
89              host member of the specified netgroup. Netgroup matches are  not
90              supported for daemon process names or for client user names.
91
92       ·      An  expression of the form `n.n.n.n/m.m.m.m´ is interpreted as a
93              `net/mask´ pair. An IPv4 host address is  matched  if  `net´  is
94              equal  to  the  bitwise  AND  of the address and the `mask´. For
95              example,  the  net/mask   pattern   `131.155.72.0/255.255.254.0´
96              matches  every  address  in  the  range  `131.155.72.0´  through
97              `131.155.73.255´.
98
99       ·      An expression of  the  form  `n.n.n.n/m´  is  interpreted  as  a
100              `net/prefixlen´ pair, as below, for IPv4 addresses.
101
102       ·      An  expression  of the form `[n:n:n:n:n:n:n:n/m]´ is interpreted
103              as a `[net/prefixlen]´ pair. An IPv6 host address is matched  if
104              `prefixlen´  bits  of  `net´ is equal to the `prefixlen´ bits of
105              the  address.   For   example,   the   [net/prefixlen]   pattern
106              `[3ffe:505:2:1::/64]´   matches   every  address  in  the  range
107              `3ffe:505:2:1::´ through `3ffe:505:2:1:ffff:ffff:ffff:ffff´.
108
109       ·      A string that begins with a `/´ character is treated as  a  file
110              name.  A  host name or address is matched if it matches any host
111              name or address pattern listed in the named file. The file  for‐
112              mat is zero or more lines with zero or more host name or address
113              patterns separated by whitespace.  A file name  pattern  can  be
114              used anywhere a host name or address pattern can be used.
115
116       ·      Wildcards  `*´  and  `?´  can  be  used to match hostnames or IP
117              addresses.  This method of matching cannot be used  in  conjunc‐
118              tion  with `net/mask´ matching, hostname matching beginning with
119              `.´ or IP address matching ending with `.´.
120

WILDCARDS

122       The access control language supports explicit wildcards:
123
124       ALL    The universal wildcard, always matches.
125
126       LOCAL  Matches any host whose name does not contain a dot character.
127
128       UNKNOWN
129              Matches any user whose name is unknown,  and  matches  any  host
130              whose  name or address are unknown.  This pattern should be used
131              with care: host names may be unavailable due to  temporary  name
132              server  problems. A network address will be unavailable when the
133              software cannot figure out what type of network  it  is  talking
134              to.
135
136       KNOWN  Matches any user whose name is known, and matches any host whose
137              name and address are known. This pattern  should  be  used  with
138              care: host names may be unavailable due to temporary name server
139              problems.  A network address will be unavailable when the  soft‐
140              ware cannot figure out what type of network it is talking to.
141
142       PARANOID
143              Matches  any  host  whose name does not match its address.  When
144              tcpd is built with -DPARANOID (default mode), it drops  requests
145              from  such  clients  even  before  looking at the access control
146              tables.  Build without -DPARANOID when  you  want  more  control
147              over such requests.
148

OPERATORS

150       EXCEPT Intended  use  is of the form: `list_1 EXCEPT list_2´; this con‐
151              struct matches anything that matches list_1  unless  it  matches
152              list_2.   The EXCEPT operator can be used in daemon_lists and in
153              client_lists. The EXCEPT operator can be nested: if the  control
154              language would permit the use of parentheses, `a EXCEPT b EXCEPT
155              c´ would parse as `(a EXCEPT (b EXCEPT c))´.
156

SHELL COMMANDS

158       If the first-matched access control rule contains a shell command, that
159       command  is  subjected  to  %<letter> substitutions (see next section).
160       The result is executed by a /bin/sh child process with standard  input,
161       output  and error connected to /dev/null.  Specify an `&´ at the end of
162       the command if you do not want to wait until it has completed.
163
164       Shell commands should not rely  on  the  PATH  setting  of  the  inetd.
165       Instead, they should use absolute path names, or they should begin with
166       an explicit PATH=whatever statement.
167
168       The hosts_options(5) document describes an  alternative  language  that
169       uses the shell command field in a different and incompatible way.
170

% EXPANSIONS

172       The following expansions are available within shell commands:
173
174       %a (%A)
175              The client (server) host address.
176
177       %c     Client  information:  user@host,  user@address,  a host name, or
178              just an address, depending on how much information is available.
179
180       %d     The daemon process name (argv[0] value).
181
182       %h (%H)
183              The client (server) host name or address, if the  host  name  is
184              unavailable.
185
186       %n (%N)
187              The client (server) host name (or "unknown" or "paranoid").
188
189       %p     The daemon process id.
190
191       %s     Server  information: daemon@host, daemon@address, or just a dae‐
192              mon name, depending on how much information is available.
193
194       %u     The client user name (or "unknown").
195
196       %%     Expands to a single `%´ character.
197
198       Characters in % expansions that may confuse the shell are  replaced  by
199       underscores.
200

SERVER ENDPOINT PATTERNS

202       In  order  to distinguish clients by the network address that they con‐
203       nect to, use patterns of the form:
204
205          process_name@host_pattern : client_list ...
206
207       Patterns like these can be used when the machine has different internet
208       addresses with different internet hostnames.  Service providers can use
209       this facility to offer FTP, GOPHER or WWW archives with internet  names
210       that  may  even belong to different organizations. See also the `twist'
211       option in the hosts_options(5) document. Some systems  (Solaris,  Free‐
212       BSD) can have more than one internet address on one physical interface;
213       with other systems you may have to resort to SLIP or PPP pseudo  inter‐
214       faces that live in a dedicated network address space.
215
216       The  host_pattern  obeys  the  same  syntax  rules  as  host  names and
217       addresses in client_list context. Usually, server endpoint  information
218       is available only with connection-oriented services.
219

CLIENT USERNAME LOOKUP

221       When  the  client  host  supports  the  RFC  931 protocol or one of its
222       descendants (TAP, IDENT, RFC 1413) the wrapper  programs  can  retrieve
223       additional information about the owner of a connection. Client username
224       information, when available, is logged together with  the  client  host
225       name, and can be used to match patterns like:
226
227          daemon_list : ... user_pattern@host_pattern ...
228
229       The  daemon wrappers can be configured at compile time to perform rule-
230       driven username lookups (default) or to always interrogate  the  client
231       host.   In  the  case  of  rule-driven username lookups, the above rule
232       would cause username lookup only when  both  the  daemon_list  and  the
233       host_pattern match.
234
235       A  user pattern has the same syntax as a daemon process pattern, so the
236       same wildcards apply  (netgroup  membership  is  not  supported).   One
237       should not get carried away with username lookups, though.
238
239       ·      The  client  username  information  cannot be trusted when it is
240              needed most, i.e. when the client system has  been  compromised.
241              In  general,  ALL  and (UN)KNOWN are the only user name patterns
242              that make sense.
243
244       ·      Username lookups are possible only with TCP-based services,  and
245              only  when  the client host runs a suitable daemon; in all other
246              cases the result is "unknown".
247
248       ·      A well-known UNIX kernel bug may  cause  loss  of  service  when
249              username  lookups  are blocked by a firewall. The wrapper README
250              document describes a procedure to find out if  your  kernel  has
251              this bug.
252
253       ·      Username lookups may cause noticeable delays for non-UNIX users.
254              The default timeout for username  lookups  is  10  seconds:  too
255              short to cope with slow networks, but long enough to irritate PC
256              users.
257
258       Selective username lookups can alleviate the last problem. For example,
259       a rule like:
260
261          daemon_list : @pcnetgroup ALL@ALL
262
263       would  match members of the pc netgroup without doing username lookups,
264       but would perform username lookups with all other systems.
265

DETECTING ADDRESS SPOOFING ATTACKS

267       A flaw in the sequence number generator of many TCP/IP  implementations
268       allows  intruders  to  easily impersonate trusted hosts and to break in
269       via, for example, the remote shell service.  The  IDENT  (RFC931  etc.)
270       service  can  be  used  to  detect such and other host address spoofing
271       attacks.
272
273       Before accepting a client request, the wrappers can use the IDENT  ser‐
274       vice to find out that the client did not send the request at all.  When
275       the client host provides IDENT service, a negative IDENT lookup  result
276       (the client matches `UNKNOWN@host') is strong evidence of a host spoof‐
277       ing attack.
278
279       A positive IDENT lookup result (the  client  matches  `KNOWN@host')  is
280       less  trustworthy.  It  is  possible  for an intruder to spoof both the
281       client connection and the IDENT  lookup,  although  doing  so  is  much
282       harder  than spoofing just a client connection. It may also be that the
283       client´s IDENT server is lying.
284
285       Note: IDENT lookups don´t work with UDP services.
286

EXAMPLES

288       The language is flexible enough that different types of access  control
289       policy  can  be expressed with a minimum of fuss. Although the language
290       uses two access control tables, the most common policies can be  imple‐
291       mented with one of the tables being trivial or even empty.
292
293       When  reading  the  examples  below it is important to realize that the
294       allow table is scanned before the deny table, that  the  search  termi‐
295       nates  when  a match is found, and that access is granted when no match
296       is found at all.
297
298       The examples use host and domain names. They can be improved by includ‐
299       ing address and/or network/netmask information, to reduce the impact of
300       temporary name server lookup failures.
301

MOSTLY CLOSED

303       In this case, access is denied by default. Only  explicitly  authorized
304       hosts are permitted access.
305
306       The default policy (no access) is implemented with a trivial deny file:
307
308       /etc/hosts.deny:
309          ALL: ALL
310
311       This  denies all service to all hosts, unless they are permitted access
312       by entries in the allow file.
313
314       The explicitly authorized hosts are listed  in  the  allow  file.   For
315       example:
316
317       /etc/hosts.allow:
318          ALL: LOCAL @some_netgroup
319          ALL: .foobar.edu EXCEPT terminalserver.foobar.edu
320
321       The first rule permits access from hosts in the local domain (no `.´ in
322       the host name) and from members of  the  some_netgroup  netgroup.   The
323       second  rule  permits  access  from  all hosts in the foobar.edu domain
324       (notice the leading dot), with  the  exception  of  terminalserver.foo‐
325       bar.edu.
326

MOSTLY OPEN

328       Here, access is granted by default; only explicitly specified hosts are
329       refused service.
330
331       The default policy (access granted) makes the allow file  redundant  so
332       that it can be omitted.  The explicitly non-authorized hosts are listed
333       in the deny file. For example:
334
335       /etc/hosts.deny:
336          ALL: some.host.name, .some.domain
337          ALL EXCEPT in.fingerd: other.host.name, .other.domain
338
339       The first rule denies some hosts and domains all services;  the  second
340       rule still permits finger requests from other hosts and domains.
341

BOOBY TRAPS

343       The  next  example permits tftp requests from hosts in the local domain
344       (notice the leading dot).  Requests from any other  hosts  are  denied.
345       Instead  of the requested file, a finger probe is sent to the offending
346       host. The result is mailed to the superuser.
347
348       /etc/hosts.allow:
349          in.tftpd: LOCAL, .my.domain
350
351       /etc/hosts.deny:
352          in.tftpd: ALL: spawn (/some/where/safe_finger -l @%h | \
353               /usr/ucb/mail -s %d-%h root) &
354
355       The safe_finger command comes with  the  tcpd  wrapper  and  should  be
356       installed in a suitable place. It limits possible damage from data sent
357       by the remote finger server.  It gives better protection than the stan‐
358       dard finger command.
359
360       The  expansion  of the %h (client host) and %d (service name) sequences
361       is described in the section on shell commands.
362
363       Warning: do not booby-trap your finger daemon, unless you are  prepared
364       for infinite finger loops.
365
366       On  network  firewall  systems  this trick can be carried even further.
367       The typical network firewall only provides a limited set of services to
368       the outer world. All other services can be "bugged" just like the above
369       tftp example. The result is an excellent early-warning system.
370

DIAGNOSTICS

372       An error is reported when a syntax error is found in a host access con‐
373       trol rule; when the length of an access control rule exceeds the capac‐
374       ity of an internal buffer; when an access control rule  is  not  termi‐
375       nated  by  a  newline character; when the result of %<letter> expansion
376       would overflow an internal  buffer;  when  a  system  call  fails  that
377       shouldn´t.  All problems are reported via the syslog daemon.
378

FILES

380       /etc/hosts.allow, (daemon,client) pairs that are granted access.
381       /etc/hosts.deny, (daemon,client) pairs that are denied access.
382

SEE ALSO

384       tcpd(8) tcp/ip daemon wrapper program.
385       tcpdchk(8), tcpdmatch(8), test programs.
386

BUGS

388       If  a name server lookup times out, the host name will not be available
389       to the access control software, even though the host is registered.
390
391       Domain name server lookups are case insensitive; NIS (formerly YP) net‐
392       group lookups are case sensitive.
393

AUTHOR

395       Wietse Venema (wietse@wzv.win.tue.nl)
396       Department of Mathematics and Computing Science
397       Eindhoven University of Technology
398       Den Dolech 2, P.O. Box 513,
399       5600 MB Eindhoven, The Netherlands
400
401
402
403
404                                                               HOSTS_ACCESS(5)
Impressum