Common Tasks

What follows is a list of common tasks that can be executed on a Gentoo Linux system. Although they will surely become routine fairly soon, since they are called “common”, it will take some time - hence this reference. Included here are tasks like emerging, unmerging, updating the system, etc. Hopefull they will proove usefull.

Installing applications/packages under Gentoo GNU/Linux is fairly easy. The package management system of Gentoo, called Portage, contains most packages that you would ever want to install. You then use the emerge command to install ( or “emerge” in Gentoo-speak) the desired package. Should, however, the unlikely case enter that a package is not found in the Portage, it is still possible to install it in Gentoo, although it becomes a bit more complicated.

If the required package is part of the Portage tree then all you need is the emerge command and the exact name/location of the package. While in most cases a simple emerge <package_name> will suffice, it can happen (if e.g. two packages share the same name) that you will be required to enter the complete Portage tree path. But for cases like these there is always the internet and the homepage of the package developer of the grep function of Gentoo enabling you to search the Portage directort for the package name and then choosing from the list which one you were looking for. (add exact command to search portage dir for packages !)

However, it may be unwise to start emerging packages without having a look at their dependencies. Remember the USE flags we set in during installation? (link to install page !) They determine which dependencies of a package are permitted to be installed. Some applications will break if not all of their dependencies are emerged as well and if your USE flags prevent their installation, your application will not work. It is therefore recommended to run emerge always with the –verbose and –ask options enabled: –verbose to have all dependencies that need to be emerged written out on screen and –ask to force an explicit check from the system where it asks you if you want to continue.

emerge --ask --verbose <package_name>

!

–pretend would be another option, very similar to –ask, since emerge would only test and showcase the dependencies it would install, but upon a repreted emerge call (this time without the –pretend option) it would have to calculate the dependencies for the application once again, which it does not have to do when using –ask. The calculation of dependencies can sometimes be the most time consuming part of the emerge process.

Furthermore, to streamline the emerge process can all options like –ask, etc. be used in their shorthand notation, i.e. -a instead of –ask and -v instead of –verbose. In addition, these shorthand versions can be added together to form a single option, creating the final emerge call that is to be used in Gentoo GNU/Linux:

emerge -av <package_name>

Most linux programs are also offered as source-tarballs (tar.gz or tar.bz2). If you want to install a program that is not available through portage, you can simply download this source tarball, unpack it, and then compile & install it yourself (see below). The disadvantages to this method are that portage doesn't lend you a hand in searching & automatically installing updates, and that those self-compiled programs usually don't (automatically) respect your USE-flags (you have to do this manually).

For this examle we want to compile the latest stable CVS snapshot of Ruby. First we need to get our tarball:

wget ftp://ftp.ruby-lang.org/pub/ruby/stable-snapshot.tar.gz

Next we unpack it. Since it is compressed using gzip, we can decompress it with tar in one go:

# 'x' means 'decompress', 'z' means that the tar-archive is gzip'ed, and 'f' tells tar that we want to unpack from a file
tar -xzf stable-snapshot.tar.gz

It is important that the f-parameter comes last, since tar expects the filename after it.

Now you should see a ruby folder. cd into it, and run ./configure –help=recursive to get a list of all the optional features and packages of Ruby. For this example, we want to build a shared library along with our binary, so we run configure with the appropriate arguments:

./configure --enable-shared

This will generate a lot of output and may take a while. After configure has finished, we can build Ruby:

make

This step will most likely take even longer than configure. After make has finished doing its work, we should run make test to ensure the binary works correctly:

make test

Note that not all programs offer this option, so if make tells you that it can't it doesn't have a rule for test, then that's okay. Also, some programs require a special setup to run their tests (e.g., a database with some tables in it, or such), which you probably won't have. It is best to check the README to find out wether you can (or should) run make test.

If all tests go according to plan (which make/ruby tells us by simply printing test succeeded), we can proceed to install ruby. This step *must* be done as root:

make install

This will copy all relevant files to their appropriate places (e.g., the binary to /usr/local/bin, etc.). After that, ruby is ready to use, which we can check by typing ruby -v. Ruby will answer with its version, builddate and architecture.

And that's it! Most other programs will follow along this line, but may require minor tweaks. These things are almost always documented in the INSTALL and/or README files, so be sure to check those right after unpacking the tarball.

There are two ways of uninstalling applications and packages under Gentoo. The first, official way, is to use an option of the emerge command called –unmerge, which removes the desired package from the system. However, the package's dependencies and prerequisites still remain within the system and need to be removed. The option –depclean of emerge takes care of that, but it is still possible that some dependencies will be “overlooked.”

emerge --unmerge <package_name>
emerge --depclean

The second and recommended way of removing an application from the system showcases Gentoo's openness. All settings in Gentoo are kept within plain text files and this applies to the installed applications as well. All packages that were explicitly emerged can therefore be found in /var/lib/portage/world. To remove a package from the system, simply delete its name from this file and clean-up using emerge.

<delete package_name from /var/lib/portage/world>

emerge --clean && emerge --depclean
revdep-rebuild

