2 .\" $OpenBSD: authpf.8,v 1.47 2009/01/06 03:11:50 mcbride Exp $
4 .\" Copyright (c) 1998-2007 Bob Beck (beck@openbsd.org>. All rights reserved.
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
24 .Nd authenticating gateway user shell
30 is a user shell for authenticating gateways.
33 rules when a user authenticates and starts a session with
35 and to undo these changes when the user's session exits.
36 Typical use would be for a gateway that authenticates users before
37 allowing them Internet use, or a gateway that allows different users into
39 Combined with properly set up filter rules and secure switches,
41 can be used to ensure users are held accountable for their network traffic.
42 It is meant to be used with users who can connect via
44 only, and requires the
48 file system mounted at
54 which allows multiple connections to take
55 place from the same IP address.
56 It is useful primarily in cases where connections are tunneled via
57 the gateway system, and can be directly associated with the user name.
58 It cannot ensure accountability when
59 classifying connections by IP address;
60 in this case the client's IP address
61 is not provided to the packet filter via the
66 Additionally, states associated with the client IP address
67 are not purged when the session is ended.
73 the user's shell needs to be set to
76 .Pa /usr/sbin/authpf-noip .
81 syntax to change filter and translation rules for an individual
82 user or client IP address as long as a user maintains an active
84 session, and logs the successful start and end of a session to
87 retrieves the client's connecting IP address via the
89 environment variable and, after performing additional access checks,
90 reads a template file to determine what filter and translation rules
92 maintains the list of IP addresses of connected users in the
95 On session exit the same rules and table entries that were added at startup
96 are removed, and all states associated with the client's IP address are purged.
100 process stores its rules in a separate ruleset inside a
108 name "authpf" is used, and the ruleset names equal the username and PID of the
110 processes as "username(pid)".
111 The following rules need to be added to the main ruleset
113 in order to cause evaluation of any
116 .Bd -literal -offset indent
117 nat-anchor "authpf/*"
118 rdr-anchor "authpf/*"
119 binat-anchor "authpf/*"
123 The "/*" at the end of the anchor name is required for
125 to process the rulesets attached to the anchor by
127 .Sh FILTER AND TRANSLATION RULES
128 Filter and translation rules for
130 use the same format described in
132 The only difference is that these rules may (and probably should) use
135 which is assigned the connecting IP address whenever
138 Additionally, the macro
140 is assigned the user name.
142 Filter and translation rules are stored in a file called
144 This file will first be searched for in
145 .Pa /etc/authpf/users/$USER/
148 Only one of these files will be used if both are present.
150 Per-user rules from the
151 .Pa /etc/authpf/users/$USER/
152 directory are intended to be used when non-default rules
153 are needed on an individual user basis.
154 It is important to ensure that a user can not write or change
155 these configuration files.
159 file must exist in one of the above locations for
163 Options are controlled by the
164 .Pa /etc/authpf/authpf.conf
166 If the file is empty, defaults are used for all
167 configuration options.
168 The file consists of pairs of the form
171 Currently, the allowed values are as follows:
176 name instead of "authpf".
180 name instead of "authpf_users".
183 On successful invocation,
185 displays a message telling the user he or she has been authenticated.
186 It will additionally display the contents of the file
187 .Pa /etc/authpf/authpf.message
188 if the file exists and is readable.
190 There exist two methods for providing additional granularity to the control
193 - it is possible to set the gateway to explicitly allow users who have
196 and deny access to only a few troublesome individuals.
197 This is done by creating a file with the banned user's login name as the
199 .Pa /etc/authpf/banned/ .
200 The contents of this file will be displayed to a banned user, thus providing
201 a method for informing the user that they have been banned, and where they can
202 go and how to get there if they want to have their service restored.
203 This is the default behaviour.
205 It is also possible to configure
207 to only allow specific users access.
208 This is done by listing their login names, one per line, in
209 .Pa /etc/authpf/authpf.allow .
210 A group of users can also be indicated by prepending "%" to the group name,
211 and all members of a login class can be indicated by prepending "@" to the
213 If "*" is found on a line, then all usernames match.
216 is unable to verify the user's permission to use the gateway, it will
217 print a brief message and die.
218 It should be noted that a ban takes precedence over an allow.
220 On failure, messages will be logged to
222 for the system administrator.
223 The user does not see these, but will be told the system is unavailable due to
224 technical difficulties.
225 The contents of the file
226 .Pa /etc/authpf/authpf.problem
227 will also be displayed if the file exists and is readable.
228 .Sh CONFIGURATION ISSUES
230 maintains the changed filter rules as long as the user maintains an
232 It is important to remember however, that the existence
233 of this session means the user is authenticated.
234 Because of this, it is important to configure
236 to ensure the security of the session, and to ensure that the network
237 through which users connect is secure.
239 should be configured to use the
240 .Ar ClientAliveInterval
242 .Ar ClientAliveCountMax
243 parameters to ensure that a ssh session is terminated quickly if
244 it becomes unresponsive, or if arp or address spoofing is used to
246 Note that TCP keepalives are not sufficient for
247 this, since they are not secure.
248 Also note that the various SSH tunnelling mechanisms,
250 .Ar AllowTcpForwarding
253 should be disabled for
255 users to prevent them from circumventing restrictions imposed by the
256 packet filter ruleset.
259 will remove state table entries that were created during a user's
261 This ensures that there will be no unauthenticated traffic
262 allowed to pass after the controlling
264 session has been closed.
267 is designed for gateway machines which typically do not have regular
268 (non-administrative) users using the machine.
269 An administrator must remember that
271 can be used to modify the filter rules through the environment in
272 which it is run, and as such could be used to modify the filter rules
273 (based on the contents of the configuration files) by regular
275 In the case where a machine has regular users using it, as well
278 as their shell, the regular users should be prevented from running
281 .Pa /etc/authpf/authpf.allow
283 .Pa /etc/authpf/banned/
287 modifies the packet filter and address translation rules, and because
288 of this it needs to be configured carefully.
290 will not run and will exit silently if the
291 .Pa /etc/authpf/authpf.conf
293 After considering the effect
295 may have on the main packet filter rules, the system administrator may
298 by creating an appropriate
299 .Pa /etc/authpf/authpf.conf
303 \- To illustrate the user-specific access control
304 mechanisms, let us consider a typical user named bob.
305 Normally, as long as bob can authenticate himself, the
307 program will load the appropriate rules.
309 .Pa /etc/authpf/banned/
311 If bob has somehow fallen from grace in the eyes of the
312 powers-that-be, they can prohibit him from using the gateway by creating
314 .Pa /etc/authpf/banned/bob
315 containing a message about why he has been banned from using the network.
316 Once bob has done suitable penance, his access may be restored by moving or
318 .Pa /etc/authpf/banned/bob .
320 Now consider a workgroup containing alice, bob, carol and dave.
322 wireless network which they would like to protect from unauthorized use.
323 To accomplish this, they create the file
324 .Pa /etc/authpf/authpf.allow
325 which lists their login ids, group prepended with "%", or login class
326 prepended with "@", one per line.
327 At this point, even if eve could authenticate to
329 she would not be allowed to use the gateway.
330 Adding and removing users from
331 the work group is a simple matter of maintaining a list of allowed userids.
332 If bob once again manages to annoy the powers-that-be, they can ban him from
333 using the gateway by creating the familiar
334 .Pa /etc/authpf/banned/bob
336 Though bob is listed in the allow file, he is prevented from using
337 this gateway due to the existence of a ban file.
339 .Sy Distributed Authentication
340 \- It is often desirable to interface with a
341 distributed password system rather than forcing the sysadmins to keep a large
342 number of local password files in sync.
347 can be used to fork the right shell.
350 should have entries that look something like this:
351 .Bd -literal -offset indent
352 shell-default:shell=/bin/csh
356 :shell=/usr/sbin/authpf
369 Using a default password file, all users will get
371 as their shell except for root who will get
374 .Sy SSH Configuration
375 \- As stated earlier,
377 must be properly configured to detect and defeat network attacks.
378 To that end, the following options should be added to
380 .Bd -literal -offset indent
382 ClientAliveInterval 15
383 ClientAliveCountMax 3
386 This ensures that unresponsive or spoofed sessions are terminated within a
387 minute, since a hijacker should not be able to spoof ssh keepalive messages.
390 \- Once authenticated, the user is shown the contents of
391 .Pa /etc/authpf/authpf.message .
392 This message may be a screen-full of the appropriate use policy, the contents
395 or something as simple as the following:
396 .Bd -literal -offset indent
397 This means you will be held accountable by the powers that be
398 for traffic originating from your machine, so please play nice.
401 To tell the user where to go when the system is broken,
402 .Pa /etc/authpf/authpf.problem
403 could contain something like this:
404 .Bd -literal -offset indent
405 Sorry, there appears to be some system problem. To report this
406 problem so we can fix it, please phone 1-900-314-1597 or send
407 an email to remove@bulkmailerz.net.
410 .Sy Packet Filter Rules
411 \- In areas where this gateway is used to protect a
412 wireless network (a hub with several hundred ports), the default rule set as
413 well as the per-user rules should probably allow very few things beyond
414 encrypted protocols like
419 On a securely switched network, with plug-in jacks for visitors who are
420 given authentication accounts, you might want to allow out everything.
421 In this context, a secure switch is one that tries to prevent address table
427 # by default we allow internal clients to talk to us using
428 # ssh and use us as a dns server.
430 gateway_addr="10.0.1.1"
431 nat-anchor "authpf/*"
432 rdr-anchor "authpf/*"
433 binat-anchor "authpf/*"
434 block in on $internal_if from any to any
435 pass in quick on $internal_if proto tcp from any to $gateway_addr \e
437 pass in quick on $internal_if proto udp from any to $gateway_addr \e
442 .Sy For a switched, wired net
444 .Pa /etc/authpf/authpf.rules
445 makes no real restrictions; it turns the IP address on and off, logging
451 pass in log quick on $internal_if proto tcp from $user_ip to any
452 pass in quick on $internal_if from $user_ip to any
455 .Sy For a wireless or shared net
457 .Pa /etc/authpf/authpf.rules
458 could be used for an insecure network (such as a public wireless network) where
459 we might need to be a bit more restrictive.
464 # rdr ftp for proxying by ftp-proxy(8)
465 rdr on $internal_if proto tcp from $user_ip to any port 21 \e
466 -> 127.0.0.1 port 8021
468 # allow out ftp, ssh, www and https only, and allow user to negotiate
469 # ipsec with the ipsec server.
470 pass in log quick on $internal_if proto tcp from $user_ip to any \e
471 port { 21, 22, 80, 443 }
472 pass in quick on $internal_if proto tcp from $user_ip to any \e
473 port { 21, 22, 80, 443 }
474 pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp
475 pass in quick proto esp from $user_ip to $ipsec_gw
480 .Pa /etc/authpf/authpf.rules
481 shows how to deal with NAT, using tags:
484 ext_addr = 129.128.11.10
486 # nat and tag connections...
487 nat on $ext_if from $user_ip to any tag $user_ip -> $ext_addr
488 pass in quick on $int_if from $user_ip to any
489 pass out log quick on $ext_if tagged $user_ip
492 With the above rules added by
494 outbound connections corresponding to each users NAT'ed connections
495 will be logged as in the example below, where the user may be identified
496 from the ruleset name.
498 # tcpdump -n -e -ttt -i pflog0
499 Oct 31 19:42:30.296553 rule 0.bbeck(20267).1/0(match): pass out on fxp1: \e
500 129.128.11.10.60539 > 198.137.240.92.22: S 2131494121:2131494121(0) win \e
501 16384 <mss 1460,nop,nop,sackOK> (DF)
504 .Sy Using the authpf_users table
507 settings can be implemented without an anchor by just using the "authpf_users"
509 For example, the following
511 lines will give SMTP and IMAP access to logged in users:
513 table <authpf_users> persist
514 pass in on $ext_if proto tcp from <authpf_users> \e
515 to port { smtp imap }
518 It is also possible to use the "authpf_users"
520 in combination with anchors.
523 processing can be sped up by looking up the anchor
524 only for packets coming from logged in users:
526 table <authpf_users> persist
527 anchor "authpf/*" from <authpf_users>
528 rdr-anchor "authpf/*" from <authpf_users>
534 allows only one session per client IP address.
535 However in some cases, such as when connections are tunneled via
539 the connections can be authorized based on the userid of the user instead of
540 the client IP address.
541 In this case it is appropriate to use
543 to allow multiple users behind a NAT gateway to connect.
545 .Pa /etc/authpf/authpf.rules
546 example below, the remote user could tunnel a remote desktop session to their
550 workstation_ip="10.2.3.4"
552 pass out on $internal_if from (self) to $workstation_ip port 3389 \e
556 .Bl -tag -width "/etc/authpf/authpf.conf" -compact
557 .It Pa /etc/authpf/authpf.conf
558 .It Pa /etc/authpf/authpf.allow
559 .It Pa /etc/authpf/authpf.rules
560 .It Pa /etc/authpf/authpf.message
561 .It Pa /etc/authpf/authpf.problem
572 program first appeared in
575 Configuration issues are tricky.
578 connection may be secured, but if the network is not secured the user may
579 expose insecure protocols to attackers on the same network, or enable other
580 attackers on the network to pretend to be the user by spoofing their IP
584 is not designed to prevent users from denying service to other users.