From 475aeb2992734ae1fdd7d29cbd67aba025c5a38e Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Fri, 24 Jul 2020 08:28:29 -0600 Subject: [PATCH] add docs for ifdown/ifup/interfaces too --- Makefile | 5 +- doc/ifdown.scd | 56 ++++++++++++++++ doc/ifup.scd | 56 ++++++++++++++++ doc/interfaces.scd | 160 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 276 insertions(+), 1 deletion(-) create mode 100644 doc/ifdown.scd create mode 100644 doc/ifup.scd create mode 100644 doc/interfaces.scd diff --git a/Makefile b/Makefile index 4c21443..fe0f01f 100644 --- a/Makefile +++ b/Makefile @@ -71,7 +71,10 @@ install: all ${SCDOC} < $< > $@ MANPAGES = \ - doc/ifquery.8 + doc/ifquery.8 \ + doc/ifup.8 \ + doc/ifdown.8 \ + doc/interfaces.5 docs: ${MANPAGES} diff --git a/doc/ifdown.scd b/doc/ifdown.scd new file mode 100644 index 0000000..fd54fff --- /dev/null +++ b/doc/ifdown.scd @@ -0,0 +1,56 @@ +ifdown(8) + +# NAME + +ifdown - take interfaces down + +# SYNOPSIS + +ifdown [<_options_>...] <_interfaces_> + +# DESCRIPTION + +*ifdown* is used to deconfigure interfaces according to how they are +configured in the configuration database. + +# OPTIONS + +*-a, --auto* + Only match interfaces that are marked as _auto_. + +*-h, --help* + Display supported options to ifquery. + +*-i, --interfaces* _FILE_ + Use _FILE_ as the config database. + +*-n, --no-act* + Show what commands would be run instead of actually running + them. Useful for testing configuration changes. + +*-v, --verbose* + Show what commands are being run as they are executed. + +*-I, --include* _PATTERN_ + Include _PATTERN_ when matching against the config or state + database. + +*-S, --state-file* _FILE_ + Use _FILE_ as the state database. + +*-V, --version* + Print the ifupdown-ng version and exit. + +*-X, --exclude* _PATTERN_ + Exclude _PATTERN_ when matching against the config or state + database. + +# SEE ALSO + +*ifup*(8)++ +*ifquery*(8)++ +*interfaces*(5) + +# AUTHORS + +Ariadne Conill diff --git a/doc/ifup.scd b/doc/ifup.scd new file mode 100644 index 0000000..4d50908 --- /dev/null +++ b/doc/ifup.scd @@ -0,0 +1,56 @@ +ifup(8) + +# NAME + +ifup - bring interfaces up + +# SYNOPSIS + +ifup [<_options_>...] <_interfaces_> + +# DESCRIPTION + +*ifup* is used to configure interfaces according to how they are +configured in the configuration database. + +# OPTIONS + +*-a, --auto* + Only match interfaces that are marked as _auto_. + +*-h, --help* + Display supported options to ifquery. + +*-i, --interfaces* _FILE_ + Use _FILE_ as the config database. + +*-n, --no-act* + Show what commands would be run instead of actually running + them. Useful for testing configuration changes. + +*-v, --verbose* + Show what commands are being run as they are executed. + +*-I, --include* _PATTERN_ + Include _PATTERN_ when matching against the config or state + database. + +*-S, --state-file* _FILE_ + Use _FILE_ as the state database. + +*-V, --version* + Print the ifupdown-ng version and exit. + +*-X, --exclude* _PATTERN_ + Exclude _PATTERN_ when matching against the config or state + database. + +# SEE ALSO + +*ifdown*(8)++ +*ifquery*(8)++ +*interfaces*(5) + +# AUTHORS + +Ariadne Conill diff --git a/doc/interfaces.scd b/doc/interfaces.scd new file mode 100644 index 0000000..3719e46 --- /dev/null +++ b/doc/interfaces.scd @@ -0,0 +1,160 @@ +interfaces(5) + +# NAME + +*/etc/network/interfaces* - interface configuration database + +# DESCRIPTION + +The */etc/network/interfaces* file is used to specify how network +interfaces are configured. The file is processed by *ifquery*(8), +*ifup*(8) and *ifdown*(8) to introspect and change system state. + +# FILE SYNTAX + +The interface configuration database is composed of a series of +stanzas. Hash symbols designate comments, which are ignored by +the system. + +A stanza is a collection of triples, where a triple is a key and +value combination that is related to an *object*. Triples which +are not associated with an *object* are considered to be part +of the root of the configuration tree. + +The following is a simple example of a stanza: + +``` +auto eth0 +iface eth0 + address 203.0.113.2/24 + gateway 203.0.113.1 +``` + +This stanza defines an interface named *eth0* which is configured +with an address of *203.0.113.2* and gateway of *203.0.113.1*. + +# SUPPORTED KEYWORDS FOR UNASSOCIATED TRIPLES + +*auto* _object_ + Designates that _object_ should be automatically configured + by the system when appropriate. + +*iface* _object_ + Begins a new declaration for _object_. Any child keyword + associated with the declaration will be stored inside + _object_. + +# SUPPORTED KEYWORDS FOR OBJECT TRIPLES + +Any keyword may be used inside an interface declaration block, but +the system will only respond to certain keywords by default: + +*address* _address_ + Associates an IPv4 or IPv6 address in CIDR notation with + the parent interface. + +*gateway* _address_ + Associates an IPv4 or IPv6 address with the parent interface + for use as a default route (gateway). + +*netmask* _netmask_ + Associates a fallback netmask with the parent interface for + addresses which do not have a CIDR length set. This option + is for backwards compatibility and should not be used in new + deployments. + +*requires* _interfaces_... + Designates one or more required interfaces that must be + brought up before configuration of the parent interface. + Interfaces associated with the parent are taken down at + the same time as the parent. + +*use* _option_ + Designates that an option should be used. See _OPTIONS_ + section for more information on options. + +*pre-down* _command_ + Runs _command_ before taking the interface down. + +*down* _command_ + Runs _command_ when the interface is taken down. + +*post-down* _command_ + Runs _command_ after taking the interface down. + +*pre-up* _command_ + Runs _command_ before bringing the interface up. + +*up* _command_ + Runs _command_ when the interface is brought up. + +*post-up* _command_ + Runs _command_ after bringing the interface up. + +Additional packages such as *bonding*, *bridge*, *tunnel* and +*vrf* add additional keywords to this vocabulary. + +# OPTIONS + +The *use* keyword designates that an _option_ should be used. +This system is extendable by additional packages, but the +most common options are: + +*bond* + The interface is a bonded interface. Configuration + of bonded interfaces requires the *bonding* package + to be installed. + +*bridge* + The interface is an ethernet bridge. Configuration + of ethernet bridges requires the *bridge* package + to be installed. + +*dhcp* + Use a DHCP client to learn the IPv4 address of an + interface. + +*loopback* + Designates the interface as a loopback device. + +*tunnel* + The interface is a tunnel. Configuration of tunnels + requires the *tunnel* package to be installed. + +*vrf* + The interface is a VRF. Configuration of VRFs requires + the *vrf* package to be installed. + +# EXAMPLES + +Configure a bridge interface *br0* with *bond0* attached to it, +which is a failover between *eth0* and *eth1*. This requires +the *bonding* and *bridge* packages to be installed: + +``` +auto br0 +iface br0 + use bridge + requires bond0 + address 203.0.113.2/24 + gateway 203.0.113.1 + +iface bond0 + use bond + requires eth0 eth1 + bond-mode 802.3ad + bond-xmit-hash-policy layer2+3 +``` + +Configure a network interface to use DHCP to learn its IPv4 +address: + +``` +auto eth0 +iface eth0 + use dhcp +``` + +# AUTHORS + +Ariadne Conill