From 25cfdc655d6e8eee89d48862029b96f07cade243 Mon Sep 17 00:00:00 2001 From: Rémy Oudompheng Date: Thu, 14 Jul 2011 12:06:59 +0200 Subject: Documentation overhaul. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/ethernet | 77 -------------------- docs/features | 80 --------------------- docs/features.txt | 80 +++++++++++++++++++++ docs/make.sh | 10 ++- docs/netcfg-profiles.txt | 180 +++++++++++++++++++++++++++++++++++++++++++++++ docs/wireless | 47 ------------- docs/wireless-dbus | 33 --------- 7 files changed, 267 insertions(+), 240 deletions(-) delete mode 100644 docs/ethernet delete mode 100644 docs/features create mode 100644 docs/features.txt create mode 100644 docs/netcfg-profiles.txt delete mode 100644 docs/wireless delete mode 100644 docs/wireless-dbus (limited to 'docs') 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 (
via ) -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 (
via ) -### 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 deleted file mode 100644 index 3a7f3c3..0000000 --- a/docs/features +++ /dev/null @@ -1,80 +0,0 @@ -% Netcfg feature documentation -% James Rayner -% 19/10/2009 - -## Network Profile management - -netcfg is profile based. Each network has an individual profile. These profiles can be individually connected/disconnected at any time. The profile configuration varies depending on whether it's a wireless, ethernet (wired) or other type of connection. The available options are documented on the netcfg website and in the included examples. The installed and available connection types can be seen at /usr/lib/network/connections/ - -To connect to a profile called 'mynetwork' which would be located at /etc/network.d/mynetwork, you may run: - - netcfg mynetwork - -To disconnect from the same profile you could run one of: - - netcfg -d mynetwork - netcfg down mynetwork - -To reconnect: - - netcfg -r mynetwork - -For more options, see ''netcfg help'' - -## Start a specific list of profiles on boot - -net-profiles allows you to start some profiles on boot. Specify the profiles you want netcfg to start in the NETWORKS line in /etc/rc.conf. For example: - - NETWORKS=(home mywireless) - -To run on boot, add 'net-profiles' to your DAEMONS line. - -## Wireless automatic connection and roaming support - -Through the use of wpa_actiond which calls commands on a wpa_supplicant event, netcfg now has automatic connection and roaming support. - -To use this: - -1. Install core/wpa_actiond -2. In /etc/rc.conf set WIRELESS_INTERFACE to your wireless interface, eg: - - WIRELESS_INTERFACE="wlan0" - -3. Run /etc/rc.d/net-auto-wireless start - -To run on boot, add 'net-auto-wireles' to your DAEMONS line. - -## Per interface configuration - -Configuration that applies to all profiles using an interface can be set at /etc/network.d/interfaces/$INTERFACE. For example: - - /etc/network.d/interfaces/eth0 - -This is useful for wpa_supplicant options, radio kill switch support, pre/post up/down scripts and net-auto-wireless. It is loaded before a profile is loaded so that any profile based options will take priority. - -## Execute commands before/after interface up/down - -If your interface requires special actions prior/after the establishment/closure of a connection, you may use the PRE_UP, POST_UP, PRE_DOWN, POST_DOWN properties. -For example, if you want to start daemon abc before connecting: - - PRE_UP="/etc/rc.d/abc start" - -Or if you want to mount your network shares after a successful connection, you could use: - - POST_UP="sleep 5; mount /mnt/shares/desktop 2>/dev/null;" - -If the commands specified in these properties return anything other than 0 (success), netcfg aborts the current operation. If you command might fail, create a separate bash script with an "exit 0;" at the end. Alternatively you may add "|| true" to the end of the command that may fail. - -## Output Hooks - -netcfg has limited support to load hooks that handle output. By default it loads the "arch" hook which provides the familiar output that you see. A syslog logging hook is also included. These can be found at /usr/lib/network/hooks - -## Menu based profile selection - -You may select a profile to connect to from a menu. This requires the 'dialog' package installed. To display a menu, simply run 'netcfg-menu'. If you wish to have a menu on boot, set NETWORKS=(menu) in your /etc/rc.conf and ensure that net-profiles is in the DAEMONS array. - -## Debugging - -To run netcfg with debugging output, set the NETCFG_DEBUG environment variable to "yes", for example: - - NETCFG_DEBUG="yes" netcfg diff --git a/docs/features.txt b/docs/features.txt new file mode 100644 index 0000000..3a7f3c3 --- /dev/null +++ b/docs/features.txt @@ -0,0 +1,80 @@ +% Netcfg feature documentation +% James Rayner +% 19/10/2009 + +## Network Profile management + +netcfg is profile based. Each network has an individual profile. These profiles can be individually connected/disconnected at any time. The profile configuration varies depending on whether it's a wireless, ethernet (wired) or other type of connection. The available options are documented on the netcfg website and in the included examples. The installed and available connection types can be seen at /usr/lib/network/connections/ + +To connect to a profile called 'mynetwork' which would be located at /etc/network.d/mynetwork, you may run: + + netcfg mynetwork + +To disconnect from the same profile you could run one of: + + netcfg -d mynetwork + netcfg down mynetwork + +To reconnect: + + netcfg -r mynetwork + +For more options, see ''netcfg help'' + +## Start a specific list of profiles on boot + +net-profiles allows you to start some profiles on boot. Specify the profiles you want netcfg to start in the NETWORKS line in /etc/rc.conf. For example: + + NETWORKS=(home mywireless) + +To run on boot, add 'net-profiles' to your DAEMONS line. + +## Wireless automatic connection and roaming support + +Through the use of wpa_actiond which calls commands on a wpa_supplicant event, netcfg now has automatic connection and roaming support. + +To use this: + +1. Install core/wpa_actiond +2. In /etc/rc.conf set WIRELESS_INTERFACE to your wireless interface, eg: + + WIRELESS_INTERFACE="wlan0" + +3. Run /etc/rc.d/net-auto-wireless start + +To run on boot, add 'net-auto-wireles' to your DAEMONS line. + +## Per interface configuration + +Configuration that applies to all profiles using an interface can be set at /etc/network.d/interfaces/$INTERFACE. For example: + + /etc/network.d/interfaces/eth0 + +This is useful for wpa_supplicant options, radio kill switch support, pre/post up/down scripts and net-auto-wireless. It is loaded before a profile is loaded so that any profile based options will take priority. + +## Execute commands before/after interface up/down + +If your interface requires special actions prior/after the establishment/closure of a connection, you may use the PRE_UP, POST_UP, PRE_DOWN, POST_DOWN properties. +For example, if you want to start daemon abc before connecting: + + PRE_UP="/etc/rc.d/abc start" + +Or if you want to mount your network shares after a successful connection, you could use: + + POST_UP="sleep 5; mount /mnt/shares/desktop 2>/dev/null;" + +If the commands specified in these properties return anything other than 0 (success), netcfg aborts the current operation. If you command might fail, create a separate bash script with an "exit 0;" at the end. Alternatively you may add "|| true" to the end of the command that may fail. + +## Output Hooks + +netcfg has limited support to load hooks that handle output. By default it loads the "arch" hook which provides the familiar output that you see. A syslog logging hook is also included. These can be found at /usr/lib/network/hooks + +## Menu based profile selection + +You may select a profile to connect to from a menu. This requires the 'dialog' package installed. To display a menu, simply run 'netcfg-menu'. If you wish to have a menu on boot, set NETWORKS=(menu) in your /etc/rc.conf and ensure that net-profiles is in the DAEMONS array. + +## Debugging + +To run netcfg with debugging output, set the NETCFG_DEBUG environment variable to "yes", for example: + + NETCFG_DEBUG="yes" netcfg 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 '' @@ -7,16 +7,20 @@ make_page() { echo '' } +# 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 + James Rayner +% 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 (
via ) +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. -- cgit v1.2.3-24-g4f1b