User:Buckshee

Automatic network detection
Maybe it just works?

If the system is connected to an Ethernet network with some kind of address management like DHCP or SLAAC it is very likely that the networking configuration has already been set up automatically. If so, then the many included network-aware commands on the installation CD such as, , , , , and , among others, will work immediately.

Determine interface names
As a result of the shift towards predictable network interface names, the interface name on the system can be quite different from the old naming convention. Recent installation media might show regular network interfaces names like, , or. Look for the interface in the output that has an IP address related to the local network.

TODO - I would argue that this trend is for ephemeral systems, and human focused systems should disable this and just use udev rules which provide an identical function

ip command
The command from /iproute2 can be used to determine interface names. The following example shows the output of, which is the shortest form of. You can also output JSON with the option, and  outputs a table missing labels for scripts.

The output of ip can be colored by running 'ip -c a', which is shorthand for, Please see https://bugs.gentoo.org/820236 about making this a default

In the remainder of this document, the handbook will assume that the operating network interface is called.

Optional: Configure any proxies
If the Internet is accessed through a proxy, then it is necessary to set up proxy information during the installation. It is very easy to define a proxy: just define a variable which contains the proxy server information.

In most cases, it is sufficient to define the variables using the server hostname. As an example, we assume the proxy is called proxy.gentoo.org and the port is 8080.

To set up an HTTP proxy (for HTTP and HTTPS traffic):

To set up an FTP proxy:

To set up an RSYNC proxy:

If the proxy requires a username and password, use the following syntax for the variable:

Testing the network
Try pinging your ISP's DNS server (found in ) and a web site of choice. This ensures that the network is functioning properly and that the network packets are reaching the net, DNS name resolution is working correctly, etc.

You can verify your external address with many tools, but a simple way from a terminal is

If this all works, then the remainder of this chapter can be skipped to jump right to the next step of the installation instructions

Automatic network configuration
If the network doesn't work immediately, the minimal installation CD provides some Gentoo tools for automatically configuring networks:


 * Ethernet users on wired and wireless networks should continue with Default: Using net-setup
 * ADSL users should continue with Alternative: Using PPP
 * PPTP users should continue with Alternative: Using PPTP
 * If install from a non Gentoo installer Manual network configuration.

Default: Using net-setup
The simplest way to set up networking if it didn't get configured automatically is to run the script which provides a menu based way to join networks. Due to the lack of convenient CLI usage in in wpa_supplicant this is the recommended way to connect to a wireless network

If you run net-setup without an interface name it will list them for you, but any steps taken from here

will ask some questions about the network environment. When all is done, the network connection should work. Test the network connection as stated before. If the tests are positive, congratulations! Skip the rest of this section and continue with

If the network still doesn't work, continue with Manual network configuration.

Alternative: Using PPP
Assuming PPPoE is needed to connect to the Internet, the installation CD (any version) has made things easier by including ppp. Use the provided script to configure the connection. During the setup the Ethernet device that is connected to your ADSL modem, the username and password, the IPs of the DNS servers and if a basic firewall is needed or not will be asked.

If something goes wrong, double-check that the username and password are correct by looking at or  and make sure to use the right Ethernet device. If the Ethernet device does not exist, the appropriate network modules need to be loaded. In that case continue with Manual network configuration as it will explain how to load the appropriate network modules there.

If everything worked, continue with.

Alternative: Using PPTP
If PPTP support is needed, use which is provided by the installation CDs. But first make sure that the configuration is correct. Edit or  so it contains the correct username/password combination:

Then adjust if necessary:

