diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 18 | ||||
| -rw-r--r-- | docs/features.txt | 155 | ||||
| -rw-r--r-- | docs/footer.txt | 22 | ||||
| -rw-r--r-- | docs/index | 57 | ||||
| -rw-r--r-- | docs/index.txt | 57 | ||||
| -rwxr-xr-x | docs/make.sh | 26 | ||||
| -rwxr-xr-x | docs/makewebsite.sh | 7 | ||||
| -rw-r--r-- | docs/netcfg-profiles.5.txt | 310 | ||||
| -rw-r--r-- | docs/netcfg-profiles.txt | 287 | ||||
| -rw-r--r-- | docs/netcfg.8.txt | 90 | ||||
| -rw-r--r-- | docs/netcfg.txt | 97 | ||||
| -rw-r--r-- | docs/website/footer.html | 9 | ||||
| -rw-r--r-- | docs/website/header.html | 54 |
13 files changed, 606 insertions, 583 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..5e434a3 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,18 @@ +# Makefile for netcfg documentation + +MANPAGES = netcfg.8 netcfg-profiles.5 +WEBPAGES = index.html features.html $(MANPAGES:%=%.html) + +.PHONY: all clean + +all: $(MANPAGES) $(WEBPAGES) + +$(MANPAGES): %: %.txt footer.txt + a2x -d manpage -f manpage -a manversion=$(VERSION) $< + +$(WEBPAGES): %.html: %.txt + asciidoc -a version=$(VERSION) $< + +clean: + -@rm -vf $(MANPAGES) $(WEBPAGES) 2>/dev/null + diff --git a/docs/features.txt b/docs/features.txt index 8120baf..17fcd8a 100644 --- a/docs/features.txt +++ b/docs/features.txt @@ -1,80 +1,143 @@ -% 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 +Netcfg Features +--------------- + +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 +--------------------- +netcfg -d mynetwork +netcfg down mynetwork +--------------------- To reconnect: - netcfg -r mynetwork +------------------- +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 this order) in the NETWORKS line in /etc/conf.d/netcfg. Prefix a profile with a @ to start it in the background. For example: +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 this order) in the +NETWORKS+ line +in '/etc/conf.d/netcfg'. Prefix a profile with a @ to start it in the +background. For example: + +-------------------------------- +NETWORKS=(@adsl @mywireless lan) +-------------------------------- - NETWORKS=(@adsl @mywireless lan) - -To run on boot, add 'net-profiles' to your DAEMONS line. +To run on boot, add `net-profiles' to your +DAEMONS+ line in +'/etc/rc.conf'. -## 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. +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: +. Install core/wpa_actiond +. In '/etc/rc.conf' set +WIRELESS_INTERFACE+ to your wireless interface, eg: ++ +--------------------------- +WIRELESS_INTERFACE="wlan0" +--------------------------- +. 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: - WIRELESS_INTERFACE="wlan0" - -3. Run /etc/rc.d/net-auto-wireless start +------------------------------ +/etc/network.d/interfaces/eth0 +------------------------------ -To run on boot, add 'net-auto-wireles' to your DAEMONS line. +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. -## Per interface configuration -Configuration that applies to all profiles using an interface can be set at /etc/network.d/interfaces/$INTERFACE. For example: +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: - /etc/network.d/interfaces/eth0 +---------------------------- +PRE_UP="/etc/rc.d/abc start" +---------------------------- -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. +Or if you want to mount your network shares after a successful +connection, you could use: -## Execute commands before/after interface up/down +--------------------------------------------------------- +POST_UP="sleep 5; mount /mnt/shares/desktop 2>/dev/null;" +--------------------------------------------------------- -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: +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. - 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;" +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/' -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 +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/conf.d/netcfg' and ensure that `net-profiles' is in the +DAEMONS+ +array. -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 +Menu based wireless network selection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can also connect to a wireless network using a menu. To display the +menu, run `wifi-menu [-o] [interface]`. The _interface_ defaults to the ++WIRELESS_INTERFACE+ from '/etc/conf.d/netcfg'. When `-o' is specified, +passwords are obscured (ie masked and saved in hexadecimal form). The +tool generates a profile file if no suitable profile was found. -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 +Debugging +~~~~~~~~~ +To run netcfg with debugging output, set the NETCFG_DEBUG environment +variable to "yes", for example: -To run netcfg with debugging output, set the NETCFG_DEBUG environment variable to "yes", for example: +------------------------------------- +NETCFG_DEBUG="yes" netcfg <arguments> +------------------------------------- - NETCFG_DEBUG="yes" netcfg <arguments> diff --git a/docs/footer.txt b/docs/footer.txt new file mode 100644 index 0000000..2a26199 --- /dev/null +++ b/docs/footer.txt @@ -0,0 +1,22 @@ +More information can be found at *<https://wiki.archlinux.org/index.php/Netcfg>*. + + +BUGS +---- +For bugtracking, *<http://bugs.archlinux.org/>* is used. + + +AUTHORS +------- +netcfg has many contributors. +For a list of contributors, use `git shortlog -s` on the netcfg.git repository. + +Current maintainer: + +* Jouke Witteveen <j.witteveen@gmail.com> + +Past maintainers: + +* Rémy Oudompheng <remy@archlinux.org> +* James Rayner <james@archlinux.org> + diff --git a/docs/index b/docs/index deleted file mode 100644 index d689c61..0000000 --- a/docs/index +++ /dev/null @@ -1,57 +0,0 @@ -% netcfg - Profile based network connection tool -% James Rayner -% - -# netcfg - -## About - -netcfg is profile based network connection tool. It can connect to wireless, wired and PPP connections and is easily expanded to support other connection types. - -## Features - -* Easy configuration -* Wireless, wired and ppp connections -* Wireless roaming and automatic connection (using wpa_actiond/wpa_supplicant) -* Radio kill switch (rfkill) awareness -* pm-utils suspend/resume support -* Execution of commands before/after up/down -* Wired link detection (using ifplugd) -* Modern iproute and wpa_supplicant based connectivity - -## Download - -The latest version is 2.5.5 - -Arch users can install netcfg via pacman, it is located in the [core] repository. Testing versions can often be found in the [testing] repository. - - pacman -S netcfg - -The source for netcfg can be found on the [Arch Linux ftp](ftp://ftp.archlinux.org/other/netcfg/), or [mirrored here](http://rayner.id.au/netcfg/source/) - -[Download latest source (2.5.5)](ftp://ftp.archlinux.org/other/netcfg/netcfg-2.5.5.tar.gz) - -### Optional dependencies - -* wpa_actiond: Wireless Roaming/autoconnect -* ifplugd: Wired link detection -* dialog: Menu support - - -## Documentation - -* [Quick Start Guide](http://wiki.archlinux.org/index.php/Network_Profiles) -* [Features](features.html) -* [Wireless options reference](wireless.html) -* [Ethernet options reference](ethernet.html) - -## Contact - -To report bugs or issues with netcfg, please use the [Arch Linux Bug Tracker](http://bugs.archlinux.org) - -To seek help using netcfg, please post on the [Arch Linux Forums](http://bbs.archlinux.org) - -To contact James regarding netcfg, please [email](mailto:james@archlinux.org) - - - diff --git a/docs/index.txt b/docs/index.txt new file mode 100644 index 0000000..4fb4e4a --- /dev/null +++ b/docs/index.txt @@ -0,0 +1,57 @@ +netcfg {version} +---------------- + +About +~~~~~ +netcfg is profile based network connection tool. It can connect to a +variety of connections (including wired, wireless and PPP) and is easily +extended to support other connection types. + + +Features +~~~~~~~~ + +* Easy configuration +* Wireless, wired and ppp connections +* Wireless roaming and automatic connection (using wpa_actiond/wpa_supplicant) +* Radio kill switch (rfkill) awareness +* pm-utils suspend/resume support +* Execution of commands before/after up/down +* Wired link detection (using ifplugd) +* Modern iproute and wpa_supplicant based connectivity + + +Optional dependencies +~~~~~~~~~~~~~~~~~~~~~ + +* wpa_supplicant: for wireless networking +* wpa_actiond: Wireless Roaming/autoconnect +* ifplugd: Wired link detection +* dialog: Menu support +* bridge-utils: To set up bridge connections + + +Documentation +~~~~~~~~~~~~~ + +* http://wiki.archlinux.org/index.php/Netcfg[Arch Linux Wiki page] +* link:features.html[Feature documentation] +* link:netcfg.8.html[netcfg man page] +* link:netcfg-profiles.5.html[netcfg-profiles man page] + + +Contact +~~~~~~~ + +To report bugs or issues with netcfg, please use the +http://bugs.archlinux.org[Arch Linux Bug Tracker] + +To seek help using netcfg, please post on the +http://bbs.archlinux.org[Arch Linux Forums] + + +Copyright +~~~~~~~~~ +netcfg is Copyright (C) 2011-2012, Netcfg Development Team +and Copyright (C) 2007-2010 James Rayner <james@archlinux.org> +and is licensed through the Modified BSD License. diff --git a/docs/make.sh b/docs/make.sh deleted file mode 100755 index da3cacc..0000000 --- a/docs/make.sh +++ /dev/null @@ -1,26 +0,0 @@ -#! /bin/bash -PAGES=(features netcfg netcfg-profiles) - -make_page() { - echo '<html><body>' - grep -v '^%' $1 | markdown -x def_list -x headerid /dev/stdin - 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.txt - else - 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/makewebsite.sh b/docs/makewebsite.sh deleted file mode 100755 index bb3d000..0000000 --- a/docs/makewebsite.sh +++ /dev/null @@ -1,7 +0,0 @@ -#! /bin/bash -PAGES=(index features netcfg netcfg-profiles) - -for page in ${PAGES[@]}; do - rm ${page}.html - pandoc --toc -w html --email-obfuscation=javascript -B website/header.html -A website/footer.html -o ${page}.html $page -done diff --git a/docs/netcfg-profiles.5.txt b/docs/netcfg-profiles.5.txt new file mode 100644 index 0000000..7c33500 --- /dev/null +++ b/docs/netcfg-profiles.5.txt @@ -0,0 +1,310 @@ +NETCFG-PROFILES(5) +================== + +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. +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 +-------------------------- + +Description +~~~~~~~~~~~ +This connection method uses the iproute suite of tools and dhcpcd to +gain an IP address. + ++IP+ (required for IPv4):: + Can be either `static' or `dhcp'. 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. 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 (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_) + +DNS configuration +^^^^^^^^^^^^^^^^^ ++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' + +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" +--------------------- + +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 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. + +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. + ++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) + + +Options for `tuntap' connections +-------------------------------- +The options of `ethernet' connections apply to set up standard IP +connectivity. + ++MODE+:: + Set to `tun' or `tap'. ++USER+:: + The owning user of the tun/tap interface. ++GROUP+:: + The owning group of the tun/tap interface. + + +Options for `ppp' connections +----------------------------- ++PEER+:: + The *pppd*(8) peer to use. ++PPP_TIMEOUT+:: + *pppd*(8) timeout. + + +Options for `vlan' connections +------------------------------ ++INTERFACE+:: + The name of the virtual interface. ++VLAN_PHYS_DEV+:: + The name of the associated physical interface. ++VLAN_ID+:: + See *ip*(8). + + +Options for `tunnel' connections +-------------------------------- +Standard `ethernet' options apply for IP configuration. + ++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 `bond' connections +------------------------------ +Standard `ethernet' options apply for IP configuration. + ++SLAVE_INTERFACES+ (Bash array):: + An array of names of interfaces to be bound together. + + +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. + + +SEE ALSO +-------- +include::footer.txt[] diff --git a/docs/netcfg-profiles.txt b/docs/netcfg-profiles.txt deleted file mode 100644 index 1c666bc..0000000 --- a/docs/netcfg-profiles.txt +++ /dev/null @@ -1,287 +0,0 @@ -% NETCFG-PROFILES(5) netcfg 2.7 | Arch Linux -% Jouke Witteveen <j.witteveen@gmail.com> - Rémy Oudompheng <remy@archlinux.org> - James Rayner <james@archlinux.org> -% 29 February 2012 - -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. -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 -========================== - -## Description -This connection method uses the iproute suite of tools and dhcpcd to gain an IP address. - -IP (required for IPv4) -: Can be either 'static' or 'dhcp'. 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. 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 (of the form *address range* via *gateway*) - -## 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 configuration -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 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. -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. -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" - -### 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 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. -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. - -Options for 'bridge' connections -================================ - -The options of 'ethernet' connections apply to set up standard IP connectivity. - -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) - -Options for 'tuntap' connections -================================ - -The options of 'ethernet' connections apply to set up standard IP connectivity. - -MODE -: Set to 'tun' or 'tap'. -USER -: The owning user of the tun/tap interface. -GROUP -: The owning group of the tun/tap interface. - -Options for 'ppp' connections -================================ - -PEER -: The **pppd**(8) peer to use. -PPP_TIMEOUT -: **pppd**(8) timeout. - -Options for 'vlan' connections -================================ - -INTERFACE -: The name of the virtual interface. -VLAN_PHYS_DEV -: The name of the associated physical interface. -VLAN_ID -: See **ip**(8). - -Options for 'tunnel' connections -================================ - -Standard 'ethernet' options apply for IP configuration. - -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 'bond' connections -============================== - -Standard 'ethernet' options apply for IP configuration. - -SLAVE_INTERFACES (Bash array) -: An array of names of interfaces to be bound together. - -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. - diff --git a/docs/netcfg.8.txt b/docs/netcfg.8.txt new file mode 100644 index 0000000..a878ba3 --- /dev/null +++ b/docs/netcfg.8.txt @@ -0,0 +1,90 @@ +NETCFG(8) +========= + +NAME +---- +netcfg - start/stop/control network profiles + + +SYNOPSIS +-------- +netcfg [_options_] + +netcfg *profile* + + +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 '/etc/rc.d/net-profiles' daemon +in '/etc/rc.conf' +DAEMONS+ line. 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`. + + +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 +*-i, 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. + + +SEE ALSO +-------- +*netcfg-profiles*(5) on how to configure netcfg. + +include::footer.txt[] diff --git a/docs/netcfg.txt b/docs/netcfg.txt deleted file mode 100644 index 499219f..0000000 --- a/docs/netcfg.txt +++ /dev/null @@ -1,97 +0,0 @@ -% NETCFG(8) netcfg 2.7 | Arch Linux -% Jouke Witteveen <j.witteveen@gmail.com> - Rémy Oudompheng <remy@archlinux.org> - James Rayner <james@archlinux.org> -% 2012-02-29 - -NAME -==== -netcfg -- start/stop/control network profiles - -SYNOPSIS -======== -netcfg [*options*] - -netcfg **profile** - -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 */etc/rc.d/net-profiles* -daemon in */etc/rc.conf* **DAEMONS** line. After boot time, it may -be used to start profiles, simply by passing only the profile name. - -When run without options, netxfg **profile** is equivalent to *netcfg -u -profile*. - -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 -`-i`, 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. -*/etc/network.d/hooks/* -: See /usr/share/doc/netcfg/contrib for examples. - -ENVIRONMENT VARIABLES -===================== - -**NETCFG_DEBUG** -: Set to 1 to activate debug output. - -BUGS -==== - -None, hopefully, but if you do find one of these elusive things, -please submit at http://bugs.archlinux.org/ or email one of the authors -below. - -SEE ALSO -======== - -**netcfg-profiles**(5) for how to configure netcfg. diff --git a/docs/website/footer.html b/docs/website/footer.html deleted file mode 100644 index c933e4a..0000000 --- a/docs/website/footer.html +++ /dev/null @@ -1,9 +0,0 @@ - </div> - <div class="foot"> - Arch Linux copyright © 2002-2009 <a href="mailto:jvinet@zeroflux.org" title="contact Judd Vinet">Judd Vinet</a> and <a href="mailto:aaron@archlinux.org" title="contact Aaron Griffin">Aaron Griffin</a>.<br /> - The Arch Linux name and logo are recognized trademarks. Some rights - reserved.<br /> - The registered trademark Linux® is used pursuant to a sublicense from LMI, the exclusive licensee of Linus Torvalds, owner of the mark on a world-wide basis. - </div> - </body> -</html> diff --git a/docs/website/header.html b/docs/website/header.html deleted file mode 100644 index f10db1c..0000000 --- a/docs/website/header.html +++ /dev/null @@ -1,54 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> - <head> - <title>Arch Linux</title> - <meta http-equiv="content-type" content="text/html; charset=utf-8" /> - <link rel="stylesheet" href="http://archlinux.org/media/arch.css" /> - <link rel="icon" href="/media/favicon.ico" type="image/x-icon" /> - <link rel="shortcut icon" href="/media/favicon.ico" type="image/x-icon" /> - -<link rel="alternate" type="application/rss+xml" title="Arch Linux News Updates" href="/feeds/news/" /> -<link rel="alternate" type="application/rss+xml" title="Arch Linux Package Updates" href="/feeds/packages/" /> -<style type="text/css"> - dt -{ -font-weight: bold; -} -dd -{ - margin-left: 2em; -} -h3 -{ - margin-top: 10px; -} -pre -{ - padding-bottom: 10px; -} -h1 a, h2 a, h3 a { - color: #000000; -} -* ul { padding: 10px 20px; } - </style> - </head> - <body> - <div id="head_container"> - <div id="title"> - <div id="logo"><h1 id="archtitle"><a href="http://archlinux.org/" title="Arch Linux (Home)">Arch Linux</a></h1></div> - </div> - <div id="main_nav"> - <ul> - <li><a href="http://aur.archlinux.org">AUR</a></li> - <li><a href="http://bugs.archlinux.org">Bugs</a></li> - <li><a href="http://wiki.archlinux.org/index.php/Network_Profiles">Wiki</a></li> - <li><a href="http://bbs.archlinux.org">Forums</a></li> - <li class="selected"><a href="/netcfg">netcfg</a></li> - <li><a href="http://archlinux.org">Home</a></li> - </ul> - </div> - </div> - <div id="content"> - - - |