HOWTO Maintain Gentoo - "Best Practices"

From Gentoo Linux Wiki

[edit] Introduction

This HOWTO documents my experiences with maintaining Gentoo. It is geared towards those who are looking for a low-effort way of running their Gentoo system and keeping them updated without doing too much fancy tinkering (if you are into that - and that can be cool at times - you'll find plenty of stuff to try elsewhere on this wiki).

This HOWTO is going to focus on two main aspects of working with a system: installing new software and updating existing software. I'm trying to keep the beginner Gentoo user in mind and will explain some basic stuff, but a rough understanding of portage is expected.

[edit] Installing new software

[edit] eix

As searching for packages with portage can take quite some time, I use the utility "eix" which builds an index of all packages and allows for fast queries. Just emerge eix, build the eix cache via running update-eix and you are set for pleasant package searching.

[edit] emerging

To actually emerge a package, I use emerge -av <whatever>. These command line flags have the following results:

• -a, --ask

portage will list all packages that it is going to emerge and then asks for confirmation

• -v, --verbose

mainly has the effect, that you'll see USE flags for all packages

• -t, --tree

shows the dependency tree for the given target by indenting dependencies. It is useful in case you want to know which package pulls which dependency

I then check the displayed USE flags and decide, whether I want to do any adjustments. As you probably know, you can set system wide USE flags in /etc/make.conf and you should do that whenever you have a USE flag that you want all or most of the time. But often you'll want to adjust USE flags just for this package. A clean way to do this is creating/editing files in /etc/portage. Avoid something like USE=cscope emerge vim, as portage will forget about your USE flag modification after that particular emerge process is completed. Then, if you update the package some time later, you will get the default USE flag setting again, unless you specify the modification again. This is error-prone and not exactly "low-effort".

Instead, you will want to create the file /etc/portage/package.use and add a line like this:

app-editors/vim  cscope

Now portage permanently knows about this USE flag setting.

[edit] Unmasking packages masked by keyword

The same goes for unmasking packages. At some point, you might want to use a masked version of a package. Again: Do not use ACCEPT_KEYWORD, but instead list your packages in /etc/portage/package.keywords like this:

app-editors/vim

or - even better - like this:

=app-editors/vim-7.0.17

Originally you always had to specify what keywords you wanted to attach to the package along side it. Recent version of portage negate this by automatically adding the ~arch keyword for your arch to any line in package.keywords

The second way is to be preferred, if you just need a specific version of a package. If you unmask all ~arch version of a package you might end up updating to an even buggier version during an system update, which you did not intend. By being very specific you minimize the impact on your system and staying very close to the standard set of stable packages is always a good idea in terms of stability and low-maintenance, in my opinion.

[edit] equery

One more thing about USE flags: To get more information about what a certain USE flag does, you can use "equery" which comes with the gentoolkit. You'll want to have that anyway, as it contains many useful tools.

emerge -av gentoolkit
equery uses vim		# lists USE flags and their descriptions

[edit] Updating existing software

[edit] dispatch-conf

The first thing to be said in this regard is: Do not use etc-update. Never ever. There is a much safer replacement called "dispatch-conf". For one thing, it can auto-merge trivial changes in configuration files - like different spacing. But the most important thing is, that it keeps record of which configuration files you edited and auto-updates those that you haven't touched. After it has collected the necessary information it will most often only prompt you for intervention where it is really necessary. You might also want to look into using dispatch-conf with RCS. There is more information elsewhere on this wiki about dispatch-conf.

It comes with portage, you only have to configure it (/etc/dispatch-conf.conf) and start using it: Whenever you are prompted to run etc-update, run dispatch-conf instead.

[edit] updating

Now to the actual system-wide update process: The first step is - of course - syncing your portage tree. This can be done with emerge --sync but if you are using eix, a more convenient way is to run eix-sync as this will have the same effect and also eix will update its cache afterwards.

eix-sync

For updating I run the command

emerge -uDNav world

which consists of these command line flags:

• -u, --update

updates packages to the _best_ version available, which sometimes might involve a downgrade. Trust the gentoo developers, that they know, what is 'best'. Higher version number is not always better. :-)

• -D, --deep

instead of looking only at the packages that are recorded in your world file, portage will also check all their dependencies for updates. Basically a "catch all" flag and that's what you'll want for a system-wide update.

• -N, --newuse

will also reemerge packages where USE flags have changed since their last compilation (like when you changed the system-wide USE flags).

• -a, --ask

as above

• -v, --verbose

as above

These seem to be the recommended command line flags to use for updating. The wiki entry Advanced Emerge World has more details about it.

[edit] eselect

With eselect you can easily switch to a new profile, manually update/correct kernel symlinks, activate opengl support, manage different versions of binutils, mailwrapper profiles ...

Just run eselect to figure out what's available on your system.

eselect

For changing the kernel symlink do the following

eselect kernel list
Available kernel symlink targets:
  [1]   linux-2.6.21-gentoo-r4 *
  [2]   linux-2.6.22-gentoo-r1

The asterisk indicates your current symlink, eselect shows all available kernels, change to whatever kernel you like.

eselect kernel set 2

Use the same syntax for other eselect modules.

[edit] Security updates

You can use the utility glsa-check to perform security only updates. Running

glsa-check -f affected

You can run

glsa-check -p affected

[edit] depclean

