Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
AUTHPF(8)               FreeBSD System Manager's Manual              AUTHPF(8)

     authpf - authenticating gateway user shell


     authpf is a user shell for authenticating gateways.  It is used to change
     pf(4) rules when a user authenticates and starts a session with sshd(8)
     and to undo these changes when the user's session exits.  It is designed
     for changing filter and translation rules for an individual source IP
     address as long as a user maintains an active ssh(1) session.  Typical
     use would be for a gateway that authenticates users before allowing them
     Internet use, or a gateway that allows different users into different
     places.  authpf logs the successful start and end of a session to
     syslogd(8).  This, combined with properly set up filter rules and secure
     switches, can be used to ensure users are held accountable for their
     network traffic.

     authpf can add filter and translation rules using the syntax described in
     pf.conf(5).  authpf requires that the pf(4) system be enabled before use.

     authpf is meant to be used with users who can connect via ssh(1) only.
     On startup, authpf retrieves the client's connecting IP address via the
     SSH_CLIENT environment variable and, after performing additional access
     checks, reads a template file to determine what filter and translation
     rules (if any) to add.  On session exit the same rules that were added at
     startup are removed.

     Each authpf process stores its rules in a separate ruleset inside a pf(4)
     anchor shared by all authpf processes.  By default, the anchor name
     "authpf" is used, and the ruleset names equal the username and PID of the
     authpf processes as "username(pid)".  The following rules need to be
     added to the main ruleset /etc/pf.conf in order to cause evaluation of
     any authpf rules:

           nat-anchor authpf
           rdr-anchor authpf
           binat-anchor authpf
           anchor authpf

     Filter and translation rules for authpf use the same format described in
     pf.conf(5).  The only difference is that these rules may (and probably
     should) use the macro user_ip, which is assigned the connecting IP
     address whenever authpf is run.  Additionally, the macro user_id is
     assigned the user name.

     Filter and nat rules will first be searched for in
     /etc/authpf/users/$USER/ and then in /etc/authpf/.  Per-user rules from
     the /etc/authpf/users/$USER/ directory are intended to be used when non-
     default rules are needed on an individual user basis.  It is important to
     ensure that a user can not write or change these configuration files.

     Filter and translation rules are loaded from the file
     /etc/authpf/users/$USER/authpf.rules.  If this file does not exist the
     file /etc/authpf/authpf.rules is used.  The authpf.rules file must exist
     in one of the above locations for authpf to run.

     Translation rules are also loaded from this file.  The use of translation
     rules in an authpf.rules file is optional.

     Options are controlled by the /etc/authpf/authpf.conf file.  If the file
     is empty, defaults are used for all configuration options.  The file
     consists of pairs of the form name=value, one per line.  Currently, the
     allowed values are as follows:

             Use the specified anchor name instead of "authpf".

     On successful invocation, authpf displays a message telling the user he
     or she has been authenticated.  It will additionally display the contents
     of the file /etc/authpf/authpf.message if the file exists and is

     There exist two methods for providing additional granularity to the
     control offered by authpf - it is possible to set the gateway to
     explicitly allow users who have authenticated to ssh(1) and deny access
     to only a few troublesome individuals.  This is done by creating a file
     with the banned user's login name as the filename in /etc/authpf/banned/.
     The contents of this file will be displayed to a banned user, thus
     providing a method for informing the user that they have been banned, and
     where they can go and how to get there if they want to have their service
     restored.  This is the default behaviour.

     It is also possible to configure authpf to only allow specific users
     access.  This is done by listing their login names, one per line, in
     /etc/authpf/authpf.allow.  If "*" is found on a line, then all usernames
     match.  If authpf is unable to verify the user's permission to use the
     gateway, it will print a brief message and die.  It should be noted that
     a ban takes precedence over an allow.

     On failure, messages will be logged to syslogd(8) for the system
     administrator.  The user does not see these, but will be told the system
     is unavailable due to technical difficulties.  The contents of the file
     /etc/authpf/authpf.problem will also be displayed if the file exists and
     is readable.

     authpf maintains the changed filter rules as long as the user maintains
     an active session.  It is important to remember however, that the
     existence of this session means the user is authenticated.  Because of
     this, it is important to configure sshd(8) to ensure the security of the
     session, and to ensure that the network through which users connect is
     secure.  sshd(8) should be configured to use the ClientAliveInterval and
     ClientAliveCountMax parameters to ensure that a ssh session is terminated
     quickly if it becomes unresponsive, or if arp or address spoofing is used
     to hijack the session.  Note that TCP keepalives are not sufficient for
     this, since they are not secure.

     authpf will remove statetable entries that were created during a user's
     session.  This ensures that there will be no unauthenticated traffic
     allowed to pass after the controlling ssh(1) session has been closed.

     authpf is designed for gateway machines which typically do not have
     regular (non-administrative) users using the machine.  An administrator
     must remember that authpf can be used to modify the filter rules through
     the environment in which it is run, and as such could be used to modify
     the filter rules (based on the contents of the configuration files) by
     regular users.  In the case where a machine has regular users using it,
     as well as users with authpf as their shell, the regular users should be
     prevented from running authpf by using the /etc/authpf/authpf.allow or
     /etc/authpf/banned/ facilities.

     authpf modifies the packet filter and address translation rules, and
     because of this it needs to be configured carefully.  authpf will not run
     and will exit silently if the /etc/authpf/authpf.conf file does not
     exist.  After considering the effect authpf may have on the main packet
     filter rules, the system administrator may enable authpf by creating an
     appropriate /etc/authpf/authpf.conf file.

     Control Files - To illustrate the user-specific access control
     mechanisms, let us consider a typical user named bob.  Normally, as long
     as bob can authenticate himself, the authpf program will load the
     appropriate rules.  Enter the /etc/authpf/banned/ directory.  If bob has
     somehow fallen from grace in the eyes of the powers-that-be, they can
     prohibit him from using the gateway by creating the file
     /etc/authpf/banned/bob containing a message about why he has been banned
     from using the network.  Once bob has done suitable penance, his access
     may be restored by moving or removing the file /etc/authpf/banned/bob.

     Now consider a workgroup containing alice, bob, carol and dave.  They
     have a wireless network which they would like to protect from
     unauthorized use.  To accomplish this, they create the file
     /etc/authpf/authpf.allow which lists their login ids, one per line.  At
     this point, even if eve could authenticate to sshd(8), she would not be
     allowed to use the gateway.  Adding and removing users from the work
     group is a simple matter of maintaining a list of allowed userids.  If
     bob once again manages to annoy the powers-that-be, they can ban him from
     using the gateway by creating the familiar /etc/authpf/banned/bob file.
     Though bob is listed in the allow file, he is prevented from using this
     gateway due to the existence of a ban file.

     Distributed Authentication - It is often desirable to interface with a
     distributed password system rather than forcing the sysadmins to keep a
     large number of local password files in sync.  The login.conf(5)
     mechanism in OpenBSD can be used to fork the right shell.  To make that
     happen, login.conf(5) should have entries that look something like this:





     Using a default password file, all users will get authpf as their shell
     except for root who will get /bin/csh.

     SSH Configuration - As stated earlier, sshd(8) must be properly
     configured to detect and defeat network attacks.  To that end, the
     following options should be added to sshd_config(5):

           Protocol 2
           ClientAliveInterval 15
           ClientAliveCountMax 3

     This ensures that unresponsive or spoofed sessions are terminated within
     a minute, since a hijacker should not be able to spoof ssh keepalive

     Banners - Once authenticated, the user is shown the contents of
     /etc/authpf/authpf.message.  This message may be a screen-full of the
     appropriate use policy, the contents of /etc/motd or something as simple
     as the following:

           This means you will be held accountable by the powers that be
           for traffic originating from your machine, so please play nice.

     To tell the user where to go when the system is broken,
     /etc/authpf/authpf.problem could contain something like this:

           Sorry, there appears to be some system problem. To report this
           problem so we can fix it, please phone 1-900-314-1597 or send
           an email to

     Packet Filter Rules - In areas where this gateway is used to protect a
     wireless network (a hub with several hundred ports), the default rule set
     as well as the per-user rules should probably allow very few things
     beyond encrypted protocols like ssh(1), ssl(8), or ipsec(4).  On a
     securely switched network, with plug-in jacks for visitors who are given
     authentication accounts, you might want to allow out everything.  In this
     context, a secure switch is one that tries to prevent address table
     overflow attacks.

     Example /etc/pf.conf:

     # by default we allow internal clients to talk to us using
     # ssh and use us as a dns server.
     nat-anchor authpf
     rdr-anchor authpf
     binat-anchor authpf
     block in on $internal_if from any to any
     pass in quick on $internal_if proto tcp from any to $gateway_addr \
           port = ssh
     pass in quick on $internal_if proto udp from any to $gateway_addr \
           port = domain
     anchor authpf

     For a switched, wired net - This example /etc/authpf/authpf.rules makes
     no real restrictions; it turns the IP address on and off, logging TCP

     external_if = "xl0"
     internal_if = "fxp0"

     pass in log quick on $internal_if proto tcp from $user_ip to any \
           keep state
     pass in quick on $internal_if from $user_ip to any

     For a wireless or shared net - This example /etc/authpf/authpf.rules
     could be used for an insecure network (such as a public wireless network)
     where we might need to be a bit more restrictive.


     # rdr ftp for proxying by ftp-proxy(8)
     rdr on $internal_if proto tcp from $user_ip to any port 21 \
           -> port 8081

     # allow out ftp, ssh, www and https only, and allow user to negotiate
     # ipsec with the ipsec server.
     pass in log quick on $internal_if proto tcp from $user_ip to any \
           port { 21, 22, 80, 443 } flags S/SA
     pass in quick on $internal_if proto tcp from $user_ip to any \
           port { 21, 22, 80, 443 }
     pass in quick proto udp from $user_ip to $ipsec_gw port = isakmp \
           keep state
     pass in quick proto esp from $user_ip to $ipsec_gw

     Dealing with NAT - The following /etc/authpf/authpf.rules shows how to
     deal with NAT, using tags:

     ext_if = "fxp1"
     ext_addr =
     int_if = "fxp0"
     # nat and tag connections...
     nat on $ext_if from $user_ip to any tag $user_ip -> $ext_addr
     pass in quick on $int_if from $user_ip to any
     pass out log quick on $ext_if tagged $user_ip keep state

     With the above rules added by authpf, outbound connections corresponding
     to each users NAT'ed connections will be logged as in the example below,
     where the user may be identified from the ruleset name.

     # tcpdump -n -e -ttt -i pflog0
     Oct 31 19:42:30.296553 rule 0.bbeck(20267).1/0(match): pass out on fxp1: \ > S 2131494121:2131494121(0) win \
     16384 <mss 1460,nop,nop,sackOK> (DF)


     pf(4), pf.conf(5), ftp-proxy(8)

     The authpf program first appeared in OpenBSD 3.1.

     Configuration issues are tricky.  The authenticating ssh(1) connection
     may be secured, but if the network is not secured the user may expose
     insecure protocols to attackers on the same network, or enable other
     attackers on the network to pretend to be the user by spoofing their IP

     authpf is not designed to prevent users from denying service to other

FreeBSD 11.0-PRERELEASE        January 10, 2002        FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help