diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/examples/bonding | 15 | ||||
| -rw-r--r-- | docs/examples/bridge | 14 | ||||
| -rw-r--r-- | docs/examples/ethernet-dhcp | 12 | ||||
| -rw-r--r-- | docs/examples/ethernet-iproute | 10 | ||||
| -rw-r--r-- | docs/examples/ethernet-static | 22 | ||||
| -rw-r--r-- | docs/examples/pppoe | 34 | ||||
| -rw-r--r-- | docs/examples/tunnel-he-ipv6 | 19 | ||||
| -rw-r--r-- | docs/examples/tuntap | 15 | ||||
| -rw-r--r-- | docs/examples/vlan-dhcp | 11 | ||||
| -rw-r--r-- | docs/examples/vlan-static | 22 | ||||
| -rw-r--r-- | docs/examples/wireless-open | 10 | ||||
| -rw-r--r-- | docs/examples/wireless-wep | 17 | ||||
| -rw-r--r-- | docs/examples/wireless-wep-string-key | 12 | ||||
| -rw-r--r-- | docs/examples/wireless-wpa | 16 | ||||
| -rw-r--r-- | docs/examples/wireless-wpa-config | 12 | ||||
| -rw-r--r-- | docs/examples/wireless-wpa-configsection | 31 | ||||
| -rw-r--r-- | docs/examples/wireless-wpa-static | 18 | ||||
| -rw-r--r-- | docs/netctl.1.txt | 141 | ||||
| -rw-r--r-- | docs/netctl.profile.5.txt | 599 | ||||
| -rw-r--r-- | docs/netctl.special.7.txt | 55 |
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) |