diff options
Diffstat (limited to 'docs/netcfg-profiles.txt')
| -rw-r--r-- | docs/netcfg-profiles.txt | 180 |
1 files changed, 180 insertions, 0 deletions
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. |