summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/examples/bonding15
-rw-r--r--docs/examples/bridge14
-rw-r--r--docs/examples/ethernet-dhcp12
-rw-r--r--docs/examples/ethernet-iproute10
-rw-r--r--docs/examples/ethernet-static22
-rw-r--r--docs/examples/pppoe34
-rw-r--r--docs/examples/tunnel-he-ipv619
-rw-r--r--docs/examples/tuntap15
-rw-r--r--docs/examples/vlan-dhcp11
-rw-r--r--docs/examples/vlan-static22
-rw-r--r--docs/examples/wireless-open10
-rw-r--r--docs/examples/wireless-wep17
-rw-r--r--docs/examples/wireless-wep-string-key12
-rw-r--r--docs/examples/wireless-wpa16
-rw-r--r--docs/examples/wireless-wpa-config12
-rw-r--r--docs/examples/wireless-wpa-configsection31
-rw-r--r--docs/examples/wireless-wpa-static18
-rw-r--r--docs/netctl.1.txt141
-rw-r--r--docs/netctl.profile.5.txt599
-rw-r--r--docs/netctl.special.7.txt55
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)