Forking netcfg to netctl (2/2)

This commit contains the refactoring and rewriting of code.

20 files changed, 590 insertions, 495 deletions

diff --git a/docs/examples/bonding b/docs/examples/bonding
index e8d4a7f..090892d 100644
--- a/docs/examples/bonding
+++ b/docs/examples/bonding
@@ -1,9 +1,6 @@
-CONNECTION="bond"
-DESCRIPTION='Bond Interface'
-INTERFACE='bond0'
-IP='static'
-ADDR="10.0.0.1"
-NETMASK="255.0.0.0"
-SLAVE_INTERFACES=("eth0" "eth2")
-SKIPNOCARRIER="yes"
-
+Description='Bond Interface'
+Interface='bond0'
+Connection=bond
+BindsToInterfaces=(eth0 eth2)
+IP=static
+Address="10.0.0.1/8"
diff --git a/docs/examples/bridge b/docs/examples/bridge
index bd422fa..f8d2915 100644
--- a/docs/examples/bridge
+++ b/docs/examples/bridge
@@ -1,9 +1,9 @@
-INTERFACE="br0"
-CONNECTION="bridge"
-DESCRIPTION="Example Bridge connection"
-BRIDGE_INTERFACES="eth0 eth1 tap0"
-IP="dhcp"
+Description="Example Bridge connection"
+Interface=br0
+Connection=bridge
+BindsToInterfaces=(eth0 eth1 tap0)
+IP=dhcp
 ## sets forward delay time
-#FWD_DELAY=0
+#FWDDelay=0
 ## sets max age of hello message
-#MAX_AGE=10
+#MaxAge=10
diff --git a/docs/examples/ethernet-dhcp b/docs/examples/ethernet-dhcp
index 0719632..5866238 100644
--- a/docs/examples/ethernet-dhcp
+++ b/docs/examples/ethernet-dhcp
@@ -1,9 +1,9 @@
-CONNECTION='ethernet'
-DESCRIPTION='A basic dhcp ethernet connection using iproute'
-INTERFACE='eth0'
-IP='dhcp'
+Description='A basic dhcp ethernet connection using iproute'
+Interface=eth0
+Connection=ethernet
+IP=dhcp
 ## for DHCPv6
-#IP6='dhcp'
+#IP6=dhcp
 ## for IPv6 autoconfiguration
-#IP6='stateless'
+#IP6=stateless
 
diff --git a/docs/examples/ethernet-iproute b/docs/examples/ethernet-iproute
index d22dd17..972f5bb 100644
--- a/docs/examples/ethernet-iproute
+++ b/docs/examples/ethernet-iproute
@@ -1,7 +1,7 @@
-CONNECTION='ethernet'
-DESCRIPTION='A more versatile static ethernet connection using iproute'
-INTERFACE='eth0'
-IP='static'
+Description='A more versatile static ethernet connection using iproute'
+Interface=eth0
+Connection=ethernet
+IP=static
 # Any valid iproute command can be placed in this array
-IPCFG=('addr add dev eth0 192.168.1.23/24 brd +' 'route add default via 192.168.1.1') 
+IPCustom=('addr add dev eth0 192.168.1.23/24 brd +' 'route add default via 192.168.1.1')
 DNS=('192.168.1.1')
diff --git a/docs/examples/ethernet-static b/docs/examples/ethernet-static
index ea88bde..0d6b5a2 100644
--- a/docs/examples/ethernet-static
+++ b/docs/examples/ethernet-static
@@ -1,17 +1,17 @@
-CONNECTION='ethernet'
-DESCRIPTION='A basic static ethernet connection using iproute'
-INTERFACE='eth0'
-IP='static'
-ADDR='192.168.1.23'
-#ROUTES=('192.168.0.0/24 via 192.168.1.2')
-GATEWAY='192.168.1.1'
+Description='A basic static ethernet connection using iproute'
+Interface=eth0
+Connection=ethernet
+IP=static
+Address='192.168.1.23'
+#Routes=('192.168.0.0/24 via 192.168.1.2')
+Gateway='192.168.1.1'
 DNS=('192.168.1.1')
 
 ## For IPv6 autoconfiguration
 #IP6=stateless
 
 ## For IPv6 static address configuration
-#IP6='static'
-#ADDR6=('1234:5678:9abc:def::1/64' '1234:3456::123/96')
-#ROUTES6=('abcd::1234')
-#GATEWAY6='1234:0:123::abcd'
+#IP6=static
+#Address6=('1234:5678:9abc:def::1/64' '1234:3456::123/96')
+#Routes6=('abcd::1234')
+#Gateway6='1234:0:123::abcd'
diff --git a/docs/examples/pppoe b/docs/examples/pppoe
index c11d125..74cc9ff 100644
--- a/docs/examples/pppoe
+++ b/docs/examples/pppoe
@@ -1,33 +1,33 @@
-CONNECTION='pppoe'
-DESCRIPTION='Example PPPoE connection'
-INTERFACE='eth0'
-USER='example@yourprovider.com'
-PASSWORD='very secret'
+Description='Example PPPoE connection'
+Interface=eth0
+Connection=pppoe
+User='example@yourprovider.com'
+Password='very secret'
 
 # Always keep a connection established
-CONNECTION_MODE='persist'
+ConnectionMode='persist'
 # Establish connection on demand
-#CONNECTION_MODE='demand'
-#IDLE_TIMEOUT=300
+#ConnectionMode='demand'
+#IdleTimeout=300
 
 # Use default route provided by the peer (default: true)
-#DEFAULTROUTE=1
+#DefaultRoute=true
 # Use DNS provided by the peer (default: true)
-#USEPEERDNS=1
+#UsePeerDNS=true
 
 # Override default LCP parameters from /etc/ppp/options
-#LCP_ECHO_INTERVAL=15
-#LCP_ECHO_FAILURE=10
+#LCPEchoInterval=15
+#LCPEchoFailure=10
 
 # PPPoE options - experts only
 #
 # PPPoE service name
