update the hostapd.conf(5) manual page with a more detailed description

of the configuration language and grammar.
thanks to jmc@ and jaredy@

1 files changed, 358 insertions, 94 deletions

diff --git a/usr.sbin/hostapd/hostapd.conf.5 b/usr.sbin/hostapd/hostapd.conf.5
index 2339f22b89d..cc8f456421f 100644
--- a/usr.sbin/hostapd/hostapd.conf.5
+++ b/usr.sbin/hostapd/hostapd.conf.5
@@ -1,4 +1,4 @@
-.\" $OpenBSD: hostapd.conf.5,v 1.5 2005/06/17 20:17:01 jmc Exp $
+.\" $OpenBSD: hostapd.conf.5,v 1.6 2005/07/04 18:12:31 reyk Exp $
 .\"
 .\" Copyright (c) 2004, 2005 Reyk Floeter <reyk@vantronix.net>
 .\"
@@ -28,7 +28,7 @@ daemon.
 .Sh SECTIONS
 The
 .Nm
-file is divided into two main sections.
+file is divided into four main sections.
 .Bl -tag -width xxxx
 .It Sy Macros
 User-defined variables may be defined and used later, simplifying the
@@ -79,11 +79,19 @@ large number of rules which differ only in link layer addresses.
 .Pp
 Tables are used for
 .Xr hostapd 8
-.Ic event rules
-to match specified IEEE 802.11 link layer addresses and address ranges
+.Em event rules
+to match specified IEEE 802.11 link layer addresses and address ranges,
 and the capability to assign link layer to IP addresses is a
 requirement for advanced IAPP functionality.
 .Pp
+Table options may be presented after the table name declaration.
+The following options are supported:
+.Bl -tag -width const
+.It Ic const
+The table is constant and cannot be later changed from its original
+definition.
+.El
+.Pp
 For example:
 .Bd -literal -offset indent
 cisco="00:40:06:ff:ff:ff / ff:ff:ff:00:00:00"