Any Linux system needs to be kept up to date in order to function properly. Moreover, the portage (= the program repository of Gentoo) needs to be regularly updated as well. It is good practice to update your system at least once a week - some people do it even everyday. The more frequently you update, the shorter will each update take ( But the more stress will be put on the update servers. Updating daily isn't really recommended, updating every few days should work just fine, unless you need a specific update right now). If you update each day, every update will be done in a couple of minutes. If, however, you update only once a month or so, the update may take hours.

If you are updating your untouched system for the first time since the install it would be prudent to emerge eix, which is a small program that synchronizes your portage and displays the changes after its done (in color, nonetheless). Basically eix synchornizes the portage by using emerge -sync and works as a replacement for it. So, first you have to emerge eix and than use it to sync your portage:

emerge eix

eix-sync

After the portage has been synced, it is time to emerge all updates:

emerge -auD world

As previously explained are auD short terms for longer parameters, in this case you are telling emerge to ask you before it updates all installed packages (world) and do a deep update, i.e. emerge all new dependencies for any programs you might have. During the process several configuration files will need updating. To not lose your precious changes and configurations, use dispatch-conf instead of etc-update to resolve the conflicts between your configuration files and the newly emerged default files, since it shows you the changes it is about to merge.

dispatch-conf

Once all updated configuration files were merged and checked (incl. the eventual kernel update), you may reboot your system. That basically takes care of it - your system is now up to date.

eix should also tell you if a new Linux kernel is available and was downloaded and installed (just like any other package). It doesn't happen very often, but should this be the case then you will need to configure and compile the new kernel. Gentoo provides a useful guide to help you. The kernel will be located in /usr/src/ as linux-#.#.##-gentoo-r#. Moreover, the kernel configuration file (i.e. the text file you edit when using make menuconfig) is also located in /usr/src/linux/.config. You will want to change into this directory since there is some work to be done there and you will probably want to emerge the new kernel:

cd /usr/src

emerge -au gentoo-sources

Unless you have symlink installed or set as a USE flag, you will need to update the symbolic link /usr/src/linux to your new kernel found under /usr/src/linux-#.#.##-gentoo-r#. You can do this with the following:

ln -sfn linux-#.#.##-gentoo-r# linux

Now it is time to configure and compile the new kernel. First, you need to change to the kernel directory, copy the .config file from the old kernel's directory and then run make oldconfig instead of make menuconfig (as you did during the install). make oldconfig takes your current kernel configuration and maps it to the new kernel, asking you a couple of questions in the process. The default answers are usually OK. And then finally you may compile the new kernel:

cd /usr/src/linux

# % depicts the old kernel number
cp ../linux-%.%.%-gentoo-r%/.config .

make oldconfig

make && make modules_install

Moreover, all external modules, such as ALSA or graphics drivers, need to be re-emerged in order to work with the new kernel. Gentoo offers a nice utility which takes care of that called module-rebuild. After the compilation of the new kernel this utility first needs to be emerged (if this is the first time running it), then populated so it will know which external modules are present and need to be re-emerged and finally told to update the modules.

emerge sys-kernel/module-rebuild
module-rebuild populate

module-rebuild rebuild

Once this is done you need to mount your /boot partition in case it isn't always mounted and copy the newly compiled kernel image over. This step is identical to the one executed during the installation.

mount /boot
cp arch/i386/boot/bzImage /boot/kernel-#.#.##-gentoo-r#

Finally you need to expand your bootloader with the new kernel to be able to boot it. Since I used GRUB (it was default in the installation), I will be discussing the grub.conf here. First, open grub.conf using vi or any other editor of choice. Next, insert the new boot options into it:

vi /boot/grub/grub.conf

> title=Gentoo Linux #.#.##-r#
> root (hd0,0)
> kernel /boot/kernel-#.#.##-gentoo-r# root=/dev/hda3

Do not delete the old kernel entry as long as you are unsure that everything works! In fact, it would be prudent to keep it for as long as you can. As a last step you should unmount the /boot partition.

How do I get root access when using the LiveCD? - LiveCD's root password is scrambled during the boot process. You need to first login as a normal user and once you are inside the X window system, hit Ctrl+Alt+F1 to get to the console. The console user is root so all you need to do is type passwd and set you new root password. You can then switch back to the X system with Ctrl+Alt+F7 and use su to switch to the root user using your newly set password.

How can I get (root) control of my system when using the LiveCD? - first gain root access to the LiveCD. then mount the /root file system of the computer you try to get access to (in my case /dev/sda3 link-back to fstab creation during install). finally chroot into the environment

chroot /mnt/<system_root> /bin/bash
env-update
source /etc/profile
export PS1="(chroot) $PS1"

! http://linuxreviews.org/gentoo/ebuilds/

How do I ascertain (as root) which groups a particular user is in? groups <user_name>

How do I find which executable is being called when I type it in the shell? which <executable

How do I list all dependencies of a dynamic executable? ldd <executable>

How do I find something in the system? emerge slocate then locate <search_term>

How can I redirect STD::ERR to a file? on a per-call basis: execute.sh » /path/to/file 2&1 system-wide: exec » /path/to/logfile 2>&1

How do I list all loadable (not load*ed*!) kernel modules? modprobe -l

How do I list all currently loaded kernel modules? lsmod

If you can't stop an /etc/init.d/ process with stop or restart, use /etc/init.d/<process> zap