Introduction

This tutorial shows how to configure the previously created Gentoo system. The following adjustments are propsed here:

  • portage overlays: Provides a method to add additional package sources to portage
  • portage git: Enables to sync portage via git which is fast, secure and up-to-date
  • tmux: Using tmux as default shell enables using multiple windows / panes / programs at the same time in one session
  • docker: Enables running a large variety of software in a sandbox without manual installation and hassle

Enabling overlays for portage

Eselect provides an easy integration of overlays into portage. The main portage respository should already be configured properly, so only a simple installation of eselect is necessary. For more information see the official wiki. Run the command shown below to install the repository module for eselect.

#!/bin/bash

# Install portage overlays
emerge --ask app-eselect/eselect-repository

The configuration for the plugin is located in the /etc/eselect/repository.conf file. The default path of the repository index is specified by the REPOS_CONF option which points to /etc/portage/repos.conf by default. Make sure that this directory exists or create it with the following command.

mkdir -p /etc/portage/repos.conf

A file named gentoo.conf should be located in this directory (/etc/portage/repos.conf) which holds the configuration for the main gentoo repository. Below is an example default configuration file which was created on my system.

[DEFAULT]
main-repo = gentoo

[gentoo]
location = /var/db/repos/gentoo
sync-type = rsync
sync-uri = rsync://rsync.de.gentoo.org/gentoo-portage/
auto-sync = yes
sync-rsync-verify-jobs = 1
sync-rsync-verify-metamanifest = yes
sync-rsync-verify-max-age = 24
sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
sync-openpgp-keyserver = hkps://keys.gentoo.org
sync-openpgp-key-refresh-retry-count = 40
sync-openpgp-key-refresh-retry-overall-timeout = 1200
sync-openpgp-key-refresh-retry-delay-exp-base = 2
sync-openpgp-key-refresh-retry-delay-max = 60
sync-openpgp-key-refresh-retry-delay-mult = 4
sync-webrsync-verify-signature = yes

The synchronization of emerge can now be done via the command below. This might take some time, depending on the internet speed and if the repository was synchronized before.

emerge --sync

Using Git for portage sync

An alternative method to sync the portage repository is to use git. For this the git package has to be installed on the system as shown below.

#!/bin/bash

# Install the git version control system
emerge --ask dev-vcs/git

Edit the sync-type and sync-uri in the portage configuration file under /etc/portage/repos.conf/gentoo.conf as shown below.

[DEFAULT]
main-repo = gentoo

[gentoo]
location = /var/db/repos/gentoo
#sync-type = rsync
#sync-uri = rsync://rsync.de.gentoo.org/gentoo-portage/
sync-type = git
sync-uri = https://github.com/gentoo-mirror/gentoo.git
auto-sync = yes
sync-rsync-verify-jobs = 1
sync-rsync-verify-metamanifest = yes
sync-rsync-verify-max-age = 24
sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
sync-openpgp-keyserver = hkps://keys.gentoo.org
sync-openpgp-key-refresh-retry-count = 40
sync-openpgp-key-refresh-retry-overall-timeout = 1200
sync-openpgp-key-refresh-retry-delay-exp-base = 2
sync-openpgp-key-refresh-retry-delay-max = 60
sync-openpgp-key-refresh-retry-delay-mult = 4
sync-webrsync-verify-signature = yes

Portage will now complain when synchronizing with git for the first time that the repository folder is not empty and that the folder can not be used to clone the git repository into it. This can be fixed by deleting the old rsync-managed repository which is located under /var/db/repos/gentoo when using the default configuration. Use the command below to do this.

#!/bin/bash

# Remove old and generate new repository
rm -r /var/db/repos/gentoo
emerge --sync

# Sync twice to test synchronization speed
emerge --sync

Tmux setup and configuration as default shell

Using tmux as default shell on a linux system enables to use multiple windows / panes in one terminal which run multiple processes in parallel. The panes can be arranged to show multiple windows side-by-side and switch between them with ease which makes working on the system faster. The tmux package can be installed on the system as shown below.

#!/bin/bash

# Install the terminal multiplexer package
emerge app-misc/tmux

