diff options
| author | Rémy Oudompheng <remy@archlinux.org> | 2011-07-14 12:06:59 +0200 |
|---|---|---|
| committer | Rémy Oudompheng <remy@archlinux.org> | 2011-07-14 12:06:59 +0200 |
| commit | 25cfdc655d6e8eee89d48862029b96f07cade243 (patch) | |
| tree | abdf3ec9d6340924fd0c1bcf25ebea97707eb598 /docs | |
| parent | 0fe676b10a8c13fd8e552f7fb56bc845aac7dd9b (diff) | |
| download | netctl-25cfdc655d6e8eee89d48862029b96f07cade243.tar.gz netctl-25cfdc655d6e8eee89d48862029b96f07cade243.tar.xz | |
Documentation overhaul.
Merge ethernet and wireless into a single netcfg-profiles.txt
file aimed at gathering documentation for all connection types
and profile writing.
Signed-off-by: Rémy Oudompheng <remy@archlinux.org>
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ethernet | 77 | ||||
| -rw-r--r-- | docs/features.txt (renamed from docs/features) | 0 | ||||
| -rwxr-xr-x | docs/make.sh | 10 | ||||
| -rw-r--r-- | docs/netcfg-profiles.txt | 180 | ||||
| -rw-r--r-- | docs/wireless | 47 | ||||
| -rw-r--r-- | docs/wireless-dbus | 33 |
6 files changed, 187 insertions, 160 deletions
diff --git a/docs/ethernet b/docs/ethernet deleted file mode 100644 index b328660..0000000 --- a/docs/ethernet +++ /dev/null @@ -1,77 +0,0 @@ -% Ethernet connections -% Arch Linux -% - -# Ethernet options reference - -## Description -This connection method uses the iproute suite of tools and dhcpcd to gain an IP address. - -## Options -INTERFACE (required) -: The wireless interface to configure -IP (required for IPv4) -: Can be either 'static' or 'dhcp'. Static requires at least one of ADDR or IPCFG. -ADDR (requires IP of 'static') -: A single IP address to configure a static IP. For example: -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 (<address range> via <gateway>) -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. -IFOPTS (deprecated, requires IP of 'static') -: Arguments to pass to 'ifconfig'. This allows you to use the syntax for the older 'ifconfig' tool. Retained for compatability. -## IPv6 options -IP6 (required for IPv6) -: Either 'dhcp', 'dhcp-noaddr', 'stateless', 'static'. Leave unset to disable IPv6. -ADDR6 (required for IP6=static) -: An array of IPv6 addresses: prefix length may be specified via '1234:bcd::11/64' syntax. -GATEWAY6 (for IP6=static) -: The gateway address for IPv6 routing. -ROUTES6 -: An array of custom routes (<address range> via <gateway>) -### DNS -DNS -: Array of DNS nameservers. Simply specify the IP's of each of the DNS nameservers. -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. -DNS1, DNS2 (deprecated) -: First and second DNS servers for /etc/resolv.conf -### DHCP -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'. - -## Examples -### Using ADDR and GATEWAY to set static IP and gateway - - IP="static" - ADDR="192.168.1.23" - GATEWAY="192.168.1.1" - -### 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") diff --git a/docs/features b/docs/features.txt index 3a7f3c3..3a7f3c3 100644 --- a/docs/features +++ b/docs/features.txt diff --git a/docs/make.sh b/docs/make.sh index 42bb7fc..da3cacc 100755 --- a/docs/make.sh +++ b/docs/make.sh @@ -1,5 +1,5 @@ #! /bin/bash -PAGES=(ethernet features wireless) +PAGES=(features netcfg netcfg-profiles) make_page() { echo '<html><body>' @@ -7,16 +7,20 @@ make_page() { echo '</body></html>' } +# HTML page generation for page in ${PAGES[@]}; do rm -f ${page}.html if which pandoc &>/dev/null; then - pandoc -s --toc -w html --email-obfuscation=javascript -c header.css -o ${page}.html $page + pandoc -s --toc -w html --email-obfuscation=javascript -c header.css -o ${page}.html $page.txt else - make_page $page > ${page}.html + make_page $page.txt > ${page}.html fi done # Generate manpages if which pandoc &>/dev/null; then pandoc -s -w man -o netcfg.8 netcfg.txt + pandoc -s -w man -o netcfg-profiles.5 netcfg-profiles.txt fi + +# vim: set ts=4 sw=4 et tw=0: diff --git a/docs/netcfg-profiles.txt b/docs/netcfg-profiles.txt new file mode 100644 index 0000000..12a13d7 --- /dev/null +++ b/docs/netcfg-profiles.txt @@ -0,0 +1,180 @@ +% NETCFG-PROFILES(5) netcfg 2.6.4 | Arch Linux +% Rémy Oudompheng <remy@archlinux.org> + James Rayner <james@archlinux.org> +% 14 July 2011 + +NAME +==== + +netcfg-profiles -- netcfg profiles documentation and syntax + +DESCRIPTION +=========== + +The **netcfg**(8) profiles are plain text files that defines variables +for netcfg behaviour. They must be compliant with **bash**(1) shell +syntax and usually do not execute any code. + +They are named */etc/network.d/${profile_name}*. + +OVERVIEW +======== + +Profiles must define mandatory variables: + +INTERFACE +: The name of the associated network interface. +DESCRIPTION +: A description of the profile. +CONNECTION +: The connection type used by the profile. + +Connections define how the network is set up for the profile and also +determine additional configuration variable that control their behaviour. +The available connection types are determined by files in +*/usr/lib/network/connections/*. + +Available connections +===================== + +ethernet +: Standard network configuration, suitable for wired connections. +wireless +: Wireless connection, with **wpa_supplicant**(1) as configuration + back-end. +bridge +: Network bridge setup. +tuntap +: TUN/TAP interfaces. +vlan +: VLAN setup. +openvpn +: OpenVPN setup. +ppp +: PPP connections setup. + +The configuration variable for these connection types is described in the +following sections. + +Ethernet options reference +========================== + +## Description +This connection method uses the iproute suite of tools and dhcpcd to gain an IP address. + +## Options +IP (required for IPv4) +: Can be either 'static' or 'dhcp'. Static requires at least one of ADDR or IPCFG. +ADDR (requires IP of 'static') +: A single IP address to configure a static IP. For example: +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 (<address range> via <gateway>) +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. +IFOPTS (deprecated, requires IP of 'static') +: Arguments to pass to 'ifconfig'. This allows you to use the syntax for the older 'ifconfig' tool. Retained for compatability. +## IPv6 options +IP6 (required for IPv6) +: Either 'dhcp', 'dhcp-noaddr', 'stateless', 'static'. Leave unset to disable IPv6. +ADDR6 (required for IP6=static) +: An array of IPv6 addresses: prefix length may be specified via '1234:bcd::11/64' syntax. +GATEWAY6 (for IP6=static) +: The gateway address for IPv6 routing. +ROUTES6 +: An array of custom routes (of the form *address range* via *gateway*) +### DNS +DNS +: Array of DNS nameservers. Simply specify the IP's of each of the DNS nameservers. +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. +DNS1, DNS2 (deprecated) +: First and second DNS servers for /etc/resolv.conf +### DHCP +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'. + +## Examples +### Using ADDR and GATEWAY to set static IP and gateway + + IP="static" + ADDR="192.168.1.23" + GATEWAY="192.168.1.1" + +### 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") + + +Wireless options reference +========================== + +## 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 it's 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. +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. +IWCONFIG (optional, deprecated) +: Run iwconfig with these options before attempting to configure the connection. + +### 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. diff --git a/docs/wireless b/docs/wireless deleted file mode 100644 index 2e466c7..0000000 --- a/docs/wireless +++ /dev/null @@ -1,47 +0,0 @@ -% WIRELESS netcfg manuals -% Arch Linux -% - -# Wireless options reference -## 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 it's options. - -## Options -INTERFACE (required) -: The wireless interface to configure -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. -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. -IWCONFIG (optional, deprecated) -: Run iwconfig with these options before attempting to configure the connection. - -### 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. diff --git a/docs/wireless-dbus b/docs/wireless-dbus deleted file mode 100644 index fc91f78..0000000 --- a/docs/wireless-dbus +++ /dev/null @@ -1,33 +0,0 @@ -% WIRELESS-DBUS netcfg manuals -% Arch Linux -% - -# 'wireless-dbus' Connection manual -## Description -This connection method uses wpa_supplicant's dbus interface to configure a wireless network connection. - -This connection uses the 'ethernet' connection after successful association and thus supports all of it's options. - -This is presently unmaintained and unsupported. - -## Options -INTERFACE (required) -: The wireless interface to configure -SECURITY (required) -: One of 'wpa', 'wep', 'none' or 'wpa-config' -KEY (required for SECURITY of 'wpa' or 'wep' only) -: Wireless encryption key. -ESSID (this or AP is required) -: Name of network to connect to. -AP (this or ESSID is required) -: AP of the network to connect to. -TIMEOUT -: Time to wait for association. Defaults to 15 seconds. - -### WPA options -WPA_CONF (for SECURITY of 'wpa-config' only) -: Path to wpa_supplicant configuration. Defaults to '/etc/wpa_supplicant.conf' -WPA_DRIVER -: wpa_supplicant driver to be used. Defaults to 'wext' -WPA_OPTS -: Extra arguments for wpa_supplicant not specified otherwise. |