@@ -97,53 +105,74 @@ table <myess> const {
 .Ed
 .Sh GLOBAL CONFIGURATION
 The following configuration settings are understood:
-.Bl -tag -width xxxx
+.Bl -tag -width Ds
 .It Ic set hostap interface Ar interface
 Specify the wireless interface running in Host AP mode.
 This option could be omitted to use
 .Xr hostapd 8
 to log received IAPP messages.
+.It Ic set hostap mode Ar mode
+Specify the Host AP mode.
+The supported modes are:
+.Pp
+.Bl -tag -width radiotap -offset indent -compact
+.It Ic radiotap
+<radiotap mode>
+.It Ic pcap
+<pcap mode>
+.El
 .It Ic set iapp interface Ar 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.
 .It Ic set iapp mode Ar mode
-Specify the IAPP mode, if not using the default one.
-IAPP could be used in multicast (default) or in broadcast mode.
-The used multicast group is 224.0.1.178.
+Specify the IAPP mode.
+The supported modes are:
 .Pp
-Possible options:
-.Bd -unfilled -offset indent
-.Ic set iapp mode multicast
-.Ic set iapp mode broadcast
-.Ed
+.Bl -tag -width broadcast -offset indent -compact
+.It Ic multicast
+Use multicast frames.
+.It Ic broadcast
+Use broadcast frames.
+.El
+.Pp
+The default is multicast.
+The multicast group used is 224.0.1.178.
 .El
 .Sh EVENT RULES
 Event rules provide a powerful way to trigger a certain action when
 receiving specified IEEE 802.11 frames on the
-.Ic hostap interface .
+.Em hostap interface .
 The rules are handled in sequential order, from first to last.
 .Pp
 In difference to packet filter rules like in
 .Xr pf.conf 5 ,
 the
 .Xr hostapd 8
-event rules are handled without a state,
+event rules are handled without a state;
 each rule is processed indepedently from the others and from
 any previous actions.
 .Pp
-All hostapd event rules are single line statements beginning with
+All
+.Xr hostapd 8
+event rules are single line statements beginning with
 the mandatory
 .Ic hostap handle
 keywords and optional rule options, frame matching,
-a specified action and a limit:
-.Bd -literal -offset indent
-hostap handle [<option>] [<frame>] [<action>] [<limit>]
+a specified action, and a limit:
+.Bd -filled -offset indent
+.Ic hostap handle
+.Op Ar option
+.Op Ar frame
+.Op Ar action
+.Op Ar limit
 .Ed
 .Pp
-The optional parts are defined below:
-.Bl -tag -width xxxx
-.It Aq Ic option
+The optional parts are defined below.
+.Ss Rule Option
 The rule
-.Ic option
+.Ar option
 will modify the behaviour of handling the statement.
 There are two possible options,
 .Ic quick
@@ -159,93 +188,328 @@ The keyword
 .Ic skip
 additionally skips any further IAPP processing of the frame,
 which is normally done after handling the event rules.
+.Ss Rule Frame
+The
+.Ar frame
+description specifies a mechanism to match IEEE 802.11 frames.
+.Bl -tag -width Ds
+.It Ic any
+Match all frames.
 .It Xo
 .Ic frame
-.Bq Aq Ar type
-.Bq Aq Ar subtype
-.Bq Aq Ar dir
-.Bq Aq Ar from
-.Bq Aq Ar to
-.Bq Aq Ar bssid
+.Op Ar type
+.Op Ar dir
+.Op Ar from
+.Op Ar to
+.Op Ar bssid
 .Xc
+Apply rules to frames matching the given parameters.
+The parameters are explained below.
+.Pp
 The
-.Ic frame
-description specifies a mechanism to match IEEE 802.11 frames.
-.It Ic with Aq Ar action
+.Ar type
+parameter specifies the frame type to match on.
+The frame type may be specified in the following ways:
+.Bl -tag -width Ds
+.It Ic type any
+Match all frame types.
+.It Xo
+.Ic type
+.Op Ic not
+.Ic data
+.Xc
+Match data frames.
+Presence of the
+.Ic not
+keyword negates the match and will match all non-data frames.
+.It Xo
+.Ic type
+.Op Ic not
+.Ic management
+.Oo Op Ic not
+.Ar subtype Oc
+.Xc
+Match management frames.
+The
+.Ar subtype
+argument may be specified to optionally match management frames of the
+given subtype.
+The subtype match may be negated by specifying the
+.Ic not
+keyword.
+See the
+.Sx Management Frame Subtypes
+section below for available subtypes specifications.
+.El
+.Pp
+The
+.Ar dir
+parameter specifies the direction the frame is being sent.
+The direction may be specified in the following ways:
+.Bl -tag -width Ds
+.It Ic dir any
+Match all directions.
+.It Ic dir Ar framedir
+Match frames with the given direction
+.Ar framedir.
+See the
+.Sx Frame Directions
+section below for available direction specifications.
+.El
+.Pp
+The
+.Ar from , to ,
+and
+.Ar bssid
+parameters specify the IEEE 802.11 address fields to match on.
+They can be specified in the following ways:
+.Bl -tag -width Ds
+.It Xo
+.Ic ( from \*(Ba to \*(Ba bssid ) Ic any
+.Xc
+Allow all addresses for the specified address field.
+.It Xo
+.Ic ( from \*(Ba to \*(Ba bssid )
+.Op Ic not
+.Aq Ar table
+.Xc
+Allow allow addresses from the given
+.Aq Ar table
+(see
+.Sx Tables
+above)
+for the specified address field.
+.It Xo
+.Ic ( from \*(Ba to \*(Ba bssid )
+.Op Ic not
+.Ar lladdr
+.Xc
+Allow the given address
+.Ar lladdr
+for the specified address field.
+.El
+.El
+.Ss Rule Action
 An optional
 .Ar action
 is triggered if a received IEEE 802.11 frame matches the frame
 description.
-The following choices are available as an
-.Ar action :
-.Bd -literal
-frame <type> <subtype> [<dir>] <from> <to> <bssid>
-.Ed
-.Bd -unfilled -offset indent
-.Ic type :
-type data
-type management
-.Ed
-.Bd -unfilled -offset indent
-.Ic subtype :
-subtype beacon
-subtype deauth [<reason>]
-subtype assoc request
-subtype assoc resp
-subtype atim
-subtype auth
-subtype probe request
-subtype probe resp
-subtype reassoc request
-subtype reassoc response
-.Ed
-.Bd -unfilled -offset indent
-.Ic reason :
-reason assoc leave
-reason assoc not authed
-reason assoc toomany
-reason auth expire
-reason auth leave
-reason ie invalid
-reason mic failure
-reason not authed
-reason not assoced
-reason rsn required
-reason rsn inconsistent
-reason unspecified
-.Ed
-.Bd -unfilled -offset indent
-.Ic dir :
-dir no ds
-dir to ds
-dir from ds
-dir ds to ds
-.Ed
-.Bd -unfilled -offset indent
-.Ic from/to/bssid :
-( from | to | bssid ) lladdr
-( from | to | bssid ) &refaddr
-.Ed
-.Bd -unfilled
-iapp radiotap
-log [verbose]
-node ( add | delete ) <lladdr>
-resend
-.Ed
+The following actions are supported:
+.Bl -tag -width Ds
 .It Xo
-.Ic limit
-.Aq Ar number
-.Pq Ar sec \*(Ba usec
+.Ic with frame Ar type
+.Op Ar dir
+.Ar from to bssid
 .Xc
-It is possible to
+Send an arbitrary constructed frame to the wireless network.
+The arguments are as follows.
+.Pp
+The
+.Ar type
+describes the IEEE 802.11 frame type to send, specified in the
+frame control header.
+The following frames types are supported at present:
+.Bl -tag -width Ds
+.It Ic type data
+Send a data frame.
+This is normally used to encapsulate ordinary IEEE 802.3
+frames into IEEE 802.11 wireless frames.
+.It Ic type Ic management Ar 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
+.Sx Management Frame Subtypes
+section below for available subtypes specifications.
+.El
+.Pp
+The
+.Ar dir
+describes the direction the IEEE 802.11 frame will be sent.
+It has the following syntax:
+.Bd -filled -offset indent
+.Ic dir Ar framedir
+.Ed
+.Pp
+See the
+.Sx Frame Directions
+section below for available direction specifications.
+.Pp
+The
+.Ar from , to ,
+and
+.Ar 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
+.Po
+.Ic from , to ,
+or
+.Ic bssid
+.Pc
+followed by one of the following address specifications:
+.Bl -tag -width "&refaddr"
+.It Ar lladdr
+Specify the link layer addresses used in the IEEE 802.11 frame address
+field.
+The link layer address
+.Ql ff:ff:ff:ff:ff:ff
+is the IEEE 802.11 broadcast address.
+.It Li & Ns Ar refaddr
+Fill in a link layer address from the previously matched IEEE 802.11
+frame.
+.Ic &from
+will use the source link layer address;
+.Ic &to
+the destination link layer address; and
+.Ic &bssid
+the BSSID link layer address of the previously matched frame.
+.It Ic 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.
+.El
+.It Ic with iapp type Ar iapp-type
+Send a
+.Xr hostapd 8
+specific IAPP frame with a raw IEEE 802.11 packet dump of the received
+frame to the wired network.
+The only supported
+.Ar iapp-type
+is
+.Ic radiotap .
+.It Ic with log Op Ic verbose
+Write informational messages to the local system log (see
+.Xr syslogd 8 )
+or standard error.
+.It Ic node add | delete Ar lladdr
+Add or remove the specified node from the internal kernel
+node table.
+.It Ic resend
+Resend the received IEEE 802.11 frame.
+.El
+.Ss Rule Limit
+It is possible to limit handling of specific rules with the
 .Ic limit
-handling of specific rules.
+keyword:
+.Bd -filled -offset indent
+.Ic limit
+.Ar number
+.Ic sec \*(Ba usec
+.Ed
+.Pp
 In some cases it is absolutely necessary to use limited matching
 to protect
 .Xr hostapd 8
 against excessive flooding with IEEE 802.11 frames.
 For example, beacon frames will be normally received every 100 ms.
+.Ss Management Frame Subtypes
+The
+.Ar subtype
+describes the IEEE 802.11 frame subtype, specified in
+the frame control header.
+The choice of subtypes depends on the used frame type.
+.Xr 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
+.Ic deauth
+and
+.Ic disassoc
+reason codes are supported:
+.Pp
+.Bl -tag -width Ds -compact
+.It Ic subtype beacon
+A beacon frame.
+Wireless access points and devices running in
+.Em ibss
+master or
+.Em hostap
+mode continuously send beacon frames to indicate their presence,
+traffic load, and capabilities.
+.It Ic subtype deauth Op Ar reason
+A deauthentication frame with an optional reason code.
+Deauthenticated stations will lose any IEEE 802.11 operational state.
+.It Ic subtype disassoc Op Ar reason
+A disassociation frame with an optional reason code.
+.It Ic subtype assoc request
+An association request frame.
+.It Ic subtype assoc response
+An association response frame.
+.It Ic subtype atim
+An announcement traffic indication message (ATIM frame).
+.It Xo
+.Ic subtype auth Op Ic open request \*(Ba response
+.Xc
+An authentication frame.
+.It Ic subtype probe request
+A probe request frame.
+Probe requests are used to probe for access points and IBSS nodes.
+.It Ic subtype probe response
+A probe response frame.
+.It Ic subtype reassoc request
+A re-association request frame.
+.It Ic subtype reassoc response
+A re-association response frame.
+.El
+.Pp
+The
+.Ar reason
+defines a descriptive reason for the actual
+.Em deauthentication
+or
+.Em disassociation
+of a station:
+.Pp
+.Bl -tag -width Ds -compact
+.It Ic reason assoc expire
+Disassociated due to inactivity.
+.It Ic reason assoc leave
+Disassociated because the sending station is leaving or has left the
+wireless network.
+.It Ic reason assoc toomany
+Disassociated because the access point has reached its limit of
+associated stations.
+.It Ic reason auth expire
+Previous authentication no longer valid.
+.It Ic reason auth leave
+Deauthenticated because the sending station is leaving or has left the
+wireless network.
+.It Ic reason ie invalid
+IEEE 802.11i extension.
+.It Ic reason mic failure
+IEEE 802.11i extension.
+.It Ic reason not authed
+Frame received from unauthenticated station.
+.It Ic reason assoc not authed
+Frame received from an associated but unauthenticated station.
+.It Ic reason not assoced
+Frame received from unassociated station.
+.It Ic reason rsn required
+IEEE 802.11i extension.
+.It Ic reason rsn inconsistent
+IEEE 802.11i extension.
+.It Ic reason unspecified
+Unspecified reason.
+.El
+.Ss Frame Directions
+The direction a frame is being transmitted
+.Pq Ar framedir
+can be specified in the following ways:
 .Pp
+.Bl -tag -width Ds -compact
+.It Ic dir no ds
+No distribution system direction is used for management frames.
+.It Ic dir to ds
+A frame sent from a station to the distribution system, the access point.
+.It Ic dir from ds
+A frame from the distribution system, the access point, to a station.
+.It Ic dir ds to ds
+A frame direction used by wireless distribution systems (WDS) for
+wireless access point to access point communication.
 .El
 .Sh GRAMMAR
 Syntax for
@@ -294,7 +558,7 @@ frmaction	= frmactiontype [ "dir" frmdir ]
 
 frmactiontype	= "type" ( "data" | "management" "subtype" frmsubtype )
 
-frmactionaddr	= lladdr | refaddr
+frmactionaddr	= lladdr | refaddr | "random"
 
 limit		= "limit" number ( "sec" | "usec" )