From eeb40937fb57d3e8219c56f1f2bf4af5078b37e1 Mon Sep 17 00:00:00 2001
From: Ariadne Conill <ariadne@dereferenced.org>
Date: Wed, 2 Dec 2020 18:48:57 -0700
Subject: [PATCH] doc: document the wifi executor as interfaces-wifi(5).

---
 Makefile                |  1 +
 doc/interfaces-wifi.scd | 55 +++++++++++++++++++++++++++++++++++++++++
 doc/interfaces.scd      |  5 ++++
 3 files changed, 61 insertions(+)
 create mode 100644 doc/interfaces-wifi.scd

diff --git a/Makefile b/Makefile
index a5b9a7d..5a44d07 100644
--- a/Makefile
+++ b/Makefile
@@ -164,6 +164,7 @@ MANPAGES_5 = \
 	doc/interfaces-ppp.5 \
 	doc/interfaces-vrf.5 \
 	doc/interfaces-vxlan.5 \
+	doc/interfaces-wifi.5 \
 	doc/interfaces-wireguard.5
 
 MANPAGES_7 = \
diff --git a/doc/interfaces-wifi.scd b/doc/interfaces-wifi.scd
new file mode 100644
index 0000000..018138b
--- /dev/null
+++ b/doc/interfaces-wifi.scd
@@ -0,0 +1,55 @@
+interfaces-wifi(5)
+
+# NAME
+
+*interfaces-wifi* - WiFi vocabulary for the interfaces(5) file format
+
+# DESCRIPTION
+
+Wi-Fi (the IEEE 802.11 family of protocols) is a commonly used wireless
+networking standard.  The following options allow for configuration of
+Wi-Fi client interfaces.
+
+# WIFI-RELATED OPTIONS
+
+*wifi-config-path* _path_
+	Denotes the absolute _path_ to a *wpa_supplicant* configuration file.
+	If no path is given, _/run/wpa_supplicant.<interface>.conf_ will be
+	used for a temporary configuration file.  This option may not be used
+	with other configuration options.
+
+*wifi-ssid* _ssid_
+	The SSID the Wi-Fi client should connect to.
+
+*wifi-psk* _psk_
+	The passphrase for connecting to the Wi-Fi network.  If unset, the
+	client will connect without WPA2 encryption.
+
+# EXAMPLES
+
+A typical setup may involve connecting to a home and work network.  To
+achieve this, we can define a pair of virtual interfaces called *wifi-home*
+and *wifi-work*, which connect to their respective wifi networks:
+
+```
+iface wifi-home
+	use dhcp
+	wifi-ssid HomeNetwork
+	wifi-psk ExamplePassphrase
+
+iface wifi-work
+	use dhcp
+	wifi-config-path /etc/network/wpa-work.conf
+```
+
+The virtual interfaces can be used with *ifup* and *ifdown*:
+
+```
+# ifup wlan0=wifi-home
+# ifdown wlan0
+# ifup wlan0=wifi-work
+```
+
+# AUTHORS
+
+Ariadne Conill <ariadne@dereferenced.org>
diff --git a/doc/interfaces.scd b/doc/interfaces.scd
index 15c43e6..00f465f 100644
--- a/doc/interfaces.scd
+++ b/doc/interfaces.scd
@@ -178,6 +178,11 @@ most common executors are:
 	The interface is a Virtual Extensible LAN (VXLAN) tunnel
 	endpoint.
 
+*wifi*
+	The interface is a Wi-Fi (IEEE 802.11) client interface.
+	Configuration of the WiFi client interface requires the
+	*wpa_supplicant* package to be installed.
+
 *wireguard*
 	The interface is a Wireguard VPN tunnel endpoint.