--- name: "hostapd.conf" section: "5" platform: "openbsd" package: "man" version: "8.0-current-20261101" release: "OpenBSD 8.0-current (2026-11-01)" platforms: ["freebsd", "openbsd"] url: "https://new.carta.tech/hostapd.conf" --- # hostapd.conf(5) configuration file for the Host Access Point daemon ## NAME **hostapd.conf** – configuration file for the Host Access Point daemon ## DESCRIPTION **hostapd.conf** is the configuration file for the [hostapd(8)](/hostapd/8.md) daemon. The **hostapd.conf** file is divided into the following main sections: - MACROS Definitions of variables that can be 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)](/hostapd/8.md). - 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)](/hostapd/8.md). The current line can be extended over multiple lines using a backslash (‘\\’). Comments can be put anywhere in the file using a hash mark (‘#’), and extend to the end of the current line. Care should be taken when commenting out multi-line text: the comment is effective until the end of the entire block. Arguments not beginning with a letter, digit, or underscore must be quoted. Additional configuration files can be included with the **include** keyword, for example: ``` include "/etc/hostapd.conf.local" ``` ## MACROS A macro is defined with a command of the form *name*=*value*. The macro *name* can contain letters, digits, and underscores and cannot be a reserved word (for example, **set**, **interface**, or **hostap**). Within unquoted arguments, the string $*name* is later expanded to *value*. 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 addresses, masked address ranges, and link layer to IP address assignments. Lookups against tables in [hostapd(8)](/hostapd/8.md) 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)](/hostapd/8.md) *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 advanced 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 original definition. For example: ``` cisco="00:40:06:ff:ff:ff & ff:ff:ff:00:00:00" table { $cisco, 00:0d:60:ff:f1:2a } table 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 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 option could be omitted to use [hostapd(8)](/hostapd/8.md) to log received IAPP messages. 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 radiotap headers. They will provide optional but useful information like received frame signal levels. - **pcap** Capture plain IEEE 802.11 frames. - **set** **hostap** **hopper** **interface** *interface* \| {*interface0*, *interface1*, *...*} Enable a channel hopper on the selected wireless interface. Multiple 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 hopping 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 disassociation 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 option is enabled by default. - \[**not**\] **radiotap** Receive *radiotap* messages. This option is enabled 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)](/multicast/4.md) frames. A multicast time-to-live (TTL) of 2 or higher is required to allow multicast forwarding, for example for use with [mrouted(8)](/mrouted/8.md). - **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 receiving 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)](/pf.conf/5.md). All [hostapd(8)](/hostapd/8.md) 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 keyword **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 interfaces. ### 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 parameters 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 specifying the **not** keyword. See the Management Frame Subtypes section below for available subtypes specifications. 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 information reported by the radiotap header. Support for the specified radiotap headers is optional and the specific parameters depend on the radiotap elements reported by the wireless interface. Support for the radiotap data link type can be verified with the [tcpdump(8)](/tcpdump/8.md) 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, in Mbps. 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 address 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 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 supported 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. Management frames are used to control states and to find access 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 mandatory in the frame action. The optional fourth address field used by wireless distribution systems (WDS) is currently not supported. 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 address. - &*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 address; 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)](/hostapd/8.md) 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)](/syslogd/8.md)) or standard error. If the Rule Rate has been specified, 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** keyword: **limit** *number* **sec** \| **usec** In some cases it is absolutely necessary to use limited matching to protect [hostapd(8)](/hostapd/8.md) 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)](/hostapd/8.md) to trigger the action only after a specific **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 denial of service (DoS) 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)](/hostapd/8.md) 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. Deauthenticated 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 associated 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 ! \ with iapp type radiotap limit 1 sec # Send deauthentication frames to stations associated to rogue APs hostap handle type data bssid ! 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 \ 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 \ with node delete &from # Log rogue access points with a strong signal quality on # channel 3 (2.422GHz) transmitting frames with 1Mbps. hostap handle type management subtype beacon bssid ! \ 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 physical collision domains, as with the [bridge(4)](/bridge/4.md) interface in OpenBSD. This may cause problems in large wireless networks with a heavy load of broadcast traffic, like broadcasted ARP, DHCP or ICMP requests. [hostapd(8)](/hostapd/8.md) 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)](/hostapd/8.md) is a router to an individual internal broadcast domain, *without* using the [bridge(4)](/bridge/4.md) 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 running [mrouted(8)](/mrouted/8.md). 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)](/hostapd/8.md) will configure the specified IP address and subnet on the wireless interface. 4. The IAPP *ADD.notify* message is used to notify other access points running [hostapd(8)](/hostapd/8.md) to remove the station and any assigned IP addresses or subnets from the wireless interface. 5. A dynamic routing daemon like [ospfd(8)](/ospfd/8.md) or [bgpd(8)](/bgpd/8.md) running on the access 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 { 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 set iapp handle subtype address roaming set iapp mode multicast ttl 2 ``` ## FILES - */etc/hostapd.conf* Default location of the configuration file. - */etc/examples/hostapd.conf* Example configuration file. ## SEE ALSO [hostapd(8)](/hostapd/8.md) ## AUTHORS The [hostapd(8)](/hostapd/8.md) 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.