Gentoo Linux x86 Handbook: Network configuration

This page is a translated version of the page Handbook:X86/Full/Networking and the translation is 100% complete.

La seguente porzione dell'handbook riguardante la gestione di rete ne descrive la configurazione 'avanzata' per sistemi utilizzanti il sistema d'init OpenRC e netifrc come sistema di gestione di rete.

Per sistemi utilizzanti systemd, i lettori dovrebbero far riferimento alla sezione di rete dell'articolo su systemd.

Per iniziare

Questa guida alle reti presuppone che l'utente abbia correttamente configurato il sistema ed abbia determinato i nomi dell'interfaccia di rete dell'hardware. Il nome dell'interfaccia di rete viene generato in base alla posizione sul bus delle schede di rete nel sistema. Per questo motivo esiste l'eventualità che vari il nome dell'interfaccia, per esempio tra: eno0, ens1, wlan0, enp1s0, ecc. Ogni sistema può avere un nome di interfaccia leggermente diverso. Il contenuto che segue ipotizza che il nome dell'interfaccia configurata sia eth0, anche se funziona per uno qualsiasi dei nomi sopra menzionati.

Per iniziare a configurare la scheda di rete, occorre comunicarlo al sistema RC di Gentoo. Ciò viene fatto creando un collegamento simbolico da net.lo a net.eth0 (o qualunque sia il nome dell'interfaccia di rete sul sistema) dentro /etc/init.d.

root #

cd /etc/init.d

root #

ln -s net.lo net.eth0

Il sistema RC di Gentoo ora è al corrente di questa interfaccia. Necessità anche di sapere come configurare la nuova interfaccia. Tutte le interfacce di rete sono configurate nel file /etc/conf.d/net. Di seguito è riportata una configurazione d'esempio per DHCP e per indirizzi statici.

FILE /etc/conf.d/netConfigurazione di rete d'esempio

# Per DHCP
config_eth0="dhcp"
  
# Per IP statici che usano la notazione CIDR
config_eth0="192.168.0.7/24"
routes_eth0="default via 192.168.0.1"
dns_servers_eth0="192.168.0.1 8.8.8.8"
  
# Per IP statici che usano la notazione netmask
config_eth0="192.168.0.7 netmask 255.255.255.0"
routes_eth0="default via 192.168.0.1"
dns_servers_eth0="192.168.0.1 8.8.8.8"

Nota
Se non viene menzionata alcuna configurazione per un'interfaccia, viene assunto DHCP.

Nota
CIDR è l'acronimo di Classless InterDomain Routing (Instradamento interdominio senza classi). Originariamente, gli indirizzi IPv4 erano classificati come A, B o C. Il sistema di classificazione iniziale non si prefigurava la grande popolarità di Internet e rischiava di esaurire i nuovi indirizzi unici. CIDR è uno schema di indirizzamento che consente a un indirizzo IP di indicare molti indirizzi IP. Un indirizzo IP CIDR si presenta come un normale indirizzo IP, però termina con una barra seguita da un numero; ad esempio, 192.168.0.0/16. CIDR è descritto nella RFC 1519.

Ora che l'interfaccia è configurata, possiamo avviarla e interromperla usando i seguenti comandi:

root #

rc-service net.eth0 start

root #

rc-service net.eth0 stop

Importante
Durante la risoluzione dei problemi di rete, si dia un'occhiata a /var/log/rc.log. Tranne nel caso in cui la variabile rc_logger sia impostata su NO in /etc/rc.conf, le informazioni sull'attività di avvio verranno memorizzate in quel file di registro.

Ora che l'interfaccia di rete è stata arrestata ed avviata con successo, il passo successivo è avviarla con l'avvio di Gentoo. Ecco come fare:

root #

rc-update add net.eth0 default

root #

rc

Nota
L'ultimo comando rc istruisce Gentoo affinché avvii qualsiasi script nel livello di esecuzione (runlevel) corrente che non sia stato ancora avviato.

Configurazione avanzata

La variabile config_eth0 è il cuore di una configurazione dell'interfaccia. È una lista di istruzioni di alto livello per configurare l'interfaccia (eth0 in questo caso). Ogni comando nella lista di istruzioni viene eseguito in sequenza. L'interfaccia è considerata OK se funziona almeno un comando.

Ecco un elenco di istruzioni integrate:

Valore	Descrizione
`null`	Non fare nulla.
`noop`	Se l'interfaccia è attiva e c'è un indirizzo, interrompere la configurazione con successo.
Un indirizzo IPv4 o IPv6	Aggiunge l'indirizzo all'interfaccia.
`dhcp`, `adsl`, o `apipa` (o un valore personalizzato da un modulo di terze parti)	Esegue il modulo che fornisce il comando. Per esempio `dhcp` eseguirà un modulo che fornisce DHCP servito da dhcpcd, dhclient, o pump.

Se un comando fallisce, specificare un valore di ripiego. Il ripiego (fallback) deve corrispondere in modo esatto alla struttura della configurazione.

È possibile concatenare questi valori insieme. Ecco alcuni esempi presi da situazioni reali:

FILE /etc/conf.d/netEsempi di configurazione

# Aggiunta di tre indirizzi IPv4
config_eth0="192.168.0.2/24
192.168.0.3/24
192.168.0.4/24"
  
# Aggiunta di un indirizzo IPv4 e due indirizzi IPv6
config_eth0="192.168.0.2/24
4321:0:1:2:3:4:567:89ab
4321:0:1:2:3:4:567:89ac"
  
# Mantiene nel nostro kernel l'indirizzo assegnato, a meno che
# l'interfaccia non funzioni allora ne assegna un altro via DHCP
# Se DHCP fallisce, aggiunge un indirizzo statico tramite APIPA
config_eth0="noop
dhcp"
fallback_eth0="null
apipa"

Nota
Quando si usa il modulo ifconfig e si aggiunge più di un indirizzo, vengono creati alias di interfaccia per ciascun indirizzo aggiunto. Quindi con i due esempi precedenti gli utenti otterranno le interfacce eth0, eth0:1 ed eth0:2. Non è possibile fare nulla di speciale con queste interfacce in quanto il kernel e gli altri programmi trattano eth0:1 ed eth0:2 semplicemente come eth0.

Importante
L'ordine di ripiego (fallback) è importante! Se non è stata specificata l'opzione null, apipa verrà eseguito solo se noop fallisce.

Nota
APIPA e DHCP sono trattati più avanti.

Dipendenze di rete

Gli script di init dentro /etc/init.d/ possono dipendere da un'interfaccia di rete specifica o semplicemente da "net" (rete). Tutte le interfacce di rete nel sistema init di Gentoo forniscono ciò che viene chiamato "net".

Se, in /etc/rc.conf, la variabile rc_depend_strict è impostata su YES, allora tutte le interfacce di rete che forniscono "net" devono essere attive prima di supporre che una dipendenza da "net" sia soddisfatta. In altre parole, se un sistema ha net.eth0 e net.eth1 e uno script di init dipende da "net", allora entrambi devono essere abilitati.

In caso contrario, se è impostato rc_depend_strict = "NO", la dipendenza "net" viene contrassegnata come risolta nel momento in cui viene attivata almeno un'interfaccia di rete.

Ma riguardo a net.br0 che dipende da net.eth0 e net.eh1? net.eh1 può essere un dispositivo wireless o PPP che necessita di una configurazione prima di poter essere aggiunto al ponte di collegamento dati (bridge). Ciò non può esser fatto in /etc/init.d/net.br0 poiché si tratta di un link simbolico a net.lo.

La risposta è definire l'impostazione rc_need_ in /etc/conf.d/net:

FILE /etc/conf.d/netAggiungere una dipendenza net.br0

rc_need_br0="net.eth0 net.eth1"

Solo questo, tuttavia, non è sufficiente. Gli script di init del lavoro di rete su Gentoo utilizzano una dipendenza virtuale chiamata "net" per informare il sistema quando la rete è disponibile. Chiaramente, nel caso precedente, la rete dovrebbe essere contrassegnata come disponibile solo quando net.br0 è attivo, non quando lo sono gli altri. Così dobbiamo specificarlo anche in /etc/conf.d/net:

FILE /etc/conf.d/netAggiornare le dipendenze virtuali e le disposizioni per la rete

rc_net_eth0_provide="!net"
rc_net_eth1_provide="!net"

Per una discussione più dettagliata sulle dipendenze, consultare la sezione sulla scrittura degli script di init sul Manuale di Gentoo. Ulteriori informazioni su /etc/rc.conf sono disponibili tramite commenti interni allo stesso file.

Nomi e valori delle variabili

Variable names are dynamic. They normally follow the structure of variable_${interface|mac|essid|apmac}. For example, the variable dhcpcd_eth0 holds the value for dhcpcd options for eth0 and dhcpcd_essid holds the value for dhcpcd options when any interface connects to the ESSID "essid".

However, there is no hard and fast rule that states interface names must be ethx. In fact, many wireless interfaces have names like wlanx, rax as well as ethx. Also, some user defined interfaces such as bridges can be given any name. To make life more interesting, wireless Access Points can have names with non alpha-numeric characters in them - this is important because users can configure networking parameters per ESSID.

The downside of all this is that Gentoo uses bash variables for networking - and bash cannot use anything outside of English alpha-numerics. To get around this limitation we change every character that is not an English alpha-numeric into an _ (underscore) character.

Another downside of bash is the content of variables - some characters need to be escaped. This can be achieved by placing the \ (backslash) character in front of the character that needs to be escaped. The following list of characters needs to be escaped in this way: ", ' and \.

In this example we use wireless ESSID as they can contain the widest scope of characters. We shall use the ESSID My "\ NET:

FILE /etc/conf.d/netVariable names

# This does work, but the domain is invalid
dns_domain_My____NET="My \"\\ NET"

The above sets the DNS domain to My "\ NET when a wireless card connects to an AP whose ESSID is My "\ NET.

Network interface naming

How it works

Network interface names are not chosen arbitrarily: the Linux kernel and the device manager (most systems have udev as their device manager although others are available as well) choose the interface name through a fixed set of rules.

When an interface card is detected on a system, the Linux kernel gathers the necessary data about this card. This includes:

The onboard (on the interface itself) registered name of the network card, which is later seen through the ID_NET_NAME_ONBOARD value.
The slot in which the network card is plugged in, which is later seen through the ID_NET_NAME_SLOT value.
The path through which the network card device can be accessed, which is later seen through the ID_NET_NAME_PATH value.
The (vendor-provided) MAC address of the card, which is later seen through the ID_NET_NAME_MAC value.

Based on this information, the device manager decides how to name the interface on the system. By default, it uses the first hit of the first three variables above (ID_NET_NAME_ONBOARD, _SLOT or _PATH). For instance, if ID_NET_NAME_ONBOARD is found and set to eno1, then the interface will be called eno1.

Given an active interface name, the values of the provided variables can be shown using udevadm:

root #udevadm test-builtin net_id /sys/class/net/enp3s0 2>/dev/null

ID_NET_NAME_MAC=enxc80aa9429d76
ID_OUI_FROM_DATABASE=Quanta Computer Inc.
ID_NET_NAME_PATH=enp3s0

As the first (and actually only) hit of the top three variables is ID_NET_NAME_PATH, its value is used as the interface name. If none of the variables contain values, then the system reverts back to the kernel-provided naming (eth0, eth1, etc.)

Using the old-style kernel naming

Before this change, network interface cards were named by the Linux kernel itself, depending on the order that drivers are loaded (amongst other, possibly more obscure reasons). This behavior can still be enabled by setting the net.ifnames=0 boot parameter in the boot loader.

Using custom names

The entire idea behind the change in naming is not to confuse people, but to make changing the names easier. Suppose a system has two interfaces that are otherwise called eth0 and eth1. One is meant to access the network through a wire, the other one is for wireless access. With the support for interface naming, users can have these called lan0 (wired) and wifi0 (wireless - it is best to avoid using the previously well-known names like eth* and wlan* as those can still collide with the suggested names).

Find out what the parameters are for the cards and then use this information to set up a custom own naming rule:

root #udevadm test-builtin net_id /sys/class/net/eth0 2>/dev/null

ID_NET_NAME_MAC=enxc80aa9429d76
ID_OUI_FROM_DATABASE=Quanta Computer Inc.

root #vim /etc/udev/rules.d/70-net-name-use-custom.rules

# First one uses MAC information, and 70- number to be before other net rules
SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="c8:0a:a9:42:9d:76", NAME="lan0"

root #vim /etc/udev/rules.d/76-net-name-use-custom.rules

# Second one uses ID_NET_NAME_PATH information, and 76- number to be between
# 75-net-*.rules and 80-net-*.rules
SUBSYSTEM=="net", ACTION=="add", ENV{ID_NET_NAME_PATH}=="enp3s0", NAME="wifi0"

Because the rules are triggered before the default one (rules are triggered in alphanumerical order, so 70 comes before 80) the names provided in the rule file will be used instead of the default ones. The number granted to the file should be between 76 and 79 (the environment variables are defined by a rule start starts with 75 and the fallback naming is done in a rule numbered 80).

Moduli di rete

Netifrc supports modular networking scripts, which means support for new interface types and configuration modules can easily be added while keeping compatibility with existing ones.

Modules load by default if the package they need is installed. If users specify a module here that doesn't have its package installed then they get an error stating which package they need to install. Ideally, the modules setting is only used when two or more packages are installed that supply the same service and one needs to be preferred over the other.

Nota
All settings discussed here are stored in /etc/conf.d/net unless otherwise specified.

FILE /etc/conf.d/netModule definitions

# Prefer ifconfig over iproute2
# modules="ifconfig"
  
# You can also specify other modules for an interface
# In this case we prefer dhclient over dhcpcd
modules_eth0="dhclient"
  
# You can also specify which modules not to use - for example you may be
# using a supplicant or linux-wlan-ng to control wireless configuration but
# you still want to configure network settings per ESSID associated with.
modules="!iwconfig"

Interface handlers

We provide two interface handlers: ifconfig and iproute2. You need one of these to do any kind of network configuration.

Both are installed by default as part of the system profile. iproute2 is the more powerful and flexible package. ifconfig and net-tools should not be used anymore for networking configuration setups.

As iproute2 and ifconfig do very similar things, we allow their basic configuration to work with each other. For example, the below configuration works regardless of the module used.

FILE /etc/conf.d/netExample configuration

config_eth0="192.168.0.2/24"
config_eth0="192.168.0.2 netmask 255.255.255.0"

DHCP

DHCP is a means of obtaining an IP address, together with other network information (DNS server(s), gateway, etc.) from a server. With a DHCP server running on a network, the user just has to tell each device to obtain configuration information via DHCP, which is then used to configure the device automatically. Of course, this requires a network connection (e.g. via a wireless access point, PPPoE, etc.).

DHCP can be provided by dhclient or dhcpcd. Each DHCP module has its pros and cons - here is a quick run down:

DHCP module	Package	Pros	Cons
dhclient	net-misc/dhcp	Made by ISC, the same people who make the BIND DNS software. Very configurable. Can be used to provide DHCPv4 or DHCPv6.	Configuration is overly complex, software is quite bloated, cannot get NTP servers from DHCP, does not send hostname by default. No longer maintained upstream.
dhcpcd	net-misc/dhcpcd	Long time Gentoo default, no reliance on outside tools, actively developed by Gentoo. Provides DHCPv4 and DHCPv6 at the same time.	Can be slow at times, does not yet daemonize when lease is infinite.

If more than one DHCP client is installed, it is possible to specify which client to use by setting the "modules" variable, e.g. modules="dhcpcd". Otherwise, if dhcpcd is installed, it's used by default.

To send specific options to the DHCP module, use module_eth0="...", where module is the name of the DHCP module being used - for example, "dhcpcd_eth0".

We try to make DHCP relatively agnostic - as such we support the following commands using the dhcp_eth0 variable. The default is not to set any of them:

release: Releases the IP address for re-use.
nodns: Don't overwrite /etc/resolv.conf
nontp: Don't overwrite /etc/ntp.conf
nonis: Don't overwrite /etc/yp.conf

FILE /etc/conf.d/netSample DHCP (v4) configuration

# Only needed if more than one DHCP module is installed
modules="dhcpcd"
  
config_eth0="dhcp"
dhcpcd_eth0="-t 10" # Timeout after 10 seconds
dhcp_eth0="release nodns nontp nonis" # Only get an address

Nota
dhcpcd sends the current hostname to the DHCP server by default so this no longer needs to be specified.

FILE /etc/conf.d/netSample DHCPv6 configuration

# Only needed if more than one DHCP module is installed
modules="dhclient"
  
config_eth0="dhcpv6"
# To use both DHCPv4 and DHCPv6 on a dual-stack network, remove the above line and uncomment the following lines
#config_eth0="dhcp
#dhcpv6"
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
# To pass runtime arguments to dhclient for DHCPv6
dhclientv6_eth0="-t 10" # Timeout after 10 seconds
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
# Set generic DHCPv6 options
dhcpv6_eth0="release nodns nontp nonis nogateway nosendhost"

ADSL with PPPoE/PPPoA

First install the ADSL software:

root #emerge --ask net-dialup/ppp

Second, create the PPP net script and the net script for the Ethernet interface to be used by PPP:

root #

ln -s /etc/init.d/net.lo /etc/init.d/net.ppp0

root #ln -s /etc/init.d/net.lo /etc/init.d/net.eth0

Be sure to set rc_depend_strict to YES in /etc/rc.conf.

Now we need to configure /etc/conf.d/net.

FILE /etc/conf.d/netA basic PPPoE setup

config_eth0=null (Specify the ethernet interface)
config_ppp0="ppp"
link_ppp0="eth0" (Specify the ethernet interface)
plugins_ppp0="pppoe"
username_ppp0='user'
password_ppp0='password'
pppd_ppp0="
noauth
defaultroute
usepeerdns
holdoff 3
child-timeout 60
lcp-echo-interval 15
lcp-echo-failure 3
noaccomp noccp nobsdcomp nodeflate nopcomp novj novjccomp"
  
rc_net_ppp0_need="net.eth0"

It is also possible to set the password in /etc/ppp/pap-secrets.

FILE /etc/ppp/pap-secretsSample pap-secrets

# The * is important
"username"  *  "password"

If PPPoE is used with a USB modem then make sure to emerge br2684ctl. Please read /var/db/repos/gentoo/net-dialup/speedtouch-usb/files/README for information on how to properly configure it.

Importante
Please carefully read the section on ADSL and PPP in /usr/share/doc/netifrc-*/net.example.bz2. It contains many more detailed explanations of all the settings any particular PPP setup will likely need.

APIPA (Automatic Private IP Addressing)

APIPA tries to find a free address in the range 169.254.0.0-169.254.255.255 by using arping to ping a random address in that range on the interface. If no reply is received, that address is assigned to the interface.

This is only useful for LANs where:

there is no DHCP server;
the system doesn't connect directly to the Internet; and
all other computers use APIPA.

For APIPA support, emerge net-misc/iputils with the arping USE flag or net-analyzer/arping.

FILE /etc/conf.d/netAPIPA configuration

# Try DHCP first - if that fails then fallback to APIPA
config_eth0="dhcp"
fallback_eth0="apipa"
  
# Just use APIPA
config_eth0="apipa"

Bonding

Bonding is used to increase network bandwidth or to improve resiliency in the face of hardware failures. If a system has two network cards going to the same network, they can be bonded: applications will see just one interface, but both network cards will be used.

There are many ways to configure bonding. Some of them, such as the 802.3ad LACP mode, require support and additional configuration of the network switch. For a reference of the individual options, please refer to the local copy of /usr/src/linux/Documentation/networking/bonding.txt.

First, clear the configuration of the participating interfaces:

FILE /etc/conf.d/netClearing interface configuration

config_eth0="null"
config_eth1="null"
config_eth2="null"

Next, define the bonding between the interfaces:

FILE /etc/conf.d/netDefine the bonding

slaves_bond0="eth0 eth1 eth2"
config_bond0="192.168.100.4/24"
# Pick a correct mode and additional configuration options which suit your needs
mode_bond0="balance-alb"

Remove the net.eth* services from the relevant runlevel, create a net.bond0 service, and add that service to the appropriate runlevel.

Bridging (802.1d support)

Bridging is used to join networks together. For example, a network may have a server that connects to the Internet via an ADSL modem, and also has a wireless adapter to allow other devices on the network to access the Internet via that modem. It is possible to create a bridge to join the two interfaces together.

FILE /etc/conf.d/netBridge configuration

# Configure the bridge - "man brctl" for more details
bridge_forward_delay_br0=0
bridge_hello_time_br0=200
bridge_stp_state_br0=1
  
# To add ports to bridge br0
bridge_br0="eth0 eth1"
  
# You need to configure the ports to null values so dhcp does not get started
config_eth0="null"
config_eth1="null"
  
# Finally give the bridge an address - you could use DHCP as well
config_br0="192.168.0.1/24"
  
# Depend on eth0 and eth1 as they may require extra configuration
rc_net_br0_need="net.eth0 net.eth1"

Importante
For using some bridge setups, consult the variable name documentation.

Importante
When bridging using IPv6, SLAAC requires STP to be set to 1 as seen in the example above.

MAC address

It is possible to change the MAC address of the interfaces through the network configuration file too.

FILE /etc/conf.d/netMAC Address change example

# To set the MAC address of the interface
mac_eth0="00:11:22:33:44:55"
  
# To randomize the last 3 bytes only
mac_eth0="random-ending"
  
# To randomize between the same physical type of connection (e.g. fibre,
# copper, wireless) , all vendors
mac_eth0="random-samekind"
  
# To randomize between any physical type of connection (e.g. fibre, copper,
# wireless) , all vendors
mac_eth0="random-anykind"
  
# Full randomization - WARNING: some MAC addresses generated by this may
# NOT act as expected
mac_eth0="random-full"

Tunneling

Tunneling does not require any additional software to be installed as the interface handler can do it.

FILE /etc/conf.d/netTunneling configuration

# For GRE tunnels
iptunnel_vpn0="mode gre remote 207.170.82.1 key 0xffffffff ttl 255"
  
# For IPIP tunnels
iptunnel_vpn0="mode ipip remote 207.170.82.2 ttl 255"
  
# To configure the interface
config_vpn0="192.168.0.2 peer 192.168.1.1"

VLAN (802.1q support)

For VLAN support, make sure that sys-apps/iproute2 is installed, and ensure that iproute2 is used as the configuration module (rather than ifconfig).

A VLAN, Virtual LAN, is a group of network devices that behave as if they were connected to a single network segment, even though they may not be. Members of a VLAN can only see other members of the same VLAN, even when they share the same physical network.

To configure VLANs, first specify the VLAN numbers in /etc/conf.d/net like so:

FILE /etc/conf.d/netSpecifying VLAN numbers

vlans_eth0="1 2"

Next, configure the interface for each VLAN:

FILE /etc/conf.d/netInterface configuration for each VLAN

config_eth0_1="172.16.3.1 netmask 255.255.254.0"
routes_eth0_1="default via 172.16.3.254"
  
config_eth0_2="172.16.2.1 netmask 255.255.254.0"
routes_eth0_2="default via 172.16.2.254"

VLAN-specific configurations are handled by vconfig like so:

FILE /etc/conf.d/netConfiguring the VLANs

vlan1_name="vlan1"
vlan1_ingress="2:6 3:5"
eth0_vlan1_egress="1:2"

Importante
For using some VLAN setups, consult the variable name documentation.

Introduction to wireless networking

Wireless networking on Linux is usually pretty straightforward. There are three ways of configuring wifi: graphical clients, text-mode interfaces, and command-line interfaces.

The easiest way is to use a graphical client once a desktop environment is installed. Most graphical clients, such as NetworkManager, are pretty self-explanatory. They offer a handy point-and-click interface that gets users on a network in just a few seconds.

Nota
NetworkManager offers text-mode or command-line interface utilities in addition to the main graphical interface. Emerge the net-misc/networkmanager package with the tools USE flag enabled. The nmtui utility is particularly useful for folks who do not use a X or Wayland based desktop environment, but still desire an easy-to-use tool that does not require hand-editing configuration files.

Wireless can also be configured from the command line by editing a few configuration files. This takes a bit more time to setup, but it also requires the fewest packages to download and install. Since the graphical clients are mostly self-explanatory (with helpful screen shots at their home pages), we'll focus on the command line alternatives.

There are three tools that support command-line driven wireless configurations: net-wireless/iw, net-wireless/wireless-tools, and net-wireless/wpa_supplicant. Of these three, net-wireless/wpa_supplicant is the preferred one. The important thing to remember is that wireless networks are configured on a global basis and not an interface basis.

The net-wireless/iw software, the successor of net-wireless/wireless-tools, supports nearly all cards and drivers, but it cannot connect to WPA-only Access Points. If the networks only offer WEP encryption or are completely open, then net-wireless/iw beats the other package over simplicity.

Some wireless cards are deactivated by default. To activate them, please consult the hardware documentation. Some of these cards can be unblocked using the rfkill application. If that is the case, use rfkill list to see the available cards and rfkill unblock INDEX to activate the wireless functionality. If not, then the wireless card might need to be unlocked through a button, switch or special key combination on the laptop.

WPA supplicant

The WPA supplicant project provides a package that allows users to connect to WPA enabled access points.

root #emerge --ask net-wireless/wpa_supplicant

Importante
It is necessary to have CONFIG_PACKET enabled in the kernel for wpa_supplicant to work. To see if it is enabled on the current kernel, try:

root #

zgrep CONFIG_PACKET /proc/config.gz

root #

grep CONFIG_PACKET /usr/src/linux/.config

Nota
Depending on the USE flags, wpa_supplicant can install a graphical interface written in Qt5, which will integrate nicely with KDE. To get it, enable USE="qt5" for the net-wireless/wpa_supplicant package.

Next, configure /etc/conf.d/net so that the wpa_supplicant module is preferred over wireless-tools (if both are installed, wireless-tools is the default).

FILE /etc/conf.d/netForce the use of wpa_supplicant

# Prefer wpa_supplicant over wireless-tools
modules="wpa_supplicant"

Nota
When using the host-ap driver it is necessary to put the card in Managed mode before it can be used with wpa_supplicant correctly. This can be achieved by setting iwconfig_eth0="mode managed" in /etc/conf.d/net.

Next configure wpa_supplicant itself (which is a bit more tricky depending on how secure the Access Points are). The below example is taken and simplified from /usr/share/doc/wpa_supplicant-<version>/wpa_supplicant.conf.gz which ships with wpa_supplicant.

FILE /etc/wpa_supplicant/wpa_supplicant.confSomewhat simplified example

# The below line not be changed otherwise wpa_supplicant refuses to work
ctrl_interface=/var/run/wpa_supplicant
  
# Ensure that only root can read the WPA configuration
ctrl_interface_group=0
  
# Let wpa_supplicant take care of scanning and AP selection
ap_scan=1
  
# Simple case: WPA-PSK, PSK as an ASCII passphrase, allow all valid ciphers
network={
  ssid="simple"
  psk="very secret passphrase"
  # The higher the priority the sooner we are matched
  priority=5
}
  
# Same as previous, but request SSID-specific scanning (for APs that reject
# broadcast SSID)
network={
  ssid="second ssid"
  scan_ssid=1
  psk="very secret passphrase"
  priority=2
}
  
# Only WPA-PSK is used. Any valid cipher combination is accepted
network={
  ssid="example"
  proto=WPA
  key_mgmt=WPA-PSK
  pairwise=CCMP TKIP
  group=CCMP TKIP WEP104 WEP40
  psk=06b4be19da289f475aa46a33cb793029d4ab3db7a23ee92382eb0106c72ac7bb
  priority=2
}
  
# Plaintext connection (no WPA, no IEEE 802.1X)
network={
  ssid="plaintext-test"
  key_mgmt=NONE
}
  
# Shared WEP key connection (no WPA, no IEEE 802.1X)
network={
  ssid="static-wep-test"
  key_mgmt=NONE
  # Keys in quotes are ASCII keys
  wep_key0="abcde"
  # Keys specified without quotes are hex keys
  wep_key1=0102030405
  wep_key2="1234567890123"
  wep_tx_keyidx=0
  priority=5
}
  
# Shared WEP key connection (no WPA, no IEEE 802.1X) using Shared Key
# IEEE 802.11 authentication
network={
  ssid="static-wep-test2"
  key_mgmt=NONE
  wep_key0="abcde"
  wep_key1=0102030405
  wep_key2="1234567890123"
  wep_tx_keyidx=0
  priority=5
  auth_alg=SHARED
}
  
# IBSS/ad-hoc network with WPA-None/TKIP
network={
  ssid="test adhoc"
  mode=1
  proto=WPA
  key_mgmt=WPA-NONE
  pairwise=NONE
  group=TKIP
  psk="secret passphrase"
}

Wireless tools

Initial setup and managed mode

The wireless tools project provides a generic way to configure basic wireless interfaces up to the WEP security level. While WEP is a weak security method it's still prevalent in the world.

Wireless tools configuration is controlled by a few main variables. The sample configuration file below should describe all that is needed. One thing to bear in mind is that no configuration means "connect to the strongest unencrypted Access Point" - wireless tools will always try and connect the system to something.

root #emerge --ask net-wireless/wireless-tools

Nota
Although net-wireless/iw is the current tool for the wireless stack, net-misc/netifrc before version 0.6.0 does not work with the new commands. net-wireless/wireless-tools must be used with netifrc with earlier versions. For more information consult the variable name documentation.

FILE /etc/conf.d/netSample iwconfig setup

# Prefer iwconfig over wpa_supplicant
modules="iwconfig"
  
# Configure WEP keys for Access Points called ESSID1 and ESSID2
# You may configure up to 4 WEP keys, but only 1 can be active at
# any time so we supply a default index of [1] to set key [1] and then
# again afterwards to change the active key to [1]
# We do this incase you define other ESSID's to use WEP keys other than 1
#
# Prefixing the key with s: means it's an ASCII key, otherwise a HEX key
#
# enc open specified open security (most secure)
# enc restricted specified restricted security (least secure)
key_ESSID1="[1] s:yourkeyhere key [1] enc open"
key_ESSID2="[1] aaaa-bbbb-cccc-dd key [1] enc restricted"
  
# The below only work when we scan for available Access Points
  
# Sometimes more than one Access Point is visible so we need to
# define a preferred order to connect in
preferred_aps="'ESSID1' 'ESSID2'"

Fine-tune AP selection

It is possible to add some extra options to fine-tune the AP selection, but these are not required.

One way is to configure the system so it only connects to preferred APs. By default if everything configured has failed and wireless-tools can connect to an unencrypted Access Point then it will. This can be controlled by the associate_order variable. Here's a table of values and how they control this.

Value	Description
any	Default behavior.
preferredonly	Only connect to visible APs in the preferred list.
forcepreferred	Forceably connect to APs in the preferred order if they are not found in a scan.
forcepreferredonly	Do not scan for APs - instead just try to connect to each one in order.
forceany	Same as forcepreferred + connect to any other available AP.

There is also the blacklist_aps and unique_ap selection. blacklist_aps works in a similar way to preferred_aps. unique_ap is a yes or no value that says if a second wireless interface can connect to the same Access Point as the first interface.

FILE /etc/conf.d/netblacklist_aps and unique_ap example

# Sometimes you never want to connect to certain access points
blacklist_aps="'ESSID3' 'ESSID4'"
  
# If you have more than one wireless card, you can say if you want
# to allow each card to associate with the same Access Point or not
# Values are "yes" and "no"
# Default is "yes"
unique_ap="yes"

Ad-hoc and master modes

To set the system up as an ad-hoc node when it fails to connect to any Access Point in managed mode, use this as a fallback:

FILE /etc/conf.d/netFallback to ad-hoc mode

adhoc_essid_eth0="This Adhoc Node"

It is also possible to connect to ad-hoc networks, or to run the system in master mode so it becomes an access point itself.

FILE /etc/conf.d/netSample ad-hoc/master configuration

# Set the mode - can be managed (default), ad-hoc or master
# Not all drivers support all modes
mode_eth0="ad-hoc"
  
# Set the ESSID of the interface
# In managed mode, this forces the interface to try and connect to the
# specified ESSID and nothing else
essid_eth0="This Adhoc Node"
  
# We use channel 3 if you don't specify one
channel_eth0="9"

Importante
An important resource about channel selection is the BSD wavelan documentation found at the NetBSD documentation. There are 14 channels possible; We are told that channels 1-11 are legal for North America, channels 1-13 for most of Europe, channels 10-13 for France, and only channel 14 for Japan. If in doubt, please refer to the documentation that came with the card or access point. Make sure that the channel selected is the same channel the access point (or the other card in an ad-hoc network) is on. The default for cards sold in North America and most of Europe is 3; the default for cards sold in France is 11, and the default for cards sold in Japan is 14.

Troubleshooting wireless tools

There are some more variables that can help to get the wireless up and running due to driver or environment problems. Here's a table of other things that can be tried.

Variable name	Default value	Description
`iwconfig_eth0`		See the iwconfig man page for details on what to send iwconfig.
`iwpriv_eth0`		See the iwpriv man page for details on what to send iwpriv.
`sleep_scan_eth0`	0	The number of seconds to sleep before attempting to scan. This is needed when the driver/firmware needs more time to active before it can be used.
`sleep_associate_eth0`	5	The number of seconds to wait for the interface to associate with the Access Point before moving onto the next one.
`associate_test_eth0`	MAC	Some drivers do not reset the MAC address associated with an invalid one when they lose or attempt association. Some drivers do not reset the quality level when they lose or attempt association. Valid settings are MAC, quality and all.
`scan_mode_eth0`		Some drivers have to scan in ad-hoc mode, so if scanning fails try setting ad-hoc here.
`iwpriv_scan_pre_eth0`		Sends some iwpriv commands to the interface before scanning. See the iwpriv man page for more details.
`iwpriv_scan_post_eth0`		Sends some iwpriv commands to the interface after scanning. See the iwpriv man page for more details.

Defining network configuration per ESSID

In this section, we show how to configure network settings based on the ESSID. For instance, with the wireless network with ESSID ESSID1 configure a static IP address while ESSID ESSID2 uses DHCP.

Nota
This works with both wpa_supplicant as well as wireless-tools

Importante
Please consult the variable name documentation.

FILE /etc/conf.d/netoverride network settings per ESSID

config_ESSID1="192.168.0.3/24 brd 192.168.0.255"
routes_ESSID1="default via 192.168.0.1"
  
config_ESSID2="dhcp"
fallback_ESSID2="192.168.3.4/24"
fallback_route_ESSID2="default via 192.168.3.1"
  
# We can define nameservers and other things too
# NOTE: DHCP will override these unless it's told not to
dns_servers_ESSID1="192.168.0.1 192.168.0.2"
dns_domain_ESSID1="some.domain"
dns_search_domains_ESSID1="search.this.domain search.that.domain"
  
# You override by the MAC address of the Access Point
# This handy if you goto different locations that have the same ESSID
config_001122334455="dhcp"
dhcpcd_001122334455="-t 10"
dns_servers_001122334455="192.168.0.1 192.168.0.2"

Standard function hooks

Four functions can be defined in /etc/conf.d/net:

preup(), called before an interface is brought up;
predown(), called before an interface is brought down;
postup(), called after an interface is brought up; and
postdown(), called after an interface is brought down.

Each of these these functions is called with the interface name, available within each function via the IFACE variable, so that one function can control multiple interfaces.

The return values for the preup() and predown() functions should be:

0 to indicate success, and that configuration or de-configuration of the interface can continue.
A non-zero value otherwise.

If preup() returns a non-zero value, interface configuration will be aborted. If predown() returns a non-zero value, the interface will not be allowed to continue de-configuration.

Return values for the postup() and postdown() functions are ignored since there's nothing to do if they indicate failure.

${IFACE} is set to the interface being brought up/down. ${IFVAR} is ${IFACE} converted to variable name bash allows.

FILE /etc/conf.d/netpre/post up/down function examples

preup() {
  # Test for link on the interface prior to bringing it up.  This
  # only works on some network adapters and requires the ethtool
  # package to be installed.
  if ethtool ${IFACE} | grep -q 'Link detected: no'; then
    ewarn "No link on ${IFACE}, aborting configuration"
    return 1
  fi
  
  # Remember to return 0 on success
  return 0
}
  
predown() {
  # The default in the script is to test for NFS root and disallow
  # downing interfaces in that case.  Note that if you specify a
  # predown() function you will override that logic.  Here it is, in
  # case you still want it...
  if is_net_fs /; then
    eerror "root filesystem is network mounted -- can't stop ${IFACE}"
    return 1
  fi
  
  # Remember to return 0 on success
  return 0
}
  
postup() {
  # This function could be used, for example, to register with a
  # dynamic DNS service.  Another possibility would be to
  # send/receive mail once the interface is brought up.
       return 0
}
  
postdown() {
  # This function is mostly here for completeness... I haven't
  # thought of anything nifty to do with it yet ;-)
  return 0
}

Nota
For more information on writing functions, please read /usr/share/doc/netifrc-*/net.example.bz2.

Wireless function hooks

Nota
This will not work with WPA Supplicant - but the ${ESSID} and ${ESSIDVAR} variables are available in the postup() function.

Two functions can be defined in /etc/conf.d/net:

preassociate(), called before association.
postassociate(), called after association.

Each of these these functions is called with the interface name, available within each function via the IFACE variable, so that one function can control multiple interfaces.

The return values for the preassociate() function should be:

0 to indicate success, and to continue configuration.
A non-zero value otherwise.

If preassociate() returns a non-zero value, interface configuration will be aborted.

The return value for the postassociate() function is ignored since there's nothing to do if it indicates failure.

Within each function, the exact ESSID of the AP the system is connecting to is available via the ESSID variable. ${ESSIDVAR} is ${ESSID} converted to a variable name bash allows.

FILE /etc/conf.d/netpre/post association functions

preassociate() {
  # The below adds two configuration variables leap_user_ESSID
  # and leap_pass_ESSID. When they are both configured for the ESSID
  # being connected to then we run the CISCO LEAP script
  
  local user pass
  eval user=\"\$\{leap_user_${ESSIDVAR}\}\"
  eval pass=\"\$\{leap_pass_${ESSIDVAR}\}\"
  
  if [[ -n ${user} && -n ${pass} ]]; then
    if [[ ! -x /opt/cisco/bin/leapscript ]]; then
      eend "For LEAP support, please emerge net-misc/cisco-aironet-client-utils"
      return 1
    fi
    einfo "Waiting for LEAP Authentication on \"${ESSID//\\\\//}\""
    if /opt/cisco/bin/leapscript ${user} ${pass} | grep -q 'Login incorrect'; then
      ewarn "Login Failed for ${user}"
      return 1
    fi
  fi
  
  return 0
}
  
postassociate() {
  # This function is mostly here for completeness... I haven't
  # thought of anything nifty to do with it yet ;-)
  
  return 0
}

Nota
${ESSID} and ${ESSIDVAR} are unavailable in predown() and postdown() functions.

Nota
For more information on writing custom functions, please read /usr/share/doc/netifrc-*/net.example.bz2.

Network management

With laptops, systems can be always on the move. As a result, the system may not always have an Ethernet cable or plugged in or an access point available. Also, the user may want networking to automatically work when an Ethernet cable is plugged in or an access point is found.

In this chapter, we cover how this can be done.

Nota
This document only talks about ifplugd, but there are alternatives such as netplug. netplug is a lightweight alternative to ifplugd, but it relies on the kernel network drivers working correctly, and many drivers do not.

ifplugd

ifplugd is a daemon that starts and stops interfaces when an Ethernet cable is inserted or removed. It can also manage detecting association to Access Points or when new ones come in range.

root #emerge --ask sys-apps/ifplugd

Configuration for ifplugd is fairly straightforward too. The configuration is held in /etc/conf.d/net. Run man ifplugd for details on the available variables. Also, see /usr/share/doc/netifrc-*/net.example.bz2 for more examples.

FILE /etc/conf.d/netSample ifplug configuration

# Replace eth0 with the interface to be monitored
ifplugd_eth0="..."
  
# To monitor a wireless interface
ifplugd_eth0="--api-mode=wlan"

In addition to managing multiple network connections, users may want to add a tool that makes it easy to work with multiple DNS servers and configurations. This is very handy when the system receives its IP address via DHCP.

root #emerge --ask net-dns/openresolv

See man resolvconf to learn more about its features.

Warning: Display title "Gentoo Linux x86 Handbook: Network configuration" overrides earlier display title "Handbook:X86/Full/Networking".