Gentoo - Deep System Upgrade

Gentoo’s update system is more flowing than a lot of other Linux distros. It’s up to you how often you’d like to do system maintenance; personally I like to do weekly or monthly updates so it doesn’t become too big of a job in the future.

We discussed a basic system upgrade in page two of the slice set up articles. The deep upgrade looks at all packages on the system and can re-emerge packages affected by changes to global USE flags.


The first part of the system upgrade is to update your local indexes to the ebuild files on the web. If you installed the ‘esearch’ ebuild as shown in page two of the slice set up articles, then to update your local indexes and the esearch cache at the same time, you’d run:

sudo esync

If you want to do it without the ‘esearch’ package you’d run:

sudo emerge --sync

Upgrade System Packages

The next step is to upgrade the low-level packages:

sudo emerge system -DNuvp

This command will show us what (if any) packages will be ‘re-emerged’ either because they have an upgrade available or because we have changed the USE flags since they were last installed.

The ‘-D’ flag means ‘deep’, the ‘-N’ flag means ‘re-emerge things if their USE flag options have changed’, and of course ‘-u’ means we’re updating, not re-emerging unnecessarily. All this information can be seen by running ‘man emerge’ and ‘man portage’.

Here’s a sample of my output (I’ve word-wrapped some of the lines):

[ebuild     U ] app-arch/lzma-utils-4.32.7 [4.32.6] USE="-nocxx" 469 kB 
[ebuild   R   ] sys-apps/tcp-wrappers-7.6-r8  USE="-ipv6*" 113 kB 
[ebuild     U ] sys-libs/gpm-1.20.5 [1.20.1-r6] USE="(-selinux)" 1,269 kB 
[ebuild     UD] app-editors/nano-2.0.9 [2.1.2-r1] USE="ncurses nls unicode -debug -justify -minimal
                                                       -slang -spell" 1,371 kB 
[ebuild     U ] sys-devel/autoconf-2.63 [2.61-r2] USE="-emacs" 1,527 kB 
[ebuild   R   ] sys-process/psmisc-22.6  USE="nls -X -ipv6* (-selinux)" 277 kB 
[ebuild     U ] sys-apps/acl-2.2.47 [2.2.45] USE="nls (-nfs)" 152 kB 
[ebuild  N    ] app-admin/eselect-1.0.11-r1  USE="bash-completion -doc -vim-syntax" 150 kB 
[ebuild  N    ] app-admin/eselect-news-20080320  6 kB 
[ebuild     U ] sys-apps/portage- [] USE="-build -doc -epydoc (-selinux)"
                                                   LINGUAS="-pl" 533 kB 
*** Portage will stop merging at this point and reload itself,
    then resume the merge.
[ebuild     U ] app-shells/bash-3.2_p39 [3.2_p33] USE="nls -afs -bashlogger -examples% -plugins
                                                       -vanilla" 2,582 kB 
[ebuild     U ] sys-libs/readline-5.2_p13 [5.2_p12-r1] 2,023 kB 
[ebuild     U ] sys-fs/e2fsprogs-1.41.3 [1.40.9] USE="nls (-static%)" 4,263 kB 
[ebuild  N    ] sys-libs/e2fsprogs-libs-1.41.3  USE="nls" 479 kB 
[blocks B     ] sys-libs/ss (is blocking sys-libs/e2fsprogs-libs-1.41.3)
[blocks B     ] <sys-fs/e2fsprogs-1.41 (is blocking sys-libs/e2fsprogs-libs-1.41.3)
[blocks B     ] sys-libs/com_err (is blocking sys-libs/e2fsprogs-libs-1.41.3)
[blocks B     ] sys-libs/e2fsprogs-libs (is blocking sys-libs/ss-1.40.9, sys-libs/com_err-1.40.9)

An explanation of this output is given in our previous article, or you can run the following for a full explanation:

man emerge

Typing ‘/OUTPUT’ (case sensitive) and hitting ‘enter’ will take you to the right place. To quit the ‘man’ program, you can just hit ‘q’.

If you see this at the end of your output; be sure to follow what it says:

* An update to portage is available. It is _highly_ recommended
 * that you update portage now, before any other packages are updated.

 * To update portage, run 'emerge portage' now.

Dealing with Blockers

Near the bottom of this example emerge output you’ll see some lines starting with ‘[blocks B ]’. These are packages that are blocking other packages from being emerged. How to deal with these is shown in this article.

Real System Emerge

Before doing the real upgrade, I always like to take a slice snapshot using the backups system and call it ‘b4_upgrade’. Of course I do recommend that you also keep your own off-site backups as well. More info on backups can be found here.

Check everything in the output matches your plans. Adjust your USE flags as required; this is covered in our previous article.

When you’re ready, you can do the full ‘real’ system emerge using the same command without the ‘vp’:

sudo emerge system -DNu

Updating the Configuration Files

Often times, after an upgrade of the libraries we’ll need to upgrade our configuration files too. Gentoo provides an excellent tool for this ‘etc-update’. This was discussed in page two of the slice set up articles . Have a look now then come back.

Emerge world

The “world set” references everything you’ve already installed on your Slice. It does include the system packages also; however I like to emerge system separately in case it brings in low level tools like gcc, that way packages emerged after that will be built using the newer tools.

Lets see what will happen if we try to upgrade ‘world’:

emerge world -DNuvp

I missed off the ‘sudo’ here on purpose; when using the ‘vp’ flags, sudo is not necessary.

Follow the same principles as with the system emerge. Make sure everything planned is to your liking and adjust your USE flags as necessary.

When ready you can do the ‘real’ world emerge by adding the ‘sudo’ and removing the ‘vp’:

sudo emerge world -DNu

Security Upgrade

Even though we’ve just updated everything, I always like to check with the Gentoo Linux Security Advisory. This is covered in page 2 of the set up articles.

Checking inter-package Links

There’s another great tool called ‘revdep-rebuild’. This is included in the ‘app-portage/gentoolkit’; so if you haven’t already, emerge that package before continuing.

‘revdep-rebuild’ checks all the installed software that it can find, looks for broken dependencies, then tries to fix them by [re-]emerging the appropriate packages.

It’s usage is similar to the other Gentoo tools; you can run it with ‘-vp’ first to see what it will do, then run it for real if required:

sudo revdep-rebuild

Restarting Services

When we emerge with ‘-vp’ it’s good to keep an eye on any daemons or services that are updated. Once the emerge has finished we should restart them to make sure nothing got broken. If you didn’t watch them go through you can see what was emerged in the emerge log:

sudo grep completed /var/log/emerge.log

To restart a service you can use:

sudo /etc/init.d/servicename restart

Where ‘servicename’ is the actual name of a daemon, for example ‘sshd’. If it doesn’t start up as expected, the first place to look for problems are in it’s log files in ‘/var/log’ there’ll usually be more information available in there.

For example to see why apache2 is not restarting, we could run:

sudo tail -30 /var/log/apache2/error_log

All Done

That’s it for the deep system upgrade. Next we’ll get into some higher level topics like setting up Apache and PHP.


Article Comments:

Tom commented Tue Dec 29 05:31:48 UTC 2009:

When I entered: iptables -A INPUT -d -i ! lo -j REJECT --reject-with icmp-port-unreachable

I get this error message: Using intrapositioned negation (--option ! this) is deprecated in favor of extrapositioned (! --option this).

Can I ask for a re-write on the phrasing? Thanks.

Want to comment?

(not made public)


(use plain text or Markdown syntax)