-#PPPOE_SERVICE=''
+#PPPoEService=''
 # PPPoE access concentrator name
-#PPPOE_AC=''
+#PPPoEAC=''
 # Attach to existing session (sessid:macaddr)
-#PPPOE_SESSION=''
+#PPPoESession=''
 # Only connect to specified MAC address
-#PPPOE_MAC=''
+#PPPoEMAC=''
 # Enable IPv6 support
-#PPPOE_IP6='yes'
+#PPPoEIP6=yes
diff --git a/docs/examples/tunnel-he-ipv6 b/docs/examples/tunnel-he-ipv6
index 81b18ad..2a19406 100644
--- a/docs/examples/tunnel-he-ipv6
+++ b/docs/examples/tunnel-he-ipv6
@@ -1,11 +1,10 @@
-CONNECTION='tunnel'
-DESCRIPTION='An example ipv6 tunnel with Hurricane Electric'
+Description='An example ipv6 tunnel with Hurricane Electric'
+Interface=he-ipv6
+Connection=tunnel
+Mode='sit'
+Remote='216.66.80.26'
+#Local='172.16.0.1'
 
-INTERFACE='he-ipv6'
-MODE='sit'
-REMOTE='216.66.80.26'
-#LOCAL='172.16.0.1'
-
-IP6='static'
-ADDR6='2001:470:1f08:d87::2/64'
-ROUTES6=('::/0')
+IP6=static
+Address6='2001:470:1f08:d87::2/64'
+Routes6=('::/0')
diff --git a/docs/examples/tuntap b/docs/examples/tuntap
index 1563520..8ce78ac 100644
--- a/docs/examples/tuntap
+++ b/docs/examples/tuntap
@@ -1,11 +1,10 @@
-INTERFACE='tun0'
-CONNECTION='tuntap'
-MODE='tun'
-USER='nobody'
-GROUP='nobody'
+Interface=tun0
+Connection=tuntap
+Mode='tun'
+User='nobody'
+Group='nobody'
 
 ## Example IP configuration
-#IP='static'
-#SKIPNOCARRIER='yes'
-#ADDR='10.10.1.2'
+#IP=static
+#Address='10.10.1.2'
 
diff --git a/docs/examples/vlan-dhcp b/docs/examples/vlan-dhcp
index 8c6ad23..c412618 100644
--- a/docs/examples/vlan-dhcp
+++ b/docs/examples/vlan-dhcp
@@ -1,5 +1,6 @@
-INTERFACE="eth0.55"
-VLAN_PHYS_DEV="eth0"
-VLAN_ID="55"
-CONNECTION="vlan"
-IP="dhcp"
+Interface=eth0.55
+Connection=vlan
+# The variable name is plural, but needs precisely one interface
+BindsToInterfaces=eth0
+VLANID=55
+IP=dhcp
diff --git a/docs/examples/vlan-static b/docs/examples/vlan-static
index b7b9753..f9e1ae5 100644
--- a/docs/examples/vlan-static
+++ b/docs/examples/vlan-static
@@ -1,12 +1,12 @@
-INTERFACE="eth0.11"
-VLAN_PHYS_DEV="eth0"
-VLAN_ID="11"
-CONNECTION="vlan"
-IP="static"
-ADDR="192.168.0.100"
-NETMASK="255.255.255.0"
-GATEWAY="192.168.0.1"
+Interface=eth0.11
+Connection=vlan
+# The variable name is plural, but needs precisely one interface
+BindsToInterfaces=eth0
+VLANID=11
+IP=static
+Address="192.168.0.100/24"
+Gateway="192.168.0.1"
 DNS=("192.168.0.2")
-HOSTNAME="myhost"
-DOMAIN="mydomain.com"
-SEARCH="mydomain.com"
+Hostname="myhost"
+DNSDomain="mydomain.com"
+DNSSearch="mydomain.com"
diff --git a/docs/examples/wireless-open b/docs/examples/wireless-open
index db8d6ef..f4bf9bb 100644
--- a/docs/examples/wireless-open
+++ b/docs/examples/wireless-open
@@ -1,8 +1,8 @@
-CONNECTION='wireless'
-DESCRIPTION='A simple opened wireless connection'
-INTERFACE='wlan0'
-SECURITY='none'
+Description='A simple opened wireless connection'
+Interface=wlan0
+Connection=wireless
+Security=none
 ESSID='MyNetwork'
 IP='dhcp'
 # Uncomment this if your ssid is hidden
-#HIDDEN=yes
+#Hidden=yes
diff --git a/docs/examples/wireless-wep b/docs/examples/wireless-wep
index b16f65e..479b8a3 100644
--- a/docs/examples/wireless-wep
+++ b/docs/examples/wireless-wep
@@ -1,11 +1,12 @@
-CONNECTION='wireless'
-DESCRIPTION='A simple WEP encrypted wireless connection'
-INTERFACE='wlan0'
-SECURITY='wep'
+Description='A simple WEP encrypted wireless connection'
+Interface=wlan0
+Connection=wireless
+Security=wep
 ESSID='MyNetwork'
-KEY='1234567890'
+# Prepend hexadecimal keys with \"
+Key=\"1234567890abcdef
 IP='dhcp'
 # Uncomment this if your ssid is hidden
-#HIDDEN=yes
-## Uncomment if you are using an ad-hoc connection
-#ADHOC=1
+#Hidden=yes
+# Uncomment if you are using an ad-hoc connection
+#AdHoc=yes
diff --git a/docs/examples/wireless-wep-string-key b/docs/examples/wireless-wep-string-key
index ebc4b0a..12483c0 100644
--- a/docs/examples/wireless-wep-string-key
+++ b/docs/examples/wireless-wep-string-key
@@ -1,9 +1,9 @@
-CONNECTION='wireless'
-DESCRIPTION='A simple WEP encrypted wireless connection'
-INTERFACE='wlan0'
-SECURITY='wep'
+Description='A simple WEP encrypted wireless connection'
+Interface=wlan0
+Connection=wireless
+Security=wep
 ESSID='MyNetwork'
