1.  Automatic Network Detection

Maybe it just works?

If your system is plugged into an Ethernet network with a DHCP server, it is very likely that your networking configuration has already been set up automatically for you. If so, you should be able to take advantage of the many included network-aware commands on the Installation CD such as ssh, scp, ping, irssi, wget and links, among others.

If networking has been configured for you, the /sbin/ifconfig command should list some network interfaces besides lo, such as eth0:

# /sbin/ifconfig
(...)
eth0      Link encap:Ethernet  HWaddr 00:50:BA:8F:61:7A
          inet addr:192.168.0.2  Bcast:192.168.0.255  Mask:255.255.255.0
          inet6 addr: fe80::50:ba8f:617a/10 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:1498792 errors:0 dropped:0 overruns:0 frame:0
          TX packets:1284980 errors:0 dropped:0 overruns:0 carrier:0
          collisions:1984 txqueuelen:100
          RX bytes:485691215 (463.1 Mb)  TX bytes:123951388 (118.2 Mb)
          Interrupt:11 Base address:0xe800 

Optional: Configure any Proxies

If you access the Internet through a proxy, you might need to set up proxy information during the installation. It is very easy to define a proxy: you just need to define a variable which contains the proxy server information.

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

(If the proxy filters HTTP traffic)
# export http_proxy="http://proxy.gentoo.org:8080"
(If the proxy filters FTP traffic)
# export ftp_proxy="ftp://proxy.gentoo.org:8080"
(If the proxy filters RSYNC traffic)
# export RSYNC_PROXY="proxy.gentoo.org:8080"

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

http://username:password@proxy.gentoo.org:8080

Testing the Network

You may want to try pinging your ISP's DNS server (found in /etc/resolv.conf) and a Web site of your choice, just to make sure that your packets are reaching the net, DNS name resolution is working correctly, etc.

# ping -c 3 www.gentoo.org

If you are now able to use your network, you can skip the rest of this section and continue with (Preparing the Disks). If not, read on.

1.  Automatic Network Configuration

If the network doesn't work immediately, some installation media allow you to use net-setup (for regular or wireless networks), pppoe-setup (for ADSL-users) or pptp (for PPTP-users - available on x86, amd64, alpha, ppc and ppc64).

If your installation medium does not contain any of these tools or your network doesn't function yet, continue with Manual Network Configuration.

• Regular Ethernet users should continue with Default: Using net-setup
• ADSL users should continue with Alternative: Using PPP
• PPTP users should continue with Alternative: Using PPTP

Default: Using net-setup

The simplest way to set up networking if it didn't get configured automatically is to run the net-setup script:

# net-setup eth0

net-setup will ask you some questions about your network environment. When all is done, you should have a working network connection. Test your network connection as stated before. If the tests are positive, congratulations! You are now ready to install Gentoo. Skip the rest of this section and continue with (Preparing the Disks).

If your network still doesn't work, continue with Manual Network Configuration.

Alternative: Using PPP

Assuming you need PPPoE to connect to the internet, the Installation CD (any version) has made things easy for you by including ppp. Use the provided pppoe-setup script to configure your connection. You will be prompted for the ethernet device that is connected to your adsl modem, your username and password, the IPs of your DNS servers and if you need a basic firewall or not.

# pppoe-setup
# pppoe-start

If something goes wrong, double-check that you correctly typed your username and password by looking at /etc/ppp/pap-secrets or /etc/ppp/chap-secrets and make sure you are using the right ethernet device. If your ethernet device doesn't exist, you will have to load the appropriate network modules. In that case you should continue with Manual Network Configuration as we explain how to load the appropriate network modules there.

If everything worked, continue with (Preparing the Disks).

Alternative: Using PPTP

If you need PPTP support, you can use pptpclient which is provided by our Installation CDs. But first you need to make sure that your configuration is correct. Edit /etc/ppp/pap-secrets or /etc/ppp/chap-secrets so it contains the correct username/password combination:

# nano -w /etc/ppp/chap-secrets

Then adjust /etc/ppp/options.pptp if necessary:

# nano -w /etc/ppp/options.pptp

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

# pptp <server ip>

Now continue with (Preparing the Disks).

1.  Manual Network Configuration

Loading the Appropriate Network Modules

When the Installation CD boots, it tries to detect all your hardware devices and loads the appropriate kernel modules (drivers) to support your 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 you need.

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

To find out what kernel modules we provide for networking, use ls:

# ls /lib/modules/`uname -r`/kernel/drivers/net

If you find a driver for your network card, use modprobe to load the kernel module:

(As an example, we load the pcnet32 module)
# modprobe pcnet32

To check if your network card is now detected, use ifconfig. A detected network card would result in something like this:

# ifconfig eth0
eth0      Link encap:Ethernet  HWaddr FE:FD:00:00:00:00  
          BROADCAST NOARP MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0 
          RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)

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

# ifconfig eth0
eth0: error fetching interface information: Device not found

If you have multiple network cards in your system they are named eth0, eth1, etc. Make sure that the network card you want to use works well and remember to use the correct naming throughout this document. We will assume that the network card eth0 is used.

