Administrate Your Gentoo System

This document is not meant to become a generic Gentoo administration guide, but more to collect a few tricks specific to the usage of the distribution on a Kurobox. For a more general documentation, please refer to the official documentation, in particular:


 * Part II of the Gentoo Handbook
 * The excellent Gentoo security guide
 * The Gentoo Samba howto, and many other specific guides.

Customize Your Environment
Now is a good time to set up your Linux environment. We're going to configure some global Gentoo settings so that all users will benefit. Individual users can customize their own settings using the .bashrc file in their home directory.

First off we will configure our default text editor. This will be the editor used by tools such as  . To set the default editor, change the  variable in the /etc/rc.conf file:

EDITOR="vi"

Gentoo defaults to   as the editor, this is a simpler editor than vi and should be used if you've not worked with vi/vim before.

You may also want to configure the root shell to use colour. To do this, copy everything from /etc/skel to root's home directory. When creating new users, the   command will create a home directory and copy these files for you if you specify the -m option.

Finally, we'll set up a few aliases to make life easier. You can add these lines to your ~/.bashrc file and they will only apply to you. If you want these aliases to be set for all users, you can create a /etc/profile.d folder and put these settings in a file called aliases (or whatever you like) in there.

alias c=clear alias r="fc -e - " alias h="fc -l"

These aliases allow you to use   to list recent commands and   to repeat them (  repeats the last,   repeats the last command beginning   and   repeats command number   from the   output).   clears the terminal window.

Keep Gentoo Up-to-date
One of the advantages of using the Gentoo distribution is it's package management system known as portage. You used this before when you first installed, but it's always a good idea to continue to keep your system up-to-date with the latest stable ppc packages (and non-stable ~ppc packages if you are adventurous!).

Use the following command to update your portage tree. This will synchronize the portage tree with an official Gentoo mirror, and let your system know what is the status of the latest packages. You can run this as a cron job, or manually when you've got some time. emerge --sync Once you've done this, you can update any packages that need to be updated. You can use the command below to do that. A description of what the switches do (from  ) is listed below that. emerge -uNDv world
 * : Updates packages to the best version available, which may not always be the highest version number due to masking  for  testing and development. This will also update direct dependencies which may not be what you want. In general, use this option only in combination with the world or system target.
 * : Tells emerge to include installed packages where USE flags have changed since compilation. An asterisk marks when a USE flag has changed since the package was compiled.
 * : When used in conjunction with --update, this flag forces emerge to consider the entire dependency tree of packages, instead of checking only the immediate dependencies of the packages. As an example, this catches updates in libraries that are not directly listed in the dependencies of a package.
 * : Tell emerge to run in verbose mode. Currently this flag causes emerge to print out GNU info errors, if any, and to show the USE flags that will be used for each package when pretending.

Install Binary Packages
Project Gentoo on the Kurobox will try to provide up-to-date binary packages for some commonly used applications that take a long time to build, such as net-www/apache, dev-db/mysql, etc. Using binary packages may seem like an unusual practice for a Gentoo system, but it is actually very simple. In /etc/make.conf, declare the hosts of binaries you want to use: PORTAGE_BINHOST="http://tdegreni.free.fr/kurobox/packages/"

Then, when you want to emerge a binary package instead of compiling from the source, use the -g switch. For example:
 * 1) emerge -g dev-db/mysql

If a suitable binary is not found, emerge will fallback to installing from the source code. If you only want to accept binary packages, use the -G switch instead of -g. Finally, if you want emerge to always try to get a binary prior to compiling without having to use the switch every time, add   to FEATURES in /etc/make.conf.

[TODO: pros and cons of binary packages, relation to USE flags, etc.]

--Jkk 09:29, 10 July 2006 (CDT) The last update to the PORTAGE_BINHOST was made March 6th, 2006.

The power/reset buttons explained
Your Gentoo system has a special setup for the power (the one in front of the box) and reset (the small one on the back) buttons:
 * to shut down your box, press the front button for ~6 seconds. That will do a "shutdown -h now".
 * to reset your box, push the front button twice in less than 3 seconds. This will do a "shutdown -r now".
 * to reset your box in EM mode (in case of troubles), press the back button for ~6 seconds.

For technical details about this feature, check the Survive without ppc_uartd page.

Set Your Timezone
The first thing to do if the your Kurobox's system time is important to you is to set the timezone. This is as simple as creating a symlink to /etc/localtime from the right place. Timezone files are stored in /usr/share/zoneinfo. You will need to search around for the appropriate file to link from.
 * 1) ln -sf /usr/share/zoneinfo/Europe/Paris /etc/localtime

Set the Hardware Clock
The hardware clock in the Kurobox may be set to Japanese time, so the system clock will be adjusted each time Gentoo boots. To fix this, set the hardware clock using /sbin/hwclock:
 * 1) /sbin/hwclock --set --date="12/31/2007 18:13:00"

Alternatively, you can edit /etc/conf.d/clock so the hardware clock is set during shutdown - this should work well when combined with a running ntp client: CLOCK_SYSTOHC="yes"
 * 1) /etc/conf.d/clock

Install NTP
NTP (Network Time Protocol) is a protocol that synchronizes the system clock with other servers. Once configured, your Kurobox will always stay perfectly on time, and can also serve as the primary time server to other machines in your network. A net-misc/ntp binary package is available, so you can use  . We recommend you read HOWTO NTP from the Gentoo Linux Wiki for configuration instructions.

Recommended Packages
After the initial installation, your system will be very minimalistic. Here are a few packages that are not necessary for Gentoo to function, but we recommend you install them.

Log Daemon
The original author of this article personally prefers app-admin/syslog and has made this available as a binary package. However, the author also mentions that app-admin/metalog is worth a try.

Once you've installed and configured your log daemon, remember to add it to the default runlevel: To complement this, and to avoid having your /var/log growing enormously large, use app-admin/logrotate to rotate, compress, and/or mail log files to you. You should add this as a cron job.
 * 1) rc-update add syslog-ng default

Task Scheduler (cron daemon)
If you would like to automate scripts to run at certain times, you will need a cron daemon. We suggest you try sys-process/fcron; it can understand traditional crontabs (à la vixie-cron and friends), but adds many other useful features and does not require your Kurobox to be on twenty-four hours a day. This should also be added to the default runlevel.

/tmp Cleaner
Just like your system logs, you will want to keep your /tmp directory size under control. You can use app-admin/tmpreaper.

Kernel modules
Depending if you are using a Kuro or a Kuro/HG, the compiled kernel modules are in two different packages: sys-kernel/modules-kurobox sys-kernel/modules-kurobox-hg You probably want to install one of this package. I've not much looked at the old Kuro ones, but the HG ones for instance add the generic scsi driver (which i think is required for mounting usb devices), more filesystems, more NLS encodings, etc. If there are there some modules you want loaded on boot, add them to /etc/modules.autoload.d/kernel-2.4, and run  .