-KEY='s:Wireless Key'
+Key='Wireless Key'
 IP='dhcp'
 # Uncomment this if your ssid is hidden
-#HIDDEN=yes
+#Hidden=yes
diff --git a/docs/examples/wireless-wpa b/docs/examples/wireless-wpa
index e2511f3..16d17e9 100644
--- a/docs/examples/wireless-wpa
+++ b/docs/examples/wireless-wpa
@@ -1,14 +1,14 @@
-CONNECTION='wireless'
-DESCRIPTION='A simple WPA encrypted wireless connection'
-INTERFACE='wlan0'
-SECURITY='wpa'
+Description='A simple WPA encrypted wireless connection'
+Interface=wlan0
+Connection=wireless
+Security=wpa
 
 ESSID='MyNetwork'
-## Uncomment if the supplied ESSID is hexadecimal
-#ESSID_TYPE='hex'
-KEY='WirelessKey'
+# Prepend hexadecimal keys with \"
+# If your key starts with ", write it as '"""<key>"'
+Key='WirelessKey'
 
 IP='dhcp' 
 
 # Uncomment this if your ssid is hidden
-#HIDDEN=yes
+#Hidden=yes
diff --git a/docs/examples/wireless-wpa-config b/docs/examples/wireless-wpa-config
index 955d845..e598dce 100644
--- a/docs/examples/wireless-wpa-config
+++ b/docs/examples/wireless-wpa-config
@@ -1,8 +1,8 @@
-CONNECTION='wireless'
-DESCRIPTION='A wpa_supplicant configuration based wireless connection'
-INTERFACE='wlan0'
-SECURITY='wpa-config'
-WPA_CONF='/etc/wpa_supplicant.conf'
+Description='A wpa_supplicant configuration based wireless connection'
+Interface=wlan0
+Connection=wireless
+Security=wpa-config
+WPAConfigFile='/etc/wpa_supplicant.conf'
 IP='dhcp' 
 # Uncomment this if your ssid is hidden
-#HIDDEN=yes
+#Hidden=yes
diff --git a/docs/examples/wireless-wpa-configsection b/docs/examples/wireless-wpa-configsection
index d6cc8ad..dde9ccd 100644
--- a/docs/examples/wireless-wpa-configsection
+++ b/docs/examples/wireless-wpa-configsection
@@ -1,17 +1,18 @@
-CONNECTION='wireless'
-INTERFACE=wlan0
-SECURITY='wpa-configsection'
+Interface=wlan0
+Connection=wireless
+Security=wpa-configsection
 # Uncomment this if your ssid is hidden
-#HIDDEN=yes
+#Hidden=yes
 IP='dhcp'
-CONFIGSECTION='
-    ssid="University"
-    key_mgmt=WPA-EAP
-    eap=TTLS
-    group=TKIP
-    pairwise=TKIP CCMP
-    anonymous_identity="anonymous"
-    identity="myusername"
-    password="mypassword"
-    priority=1
-    phase2="auth=PAP"'
+WPAConfigSection=(
+    'ssid="University"'
+    'key_mgmt=WPA-EAP'
+    'eap=TTLS'
+    'group=TKIP'
+    'pairwise=TKIP CCMP'
+    'anonymous_identity="anonymous"'
+    'identity="myusername"'
+    'password="mypassword"'
+    'priority=1'
+    'phase2="auth=PAP"'
+)
diff --git a/docs/examples/wireless-wpa-static b/docs/examples/wireless-wpa-static
index 25da514..66b6970 100644
--- a/docs/examples/wireless-wpa-static
+++ b/docs/examples/wireless-wpa-static
@@ -1,12 +1,12 @@
-CONNECTION='wireless'
-DESCRIPTION='A simple WPA encrypted wireless connection using a static IP'
-INTERFACE='wlan0'
-SECURITY='wpa'
+Description='A simple WPA encrypted wireless connection using a static IP'
+Interface=wlan0
+Connection=wireless
+Security=wpa
 ESSID='MyNetwork'
-KEY='WirelessKey'
-IP='static' # Any other CONNECTION='ethernet' options may be used.
-ADDR='192.168.1.23'
-GATEWAY='192.168.1.1'
+Key='WirelessKey'
+IP=static
+Address='192.168.1.23'
+Gateway='192.168.1.1'
 DNS=('192.168.1.1')
 # Uncomment this if your ssid is hidden
-#HIDDEN=yes
+#Hidden=yes
diff --git a/docs/netctl.1.txt b/docs/netctl.1.txt
index 54fbd78..06638a2 100644
--- a/docs/netctl.1.txt
+++ b/docs/netctl.1.txt
@@ -1,91 +1,92 @@
-NETCFG(8)
+NETCTL(1)
 =========
 
 NAME
 ----
-netcfg - start/stop/control network profiles
+netctl - Control the netctl network profile manager
 
 
 SYNOPSIS
 --------
-netcfg [_options_]
+*netctl* {*COMMAND*} [+PROFILE+]
 
-netcfg *profile*
+*netctl* [--help | --version]
 
 
 DESCRIPTION
 -----------
-*netcfg* is used to configure and manage network connections via
-profiles. It has pluggable support for a range of connection types, such
-as wireless, ethernet, ppp. It is also capable of starting/stopping many
-to one connections, that is, multiple connections within the same
-profile, optionally with bonding.
-
-It may be run at boot, by enabling the 'netcfg' systemd service, or, on
-legacy systems, by adding 'net-profiles' to +DAEMONS+ in '/etc/rc.conf'.
-After boot time, it may be used to start profiles, simply by passing only
-the profile name.
-
-When run without options, `netcfg profile` is equivalent to `netcfg -u
-profile`.
+*netctl* may be used to introspect and control the state of the systemd
+services for the network profile manager.
 
 
 OPTIONS
 -------
