From 4e457e0efd0e5fd5df24c7e9ed63b02d0196ea8d Mon Sep 17 00:00:00 2001 From: Jouke Witteveen Date: Fri, 28 Dec 2012 02:38:58 +0100 Subject: Forking netcfg to netctl (1/2) This commit contains the moving of files. --- docs/Makefile | 19 +-- docs/examples/openvpn | 5 - docs/examples/ppp | 4 - docs/features.txt | 147 --------------------- docs/footer.txt | 22 ---- docs/index.txt | 57 -------- docs/netcfg-profiles.5.txt | 321 --------------------------------------------- docs/netcfg.8.txt | 91 ------------- docs/netctl.1.txt | 91 +++++++++++++ docs/netctl.profile.5.txt | 321 +++++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 417 insertions(+), 661 deletions(-) delete mode 100644 docs/examples/openvpn delete mode 100644 docs/examples/ppp delete mode 100644 docs/features.txt delete mode 100644 docs/footer.txt delete mode 100644 docs/index.txt delete mode 100644 docs/netcfg-profiles.5.txt delete mode 100644 docs/netcfg.8.txt create mode 100644 docs/netctl.1.txt create mode 100644 docs/netctl.profile.5.txt (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index ef05303..879e5ac 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,21 +1,12 @@ -# Makefile for netcfg documentation +# Makefile for netctl documentation -MANPAGES = netcfg.8 netcfg-profiles.5 -WEBPAGES = index.html features.html $(MANPAGES:%=%.html) +MANPAGES = netctl.1 netctl.profile.5 netctl.special.7 -.PHONY: manpages website clean +.PHONY: manpages clean manpages: $(MANPAGES) -website: website.tar.xz - -$(MANPAGES): %: %.txt footer.txt +$(MANPAGES): %: %.txt a2x -d manpage -f manpage -a manversion=$(VERSION) $< -$(WEBPAGES): %.html: %.txt - asciidoc -a disable-javascript -a linkcss -a max-width=960px $< - -website.tar.xz: $(WEBPAGES) - tar --transform "s%^%netcfg/%" -cJf $@ $^ -C /etc/asciidoc/stylesheets asciidoc.css - clean: - -@rm -vf $(MANPAGES) $(WEBPAGES) website.tar.xz 2>/dev/null + -@rm -vf $(MANPAGES) 2>/dev/null diff --git a/docs/examples/openvpn b/docs/examples/openvpn deleted file mode 100644 index b6106aa..0000000 --- a/docs/examples/openvpn +++ /dev/null @@ -1,5 +0,0 @@ -CONNECTION="openvpn" -INTERFACE="ignore" -OVPN_CONFIG="/etc/openvpn/example/openvpn.conf" -OVPN_PID_FILE="/tmp/openvpn.example.pid" -OVPN_FLAGS="" diff --git a/docs/examples/ppp b/docs/examples/ppp deleted file mode 100644 index dfb6bc1..0000000 --- a/docs/examples/ppp +++ /dev/null @@ -1,4 +0,0 @@ -CONNECTION='ppp' -INTERFACE='ignore' -PEER='provider' -PPP_TIMEOUT=10 diff --git a/docs/features.txt b/docs/features.txt deleted file mode 100644 index 4cf7def..0000000 --- a/docs/features.txt +++ /dev/null @@ -1,147 +0,0 @@ -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 ---------------------- - -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 at boot time. Specify the -profiles you want netcfg to start (in the order you want them to be -started) 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) --------------------------------- - -Alternatively, you can have netcfg restart the profiles you had running -at the previous shutdown by specifying +NETWORKS=(last)+. - -Next, enable the `netcfg' systemd service or, on legacy systems, add -`net-profiles' to +DAEMONS+ 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. - -To use this: - -. Install core/wpa_actiond -. In '/etc/conf.d/netcfg' set +WIRELESS_INTERFACE+ to your wireless interface, eg: -+ ---------------------------- -WIRELESS_INTERFACE="wlan0" ---------------------------- -. Run `systemctl start net-auto-wireless` - -To run on boot, enable the `net-auto-wireless' systemd service. - - -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 run a -script before connecting: - ------------------------- -PRE_UP="/path/to/script" ------------------------- - -Or if you want to manage resolv.conf through resolvconf, you could -remove any DNS related options and use the following, which will be run -after a successful connection: - ----------------------------------------------------------------- -POST_UP='echo "nameserver 8.8.8.8" | resolvconf -a "$INTERFACE"' ----------------------------------------------------------------- - -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/conf.d/netcfg' and ensure that `net-profiles' is in the +DAEMONS+ -array. A boot-time menu is not supported on systemd installations. - - -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. - - -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/footer.txt b/docs/footer.txt deleted file mode 100644 index c9efbad..0000000 --- a/docs/footer.txt +++ /dev/null @@ -1,22 +0,0 @@ -More information can be found at **. - - -BUGS ----- -For bugtracking, ** 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 - -Past maintainers: - -* Rémy Oudompheng -* James Rayner - diff --git a/docs/index.txt b/docs/index.txt deleted file mode 100644 index 10ba380..0000000 --- a/docs/index.txt +++ /dev/null @@ -1,57 +0,0 @@ -netcfg home page ----------------- - -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 -~~~~~~~~~~~~~ - -* https://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 -https://bugs.archlinux.org[Arch Linux Bug Tracker] - -To seek help using netcfg, please post on the -https://bbs.archlinux.org[Arch Linux Forums] - - -Copyright -~~~~~~~~~ -netcfg is Copyright (C) 2011-2012, Netcfg Development Team -and Copyright (C) 2007-2010 James Rayner -and is licensed through the Modified BSD License. diff --git a/docs/netcfg-profiles.5.txt b/docs/netcfg-profiles.5.txt deleted file mode 100644 index f929e47..0000000 --- a/docs/netcfg-profiles.5.txt +++ /dev/null @@ -1,321 +0,0 @@ -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 behavior. They must be compliant with *bash*(1) shell syntax and -usually do not execute any code. - -They are named '/etc/network.d/$\{profile_name}', where -+$\{profile_name\}+ must not contain a newline character and should not -start with the `@'-sign. - - -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 -behavior. 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):: - Either `static' or `dhcp'. Set to `no' to have netcfg bring the interface - up but assign no addresses. 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. -+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_) -+DAD_TIMEOUT+:: - Time to wait for Duplicate Address Detection to succeed. Defaults to - 3 seconds. - -DNS configuration -^^^^^^^^^^^^^^^^^ -+DNS+:: - Array of DNS nameservers. Simply specify the IP's of each of the DNS - nameservers. -+DNS_OPTIONS+:: - Array of ``option'' lines for '/etc/resolv.conf' -+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. -+PRIORITY+ (optional):: - Priority group for the network. The matched network with the highest - priority will be selected. Defaults to 0. - -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.8.txt b/docs/netcfg.8.txt deleted file mode 100644 index 54fbd78..0000000 --- a/docs/netcfg.8.txt +++ /dev/null @@ -1,91 +0,0 @@ -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 'netcfg' systemd service, or, on -legacy systems, by adding 'net-profiles' to +DAEMONS+ in '/etc/rc.conf'. -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 -*-D, 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/netctl.1.txt b/docs/netctl.1.txt new file mode 100644 index 0000000..54fbd78 --- /dev/null +++ b/docs/netctl.1.txt @@ -0,0 +1,91 @@ +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 'netcfg' systemd service, or, on +legacy systems, by adding 'net-profiles' to +DAEMONS+ in '/etc/rc.conf'. +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 +*-D, 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/netctl.profile.5.txt b/docs/netctl.profile.5.txt new file mode 100644 index 0000000..f929e47 --- /dev/null +++ b/docs/netctl.profile.5.txt @@ -0,0 +1,321 @@ +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 behavior. They must be compliant with *bash*(1) shell syntax and +usually do not execute any code. + +They are named '/etc/network.d/$\{profile_name}', where ++$\{profile_name\}+ must not contain a newline character and should not +start with the `@'-sign. + + +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 +behavior. 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):: + Either `static' or `dhcp'. Set to `no' to have netcfg bring the interface + up but assign no addresses. 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. ++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_) ++DAD_TIMEOUT+:: + Time to wait for Duplicate Address Detection to succeed. Defaults to + 3 seconds. + +DNS configuration +^^^^^^^^^^^^^^^^^ ++DNS+:: + Array of DNS nameservers. Simply specify the IP's of each of the DNS + nameservers. ++DNS_OPTIONS+:: + Array of ``option'' lines for '/etc/resolv.conf' ++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. ++PRIORITY+ (optional):: + Priority group for the network. The matched network with the highest + priority will be selected. Defaults to 0. + +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[] -- cgit v1.2.3-24-g4f1b