HOSTAPD.CONF(5)           OpenBSD Programmer's Manual          HOSTAPD.CONF(5)

NAME
     hostapd.conf - configuration file for the Host Access Point daemon

DESCRIPTION
     hostapd.conf is the configuration file for the hostapd(8) daemon.

SECTIONS
     The hostapd.conf file is divided into four main sections.

     Macros
           User-defined variables may be defined and used later, simplifying
           the configuration file.

     Tables
           Tables provide a mechanism to handle a large number of link layer
           addresses easily, with increased performance and flexibility.

     Global Configuration
           Global runtime settings for hostapd(8).

     Event Rules
           Event rules provide a powerful mechanism to trigger certain actions
           when receiving specified IEEE 802.11 frames.

     IP Roaming
           The concepts and details about the optional IP based roaming in
           hostapd(8).

     Comments can be put anywhere in the file using a hash mark (`#'), and ex-
     tend to the end of the current line.

     Additional configuration files can be included with the include keyword,
     for example:

           include "/etc/hostapd.conf.local"

MACROS
     Macros can be defined that will later be expanded in context.  Macro
     names must start with a letter, and may contain letters, digits and un-
     derscores.  Macro names may not be reserved words (for example, set,
     interface, or hostap).  Macros are not expanded inside quotes.

     For example:

           wlan="ath0"
           set iapp handle subtype { ! add notify, radiotap }
           set iapp interface $wlan

TABLES
     Tables are named structures which can hold a collection of link layer ad-
     dresses, masked address ranges, and link layer to IP address assignments.
     Lookups against tables in hostapd(8) are relatively fast, making a single
     rule with tables much more efficient, in terms of processor usage and
     memory consumption, than a large number of rules which differ only in
     link layer addresses.

     Tables are used for hostapd(8) event rules to match specified IEEE 802.11
     link layer addresses and address ranges, and the capability to assign
     link layer to IP addresses and an option netmask is a requirement for ad-
     vanced IAPP functionality.

     Table options may be presented after the table name declaration.  The
     following options are supported:

     const  The table is constant and cannot be later changed from its origi-
            nal definition.

     For example:

           cisco="00:40:06:ff:ff:ff & ff:ff:ff:00:00:00"

           table <black> { $cisco, 00:0d:60:ff:f1:2a }
           table <myess> const {
                   00:00:24:c3:40:18 -> 10.195.64.24,
                   00:00:24:c3:40:19 -> 10.195.64.25,
                   00:00:24:c3:40:1a -> 10.195.64.26
           }
           table <myclient> const {
                   00:05:4e:45:d4:b9 -> 172.23.5.1/30
           }

GLOBAL CONFIGURATION
     The following configuration settings are understood:

     set hostap interface interface | { interface0, interface1, ... }
             Specify the wireless interface running in Host AP mode.  This op-
             tion could be omitted to use hostapd(8) to log received IAPP mes-
             sages.  Multiple hostap interfaces may be specified as a comma-
             separated list, surrounded by curly braces.

     set hostap mode mode
             Specify the Host AP capture mode.  The supported modes are:

                   radiotap  Capture IEEE 802.11 frames with additional radio-
                             tap headers.  They will provide optional but use-
                             ful information like received frame signal lev-
                             els.
                   pcap      Capture plain IEEE 802.11 frames.

     set hostap hopper interface interface | { interface0, interface1, ... }
             Enable a channel hopper on the selected wireless interface.  Mul-
             tiple hostap interfaces may be specified as a comma-separated
             list, surrounded by curly braces.

     set hostap hopper delay number
             Set the delay in milliseconds for the channel hopper before hop-
             ping to the next available channel.  The default value is 800
             milliseconds.

     set iapp interface interface
             Specify the mandatory Inter-Access-Point (IAPP) interface.  It is
             important that the IAPP interface is on a trusted network because
             there is no authentication and an attacker could force disassoci-
             ation of selected stations on all listening access points.

     set iapp [address | route] roaming table <table>
             Specify a table used for IP Roaming lookups of link layer address
             to IP address or subnet assignments.

     set iapp handle subtype subtype | { subtype0, subtype1, ... }
             Specify the IAPP subtypes to use:

                   [not] add notify
                              Send and receive ADD.notify messages.  This op-
                              tion is enabled by default.
                   [not] radiotap
                              Receive radiotap messages.  This option is en-
                              abled by default.
                   [not] [address | route] roaming
                              Enable dynamic roaming of IP addresses or
                              routes.  These options are disabled by default.

     set iapp mode mode
             Specify the IAPP mode.  The supported modes are:

                   multicast [address ipv4addr] [port number] [ttl number]
                              Use multicast(4) frames.  A multicast time-to-
                              live (TTL) of 2 or higher is required to allow
                              multicast forwarding, for example for use with
                              mrouted(8).
                   broadcast [port number]
                              Use broadcast frames.

             The default is multicast using the multicast address 224.0.1.178
             and port 3517 with a TTL limited to 1 hop.  Some access point
             vendors still use broadcast with the pre-standard IAPP port 2313.

EVENT RULES
     Event rules provide a powerful way to trigger a certain action when re-
     ceiving specified IEEE 802.11 frames on the hostap interface.  The rules
     are handled in sequential order, from first to last.  Rules are handled
     without a state: each rule is processed independently from the others and
     from any previous actions.  This behaviour is somewhat different to that
     of packet filter rules specified in pf.conf(5).

     All hostapd(8) event rules are single line statements beginning with the
     mandatory hostap handle keywords and optional rule options, interface,
     frame matching, a specified action, a limit, and a minimal rate:

           hostap handle [option] [interface] [frame] [action] [limit] [rate]

     Some rule statements support the optional keyword not, also represented
     by the ! operator, for inverse matching.

     The optional parts are defined below.

   Rule Option
     The rule option will modify the behaviour of handling the statement.
     There are two possible options, quick and skip.  If either the keyword
     quick or the keyword skip is specified, no further event rules will be
     handled for this frame after processing this rule successfully.  The key-
     word skip additionally skips any further IAPP processing of the frame,
     which is normally done after handling the event rules.

   Rule Interface
     The rule interface specifies the hostap interface the rule is matched on.
     The available interface list is specified by the global set hostap
     interface configuration setting.

           on [not] interface

     If not given, the event rule is matched on all available hostap inter-
     faces.

   Rule Frame
     The frame description specifies a mechanism to match IEEE 802.11 frames.

     any     Match all frames.

     frame [type] [dir] [from] [to] [bssid] [radiotap]
             Apply rules to frames matching the given parameters.  The parame-
             ters are explained below.

             The type parameter specifies the frame type to match on.  The
             frame type may be specified in the following ways:

             type any
                     Match all frame types.

             type [not] data
                     Match data frames.  Presence of the not keyword negates
                     the match and will match all non-data frames.

             type [not] management [[not] subtype]
                     Match management frames.  The subtype argument may be
                     specified to optionally match management frames of the
                     given subtype.  The subtype match may be negated by spec-
                     ifying the not keyword.  See the Management Frame
                     Subtypes section below for available subtypes specifica-
                     tions.

             The dir parameter specifies the direction the frame is being
             sent.  The direction may be specified in the following ways:

             dir any
                     Match all directions.

             dir framedir
                     Match frames with the given direction framedir.  See the
                     Frame Directions section below for available direction
                     specifications.

             The radiotap rules allow parsing and matching of the extra infor-
             mation reported by the radiotap header.  Support for the speci-
             fied radiotap headers is optional and the specific parameters de-
             pend on the radiotap elements reported by the wireless interface.
             Support for the radiotap data link type can be verified with the
             tcpdump(8) command.  These rules require hostap mode radiotap in
             the global configuration.

             signal [operator] percentage %
                     Match the signal quality of the received frame.

             freq [operator] value (GHz | MHz)
                     Match the transmit rate of the received frame.

             txrate [operator] rate Mb
                     Match the frequency of the received frame.

             The radiotap rules support the following operators.  If omitted,
             the specified value will be checked if it is equal or not.

                   =       (equal)
                   !=      (not equal)
                   <       (less than)
                   <=      (less than or equal)
                   >       (greater than)
                   >=      (greater than or equal)

             The from, to, and bssid parameters specify the IEEE 802.11 ad-
             dress fields to match on.  They can be specified in the following
             ways:

             (from | to | bssid) any
                     Allow all addresses for the specified address field.

             (from | to | bssid) [not] <table>
                     Allow allow addresses from the given <table> (see Tables
                     above) for the specified address field.

             (from | to | bssid) [not] lladdr
                     Allow the given address lladdr for the specified address
                     field.

   Rule Action
     An optional action is triggered if a received IEEE 802.11 frame matches
     the frame description.  The following actions are supported:

     with frame type [dir] from to bssid
             Send an arbitrary constructed frame to the wireless network.  The
             arguments are as follows.

             The type describes the IEEE 802.11 frame type to send, specified
             in the frame control header.  The following frames types are sup-
             ported at present:

             type data
                     Send a data frame.  This is normally used to encapsulate
                     ordinary IEEE 802.3 frames into IEEE 802.11 wireless
                     frames.

             type management subtype
                     Send a management frame with the specified subtype.  Man-
                     agement frames are used to control states and to find ac-
                     cess points and IBSS nodes in IEEE 802.11 networks.  See
                     the Management Frame Subtypes section below for available
                     subtypes specifications.

             The dir describes the direction the IEEE 802.11 frame will be
             sent.  It has the following syntax:

                   dir framedir

             See the Frame Directions section below for available direction
             specifications.

             The from, to, and bssid arguments specify the link layer address
             fields used in IEEE 802.11 frames.  All address fields are manda-
             tory in the frame action.  The optional fourth address field used
             by wireless distribution systems (WDS) is currently not support-
             ed.  Each argument is specified by a keyword of the same name
             (from, to, or bssid) followed by one of the following address
             specifications:

             lladdr    Specify the link layer addresses used in the IEEE
                       802.11 frame address field.  The link layer address
                       `ff:ff:ff:ff:ff:ff' is the IEEE 802.11 broadcast ad-
                       dress.

             &refaddr  Fill in a link layer address from the previously
                       matched IEEE 802.11 frame.  &from will use the source
                       link layer address; &to the destination link layer ad-
                       dress; and &bssid the BSSID link layer address of the
                       previously matched frame.

             random    Use a random link layer address in the specified IEEE
                       802.11 frame address field.  Multicast and broadcast
                       link layer addresses will be skipped.

     with iapp type iapp-type
             Send a hostapd(8) specific IAPP frame with a raw IEEE 802.11
             packet dump of the received frame to the wired network.  The only
             supported iapp-type is radiotap.

     with log [verbose]
             Write informational messages to the local system log (see
             syslogd(8)) or standard error.  If the Rule Rate has been speci-
             fied, log will print the actual rate.

     node add | delete lladdr
             Add or remove the specified node from the internal kernel node
             table.

     resend  Resend the received IEEE 802.11 frame.

   Rule Limit
     It is possible to limit handling of specific rules with the limit key-
     word:

           limit number sec | usec

     In some cases it is absolutely necessary to use limited matching to pro-
     tect hostapd(8) against excessive flooding with IEEE 802.11 frames.  For
     example, beacon frames will be normally received every 100 ms.

   Rule Rate
     It is possible to tell hostapd(8) to trigger the action only after a spe-
     cific rate of matched frames.

           rate number / number sec

     This will help to detect excessive flooding of IEEE 802.11 frames.  For
     example, de-auth flooding is a DoS (Denial of Service) attack against
     IEEE 802.11 wireless networks.

   Management Frame Subtypes
     The subtype describes the IEEE 802.11 frame subtype, specified in the
     frame control header.  The choice of subtypes depends on the used frame
     type.  hostapd(8) currently only supports management frame subtypes.
     Most frame subtypes require an additional subtype-specific header in the
     frame body, but currently only the deauth and disassoc reason codes are
     supported:

        subtype beacon
        A beacon frame.  Wireless access points and devices running in ibss
        master or hostap mode continuously send beacon frames to indicate
        their presence, traffic load, and capabilities.

        subtype deauth [reason]
        A deauthentication frame with an optional reason code.  Deauthenticat-
        ed stations will lose any IEEE 802.11 operational state.

        subtype disassoc [reason]
        A disassociation frame with an optional reason code.

        subtype assoc request
        An association request frame.

        subtype assoc response
        An association response frame.

        subtype atim
        An announcement traffic indication message (ATIM frame).

        subtype auth [open request | response]
        An authentication frame.

        subtype probe request
        A probe request frame.  Probe requests are used to probe for access
        points and IBSS nodes.

        subtype probe response
        A probe response frame.

        subtype reassoc request
        A re-association request frame.

        subtype reassoc response
        A re-association response frame.

     The reason defines a descriptive reason for the actual deauthentication
     or disassociation of a station:

        reason assoc expire
        Disassociated due to inactivity.

        reason assoc leave
        Disassociated because the sending station is leaving or has left the
        wireless network.

        reason assoc toomany
        Disassociated because the access point has reached its limit of asso-
        ciated stations.

        reason auth expire
        Previous authentication no longer valid.

        reason auth leave
        Deauthenticated because the sending station is leaving or has left the
        wireless network.

        reason ie invalid
        IEEE 802.11i extension.

        reason mic failure
        IEEE 802.11i extension.

        reason not authed
        Frame received from unauthenticated station.

        reason assoc not authed
        Frame received from an associated but unauthenticated station.

        reason not assoced
        Frame received from unassociated station.

        reason rsn required
        IEEE 802.11i extension.

        reason rsn inconsistent
        IEEE 802.11i extension.

        reason unspecified
        Unspecified reason.

   Frame Directions
     The direction a frame is being transmitted (framedir) can be specified in
     the following ways:

        dir no ds
        No distribution system direction is used for management frames.

        dir to ds
        A frame sent from a station to the distribution system, the access
        point.

        dir from ds
        A frame from the distribution system, the access point, to a station.

        dir ds to ds
        A frame direction used by wireless distribution systems (WDS) for
        wireless access point to access point communication.

EVENT RULE EXAMPLES
     # Log probe requests locally
     hostap handle type management subtype probe request \
         with log

     # Detect flooding of management frames except beacons.
     # This will detect some possible Denial of Service attacks
     # against the IEEE 802.11 protocol.
     hostap handle skip type management subtype ! beacon \
         with log \
         rate 100 / 10 sec

     # Log rogue access points via IAPP, limited to every second,
     # and skip further IAPP processing.
     hostap handle skip type management subtype beacon bssid !<myess> \
         with iapp type radiotap limit 1 sec

     # Send deauthentication frames to stations associated to rogue APs
     hostap handle type data bssid !<myess> with frame type management \
         subtype deauth reason auth expire \
         from &bssid to &from bssid &bssid

     # Send authentication requests from random station addresses to
     # rogue access points. This is a common way to test the quality of
     # various hostap implementations.
     hostap handle skip type management subtype beacon bssid <pentest> \
         with frame type management subtype auth \
         from random to &bssid bssid &bssid

     # Re-inject a received IEEE 802.11 frame on the interface ath0
     hostap handle on ath0 type management subtype auth with resend

     # Remove a blacklisted node from the kernel node tree
     hostap handle type management subtype auth from <blacklist> \
         with node delete &from

     # Log rogue access points with a strong signal quality on
     # channel 3 (2.422GHz) transmitting frames with 1Mb.
     hostap handle type management subtype beacon bssid !<myess> \
         signal >= 50% txrate 1Mb freq 2.422GHz \
         with log

IP ROAMING
     In a traditional wireless network, multiple access points are members of
     a single layer 3 broadcast domain.  The traffic is bridged between physi-
     cal collision domains, as with the bridge(4) interface in OpenBSD.  This
     may cause problems in large wireless networks with a heavy load of broad-
     cast traffic, like broadcasted ARP, DHCP or ICMP requests.

     hostapd(8) implements IP based roaming to build wireless networks without
     the requirement of a single broadcast domain.  This works as follows:

     1.   Every access point running hostapd(8) is a router to an individual
          internal broadcast domain, without using the bridge(4) interface.
     2.   An increased multicast TTL is used for IAPP communication between
          access points in multiple network segments.  Multicast routing is
          required in the network infrastructure, like an OpenBSD router run-
          ning mrouted(8).
     3.   The configuration file hostapd.conf is used to assign IP subnets to
          link layer addresses.  If a station with the specified link layer
          address successfully associates to the access point, hostapd(8) will
          configure the specified IP address and subnet on the wireless inter-
          face.
     4.   The IAPP ADD.notify message is used to notify other access points
          running hostapd(8) to remove the station and any assigned IP ad-
          dresses or subnets from the wireless interface.
     5.   A dynamic routing daemon like ospfd(8) or bgpd(8) running on the ac-
          cess point will be used to announce the new IP route to the internal
          network and routers.

     For example:

           # Assign IP addresses to layer 2 addresses
           table <clients> {
                   00:02:6f:42:d0:01 -> 172.23.5.1/30
                   00:05:4e:45:d3:b8 -> 172.23.5.4/30
                   00:04:2e:12:03:e0 -> 172.23.5.8/30
           }

           # Global options
           set hostap interface ath0
           set hostap mode radiotap
           set iapp interface sis0
           set iapp address roaming table <clients>
           set iapp handle subtype address roaming
           set iapp mode multicast ttl 2

FILES
     /etc/hostapd.conf  Default location of the configuration file.

SEE ALSO
     hostapd(8)

AUTHORS
     The hostapd(8) program was written by Reyk Floeter <reyk@openbsd.org>.

CAVEATS
     IP Roaming requires statically assigned IP addresses of stations and does
     not support DHCP at present.

OpenBSD 4.7                     April 16, 2009                               9
