Documentation update

5 files changed, 222 insertions, 0 deletions

diff --git a/docs/ethernet b/docs/ethernet
new file mode 100644
index 0000000..1781a03
--- /dev/null
+++ b/docs/ethernet
@@ -0,0 +1,59 @@
+% Ethernet connections
+% Arch Linux
+%
+
+
+## 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)
+:   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
+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. 
+### 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
+:   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
+### 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
new file mode 100644
index 0000000..3a7f3c3
--- /dev/null
+++ b/docs/features
@@ -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 <arguments>
diff --git a/docs/make.sh b/docs/make.sh
new file mode 100755
index 0000000..b101117
--- /dev/null
+++ b/docs/make.sh
@@ -0,0 +1,7 @@
+#! /bin/bash
+PAGES=(index ethernet features wireless)
+
+for page in ${PAGES[@]}; do
+    rm ${page}.html
+    pandoc -s --toc -w html --email-obfuscation=javascript -c header.css -o ${page}.html $page
+done
diff --git a/docs/wireless b/docs/wireless
new file mode 100644
index 0000000..30d9b28
--- /dev/null
+++ b/docs/wireless
@@ -0,0 +1,43 @@
+% WIRELESS netcfg manuals 
+% Arch Linux
+%
+
+# 'wireless' Connection manual
+## 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'. Old iwconfig based configuration code can be used with 'wep-old' and 'none-old'.
+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 (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)
+:   Arguments to pass to iwconfig before attempting to configure the connection. For example, BSSID.
+
+### 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)
+:   The wpa_supplicant driver interface to be used. Defaults to 'wext'. nl80211 based drivers are recommended to use 'nl80211'
+ 
+### 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
new file mode 100644
index 0000000..fc91f78
--- /dev/null
+++ b/docs/wireless-dbus
@@ -0,0 +1,33 @@
+% 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.