-*-l, list*::
-  List all available profiles
-*current*::
-  Report currently running profiles
-*-c, check-iface* _profile_::
-  Start the specified profile, only if it's interface is not currently up.
-*-u, up* _profile_::
-  Start the specified profile
-*-r, reconnect* _profile_::
-  Disconnect and reconnect the specified profile
-*-R, iface-recon* _interface_::
-  Reconnect profile active on specified interface
-*-d, down* _profile_::
-  Stop the specified profile
-*-D, iface-down* _interface_::
-  Stop the profile up on the specified interface.
-*-a, all-down*::
-  Stop all connected profiles
-*all-suspend*::
-  Suspend and store the name of all active profiles.
-*all-resume*::
-  Reconnect any profiles that have been suspended.
-*-v, --version*::
-  Display version information and exit
-*-h, --help*::
-  Display help message and exit
-
-
-CONFIGURATION FILES
--------------------
-'/etc/conf.d/netcfg'::
-  Parameters for startup.
-'/etc/network.d/'::
-  User-defined profiles.
-
-
-FILES
------
-'/usr/lib/network/connections/'::
-  Currently installed network profile types.
-'/etc/network.d/examples/'::
-  Example profiles.
-'/usr/share/doc/netcfg/contrib/'::
-  Inspirational scripts.
-
-
-ENVIRONMENT VARIABLES
----------------------
-+NETCFG_DEBUG+::
-  Set to 1 to activate debug output.
+The following commands are understood:
+
+*list*::
+    List all available profiles. Active profiles will be marked with a
+    `*'.
+
+*store*::
+    Saves which profiles are currently active.
+
+*restore*::
+    Loads the profiles that were active during the last invocation of
+    `*store*'.
+
+*stop-all*::
+    Stops all active network profiles.
+
+*start [+PROFILE+]*::
+    Start the network profile specified on the command line.
+
+*stop [+PROFILE+]*::
+    Stop the network profile specified on the command line.
+
+*restart [+PROFILE+]*::
+    Restart the network profile specified on the command line. If it is
+    not started yet, it will be started.
+
+*switch-to [+PROFILE+]*::
+    Starts the network profile specified on the command line after
+    stopping all profiles that refer to the same interface.
+
+*status [+PROFILE+]*::
+    Show terse runtime status information about a profile, followed by
+    its most recent log data from the journal.
+
+*enable [+PROFILE+]*::
+    Enable the systemd unit for the profile specified. This will create
+    a unit configuration file. If the file already exists, the command
+    fails. No other profiles than the one specified will be enabled.
+    Changes to the general options in a profile specification will not
+    propagate to the unit configuration file automatically. After such
+    changes, it is necessary to `*reenable*' the profile.
+
+*disable [+PROFILE+]*::
+    Disable the systemd unit for the profile specified. This will remove
+    the file created by `*enable*' even if it was customized, so be
+    carefull.
+
+*reenable [+PROFILE+]*::
+    Reenable the systemd unit for the profile specified. This is
+    effectively a combination of `*disable*' and `*enable*'.
+
+
+EXIT STATUS
+-----------
+On success 0 is returned, a non-zero failure code otherwise.
+
+
+ENVIRONMENT
+-----------
+'$NETCTL_DEBUG'::
+    If set to `"yes"`, debugging output is generated.
+'$NETCTL_STATE_FILE'::
+    The location of the state file. Defaults to
+    '/var/lib/netctl/netctl.state'.
 
 
 SEE ALSO
 --------
-*netcfg-profiles*(5) on how to configure netcfg.
-
-include::footer.txt[]
+*netctl.profile*(5) *netctl.special*(7) *systemctl*(1)
diff --git a/docs/netctl.profile.5.txt b/docs/netctl.profile.5.txt
index f929e47..21ea52c 100644
--- a/docs/netctl.profile.5.txt
+++ b/docs/netctl.profile.5.txt
@@ -1,321 +1,362 @@
-NETCFG-PROFILES(5)
-==================
+NETCTL.PROFILE(5)
+=================
 
 NAME
 ----
-netcfg-profiles - netcfg profiles documentation and syntax
+netctl.profile - Profile options
+
+
+SYNOPSIS
+--------
+netctl.profile
 
 
 DESCRIPTION
 -----------
-The *netcfg*(8) profiles are plain text files that defines variables for
-netcfg behavior. They must be compliant with *bash*(1) shell syntax and
-usually do not execute any code.
+Profiles for netctl live under '/etc/network.d/' and are plain text
+files. The files consist of variable definitions following the bash
+shell syntax and are not expected to execute any code. It is good to
+omit as much quoting as possible. For a few WPA-related variables,
+special quoting rules (see below) apply.
 