After portage has finished updating, you may want to remove packages that are no longer needed. However, this process is known to fail at times, thereby horribly breaking the system. If you watch the process carefully and make sensible decisions, it shouldn't be that risky. Basically the idea is that all packages are checked whether they appear in your world file or as a dependency of one of the packages in your world file. If that is not the case, the package is - in theory - no longer needed. This assumption might break in certain cases: Imagine you have packages A, X, Y and Z. A depends on X and Y, but at compile time it detected the presence of package Z and compiles (optional) support for it in. Now it sort of 'depends' on the presence of Z even though its portage dependencies don't reflect that. Removing Z will now break A. The solution is to recompile A after removing Z.

We'll come to that, but for now - if you are courageous - run emerge -av --depclean. In my experience, you don't have to be that courageous. I run this command on a regular basis, and it has not caused much trouble. Make sure you check the list of packages that portage wants to remove before giving confirmation. The latter applies especially when you do a dependency clean for the first time (that is after your first world update and thus on a "fresh" system). Here, for example, it wanted to remove grub. If you find packages that you would prefer to keep on your system, you may use emerge --noreplace <atom> in order to add the given package to the world file (please check that this sentence conforms to the "Best practices" goal, and remove this notice).

emerge -av --depclean

[edit] revdep-rebuild

Now, after depclean has finished, some packages might be left broken as mentioned above. This is when you should use revdep-rebuild. It will check all binaries for missing libraries, figure out which binary belongs to which ebuild, and reemerge those ebuilds. If you use emerge -av --depclean, always do a revdep-rebuild afterwards.

revdep-rebuild

[edit] eclean

Finally, you might want to run eclean distfiles (eclean is also part of the gentoolkit) which will figure out if any of the distfiles in /usr/portage/distfiles are not longer needed and will free up some disk space in this way.

eclean distfiles

Congratulations! Your system is now up to date and cleaned from old cruft.

[edit] enotice

Regarding the emerge process in general you might also want to look into the utility enotice (http://www.fmp.com/enotice/). One of the things that have always baffled me about Gentoo is the fact that all of these important/helpful notes that ebuilds tend to display while emerging are buried in between compiler outputs. As if anyone would actually watch the screen all the time while emerging more than a few packages. Enotice logs all of these notes on a per-package basis and collects them for later reviewing.

Enotice won't be in portage, because it could do nasty things and the functionality has now been replaced by portage's elog feature. See also the forum discussion on enotice

[edit] Portage elog

Add the following lines to your /etc/make.conf:

PORTAGE_ELOG_CLASSES="info warn error log"
PORTAGE_ELOG_SYSTEM="save"

You can edit the CLASSES section to include only what you want. The logs are then placed in $PORT_LOGDIR/elog ( /var/log/portage/elog by default). Setting PORT_LOGDIR also saves the entire emerge output.

A good gui viewer to browse these logs is elogviewer.

emerge -av elogviewer

For further help on the elog functionality, please see /etc/make.conf.example.

[edit] eix-test-obsolete

From the man page:"eix-test-obsolete is a script which calls eix several times to display the output of eix -tTc in a more organized manner."

What it shows are non-matching entries, redundant entries, and uninstalled entries in /etc/portage/package.keywords, package.mask, package.unmask, package.use, and package.cflags. Also the names of all installed packages (with all installed versions) are checked to be in the database. The output of the following command should point you to changes that you can do to keep your /etc/portage/* clean.

[edit] Portage kernel modules

When you upgrade your kernel you need to also reinstall the kernel modules that you built from portage, for example nvidia-drivers, alsa-driver, and so on.

If you can't remember which kernel modules you built from portage or you just want a tool to manage them module-rebuild comes in handy. It's a simple tool with no man page or even --help just run it by it's self to see which options and actions it offers.

First, you'll need to install the package:

# emerge -av module-rebuild

Now you can run the command.

module-rebuild

Then get the modules rebuilt to work with your new kernel:

module-rebuild rebuild

[edit] make.conf

Some tips to organize /etc/make.conf:

• use comments
• split bash variables like USE and FEATURES into multiple lines

USE="${USE} acpi"       #hardware

#nVidia TNT2
VIDEO_CARDS="nv nvidia"

ALSA_CARDS="via82xx"

USE="${USE} apache2"

# generic

USE="${USE} bash-completion"
USE="${USE} emacs"

INPUT_DEVICES="keyboard mouse"

# distcc
FEATURES="${FEATURES} distcc"
MAKEOPTS="-j5"

FEATURES="${FEATURES} ccache"
FEATURES="${FEATURES} parallel-fetch"

USE="${USE} pic"                
USE="${USE} cjk"        #UTF-8 support

A make.conf like the one above allows you to toggle features as necessary. For example this user might want to disable distcc occasionally. To do this they simply comment out the 2 lines under the distcc section.

[edit] Dealing with Common Problems

[edit] Digest problems / Filesize does not match recorded size

When emerging, this is an error that is produced when an ebuild's digest is incorrect.

What is a digest? Digests are a method of checksumming a file to ensure that the file you download is the same one that the developers built against.

Why digest? Digesting helps to avoid a range of problems, including helping to ensure that the package will work as expected and that the file on the download server hasn't been tampered with.

Why does it fail? Digests can fail for a number of reasons. Frequently it indicates that the file on the server has changed since the developers added the package to portage (Sun packages are renowned for this, among others). However, don't be so quick to dismiss the failure - it could also be a sign that someone has maliciously changed the file on the mirror (real world examples include inserting a trojan (malicious program) into the download file).

How to solve it? Generally the problem is already known and the easiest thing to do is simply wait a few hours, run emerge --sync and try again. If that doesn't work, file a bug (after searching to check one doesn't already exist).

[edit] See also

• TIP Portage utilities not in portage - A LOT of interesting utilities and scripts for maintaining Gentoo