There are some configuration options which should be set when using tmux as shell to enable a quick workflow. Create a file named .tmux.conf in your user home directory (~ or /root/) to configure the terminal multiplexer. Below is the configuration which I personally use on my system. The shell which is running inside tmux is set to /bin/bash and the current working directory is kept, when creating a new window / pane in the multiplexer.

When using tmux on a remote system (via ssh or similar) the tmux command prefix CTRL+B conflicts with the same prefix on the target system. Per default the prefix has to be pressed twice to trigger a command on the remote system. Therefore a remapping is done, which assigns CTRL+A to send the command prefix CTRL+B to the remote system, which makes navigation on the remote system faster.

Tmux shows the current time, date and the title of the running program in the right lower corner of the terminal. Since the window titles tend to be quite long the space for the title is resized to 80 characters. The date and time format has been changed to "dd.mm.YYYY HH:MM" ("%d.%m.%Y %H:%M") which looks like "25.03.2020 19:25". If a different style like "mm/dd/YYYY HH:MM" ("%m/%d/%Y %H:%M") is preferred which looks like "03/25/2020 19:25" this can be adjusted by setting the status-right option.

# Set shell in tmux to bash
set-option -g default-shell /bin/bash

# Enable easy nesting of tmux sessions on remote systems
# This assigns the Ctrl+A prefix to send a Ctrl+B prefix to the remote system
set-option -g prefix C-b
bind-key -n C-a send-prefix

# Stay in current working directory when creating new windows
bind '"' split-window -c "#{pane_current_path}"
bind % split-window -h -c "#{pane_current_path}"
bind c new-window -c "#{pane_current_path}"

# Extend window title on bottom right to fit longer titles
# Date, time format is dd.mm.YYYY HH:MM
# Adjust to own personal preferrence
set-option -g status-right-length 80
set-option -g status-right "#{?window_bigger,[#{window_offset_x}#,#{window_offset_y}] ,}\"#{=61:pane_title}\" %d.%m.%Y %H:%M"

Now the default shell can be set to use tmux by issuing the following command.

usermod --shell /usr/bin/tmux root

Docker installation

No linux development system is nowdays complete without docker. It enables fast switching of software versions combined with file and network sandboxing features.

The installation of docker on Gentoo requires to have the linux kernel sources present in the "/usr/src/linux" directory. This is the first step before installing the docker daemon and tools.

Depending on the kernel which is in use the sources might already present. If you are not running a vanilla Linux kernel you might have to download it from a different location / repository. When using git the switch "--depth 1" can be used to download only the most current version. The switch "--branch master" or "--branch v5.5" can be used to check out different kernel versions. Consult the repository for a list of available versions.

#!/bin/bash

# Create the directory to hold kernel sources
mkdir -p /usr/src/linux

# When running a vanilla Linux kernel
git clone https://github.com/torvalds/linux.git /usr/src/linux

# When running Gentoo using WSL 2
# git clone https://github.com/microsoft/WSL2-Linux-Kernel /usr/src/linux

Create a portage configuration file as shown below named "docker.use" for the docker package in the /etc/portage/package.use/ directory. If /etc/portage/package.use is a file then append the lines below to the file. The configuration below enables the AppArmor feature for docker and virt-network for the case that docker-machine is required later.

app-emulation/docker apparmor
app-emulation/runc apparmor
app-emulation/libvirt apparmor virt-network

Now the docker package can be installed with the following command. The installation might show some warnings which can be ignored since docker should run fine even when not every kernel feature is supported.

emerge app-emulation/docker

Create a new window / terminal to run the docker daemon with the command "dockerd". Then use the commands below to verify that docker is working. The docker daemon can be shut down after the test by pressing Ctrl+C on the keyboard when having the terminal of the docker daemon opened.

#!/bin/bash

# Run the docker client and show the version
# The output should be similar to "Docker version 19.03.8, build afacb8b7f0"
docker --version

# Test the docker daemon with a simple image
# The output should contain the following text:
# "Hello from Docker!"
# "This message shows that your installation appears to be working correctly."
docker run --rm hello-world

(Un-)License

This is free and unencumbered software released into the public domain.


Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.


In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain. We make this dedication for the benefit of the public at large and to the detriment of our heirs and successors. We intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


For more information, please refer to http://unlicense.org/