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