summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDarren 'Tadgy' Austin <darren@afterdark.org.uk>2020-11-17 18:47:39 +0000
committerRobby Workman <rworkman@slackware.com>2021-02-27 23:47:58 -0600
commitca2c2ff6ce2b0be389e7041837178a3304bebc73 (patch)
tree45455ce765eb48286915fd1b84ec66f07a30338a
parente73a1f9586eaa40f02f9d187951ef96c3767ac82 (diff)
downloadslacknetsetup-ca2c2ff6ce2b0be389e7041837178a3304bebc73.tar.xz
Add first draft of README.networking.
-rw-r--r--README.networking550
1 files changed, 550 insertions, 0 deletions
diff --git a/README.networking b/README.networking
new file mode 100644
index 0000000..0dfa103
--- /dev/null
+++ b/README.networking
@@ -0,0 +1,550 @@
+Slackware Network Configuration
+===============================
+
+Networking in Slackware is configured by the /etc/rc.d/rc.inet1 script, and the
+configuration file /etc/rc.d/rc.inet1.conf. Wireless interfaces are configured
+just like any network interface, but accept many more configuration parameters.
+
+The rc.inet1.conf file contains a series of variable array definitions, with
+each array index corresponding to a single network interface. This means that
+each set of parameters with an index of 0 configure the first interface (since
+indexing starts at 0), parameters with an index of 1 configure the second
+interface, and so on. Not all parameters need to be set for each type of
+interface, or interface number. This is better illustrated with examples, which
+you will find in the documentation below.
+
+
+Starting and Stopping Interfaces
+--------------------------------
+The way to start networking (configuring all NICs, bringing the interfaces up,
+and creating a default route, if required) is by running the command:
+ /etc/rc.d/rc.inet1 start
+This command will configure all networking interfaces which are defined in the
+configuration file, and is used at boot time to bring networking up.
+
+The counterpart to this is the:
+ /etc/rc.d/rc.inet1 stop
+command, which will bring all networking to a stop. It is advised to use this
+with caution as it can make your host completely inaccessable from the network.
+
+Restarting the whole network (all available network interfaces) and resetting
+the default gateway (if set) is done in a similar fashion to starting it:
+ /etc/rc.d/rc.inet1 restart
+And will first deconfigure all interfaces, before bringing them back up - which
+is functionally equalivant to a 'stop' and 'start' operation.
+
+More specifically speaking, you can start/stop/restart any network interface on
+an individual basis using the commands:
+ /etc/rc.d/rc.inet1 <interface>_start
+ /etc/rc.d/rc.inet1 <interface>_stop
+ /etc/rc.d/rc.inet1 <interface>_restart
+where <interface> is the name of an existing network interface (eth0, eth1,
+wlan0, etc).
+
+
+Guided Networking Configuration
+-------------------------------
+The 'netconfig' script is capable of configuring basic networking parameters for
+the first ethernet interface of the system, and writing a
+/etc/rc.d/rc.inet1.conf configuration file. 'netconfig' is usually invoked
+during installation to configure the first ethernet interface of your freshly
+installed system.
+
+'netconfig' is capable of configuring a set of IPv4 and/or IPv6 addresses for an
+interface, or setting the interface to be configured using DHCP (both DHCPv4 and
+DHCPv6) and IPv6 StateLess Address Auto Configuration (SLAAC). A default
+gateway and nameservers can also be configured through the guided interface.
+
+The option to use NetworkManager for interface configuration (instead of
+rc.inet1.conf) is also available.
+
+For most users with a single ethernet interface, and simple IP configuration
+requirements, 'netconfig' can completely configure the networking sub-system for
+you.
+
+
+Deprecated and New IPv4 Configuration Syntax
+--------------------------------------------
+With the release of Slackware 15.0, several parameters used in older
+rc.inet1.conf configurations have become deprecated and are substituted by a
+new, singular, IP parameter for v4 addresses.
+
+Specifically, the following parameters used in previous rc.inet1.conf
+configurations to configure IPv4 addresses have become deprecated:
+ IPADDR[x]=""
+ NETMASK[x]=""
+ IPALIASES[x]=""
+These parameters should no longer be used in new configurations.
+
+New configurations should use the updated syntax parameter:
+ IPADDRS[x]=""
+which can hold multiple, space delimited, IPv4 addresses with their CIDR
+masks in order to configure an interface.
+
+The format for the addresses specified in this new parameter is:
+ IP-address/mask
+For example:
+ IPADDRS[0]="192.168.0.1/24 10.10.10.10/8"
+which would be the equilivant of old syntax:
+ IPADDR[0]="192.168.0.1"
+ NETMASK[0]="255.255.255.0"
+ IPALIASES[0]="10.10.10.10/8"
+
+If a mask (in CIDR notation) is not provided with the IP address in IPADDRS, it
+is assumed to be /24 (aka, 255.255.255.0). A warning will also be emitted about
+the missing mask.
+
+rc.inet1 is fully backwards compatible with the older syntax - old configuration
+files will contiinue to be accepted for the foreseeable future, but 'netconfig'
+has been adjusted to output the new syntax.
+
+Notes:
+ * When DHCP or SLAAC is used to dynamically configure the interface, IP
+ addresses specified in IPADDRS will be added to the interface as alias IPs.
+ However, any address specified in IPADDR is *not* added to the interface in
+ order to maintain backwards semantics with the pre 15.0 rc.inet1.
+ * Should an rc.inet1.conf contain both the IPADDR and IPADDRS parameters
+ (without DHCP or SLAAC being in use) the addresses listed in IPADDRS will be
+ added to the interface after the IPADDR address is set.
+
+
+IPv6
+----
+ Overview
+ ~~~~~~~~
+
+ With the new IPv4 syntax detailed above, there is the addition of optional
+ configuration semantics for IPv6.
+
+ The IPv6 capabilities in Slackware 15.0+ are as follows:
+ * Dual stack. Interfaces can be configured with an IPv4 address or an IPv6
+ address, or both.
+ * Each interface can have single or multiple v4 and/or v6 IPs.
+ * Optional StateLess Address Auto Configuration (SLAAC) of v6 IP addresses,
+ for quick and easy IPv6 configuration on supported networks.
+ * DHCPv6 support for server controlled dynamic address configuration.
+ * Fixed IPv6 addresses configured interfaces.
+
+ 'netconfig' can be used for guided configuration of all of the above features,
+ or they can be configured manually using the options below.
+
+
+ IPv6 Parameters
+ ~~~~~~~~~~~~~~~
+ v6 IPs can be configured via SLAAC, DHCP6 or statically using the following
+ new options for rc.inet1.conf:
+ USE_SLAAC[x]="" Allow StateLess Address Auto Configuration of a
+ (potentially) globally routable v6 IP. With this
+ parameter set to "yes", the interface's v6 IP will ONLY
+ be configured via SLAAC, even if Router Advertisment
+ indicates DHCPv6 is available on the network - if SLAAC
+ is not available on the network, no IPv6 address will be
+ assigned.
+
+ Since 'dhcpcd' is capable of handling SLAAC as well as
+ DHCPv6, it is better practice to set USE_DHCP6[x]="yes"
+ to perform full auto configuration instead.
+
+ USE_DHCP6[x]="" Use 'dhcpcd' to configure the interface. This will
+ bring up the interface using DHCPv6, falling back to
+ SLAAC (if supported on the network), or will leave the
+ interface unconfigured after a timeout. When this
+ parameter is set to "yes", the USE_SLAAC[x] option is
+ ignored.
+
+ This is the preferred option to configure an interface
+ dynamically - whether the network is setup for DHCPv6 or
+ SLAAC, 'dhcpcd' will be able to configure the interface.
+
+ IP6ADDRS[x]="" The static v6 IP addresses for the interface. This
+ parameter takes a list of v6 IP addresses and prefix
+ lengths in CIDR notation, in a space delimited list.
+ For example: IP6ADDRS[x]="a:b:c:d:e::1/48 1:2:3:4::5/64"
+
+ If a prefix length is not given (separated from the IP
+ address with a /), a length of 64 will be assumed, and
+ a warning emitted about the unset value.
+
+ When either the USE_DHCP6[x] or USE_SLAAC[x] options are
+ set to "yes", the IP addresses listed in this parameter
+ are also added to the interface, but only upon sucessful
+ assigning of the dynamic IP address.
+
+ A static gateway can be configured using this parameter:
+ GATEWAY6="" The default IPv6 gateway for the network. This is a
+ single IPv6 address in standard format, without a
+ prefix suffix.
+
+ The following lesser used misc options can be used for tailouring of the IPv6
+ configuration process:
+ USE_RA[x]="" Normally, unless USE_SLAAC[x]="yes" is set, Router
+ Advertisment (RA) is disabled for the interface as it
+ can result in extraneous routes being added to the
+ routing table. With this option set to "yes", RA
+ packets will be accepted on the interface even when DHCP
+ or fixed IP addressing is used, and the routes
+ advertised by the router will be added to the table.
+
+ Conversely, if this parameter is explicitly set to "no",
+ RA will be disabled at all times - meaning SLAAC cannot
+ be performed even when USE_SLAAC[x]="yes" is set. The
+ default (unset) is to enable RA when SLAAC is in use,
+ and to disable it otherwise.
+
+ The use of this parameter should rarely be required as
+ rc.inet1 will do the right thing.
+
+ SLAAC_TIMEOUT[x]="" The time to wait (in seconds) for an interface to be
+ configured by SLAAC. When unset, the default is 15.
+ Some networks may require a longer period for the router
+ to broadcast an advertisement packet on the network, so
+ may need to increase this value.
+
+
+ Disabling IPv6
+ ~~~~~~~~~~~~~~
+ For some use cases, where IPv6 support is not required at all, disabling IPv6
+ may be a better option than leaving the interface unconfigured.
+
+ There are two similar methods which can be used to disable IPv6. Both of the
+ options involve creating (or replacing the content if it already exists in)
+ the file:
+ /etc/modprobe.d/ipv6.conf
+ (which overrides any configuration in the /lib/modprobe.d/ipv6.conf file),
+ with the content:
+ alias ipv6 off
+ alias net-pf-10 off
+ Or:
+ install ipv6 /bin/true
+ install net-pf-10 /bin/true
+
+ It is important to disable both the 'ipv6' and 'net-pf-10' modules since the
+ module can be automatically loaded by either name.
+
+
+ Changes From Previous Behaviour
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * Previous to Slackware 15.0, if the network the host is connecting to is set
+ up for StateLess Address Auto Configuration (SLAAC), the host would bring up
+ an interface with a (potentially) globally routable IPv6 address with no
+ configuration by the user. This has been changed so that all network
+ configuration must be explicitly enabled. Thus, interfaces will no longer
+ automatically come up with a valid IPv6 address on networks which support
+ auto configuration, without enabling the USE_SLAAC[x]="yes" parameter for
+ the interface. This is a security enhancement.
+
+ * Unless RA is explicitly enabled using the USE_RA[x]="yes" option, rc.inet1
+ now disables RA (via the accept_ra tunable in /proc) for an interface before
+ trying to add any IPs configured for it. This prevents RA on the network
+ from automatically adding any routes to the table. When USE_SLAAC[x]="yes"
+ is set, RA is implicitly re-enabled for the interface (since SLAAC and RA
+ are usually used together on a network), unless explicitly disabled with
+ USE_RA[x]="no". This is a change from previous versions of Slackware, which
+ would auto configure routes without any user intevention. This is a
+ security enhancement.
+
+
+ Caveats
+ ~~~~~~~
+ * When being configured with the USE_DHCP[x]="yes" and USE_DHCP6[x]="yes"
+ parameters for an interface (that is, configured to obtain both a v4 and v6
+ addresses via DHCP), 'dhcpcd' will only wait until one type of IP is
+ obtained before backgrounding - it will not wait for both a v4 AND v6 to be
+ configured. This means there is no way to know if the interface has been
+ completely configured for both types of IP, as one type will continue to be
+ sought in the background; but MAY ultimately fail. This is an issue with
+ the way dhcpcd operates, not an issue with rc.inet1.
+
+
+Manual networking configuration
+-------------------------------
+
+
+Bonding / Link Aggrigation
+--------------------------
+ Overview
+ ~~~~~~~~
+ Bonding (or Link Aggrigation) is a teccnique for combining two or more
+ physical interfaces into a single, logical, interface; a logical interface
+ which has all the capabilities of a single physical interface.
+
+ The Slackware bonding options provide full support for the features offered by
+ the bonding kernel module, in the familiar Slackware parameter configuration
+ syntax. Included is the ability to select the bonding mode, easy addition of
+ interfaces to a bond using a new parameter in rc.inet1.conf, and the setting
+ of bonding module options via a new, generic, IFOPTS[x] parameter.
+
+ At this time 'netconfig' is unable to configure bonded interfaces, so they
+ must be configured manually with the parameters detailed below.
+
+
+ Bonding Parameters
+ ~~~~~~~~~~~~~~~~~~
+ Bonded interfaces can be configured via two new bond specific parameters for
+ use in rc.inet1.conf, plus the new, generic, IFOPTS[x] parameter. The new
+ bonding parameters are:
+ BONDNICS[x]="" The space delimited list of interfaces to add to this
+ bond. The interfaces will be brought up and configured
+ while bringing up the interface, so do not need to be
+ previously defined in rc.inet1.conf. A bond can be
+ created with only 1 interface, but does not become
+ useful until at least 2 interfaces are configured.
+
+ BONDMODE[x]="" This parameter sets the bonding mode for the logical
+ interface. If not specified when BONDNICS[x] has been
+ used, the default is 'balance-rr'. See below for a
+ list of all bonding modes available.
+
+
+ Bonding Modes
+ ~~~~~~~~~~~~~
+ When a bonded logical interface is created, it needs to operate in a
+ particular mode. By default that mode is 'balance-rr'. The following modes,
+ along with details of their functionallity, are available using the kernel
+ bonding driver:
+ 802.3ad Also known as LACP. This mode requires a switch that
+ supports an IEEE 802.3ad. The physical interfaces must
+ share the same speed and duplex settings and form a
+ logical interface which provides fault tolerance and
+ load balancing.
+ active-backup When in this mode only one interface set to active,
+ while all other interfaces are in the backup state. If
+ the active interface fails, a backup interface replaces
+ it as the only active interface in the bond. This mode
+ only provides fault tolerance, no load balancing.
+ This mode requires that the 'primary <interface>'
+ option be configured with the IFOPTS[x]="" parameter.
+ balance-alb The receiving packets are load balanced through Address
+ Resolution Protocol (ARP) negotiation. This mode
+ provides fault tolerance and load balancing.
+ balance-rr This mode is also known as round-robin mode. Packets
+ are sequentially transmitted and received through each
+ interface one by one. This mode provides load
+ balancing functionality along with fault tolerance.
+ This is the default mode of operation.
+ balance-tlb This mode ensures that outgoing traffic is distributed
+ according to the load on each physical interface. If
+ one interface fails to receive traffic, another
+ interface is assigned to the receiving role. This mode
+ provides fault tolerance and load balancing.
+ balance-xor The source MAC address uses eXclusive OR (XOR) logic
+ with the destination MAC address in order to determine
+ which physical interface the packet should be sent via.
+ This calculation ensures that the same physical (slave)
+ interface is selected for each destination host. If the
+ physical interface to be used is in a failed state, one
+ of the backup interfaces is used instead. This mode
+ provides fault tolerance and load balancing.
+ broadcast All packets are sent to all the physical (slaved)
+ interfaces at once. This mode provides fault tolerence
+ but may result in duplicate packets arriving at the
+ destination host, assuming they are not screened out by
+ networking hardware.
+
+
+ Bonding Options
+ ~~~~~~~~~~~~~~~
+ Bonding specific options can be set using the the IFOPTS[x]="" paramter (which
+ takes a pipe (|) delimited list of options) for the interface being
+ configured. The following are the most useful options (but not an exhaustive
+ list - see "Further Reading" below for more information) which can be set:
+ lacp_rate This option specifies the rate at which the host will
+ ask the switch to transmit LACPDU packets in 802.3ad
+ mode. Possible values are:
+ slow Transmit LACPDUs every 30 seconds.
+ fast Transmit LACPDUs every 1 second.
+ The default is slow, but fast is recommended for rapid
+ recovery after a physical link failure.
+ miimon Specifies the MII link monitoring frequency in
+ milliseconds. This determines how often the link state
+ of each physical (slaved) interface is checked for link
+ failures. A value of zero disables MII link monitoring,
+ but this is NOT advised. A value of 100 is a good
+ starting point. The default value is 0, so be sure to
+ set this option with ALL bonding modes.
+ primary The physical (slave) interface (eth0, eth1, etc) which
+ is to be used as the primary interface. The specified
+ interface will always be the active slave while it is
+ available. Only when the primary interface is off-line
+ will alternate interfaces be used. This is useful when
+ one interface is preferred over another (e.g. when one
+ interface has higher throughput than another). This
+ option is only valid for "active-backup", "balance-tlb",
+ and "balance-alb" bonding modes.
+ xmit_hash_policy Selects the transmit hash policy to use for interface
+ selection in "balance-xor", "802.3ad", and "balance-tlb"
+ bonding modes. Possible values are:
+ layer2 Use eXclusive OR (XOR) of source and
+ destination MAC addresses and packet
+ type ID fields to generate the hash.
+ This algorithm will place all traffic
+ to a particular destination on the
+ same phydivsl (slave) interface.
+ layer2+3 Use a combination of layer2 and
+ layer3 protocol information (MAC
+ addresses and IP addresses) to
+ generate the hash. This algorithm
+ will place all traffic to a particular
+ destination on the same physical
+ (slave) interface. This policy is
+ intended to provide a more balanced
+ distribution of traffic than layer2
+ alone.
+ layer3+4 This policy uses upper layer protocol
+ information, when available, to
+ generate the hash. This allows for
+ traffic to a particular destination to
+ span multiple physical (slave)
+ interfaces, although a single
+ connection will not span multiple
+ slaves.
+ The default value is layer2. Additional (lesser used)
+ policies are available - see the "Further Reading"
+ section below for further details.
+
+
+ Caveats
+ ~~~~~~~
+ * The IFOPTS[x]="" parameter should always include the 'miimon' option - not
+ using this option will result in network degradation.
+ * In "active-backup" mode, the "primary" option should also always be
+ supplied.
+ * When using "802.3ad" mode, set "lacp_rate fast" for faster recovery from an
+ interface failure. In other modes, the 'xmit_hash_policy' should be set.
+
+
+ Examples
+ ~~~~~~~~
+ FIXME: Add examples.
+
+
+ Further Reading
+ ~~~~~~~~~~~~~~~
+ Full documentation of the bonding layer is available in the kernel source
+ documentation at: /usr/src/linux/Documentation/networking/bonding.txt.
+
+
+VLANs (a.k.a, 802.1q)
+---------------------
+ Overview
+ ~~~~~~~~
+ Virtual LANs (VLANs) allow the segmentation of physical networks into
+ multiple, isolated, private virtual networks, whilst using shared network
+ switches and hardware.
+
+ VLANs work by applying tags to network frames to form virtual private LANs.
+ In this way, VLANs can keep network applications separate despite being
+ connected to the same physical network, and without requiring multiple sets of
+ cabling and networking devices to be deployed.
+
+ In essence, a VLAN is a collection of devices or network hosts that
+ communicate with one another as if they make up a single LAN, but utilising
+ shared network hardware.
+
+ Because VLAN frames are tagged with a VLAN ID, it is possible to 'cherry-pick'
+ those frames from the network by use of a VLAN interface on the host.
+
+ Slackware now allows configuration of such interfaces in order to allow a host
+ to join a specific VLAN or VLANs. The guided deployment in 'netconfig' has
+ been updated to support the creation of such VLAN interfaces.
+
+ The configuration in rc.inet1.conf for VLANs is a simple modification of the
+ existing support for declaration of a network interface using the standard
+ Slackware IFNAME[x] parameter. As shown in the examples below, VLANs
+ interfaces can be built on top on top of regular, physical, interfaces, or on
+ top of a bond interface to allow for link aggrigation.
+
+ The new IFOPT[x] generic interface options parameter can be used to customise
+ the usage and configuration of the VLAN interfaces, but is not required in a
+ normal configuration setting.
+
+
+ Exposing VLANs
+ ~~~~~~~~~~~~~~
+ Configuring VLAN interfaces utilises the standard Slackware networking
+ configuration syntax in rc.inet1.conf; with setting up an interface as simple
+ as changing the IFNAME[x]="" parameter.
+
+ VLAN interfaces can be configured quite simply in rc.inet1.conf, in the
+ standard Slackware way of defining an interface. The key to the configuration
+ is to use the correct IFNAME[x]="" parameter for the underlying physical (or
+ bond) interface and the tagged VLAN ID that should be exposed. For example:
+ IFNAME[0]="eth0.10"
+ IFOPTS[0]=""
+ IPADDRS[0]="192.168.10.1/24"
+
+ The VLAN ID is taken from the full interface name, as set in the IFNAME[x]
+ parameter which is comprised of the underlying physical (or bond) interface
+ name, a period (.) and the VLAN ID to expose. The above example would use the
+ physical interface 'eth0', and expose the VLAN with ID 10, and configure the
+ interface with the IPv4 address 192.168.10.1 with a mask of 24.
+
+ IFOPTS[x]="" is a pipe (|) delimited list of VLAN kernel module specific
+ settings to be applied to the interface. The ip-link(8) man page contains
+ details of exactly what settings can be used with this option (search for
+ "VLAN Type Support"). For example:
+ IFOPTS[x]="protocol 802.1ad | reorder_hdr off"
+ Under normal circumstances, where a standard VLAN interface is required, no
+ options need be supplied.
+
+
+ Examples
+ ~~~~~~~~
+ FIXME: Add examples.
+
+
+Bridges
+-------
+
+
+Wireless (WiFi) Network Interfaces
+----------------------------------
+
+
+TUN/TAP
+-------
+
+
+Advanced networking configuration
+---------------------------------
+(stacking interface configs - bond, then VLAN, then bridge)
+
+ It is also possible to use a bond as the underlying interface, which allows
+ link aggregated VLAN interfaces to be created for network redundancy. For
+ example:
+ IFNAME[0]="bond0.5"
+ BONDNICS[0]="eth0 eth1"
+ BONDMODE[0]="active-backup"
+ IFOPTS[0]="miimon 100 | primary eth0"
+ IPADDRS[0]="192.168.5.10/24"
+ IP6ADDRS[0]="a:b:c:d::1/64"
+ Would create a bond interface using the eth0 and eth1 physical ethernet
+ interfaces, in an "active-backup" redundancy configuration with the primary
+ interface being "eth0", exposing VLAN ID 5 and setting an IPv4 address of
+ "192.168.5.10" mask "24", plus an IPv6 address of "a:b:c:d::1" prefix "64"
+ for the interface.
+
+
+General Caveats
+---------------
+
+ The network interface definitions are stored in variable arrays. The bash shell has no facilities to retrieve the largest array index used. There-
+ fore, the rc.inet1 script makes the assumption that array indexes stay below the value of 6. Effectively this means that you can configure up to 6
+ network interfaces in rc.inet1.conf by default.
+
+ If you want to configure more than six network interfaces, you will have to edit the file /etc/rc.d/rc.inet1.conf and change the value `6' in the
+ line:
+ #MAXNICS="6"
+ (at the very bottom of the file) to a value that is larger than the largest index value you use, and uncomment the line.
+
+ The /etc/rc.d/rc.wireless script is not meant to be run on its own by the user!
+
+
+rc.inet1 does not keep a record of how an interface was configured. If the
+interface config is changed in rc.inet1.conf from, say, DHCP to static IP,
+restarting networking may fail because the previous type of interface config
+cannot be stopped (because its type is unknown). In this instance, it is easier
+to reboot to start from fresh. However, if reboot is not possible, it may be
+required to bring the interface down manually (either by deconfiguring the IPs,
+or killing dhcpcd) before trying to restart the interface.
+