Assuming that you now have a detected network card, you can retry net-setup or pppoe-setup again (which should work now), but for the hardcore people amongst you we explain how to configure your network manually.

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

• Using DHCP for automatic IP retrieval
• Preparing for Wireless Access if you have a wireless card
• Understanding Network Terminology explains what you need to know about networking
• Using ifconfig and route explains how to set up your 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 you have a DHCP server in your network (or if your provider provides a DHCP service). To have a network interface receive this information automatically, use dhcpcd:

# dhcpcd eth0
Some network admins require that you use the
hostname and domainname provided by the DHCP server.
In that case, use
# dhcpcd -HD eth0

If this works (try pinging some internet server, like Google), then you are all set and ready to continue. Skip the rest of this section and continue with (Preparing the Disks).

Preparing for Wireless Access

If you are using a wireless (802.11) card, you may need to configure your wireless settings before going any further. To see the current wireless settings on your card, you can use iwconfig. Running iwconfig might show something like:

# iwconfig eth0
eth0      IEEE 802.11-DS  ESSID:"GentooNode"                                   
          Mode:Managed  Frequency:2.442GHz  Access Point: 00:09:5B:11:CC:F2    
          Bit Rate:11Mb/s   Tx-Power=20 dBm   Sensitivity=0/65535               
          Retry limit:16   RTS thr:off   Fragment thr:off                       
          Power Management:off                                                  
          Link Quality:25/10  Signal level:-51 dBm  Noise level:-102 dBm        
          Rx invalid nwid:5901 Rx invalid crypt:0 Rx invalid frag:0 Tx          
          excessive retries:237 Invalid misc:350282 Missed beacon:84            

For most users, there are only two settings that might be important to change, the ESSID (aka wireless network name) or the WEP key. If the ESSID and Access Point address listed are already that of your access point and you are not using WEP, then your wireless is working. If you need to change your ESSID, or add a WEP key, you can issue the following commands:

(This sets the network name to "GentooNode")
# iwconfig eth0 essid GentooNode

(This sets a hex WEP key)
# iwconfig eth0 key 1234123412341234abcd

(This sets an ASCII key - prefix it with "s:")
# iwconfig eth0 key s:some-password

You can then confirm your wireless settings again by using iwconfig. Once you have wireless working, you can continue configuring the IP level networking options as described in the next section (Understanding Network Terminology) or use the net-setup tool as described previously.

Understanding Network Terminology

If all of the above fails, you will have to configure your network manually. This is not difficult at all. However, you need to be familiar with some network terminology, as you will need it to be able to configure your network to your satisfaction. After reading this, you will know what a gateway is, what a netmask serves for, how a broadcast address is formed and why you need nameservers.

In a network, hosts are identified by their IP address (Internet Protocol address). Such an address is a combination of four numbers between 0 and 255. Well, at least that is how we perceive it. In reality, such an IP address consists of 32 bits (ones and zeros). Let's view an example:

IP Address (numbers):   192.168.0.2
IP Address (bits):      11000000 10101000 00000000 00000010
                        -------- -------- -------- --------
                           192      168       0        2

Such an IP address is unique to a host as far as all accessible networks are concerned (i.e. every host that you are 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.

IP-address:    192      168      0         2
            11000000 10101000 00000000 00000010
Netmask:    11111111 11111111 11111111 00000000
               255      255     255        0
           +--------------------------+--------+
                    Network              Host

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

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

IP-address:    192      168      0         2
            11000000 10101000 00000000 00000010
Broadcast:  11000000 10101000 00000000 11111111
               192      168      0        255
           +--------------------------+--------+
                     Network             Host

To be able to surf on the internet, you 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).

We previously stated that every host has its own IP address. To be able to reach this host by a name (instead of an IP address) you 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, you must define the necessary name servers in /etc/resolv.conf.

In some cases, your gateway also serves as nameserver. Otherwise you will have to enter the nameservers provided by your ISP.

To summarise, you will need the following information before continuing:

Using ifconfig and route

Setting up your network consists of three steps. First we assign ourselves an IP address using ifconfig. Then we set up routing to the gateway using route. Then we finish up by placing the nameserver IPs in /etc/resolv.conf.

To assign an IP address, you will need your IP address, broadcast address and netmask. Then execute the following command, substituting ${IP_ADDR} with your IP address, ${BROADCAST} with your broadcast address and ${NETMASK} with your netmask:

# ifconfig eth0 ${IP_ADDR} broadcast ${BROADCAST} netmask ${NETMASK} up

Now set up routing using route. Substitute ${GATEWAY} with your gateway IP address:

# route add default gw ${GATEWAY}

Now open /etc/resolv.conf with your favorite editor (in our example, we use nano):

# nano -w /etc/resolv.conf

Now fill in your nameserver(s) using the following as a template. Make sure you substitute ${NAMESERVER1} and ${NAMESERVER2} with the appropriate nameserver addresses:

nameserver ${NAMESERVER1}
nameserver ${NAMESERVER2}

That's it. Now test your network by pinging some Internet server (like Google). If this works, congratulations then. You are now ready to install Gentoo. Continue with (Preparing the Disks).