-They are named '/etc/network.d/$\{profile_name}', where
-+$\{profile_name\}+ must not contain a newline character and should not
-start with the `@'-sign.
+The name of the profile is the name of the file. Profile names must not
+contain newlines and should not end in '.service' or '.conf'. Whenever a
+profile is read, all executable scripts in '/etc/network.d/hooks/' and
+any executable script in '/etc/network.d/interfaces/' with the name of
+the interface for the profile are sourced. For each connection type,
+there are example profile files in '/etc/network.d/examples/'.
 
 
-OVERVIEW
---------
-Profiles must define mandatory variables:
+AVAILABLE CONNECTION TYPES
+--------------------------
++ethernet+::
+    For wired connections.
++wireless+::
+    For wireless connections. This connection type requires
+    *wpa_supplicant* to be available.
++bond+::
+    Network bonding. This connection type requires *ifenslave* to be
+    available.
++bridge+::
+    Network bridging. This connection type requires *brctl* to be
+    available.
++pppoe+::
+    For PPPoE connections.
++tunnel+::
+    For tunnel interfaces.
++tuntap+::
+    For TUN/TAP interfaces.
++vlan+::
+    For VLANs on ethernet-like connections.
+
+
+GENERAL OPTIONS
+---------------
+'Description='::
+    A description of the profile.
+
+'Connection=' [mandatory for all profiles]::
+    The connection type used by the profile.
+
+'Interface=' [mandatory for all profiles]::
+    The name of the associated network interface. The interface name
+    should not be quoted.
+
+'BindsToInterfaces=()'::
+    An array of physical network interfaces that this profile needs
+    before it can be started. For `enabled' profiles, *systemd* will
+    wait for the presence of the specified interfaces before starting a
+    profile. If this variable is not specified, it defaults to the value
+    of 'Interface'.
+
+'After=()'::
+    An array of profile names that should be started before this profile
+    is started. This is only an ordering dependency and is not intended
+    to be a list of profiles that this profile requires. The meaning is
+    the same as 'After' in *systemd.unit*(5).
+
+'ExecUpPost='::
+    A command that is executed after a connection is established. If the
+    specified command returns anything other than 0 (success), *netctl*
+    will abort and stop the profile. If the command should be allowed to
+    fail, add ``|| true`' to the end of it.
+
+'ExecDownPre='::
+    A command that is executed after a connection is brought down.
+    Similar precautions should be taken as with 'ExecUpPost'.
+
+
+IP OPTIONS
+----------
+These options apply to all connections that set up an IP-enabled
+network. In particular, these connection types are +ethernet+,
++wireless+, +bond+, +bridge+, +tunnel+, +tuntap+, and +vlan+.
+
+'IP=' [mandatory for IPv4]::
+    One of `static', `dhcp', or `no', depending on the desired way of
+    obtaining an address.
+
+'IP6=' [mandatory for IPv6]::
+    One of `static', `stateless', `dhcp-noaddr', `dhcp', `no' or left
+    out (empty) altogether. The difference between not specifying and
+    setting to `no' is in the handling of __router advertisement__
+    packages, which is blocked by `no'.
+
+'Address=()' [requires 'IP=static']::
+    An array of IP addresses, optionally suffixed with ``/<netmask>`',
+    where netmask is an integer between 0 and 255. The default netmask
+    is 24. Leaving out brackets for arrays consisting of a single
+    element is accepted in the Bash syntax.
+
+'Gateway=' [requires 'IP=static']::
+    An IP routing gateway address.
+
+'Routes='::
+    An array of custom routes of the form +
+    `**<address range>** via **<gateway>**'.
+
+'Address6=()' [requires 'IP6=static']::
+    An array of IPv6 addresses. Prefix length may be specified via
+    `1234:bcd::11/64' syntax.
+
+'Gateway6=' [requires 'IP6=static']::
+    An IPv6 routing gateway address.
+
+'Routes6='::
+    An array of custom routes of the form +
+    `**<address range>** via **<gateway>**'.
+
+'DHCPClient=' [requires a DHCP setting]::
+    The name of the preferred DHCP client. Supported options are
+    `dhcpcd' and `dhclient'. Defaults to `dhcpcd'.
+
+'IPCustom=()'::
+    An array of argument lines to pass to `ip`. This can be used to
+    achieve complicated configurations within the framework of *netctl*.
+
+'Hostname='::
+    A system hostname.
+
+'DNS=()'::
+    An array of DNS nameservers. Simply specify the IP addresses of each
+    of the DNS nameservers.
 
-+INTERFACE+::
-  The name of the associated network interface.
-+DESCRIPTION+::
-  A description of the profile.
-+CONNECTION+::
-  The connection type used by the profile.
+'DNSDomain='::
+    A ``domain`' line for '/etc/resolv.conf'.
 
-Connections define how the network is set up for the profile and also
-determine additional configuration variable that control their
-behavior. The available connection types are determined by files in
-'/usr/lib/network/connections/'.
+'DNSSearch='::
+    A ``search`' line for '/etc/resolv.conf'.
 
+'DNSOptions=()'::
+    An array of ``options`' lines for '/etc/resolv.conf'.
 
-Available connections
----------------------
-ethernet::
-  Standard network configuration, suitable for wired connections.
-wireless::
-  Wireless connection, with *wpa_supplicant*(1) as configuration
-  back-end.
-bond::
-  Bonded network interfaces using *ifenslave*.
-bridge::
-  Network bridge setup using *brctl*(8).
-tuntap::
-  TUN/TAP interfaces.
-tunnel::
-  Tunnel interfaces.
-vlan::
-  VLAN setup.
-openvpn::
-  OpenVPN setup.
-ppp::
-  PPP connections setup.
-pppoe::
-  PPPoE connections setup.
-
-The configuration variable for these connection types is described in
-the following sections.
-
-
-Ethernet options reference
---------------------------
+'TimeoutDHCP='::
+    Maximum time, in seconds, to wait for DHCP to be successful.
+    Defaults to ``10`'.
 