When all that is done, run (along with the options that couldn't be set in ) to connect the server:

Now continue with

Loading the appropriate network modules
When the Installation CD boots, it tries to detect all the hardware devices and loads the appropriate kernel modules (drivers) to support the hardware. In the vast majority of cases, it does a very good job. However, in some cases, it may not auto-load the kernel modules needed to communicate properly with the present network hardware.

If or  failed, then it is possible that the network card wasn't found immediately. This means users may have to load the appropriate kernel modules manually.

To find out what kernel modules are provided for networking, use the command:

If a driver is found for the network device, use to load the kernel module. For instance, to load the module:

To check if the network card is now detected, use. A detected network card would result in something like this (again, here is just an example):

If however the following error is shown, the network card is not detected:

The available network interface names on the system can be listed through the file system:

In the above example, 6 interfaces are found. The one is most likely the (wired) Ethernet adapter whereas  is the wireless one.

Assuming that the network card is now detected, retry or  again (which should work now), but for the hardcore people we explain how to configure the network manually as well.

Select one of the following sections based on your network setup:


 * Using DHCP for automatic IP retrieval
 * Understanding network terminology explains the basics about networking
 * Using ifconfig and route explains how to set up networking manually

Using DHCP
DHCP (Dynamic Host Configuration Protocol) makes it possible to automatically receive networking information (IP address, netmask, broadcast address, gateway, nameservers etc.). This only works if a DHCP server is in the network (or if the ISP provider provides a DHCP service). To have a network interface receive this information automatically, use :

Some network administrators require that the hostname and domainname provided by the DHCP server is used by the system. In that case, use:

Understanding network terminology
If all of the above fails, the network will need to be configured manually. This is not difficult at all. However, some knowledge of network terminology and basic concepts might be necessary. After reading this section, users will know what a gateway is, what a netmask serves for, how a broadcast address is formed and why systems need nameservers.

In a network, hosts are identified by their IP address (Internet Protocol address). Such an address is perceived as a combination of four numbers between 0 and 255. Well, at least when using IPv4 (IP version 4). In reality, such an IPv4 address consists of 32 bits (ones and zeros). Let's view an example:

Such an IP address is unique to a host as far as all accessible networks are concerned (i.e. every host that one wants to be able to reach must have a unique IP address). In order to distinguish between hosts inside and outside a network, the IP address is divided in two parts: the network part and the host part.

The separation is written down with the netmask, a collection of ones followed by a collection of zeros. The part of the IP that can be mapped on the ones is the network-part, the other one is the host-part. As usual, the netmask can be written down as an IP address.

In other words, 192.168.0.14 is part of the example network, but 192.168.1.2 is not.

The broadcast address is an IP address with the same network-part as the network, but with only ones as host-part. Every host on the network listens to this IP address. It is truly meant for broadcasting packets.

To be able to surf on the Internet, each computer in the network must know which host shares the Internet connection. This host is called the gateway. Since it is a regular host, it has a regular IP address (for instance 192.168.0.1).

Previously we stated that every host has its own IP address. To be able to reach this host by a name (instead of an IP address) we need a service that translates a name (such as dev.gentoo.org) to an IP address (such as 64.5.62.82). Such a service is called a name service. To use such a service, the necessary name servers need to be defined in.

In some cases, the gateway also serves as a nameserver. Otherwise the nameservers provided by the ISP need to be entered in this file.

To summarize, the following information is needed before continuing:

iproute2
Linux's standard tool for configuring interfaces is, which can configure an interface with the following commands: (EOD what are the fully unshortened commands? eg ip link set dev eth0 up, import the human language and mention classic tools as a note)

ifconfig and route
The classic tools from the package, setting up the network manually generally consists of three steps:


 * 1) Assign an IP address using the  command.
 * 2) Set up routing to the gateway using the  command.
 * 3) Finish up by placing valid nameserver IPs in the  file.

To assign an IP address, the IP address, broadcast address, and netmask are needed. Execute the following command, substituting ${IP_ADDR} with the target IP address, ${BROADCAST} with the target broadcast address, and ${NETMASK} with the target netmask:

To configure routing using, substitute the ${GATEWAY} value with the appropriate gateway IP address:

Now open the file using a text editor:

Fill in the nameserver(s) using the following as a template substituting ${NAMESERVER1} and ${NAMESERVER2} with nameserver IP addresses as necessary. More than one nameserver can be added: