User:SwifT/Complete Handbook/Configuring the system

From Gentoo Wiki
Jump to:navigation Jump to:search

File system information

The fstab file

fstab stands for file system table; when you would take a look at a fully configured /etc/fstab file you can easily see why:

FILE /etc/fstab
/dev/sda8               /             ext3    defaults,noatime          0 0
/dev/sda5               none          swap    sw                        0 0
/dev/sda6               /boot         ext2    noauto,noatime            0 0
/dev/sda7               /home         ext3    defaults,noatime,noexec   0 0
/dev/cdroms/cdrom0      /media/cdrom  auto    defaults,user,noauto      0 0

Each line declares what storage location (first field) is mounted at a certain location (second field) using a file system (third field) and mounted with one or more options (fourth field). The last two numbers are not that actively used anymore so you can safely set them to 0 0.

It is vital that your /etc/fstab file is a reflection of your environment. By default, Gentoo offers an almost empty /etc/fstab file with illegal storage locations (such as /dev/BOOT and /dev/ROOT). Any user should change the file, otherwise the system might not boot.

The fstab file is used during the system boot procedure to find out what file systems should be mounted, but also during regular system operation. For instance, when you insert a CD in your CD-ROM player, Linux ought to know where it should mount the CD so that you (and perhaps other users) can reach it.

Mount options

The mount options which you can place in the fourth field in /etc/fstab are well documented in the mount manual page:

user $man mount

Each set of mount options is documented in a section pertaining to the file system used (for instance, ext2, reiserfs, ...). Some of them are available to all file systems, such as defaults, auto, or noauto (automatically mount file system or not).

Special file systems

Some lines in the /etc/fstab file have a none as the storage location. Such file systems are pseudo file systems and do not require any storage on the disk.

  • The proc file system represents kernel information (like statistics, hardware settings, process information, memory data, ...) as regular files on the file system. You can read from those files to obtain the information you need, but these files are never actually written to disk. Every time you read them, the information is recalculated.
  • The tmpfs file system is storage located entirely in memory. Although it is extremely fast, it is also volatile meaning that it loses its content when you reboot the system. The tmpfs file system is often used for temporary file storage (hence the name), but in the previously given /etc/fstab example it serves as a storage point for certain applications who want to share memory without using the shared memory functionality offered by the C library.
  • The sysfs file system (not shown in the example as Gentoo mounts /sys automatically when it is present) is the successor of the proc file system. It servers the same purpose, but is restructured so it scales well in larger environments.

Edit /etc/fstab

Don't forget to edit /etc/fstab to suit your environment. You can use nano to open the file:

root #nano -w /etc/fstab

System logging

Purpose of logging

The system logger is an important daemon on the system. A daemon is a tool that runs in the background; you can't work with it interactively.

The job of the system logger is to obtain information from various processes (and in certain configurations even from remote processes) like logon events, web server requests, security events, kernel messages, ... and write them down in separate files: log files.

Such log files can then be used to resolve issues on the machine (hardware errors are usually quite verbose), generate usage statistics (for instance for web servers), backtrack logon events (for security purposes), etc.

Installing a system logger

Gentoo provides various system loggers, each of them with their own pros and cons: metalog, newsyslog, rsyslog, socklog, sysklogd, and syslog-ng. Which one you choose is up to you, but it is quite important that you pick one: if you do not install a system logger, all events will be displayed on your terminal, cluttering up your screen instead of nicely archiving the events in files.

root #emerge --ask <systemlogger>

Next you'll need to add the system logger of your choice to the default run level. First find out how the init script is called:

root #ls /etc/init.d

Then, add it to the default runlevel:

root #rc-update add <initscript> default

System information

Root password

With the passwd tool you can set or change any user account password. At first, you need to set the root user password. Run passwd and enter the new password. The tool will ask you to confirm the password by reentering it after which the password is updated.

root #passwd

You might want to verify that your keyboard settings are correct before you enter the root password. If the keyboard settings deviate a bit from what you expect them to be, your root password might actually differ from the one you thought you have entered. As the passwd tool does not echo the characters on screen, you can not verify the password by just looking at it.

On most Gentoo installations, the password itself will be stored in a hashed format in /etc/shadow which is only readable by the root user. Hashed means that the password itself is not shown, but a mathematical result based on the password. A hash gives a theoretically unique value based on certain input (here: the password) but from which you can not revert (i.e. you can not use the hash to obtain the password).

The /etc/passwd file, which contains user account information, is readable by any user. Note though that this file does not always contain your user account information - larger networks will probably store this information on a central server (for instance an LDAP server). The system will look for account information according to the passwd field in /etc/nsswitch.conf.

User account

Next, it is heavily recommended to create a user account for daily tasks. The root user is all-powerful; any mistyped command can severely damage your system. Running your applications as the root user also exposes you to security breaches - although not many Linux viruses exist, the damage that a virus can do depends on the privileges it obtains, and it obtains the privileges from the tool whose flaw it has exploited.

To create a user, use useradd and pass on the -m option so that the user's home directory (/home/username for the username user) is created. Also add the groups to which you want to make the user part of:

root #useradd -m -g users -G wheel,audio,cdrom,games,users john

Most groups are self-explanatory, but the wheel group might need a small introduction.

The wheel group contains all users who can run su to switch from one user to another (including the root user). Only put trusted users in this group. A better alternative to the wheel access (since it still requires the user to know the passwords of the accounts it wants to switch to) is to use sudo of which an excellent guide exists.

Networking information

Gentoo provides several tools for managing your network connections, see Network management.

Managing network with dhcpcd

The easiest of them to use is dhcpcd. It has perfect integration for wpa_supplicant and automatically switches between wired and wireless connections.


Install dhcpcd, add it to the default runlevel and start it:

root #emerge --ask net-misc/dhcpcd
root #rc-update add dhcpcd default
root #/etc/init.d/dhcpcd start

All its configuration goes into /etc/dhcpcd.conf but for most installations nothing needs to be done there.[1] Though man 5 dhcpcd.conf will be helpful in case of advanced configuration demand.


First follow the setup guide for dhcpcd.

Emerge wpa_supplicant (Version >=2.6-r2 is needed in order to get the CONFIG_MATCH_IFACE option added in April 2017):

root #emerge --ask net-wireless/wpa_supplicant

Using OpenRC

Complete its conf.d file with the -M option for the wireless network interface:

FILE /etc/conf.d/wpa_supplicant
wpa_supplicant_args="-B -M -c /etc/wpa_supplicant/wpa_supplicant.conf"

In case authentication for the wired interface is needed, this configuration file should look like:

FILE /etc/conf.d/wpa_supplicant
wpa_supplicant_args="-ieth0 -Dwired -c/etc/wpa_supplicant/wpa_supplicant_wired.conf -B -M -c/etc/wpa_supplicant/wpa_supplicant.conf"

With the configuration done, run it as a service:

root #rc-update add wpa_supplicant default
root #rc-service wpa_supplicant start

Using Systemd

Systemd allows a simpler per-device setup without needing to create the above conf.d files. As explained under wpa_supplicant item in the Native services section, a service symlink such as wpa_supplicant@wlan0.service looks for a separate configuration file to manage the device wlan0 in this case.

To configure a specific device this way, first copy or rename the /etc/wpa_supplicant/wpa_supplicant.conf file as /etc/wpa_supplicant/wpa_supplicant-DEVNAME.conf where DEVNAME should be the name of the device, such as wlan0.

Then, navigate to /etc/systemd/system/ and create the symlink:

root #ln -s /lib/systemd/system/wpa_supplicant@.service wpa_supplicant@DEVNAME.service

where DEVNAME is same device name as in the conf file above.

Note the @ signs on both arguments in the symlink step.

Test the system:

root #systemctl daemon-reload
root #systemctl start wpa_supplicant@DEVNAME
root #systemctl status wpa_supplicant@DEVNAME

Static IP address

In case the network interface card should be configured with a static IP address, add their data to the configuration file as shown for the following example.[2]

FILE /etc/dhcpcd.confHere is an example which configures a static address, routes, and DNS
interface eth0
   static ip_address=
   static routers=
   static domain_name_servers=

The hosts file

The /etc/hosts file is a small table the system uses to make immediate translations between hostnames and IP addresses. This file should at least contain one line:

FILE /etc/hosts       localhost

All other lines should be set under that line using the following syntax:

FILE /etc/hosts
<ip address> <fully qualified hostname> <aliases>

For instance, if you want to assign the host name gentoobox to the eth0 interface address (for instance,

FILE /etc/hosts     gentoobox

If you use a domain name for your network (such as boxes, but it can also be a real reserved domain name like, you should set it like so:

FILE /etc/hosts     gentoobox.boxes     gentoobox

Next to the host names assigned to your interfaces, you can also add in the IP address and hostname information for the other hosts on your system if they aren't known to the DNS servers you've specified (in /etc/resolv.conf, perhaps automatically with DHCP).

Various configuration settings

The /etc/rc.conf file

The information in this section is probably outdated. You can help the Gentoo community by verifying and updating this section.

The /etc/rc.conf file contains system-wide settings for the entire system. You will find lots of variables already defined in the file, accompanied with lots of documentation.

The first variable you'll see is the UNICODE variable. Unicode (also known as UTF-8) is the new standard for character encoding[3]. Character encoding tells the system what sequence of bits resembles what character. Well-known encodings are ASCII, ISO-8859-1, etc. The UTF-8 or Unicode encoding is important because it is able to provide encodings for every possible language (including special characters like ¬ but also Chinese characters, etc.).

If you are interested in using Unicode on your system, please read the UTF-8 guide.

Another variable of importance is DISPLAYMANAGER. A display manager is a tool which shows a graphical logon screen after having booted your system. Most display managers even allow you to automatically log on as a specific user. If you want to use a display manager, you need to install one, add the xdm init script to the default runlevel and make sure that this variable points to the display manager of your choice.

Together with the DISPLAYMANAGER variable you'll find the XSESSION one. This tells the display manager what graphical environment it should load by default if the user didn't specify one explicitly. Well-known graphical environments are KDE, GNOME, XFCE, fluxbox, ... For specific instructions on how this variable influences the graphical logon process please read the comments in the rc.conf file.

Select keyboard language

If you aren't using a US QWERTY keyboard, you'll need to edit the /etc/conf.d/keymaps file to tell the Gentoo system what keyboard layout it should use.


  1. Presumed that most computers nowadays are behind a router or access point providing DHCP
  2. See the dhcpcd.conf(5) man page
  3. wikipedia:Character_encoding