-Description
-~~~~~~~~~~~
-This connection method uses the iproute suite of tools and dhcpcd to
-gain an IP address.
-
-+IP+ (required for IPv4)::
-  Either `static' or `dhcp'. Set to `no' to have netcfg bring the interface
-  up but assign no addresses. Static requires at least one of +ADDR+ or
-  +IPCFG+.
-
-IPv4 options
-~~~~~~~~~~~~
-+ADDR+ (requires +IP+ of `static')::
-  A single IP address to configure a static IP.
-+GATEWAY+ (requires +IP+ of `static')::
-  Set specified gateway
-+NETMASK+ (requires +IP+ of `static')::
-  Set specified netmask. Defaults to 24.
-+ROUTES+::
-  An array of custom routes (of the form _address range_ via _gateway_)
-
-IPv6 options
-~~~~~~~~~~~~
-+IP6+ (required for IPv6)::
-  Either `dhcp', `dhcp-noaddr', `stateless', `static'. Set to `no' to
-  disable IPv6.
-+ADDR6+ (required when +IP6+ is `static')::
-  An array of IPv6 addresses: prefix length may be specified via
-  `1234:bcd::11/64' syntax.
-+GATEWAY6+ (requires +IP6+ of `static')::
-  The gateway address for IPv6 routing.
-+ROUTES6+::
-  An array of custom routes (of the form _address range_ via _gateway_)
-+DAD_TIMEOUT+::
-  Time to wait for Duplicate Address Detection to succeed. Defaults to
-  3 seconds.
-
-DNS configuration
-^^^^^^^^^^^^^^^^^
-+DNS+::
-  Array of DNS nameservers. Simply specify the IP's of each of the DNS
-  nameservers.
-+DNS_OPTIONS+::
-  Array of ``option'' lines for '/etc/resolv.conf'
-+SEARCH+::
-  ``search'' line for '/etc/resolv.conf'
-+DOMAIN+::
-  ``domain'' line for '/etc/resolv.conf'
-+HOSTNAME+::
-  Set the system hostname. Ensure any hostname is correctly referenced
-  in '/etc/hosts'
-
-DHCP configuration
-^^^^^^^^^^^^^^^^^^
-+DHCP_OPTIONS+ (ipv4)::
-  String. Any extra arguments to pass to the dhcp client, presently
-  dhcpcd.
-+DHCP_TIMEOUT+::
-  Integer. Maximum time to try for a DHCP IP. Default is 10 seconds.
-+DHCLIENT+::
-  yes/no. Use dhclient instead of dhcpcd. Defaults to no
-+DHCLIENT_OPTIONS+ (ipv4)::
-  String. Extra options to pass to dhclient for IPv4.
-+DHCLIENT6_OPTIONS+ (ipv6)::
-  String. Extra options to pass to dhclient for IPv6.
-
-802.11x Authentication
-^^^^^^^^^^^^^^^^^^^^^^
-+AUTH8021X+::
-  Use 802.11x authentication. Enable with `yes'.
-+WPA_CONF+ (required for an +AUTH8021X+ of `yes' only)::
-  Path to wpa_supplicant configuration. Defaults to
-  '/etc/wpa_supplicant.conf'
-+WPA_OPTS+ (optional for an +AUTH8021X+ of `yes')::
-  Extra arguments for wpa_supplicant not specified otherwise. Any option
-  here must specify wpa_supplicant driver. Defaults to _-Dwired_.
-
-Miscellaneous options
-^^^^^^^^^^^^^^^^^^^^^
-+IPCFG+::
-  Array of arguments to pass to `ip`. The power of this options is that
-  it allows both simple and complicated routing configurations, within
-  the framework of netcfg.
-+SKIPNOCARRIER+::
-  `yes'/`no'. Don't abort interface setup if no carrier is found.
-
-
-Examples
-~~~~~~~~
-
-Using ADDR and GATEWAY to set static IP and gateway
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------
-IP="static"
-ADDR="192.168.1.23"
-GATEWAY="192.168.1.1"
----------------------
+'TimeoutDAD='::
+    Maximum time, in seconds, to wait for IPv6's Duplicate Address
+    Detection to succeed. Defaults to ``3`'.
 
-Using IPCFG to set a static IP and gateway with custom DNS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
--------------------------------------------------------------------------------------
-IP="static"
-IPCFG=("addr add dev eth0 192.168.1.23/24 brd +" "route add default via 192.168.1.1")
-DNS=("208.67.222.222" "208.67.220.220")
--------------------------------------------------------------------------------------
 
+OPTIONS FOR `ethernet' CONNECTIONS
+----------------------------------
+Next to the *ip options*, the following are understood for connections
+of the `ethernet' type:
 
-Wireless options reference
---------------------------
+'SkipNoCarrier='::
+    Whether or not the absence of a carrier (plugged-in cable) is
+    acceptable. Defaults to ``no`'.
 
-Description
-~~~~~~~~~~~
-This connection method uses wpa_supplicant to configure a wireless
-network connection. This connection uses the 'ethernet' connection after
-successful association and thus supports all of its options.
-
-Options
-~~~~~~~
-+SECURITY+ (required for security of `wep', `wpa', `wpa-configsection' or `wpa-config')::
-  One of `wpa', `wep', `none', `wpa-configsection' or `wpa-config'.
-  Defaults to `none'.
-+KEY+ (required for +SECURITY+ of `wpa' or `wep' only)::
-  Wireless encryption key.
-+ESSID+ (this or +AP+ is required)::
-  Name of network to connect to, or hexadecimal digits (see
-  `ESSID_TYPE')
-+ESSID_TYPE+ (optional, defaults to `ascii')::
-  Set to `ascii' or `hex', if set to `hex', +ESSID+ will be interpreted as
-  an hexadecimal +SSID+ and written unquoted to the wpa_supplicant
-  configuration file.
-+AP+ (this or +ESSID+ is required)::
-  AP (BSSID) of the network to connect to.
-+HIDDEN+ (optional)::
-  Define this to connect to hidden ESSIDs.
-+ADHOC+ (optional)::
-  Define this to use ad-hoc mode for wireless.
-+TIMEOUT+ (optional)::
-  Time to wait for association. Defaults to 15 seconds.
-+SCAN+ (optional)::
-  `yes'/`no'. Scan for a wireless network rather than blindly attempting to
-  connect. Hidden SSID networks do not appear in a scan.
-+PRIORITY+ (optional)::
-  Priority group for the network. The matched network with the highest
-  priority will be selected. Defaults to 0.
-
-WPA options
-^^^^^^^^^^^
-+WPA_CONF+ (for +SECURITY+ of `wpa-config' only)::
-  Path to wpa_supplicant configuration. Defaults to
-  '/etc/wpa_supplicant.conf'
-+WPA_OPTS+::
-  Extra arguments for wpa_supplicant not specified otherwise.
-+WPA_GROUP+::
-  Group that has authority to configure wpa_supplicant via it's control
-  interface. Used in any configuration that is generated by netcfg.
-+WPA_COUNTRY+ (optional, nl80211 based drivers)::
-  The country where the device will be used. This allows wpa_supplicant
-  to enforce any local regulatory limitations and will allow all
-  appropriate channels/frequencies for your device.
-+WPA_DRIVER+ (optional)::
-  A comma-separated list of wpa_supplicant driver interfaces to try.
-  Defaults to `nl80211,wext'.
-
-rfkill (Radio Kill Switch) options
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-+RFKILL+::
-  hard/soft A switch with physical on/off state that cannot be
-  controlled via software is considered a *hard* switch. Any switch that
-  can be controlled via software is considered *soft*.
-+RFKILL_NAME+::
-  Some switches sysfs entries are not linked with the interface. To
-  match them up, configure the name from '/sys/class/rfkill/rfkillX/name'
-  here so that netcfg can identify which to control.
-
-
-Options for `bridge' connections
---------------------------------
-The options of `ethernet' connections apply to set up standard IP
-connectivity.
+'Auth8021X='::
+    Set to ``yes`' to use 802.11x authentication.
 
-+BRIDGE_INTERFACES+::
-  List of network interfaces taking part in the bridge.
-+FWD_DELAY+::
-  Forward delay of the bridge, see *brctl*(8)
-+MAX_AGE+::
-  maxage parameter, see *brctl*(8)
+'WPAConfigFile='::
+    Path to a *wpa_supplicant* configuration file. Defaults to
+    '/etc/wpa_supplicant.conf'.
 
+'WPADriver='::
+    The *wpa_supplicant* driver to use for 802.11x authentication.
+    Defaults to ``wired`'.
 
-Options for `tuntap' connections
---------------------------------
-The options of `ethernet' connections apply to set up standard IP
-connectivity.
+'TimeoutCarrier='::
+    Maximum time, in seconds, to wait for a carrier. Defaults to ``5`'.
+
+'TimeoutWPA='::
+    Maximum time, in seconds, to wait for 802.11x authentication to
+    succeed. Defaults to ``15`'.
+
+
+OPTIONS FOR `wireless' CONNECTIONS
+----------------------------------
+Next to the *ip options*, the following are understood for connections
+of the `wireless' type:
+
+'Security='::
+    One of `none', `wep', `wpa', `wpa-configsection', or `wpa-config'.
+    Defaults to ``none`'.
+
+'ESSID=' [mandatory]::
+    The name of the network to connect to.
+    Special quoting rules (see below) apply.
+
+'AP='::
+    The BSSID (MAC address) of the access point to connect to.
+
+'Key='::
+    The secret key to a WEP, or WPA encrypted network.
+    Special quoting rules (see below) apply.
 
-+MODE+::
-  Set to `tun' or `tap'.
-+USER+::
-  The owning user of the tun/tap interface.
-+GROUP+::
-  The owning group of the tun/tap interface.
+'Hidden='::
+    Whether or not the specified network is a hidden network. Defaults
+    to ``no`'.
 
+'Scan='::
+    Whether or not to scan for the presence of a network before
+    attempting to connect. Hidden networks do not appear in a scan.
+    Defaults to ``no`'.
 
-Options for `ppp' connections
------------------------------
-+PEER+::
-  The *pppd*(8) peer to use.
-+PPP_TIMEOUT+::
-  *pppd*(8) timeout.
+'AdHoc='::
+    Whether or not to use ad-hoc mode. Defaults to ``no`'.
 
+'Country='::
+    The country for which frequency regulations will be enforced.
 
-Options for `vlan' connections
+'Priority='::
+    Priority group for the network. In case of automatic profile
+    selection, the matched network with the highest priority will be
+    selected. Defaults to ``0`'.
+
+'WPAGroup='::
+    Group that has the authority to configure *wpa_supplicant* via its
+    control interface. Defaults to ``wheel`'.
+
+'WPAConfigSection=()' [mandatory for 'Security=wpa-configsection']::
+    Array of lines that form a network block for *wpa_supplicant*.
+
+'WPAConfigFile='::
+    Path to a *wpa_supplicant* configuration file. Defaults to
+    '/etc/wpa_supplicant.conf'. Used for 'Security=wpa-config'.
+
+'WPADriver='::
+    The *wpa_supplicant* driver to use. Defaults to ``nl80211,wext`'.
+
+'TimeoutWPA='::
+    Maximum time, in seconds, to wait for steps in the association and
+    authentication to succeed. Defaults to ``15`'.
+
+'RFKill='::
+    The name of an *rfkill* device. When specified, the device is used
+    to block/unblock the interface when appropriate. Names can be found
+    in '/sys/class/rfkill/rfkillX/name'. It is also possible to set this
+    variable to ``auto`'. In that case an *rfkill* device that is
+    associated with the network interface is used.
+
+
+OPTIONS FOR `bond' CONNECTIONS
 ------------------------------
-+INTERFACE+::
-  The name of the virtual interface.
-+VLAN_PHYS_DEV+::
-  The name of the associated physical interface.
-+VLAN_ID+::
-  See *ip*(8).
+The interfaces of 'BindsToInterfaces' are bound together in the
+interface named by 'Interface'. All *ip options* are understood for
+connections of the `bond' type.
 
 
-Options for `tunnel' connections
+OPTIONS FOR `bridge' CONNECTIONS
 --------------------------------
-Standard `ethernet' options apply for IP configuration.
+The interfaces of 'BindsToInterfaces' take part in the bridge named by
+'Interface'. Next to the *ip options*, the following are understood for
+connections of the `bridge' type:
+
+'FwdDelay='::
+    Forward delay of the bridge. See *brctl*(8) for details.
+
+'MaxAge='::
+    Maximum age parameter. See *brctl*(8) for details.
 
-+INTERFACE+::
-  The name of the tunnel interface.
-+MODE+::
-  The tunnel type (e.g. `sit'). See *ip*(8) for available modes.
-+LOCAL+::
-  The address of the local end of the tunnel.
-+REMOTE+::
-  The address of the remote end of the tunnel.
 
+OPTIONS FOR `tunnel' CONNECTIONS
+----------------------------------
+The name of the tunnel interface is specified in 'Interface'. Next to
+the *ip options*, the following are understood for connections of the
+`tunnel' type:
 
-Options for `bond' connections
+'Mode='::
+    The tunnel type (e.g. `sit'). See *ip*(8) for available modes.
+
+'Local='::
+    The address of the local end of the tunnel.
+'Remote='::
+    The address of the remote end of the tunnel.
+
+
+OPTIONS FOR `tuntap' CONNECTIONS
+----------------------------------
+The name of the tuntap interface is specified in 'Interface'. Next to
+the *ip options*, the following are understood for connections of the
+`tuntap' type:
+
+'Mode='::
+    Either ``tun`', or ``tap`'.
+
+'User='::
+    The owning user of the tun/tap interface.
+
+'Group='::
+    The owning group of the tun/tap interface.
+
+
+OPTIONS FOR `vlan' CONNECTIONS
 ------------------------------
-Standard `ethernet' options apply for IP configuration.
+The name of the vlan interface is specified in 'Interface'. The
+underlying physical interface is specified in 'BindsToInterfaces'.
+Hence, for vlan profiles, 'BindsToInterfaces' contains the name of a
+single network interface.
 
-+SLAVE_INTERFACES+ (Bash array)::
-  An array of names of interfaces to be bound together.
+All options for connections of the `ethernet' type are understood for
+connections of the `vlan' type. Additionally, connections of the `vlan'
+type can set a vlan identifier using 'VLANID='. See *ip*(8) for details.
 
 
-Options for `openvpn' connections
----------------------------------
-+OVPN_CONFIG+::
-  Path to the *openvpn*(8) config file.
-+OVPN_PID_FILE+::
-  Path to the *openvpn*(8) PID file.
-+OVPN_FLAGS+::
-  Options to pass to *openvpn*(8) invocation.
+SPECIAL QUOTING RULES
+---------------------
+Configuration files for *wpa_supplicant* use non-standard quoting.
+Therefore, non-standard quoting rules exist for some variables for
+connections of the `wireless' type. In particular, these variables are
+'ESSID', and 'Key'.
+
+A variable is considered *quoted* by *wpa_supplicant* if it is enclosed
+in double quotes ("). A variable is considered *non-quoted* by
+*wpa_supplicant* if it does not start with a double quote. Hexadecimal
+values are specified *non-quoted* in configuration files of
+*wpa_supplicant*. In *netctl*, variables are written to *wpa_supplicant*
+configuration files *quoted* by default. When special quoting rules
+apply, it is possible to specify an unquoted (hexadecimal) value using a
+special syntax.
+
+The special quoting rules of *netctl* are as follows. A string that
+starts with a literal double quote is considered *non-quoted*. Any other
+string is considered *quoted*. It is possible to specify quoted strings
+that start with a double quote by quoting manually. An extreme example
+is the specification of a *quoted* double quote: '`X='""""'`'. On the
+other end of the spectrum there is the *non-quoted* backslash:
+'`X=\"\\`'.
+
+Further examples of *quoted* strings (all equivalent):
+-------------
+X=string
+X="string"
+X='""string"'
+-------------
+
+Further examples of *non-quoted* strings (all equivalent):
+------------
+X=\"string
+X="\"string"
+X='"string'
+------------
+
+A mnemonic is to think of the prefix ``\"`' as saying `non'-`quote'.
 
 
 SEE ALSO
 --------
-include::footer.txt[]
+*netctl*(1)
diff --git a/docs/netctl.special.7.txt b/docs/netctl.special.7.txt
new file mode 100644
index 0000000..eabb4d3
--- /dev/null
+++ b/docs/netctl.special.7.txt
@@ -0,0 +1,55 @@
+NETCTL.SPECIAL(7)
+=================
+
+NAME
+----
+netctl.special - Special netctl systemd units
+
+
+SYNOPSIS
+--------
+netctl.service, netctl-auto.service, netctl-ifplugd.service
+
+
+DESCRIPTION
+-----------
+Bundled with netctl come a few systemd units that are not controlled
+through the netctl command. They can be used through the systemctl
+utility of systemd.
+
+
+SPECIAL UNITS
+-------------
+netctl.service::
+    When started, this unit tries to start the profiles that were
+    running when the unit was last stopped. In some cases, the interface
+    a profile binds to might not be available yet, when netctl.service
+    tries to bring a profile up. A simple, hackish, solution is to do:
+--------------------------------------------------------------------
+echo "[[ -t 0 ]] || sleep 3" > /etc/network.d/interfaces/<interface>
+chmod 755 /etc/network.d/interfaces/<interface>
+--------------------------------------------------------------------
+    A more concise solution is to first enable a profile through netctl
+    and then disable it again through systemctl:
+--------------------------------------------------------------------
+netctl enable <profile>
+systemctl disable netctl@<profile>
+--------------------------------------------------------------------
+    This way the unit configuration file for the profile remains in
+    existence, while the profile is not enabled.
+
+netctl-auto@<interface>.service::
+    This unit issues a scan on the interface it is used for and tries to
+    start a profile for a network it finds. It is targeted to wireless
+    interfaces.
+
+netctl-ifplugd@<interface>.service::
+    This unit starts ifplugd on the interface it is used for. It will
+    try to start a netctl profile whenever a cable is plugged into the
+    interface and stop the profile when the cable is unplugged. Note
+    that this unit does not provide network.target.
+
+
+SEE ALSO
+--------
+*netctl*(1), *netctl.profile*(5)