src/lib/libwrap/hosts_access.5 - annotate

Return to hosts_access.5 CVS log

Up to [cvs.NetBSD.org] / src / lib / libwrap

Annotation of src/lib/libwrap/hosts_access.5, Revision 1.16

1.1 mrg 1: .TH HOSTS_ACCESS 5
2: .SH NAME
1.4 mrg 3: hosts_access,
4: hosts.allow,
1.5 christos 5: hosts.deny \- format of host access control files
1.1 mrg 6: .SH DESCRIPTION
7: This manual page describes a simple access control language that is
8: based on client (host name/address, user name), and server (process
1.14 wiz 9: name, host name/address) patterns.
10: Examples are given at the end.
11: The impatient reader is encouraged to skip to the EXAMPLES section for a
1.1 mrg 12: quick introduction.
13: .PP
1.3 cjs 14: Note that in a `stock' installation of the tcp_wrappers package, a
15: program called \fItcpd\fR is called from \fI/etc/inetd.conf\fR, and
16: this program performs the wrapper checks and then executes the daemon.
17: In NetBSD \fIinetd\fR(8) has been modified to perform this check
18: internally, and so tcpd is neither used nor supplied.
19: .PP
20: Also note that libwrap under NetBSD uses the extensions to the access
21: control language as described in the \fIhosts_options\fR(5).
1.1 mrg 22: .PP
1.2 perry 23: In the following text, \fIdaemon\fR is the process name of a
1.1 mrg 24: network daemon process, and \fIclient\fR is the name and/or address of
1.14 wiz 25: a host requesting service.
26: Network daemon process names are specified in the inetd configuration file.
1.5 christos 27: .SH "ACCESS CONTROL FILES"
1.14 wiz 28: The access control software consults two files.
29: The search stops at the first match:
1.1 mrg 30: .IP \(bu
31: Access will be granted when a (daemon,client) pair matches an entry in
32: the \fI/etc/hosts.allow\fR file.
33: .IP \(bu
34: Otherwise, access will be denied when a (daemon,client) pair matches an
35: entry in the \fI/etc/hosts.deny\fR file.
36: .IP \(bu
37: Otherwise, access will be granted.
38: .PP
39: A non-existing access control file is treated as if it were an empty
1.14 wiz 40: file.
41: Thus, access control can be turned off by providing no access
1.1 mrg 42: control files.
1.5 christos 43: .SH "ACCESS CONTROL RULES"
1.14 wiz 44: Each access control file consists of zero or more lines of text.
45: These lines are processed in order of appearance.
46: The search terminates when a match is found.
47: .IP \(bu
48: A newline character is ignored when it is preceded by a backslash character.
49: This permits you to break up long lines so that they are easier to edit.
50: \fBWARNING:\fP The total length of an entry can be no
1.5 christos 51: more than 2047 characters long including the final newline.
1.1 mrg 52: .IP \(bu
53: Blank lines or lines that begin with a `#\' character are ignored.
54: This permits you to insert comments and whitespace so that the tables
55: are easier to read.
56: .IP \(bu
57: All other lines should satisfy the following format, things between []
58: being optional:
59: .sp
60: .ti +3
1.3 cjs 61: daemon_list : client_list : option : option ...
1.1 mrg 62: .PP
63: \fIdaemon_list\fR is a list of one or more daemon process names
1.11 wiz 64: (argv[0] values) or wildcards (see below).
1.1 mrg 65: .PP
66: \fIclient_list\fR is a list
67: of one or more host names, host addresses, patterns or wildcards (see
68: below) that will be matched against the client host name or address.
1.10 itojun 69: When a client_list item needs to include colon character (for IPv6 addresses),
70: the item needs to be wrapped with square bracket.
1.1 mrg 71: .PP
72: The more complex forms \fIdaemon@host\fR and \fIuser@host\fR are
73: explained in the sections on server endpoint patterns and on client
74: username lookups, respectively.
75: .PP
1.11 wiz 76: List elements should be separated by blanks and/or commas.
1.1 mrg 77: .PP
78: With the exception of NIS (YP) netgroup lookups, all access control
79: checks are case insensitive.
80: .ne 4
81: .SH PATTERNS
82: The access control language implements the following patterns:
83: .IP \(bu
1.14 wiz 84: A string that begins with a `.\' character.
85: A host name is matched if
86: the last components of its name match the specified pattern.
87: For example, the pattern `.tue.nl\' matches the host name
1.1 mrg 88: `wzv.win.tue.nl\'.
89: .IP \(bu
1.14 wiz 90: A string that ends with a `.\' character.
91: A host address is matched if
92: its first numeric fields match the given string.
93: For example, the
1.1 mrg 94: pattern `131.155.\' matches the address of (almost) every host on the
95: Eind\%hoven University network (131.155.x.x).
96: .IP \(bu
97: A string that begins with an `@\' character is treated as an NIS
1.14 wiz 98: (formerly YP) netgroup name.
99: A host name is matched if it is a host member of the specified netgroup.
100: Netgroup matches are not supported
1.1 mrg 101: for daemon process names or for client user names.
102: .IP \(bu
103: An expression of the form `n.n.n.n/m.m.m.m\' is interpreted as a
1.14 wiz 104: `net/mask\' pair.
105: A host address is matched if `net\' is equal to the
106: bitwise AND of the address and the `mask\'.
107: For example, the net/mask
1.1 mrg 108: pattern `131.155.72.0/255.255.254.0\' matches every address in the
109: range `131.155.72.0\' through `131.155.73.255\'.
1.10 itojun 110: Note that `m.m.m.m\' portion must always be specified.
111: .IP \(bu
112: An expression of the form `ipv6-addr/ipv6-mask\' is interpreted as
113: masked IPv6 address match, just like masked IPv4 address match (see above).
114: Note that `ipv6-mask\' portion must always be specified.
115: .IP \(bu
116: An expression of the form `ipv6-addr/prefixlen\' is interpreted as
117: masked IPv6 address match (with mask specified by numeric prefixlen),
118: just like masked IPv4 address match (see above).
119: Note that `prefixlen\' portion must always be specified.
1.16 ! christos 120: .IP \(bu
! 121: A string that begins with a `/\' character is treated as a file
! 122: name. A host name or address is matched if it matches any host name
! 123: or address pattern listed in the named file. The file format is
! 124: zero or more lines with zero or more host name or address patterns
! 125: separated by whitespace. A file name pattern can be used anywhere
! 126: a host name or address pattern can be used.
1.1 mrg 127: .SH WILDCARDS
128: The access control language supports explicit wildcards:
129: .IP ALL
130: The universal wildcard, always matches.
131: .IP LOCAL
132: Matches any host whose name does not contain a dot character.
133: .IP UNKNOWN
134: Matches any user whose name is unknown, and matches any host whose name
1.14 wiz 135: \fIor\fR address are unknown.
136: This pattern should be used with care:
137: host names may be unavailable due to temporary name server problems.
138: A network address will be unavailable when the software cannot figure out
1.1 mrg 139: what type of network it is talking to.
140: .IP KNOWN
141: Matches any user whose name is known, and matches any host whose name
1.14 wiz 142: \fIand\fR address are known.
143: This pattern should be used with care:
144: host names may be unavailable due to temporary name server problems.
145: A network address will be unavailable when the software cannot figure out
1.1 mrg 146: what type of network it is talking to.
147: .IP PARANOID
1.3 cjs 148: Matches any host whose name does not match its address.
149: Note that unlike the default mode of \fItcpd\fR, NetBSD \fIinetd\fR
150: does not automatically drop these requests; you must explicitly
1.14 wiz 151: drop them in your \fI/etc/hosts.allow\fR or \fI/etc/hosts.deny\fR file.
1.6 christos 152: .IP "{RBL}.\fIdomain\fR"
153: Matches any host whose reversed address appears in the DNS under
1.14 wiz 154: \fIdomain\fR.
155: The primary such domain used for blocking unsolicited
1.6 christos 156: commercial e-mail (spam) is `.rbl.maps.vix.com\'.
1.1 mrg 157: .ne 6
158: .SH OPERATORS
159: .IP EXCEPT
160: Intended use is of the form: `list_1 EXCEPT list_2\'; this construct
161: matches anything that matches \fIlist_1\fR unless it matches
1.14 wiz 162: \fIlist_2\fR.
163: The EXCEPT operator can be used in daemon_lists and in client_lists.
164: The EXCEPT operator can be nested: if the control
1.1 mrg 165: language would permit the use of parentheses, `a EXCEPT b EXCEPT c\'
166: would parse as `(a EXCEPT (b EXCEPT c))\'.
167: .br
168: .ne 6
169: .SH % EXPANSIONS
1.3 cjs 170: The following expansions are available within some options:
1.1 mrg 171: .IP "%a (%A)"
172: The client (server) host address.
173: .IP %c
174: Client information: user@host, user@address, a host name, or just an
175: address, depending on how much information is available.
176: .IP %d
177: The daemon process name (argv[0] value).
178: .IP "%h (%H)"
179: The client (server) host name or address, if the host name is
180: unavailable.
181: .IP "%n (%N)"
182: The client (server) host name (or "unknown" or "paranoid").
183: .IP %p
184: The daemon process id.
185: .IP %s
186: Server information: daemon@host, daemon@address, or just a daemon name,
187: depending on how much information is available.
188: .IP %u
189: The client user name (or "unknown").
190: .IP %%
191: Expands to a single `%\' character.
192: .PP
193: Characters in % expansions that may confuse the shell are replaced by
194: underscores.
1.5 christos 195: .SH "SERVER ENDPOINT PATTERNS"
1.1 mrg 196: In order to distinguish clients by the network address that they
197: connect to, use patterns of the form:
198: .sp
199: .ti +3
200: process_name@host_pattern : client_list ...
201: .sp
202: Patterns like these can be used when the machine has different internet
1.14 wiz 203: addresses with different internet hostnames.
204: Service providers can use
1.1 mrg 205: this facility to offer FTP, GOPHER or WWW archives with internet names
1.14 wiz 206: that may even belong to different organizations.
207: See also the `twist' option in the hosts_options(5) document.
208: Some systems (Solaris, FreeBSD, NetBSD) can have more than one
209: internet address on one physical interface; with other systems
210: you may have to resort to SLIP or PPP pseudo interfaces that
211: live in a dedicated network address space.
1.1 mrg 212: .sp
213: The host_pattern obeys the same syntax rules as host names and
1.14 wiz 214: addresses in client_list context.
215: Usually, server endpoint information
1.1 mrg 216: is available only with connection-oriented services.
1.5 christos 217: .SH "CLIENT USERNAME LOOKUP"
1.1 mrg 218: When the client host supports the RFC 931 protocol or one of its
219: descendants (TAP, IDENT, RFC 1413) the wrapper programs can retrieve
1.14 wiz 220: additional information about the owner of a connection.
221: Client username information, when available,
222: is logged together with the client host
1.1 mrg 223: name, and can be used to match patterns like:
224: .PP
225: .ti +3
226: daemon_list : ... user_pattern@host_pattern ...
227: .PP
228: The daemon wrappers can be configured at compile time to perform
229: rule-driven username lookups (default) or to always interrogate the
1.14 wiz 230: client host.
231: In the case of rule-driven username lookups, the above
1.1 mrg 232: rule would cause username lookup only when both the \fIdaemon_list\fR
1.11 wiz 233: and the \fIhost_pattern\fR match.
1.1 mrg 234: .PP
235: A user pattern has the same syntax as a daemon process pattern, so the
1.14 wiz 236: same wildcards apply (netgroup membership is not supported).
237: One should not get carried away with username lookups, though.
1.1 mrg 238: .IP \(bu
239: The client username information cannot be trusted when it is needed
1.14 wiz 240: most, i.e. when the client system has been compromised.
241: In general,
1.1 mrg 242: ALL and (UN)KNOWN are the only user name patterns that make sense.
243: .IP \(bu
244: Username lookups are possible only with TCP-based services, and only
245: when the client host runs a suitable daemon; in all other cases the
246: result is "unknown".
247: .IP \(bu
248: A well-known UNIX kernel bug may cause loss of service when username
1.14 wiz 249: lookups are blocked by a firewall.
250: The wrapper README document
1.1 mrg 251: describes a procedure to find out if your kernel has this bug.
252: .IP \(bu
1.14 wiz 253: Username lookups may cause noticeable delays for non-UNIX users.
254: The default timeout for username lookups is 10 seconds: too short to cope
1.1 mrg 255: with slow networks, but long enough to irritate PC users.
256: .PP
1.14 wiz 257: Selective username lookups can alleviate the last problem.
258: For example, a rule like:
1.1 mrg 259: .PP
260: .ti +3
261: daemon_list : @pcnetgroup ALL@ALL
262: .PP
263: would match members of the pc netgroup without doing username lookups,
264: but would perform username lookups with all other systems.
1.5 christos 265: .SH "DETECTING ADDRESS SPOOFING ATTACKS"
1.1 mrg 266: A flaw in the sequence number generator of many TCP/IP implementations
267: allows intruders to easily impersonate trusted hosts and to break in
1.14 wiz 268: via, for example, the remote shell service.
1.15 wiz 269: The IDENT (RFC 931 etc.) service can be used to detect such and
1.14 wiz 270: other host address spoofing attacks.
1.1 mrg 271: .PP
272: Before accepting a client request, the wrappers can use the IDENT
273: service to find out that the client did not send the request at all.
274: When the client host provides IDENT service, a negative IDENT lookup
275: result (the client matches `UNKNOWN@host') is strong evidence of a host
276: spoofing attack.
277: .PP
278: A positive IDENT lookup result (the client matches `KNOWN@host') is
1.14 wiz 279: less trustworthy.
280: It is possible for an intruder to spoof both the
1.1 mrg 281: client connection and the IDENT lookup, although doing so is much
1.14 wiz 282: harder than spoofing just a client connection.
283: It may also be that the client\'s IDENT server is lying.
1.1 mrg 284: .PP
1.11 wiz 285: Note: IDENT lookups don\'t work with UDP services.
1.1 mrg 286: .SH EXAMPLES
287: The language is flexible enough that different types of access control
1.14 wiz 288: policy can be expressed with a minimum of fuss.
289: Although the language
1.1 mrg 290: uses two access control tables, the most common policies can be
291: implemented with one of the tables being trivial or even empty.
292: .PP
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
295: terminates when a match is found, and that access is granted when no
296: match is found at all.
297: .PP
1.14 wiz 298: The examples use host and domain names.
299: They can be improved by
1.1 mrg 300: including address and/or network/netmask information, to reduce the
301: impact of temporary name server lookup failures.
1.5 christos 302: .SH "MOSTLY CLOSED"
1.14 wiz 303: In this case, access is denied by default.
304: Only explicitly authorized hosts are permitted access.
1.1 mrg 305: .PP
1.14 wiz 306: The default policy (no access) is implemented with a trivial deny file:
1.1 mrg 307: .PP
308: .ne 2
1.11 wiz 309: /etc/hosts.deny:
1.1 mrg 310: .in +3
311: ALL: ALL
312: .PP
313: This denies all service to all hosts, unless they are permitted access
314: by entries in the allow file.
315: .PP
316: The explicitly authorized hosts are listed in the allow file.
317: For example:
318: .PP
319: .ne 2
1.11 wiz 320: /etc/hosts.allow:
1.1 mrg 321: .in +3
322: ALL: LOCAL @some_netgroup
323: .br
324: ALL: .foobar.edu EXCEPT terminalserver.foobar.edu
325: .PP
326: The first rule permits access from hosts in the local domain (no `.\'
1.14 wiz 327: in the host name) and from members of the \fIsome_netgroup\fP netgroup.
328: The second rule permits access from all hosts in the
1.1 mrg 329: \fIfoobar.edu\fP domain (notice the leading dot), with the exception of
330: \fIterminalserver.foobar.edu\fP.
1.5 christos 331: .SH "MOSTLY OPEN"
1.1 mrg 332: Here, access is granted by default; only explicitly specified hosts are
1.11 wiz 333: refused service.
1.1 mrg 334: .PP
335: The default policy (access granted) makes the allow file redundant so
1.14 wiz 336: that it can be omitted.
337: The explicitly non-authorized hosts are listed in the deny file.
338: For example:
1.1 mrg 339: .PP
340: /etc/hosts.deny:
341: .in +3
342: ALL: some.host.name, .some.domain
343: .br
344: ALL EXCEPT in.fingerd: other.host.name, .other.domain
345: .PP
346: The first rule denies some hosts and domains all services; the second
347: rule still permits finger requests from other hosts and domains.
1.5 christos 348: .SH "BOOBY TRAPS"
1.1 mrg 349: The next example permits tftp requests from hosts in the local domain
1.14 wiz 350: (notice the leading dot).
351: Requests from any other hosts are denied.
352: Instead of the requested file, a finger probe is sent to the offending host.
353: The result is mailed to the superuser.
1.1 mrg 354: .PP
355: .ne 2
356: /etc/hosts.allow:
357: .in +3
358: .nf
359: in.tftpd: LOCAL, .my.domain
360: .PP
361: .ne 2
362: /etc/hosts.deny:
363: .in +3
364: .nf
1.3 cjs 365: in.tftpd: ALL: spawn (/some/where/safe_finger -l @%h | \\
1.12 ross 366: /usr/ucb/mail -s %d-%h root) \*[Am]
1.1 mrg 367: .fi
368: .PP
1.3 cjs 369: (The safe_finger command can be gotten from the tcp_wrappers package and
1.14 wiz 370: installed in a suitable place.
371: It limits possible damage from data sent by the remote finger server.
372: It gives better protection than the standard finger command.)
1.1 mrg 373: .PP
374: The expansion of the %h (client host) and %d (service name) sequences
375: is described in the section on shell commands.
376: .PP
377: Warning: do not booby-trap your finger daemon, unless you are prepared
378: for infinite finger loops.
379: .PP
380: On network firewall systems this trick can be carried even further.
381: The typical network firewall only provides a limited set of services to
1.14 wiz 382: the outer world.
383: All other services can be "bugged" just like the above tftp example.
384: The result is an excellent early-warning system.
1.1 mrg 385: .br
386: .ne 4
387: .SH DIAGNOSTICS
388: An error is reported when a syntax error is found in a host access
389: control rule; when the length of an access control rule exceeds the
390: capacity of an internal buffer; when an access control rule is not
1.12 ross 391: terminated by a newline character; when the result of %\*[Lt]letter\*[Gt]
1.1 mrg 392: expansion would overflow an internal buffer; when a system call fails
1.14 wiz 393: that shouldn\'t.
394: All problems are reported via the syslog daemon.
1.1 mrg 395: .SH FILES
396: .na
397: .nf
398: /etc/hosts.allow, (daemon,client) pairs that are granted access.
399: /etc/hosts.deny, (daemon,client) pairs that are denied access.
400: .ad
401: .fi
1.5 christos 402: .SH "SEE ALSO"
1.1 mrg 403: .nf
1.9 bouyer 404: hosts_options(5), hosts_access(3)
405: tcpdchk(8), tcpdmatch(8), test programs.
1.1 mrg 406: .SH BUGS
407: If a name server lookup times out, the host name will not be available
408: to the access control software, even though the host is registered.
409: .PP
410: Domain name server lookups are case insensitive; NIS (formerly YP)
411: netgroup lookups are case sensitive.
1.5 christos 412: .PP
413: The total length of an entry can be no more than 2047 characters long,
414: including the final newline.
1.1 mrg 415: .SH AUTHOR
416: .na
417: .nf
418: Wietse Venema (wietse@wzv.win.tue.nl)
419: Department of Mathematics and Computing Science
420: Eindhoven University of Technology
1.11 wiz 421: Den Dolech 2, P.O. Box 513,
1.1 mrg 422: 5600 MB Eindhoven, The Netherlands
1.13 wiz 423: .\" @(#) hosts_access.5 1.20 95/01/30 19:51:46
1.16 ! christos 424: .\" $NetBSD: hosts_access.5,v 1.15 2003/09/07 16:22:22 wiz Exp $

CVSweb <webmaster@jp.NetBSD.org>