Gentool

Gentool is a command line tool to help manage the Gentoo OS (no relation to gentoolkit).

The main feature is the ability to instantly revert back to a previously working system if something goes wrong with an emerge. Portage is an excellent package manager but, even so, you will have occasional problems. Maybe a new version of an app isn't working properly, or maybe you can't even start X. When it does happen, sod's law says it will be at a time when you've got work to do and a deadline to meet.

Bootable backup partitions, as used by gentool, are the quickest, easiest solution to get up and running again. No time is wasted with rescue disks, hunting around for backup tarballs, or reinstalling files. Bootable backups are ready to go at a moment's notice. You're free to experiment with new software — even on a vital work machine — and, if it doesn't work out, you're guaranteed no down time.

Gentool also has one or two other functions intended to simplify basic system tasks such as rebuilding a kernel, fixing the broken system, et al. The full command list:

Requirements

Ideally you will also have moved large data dirs such as /home, /var/www, or /var/mysql onto their own partitions. OS, apps and data differ greatly in size and have different rates of change — hence they need different backup schedules. Partitioning schemes can assist this.

Note that, although this is the kind of setup which plays well with gentool, it doesn't insist on a strict separation between OS/apps and data. However, if you mix up data and OS/apps, there are a couple of things to watch out for (explained in the config file /etc/gentool/config.sh).

Install

First you'll need to install layman. See Gentoo Overlays User Guide.

Note that in future when you "emerge --sync" you should also "layman -S" to update your layman overlays.

Next, add the underlay overlay:

$ layman -a underlay

You need to edit package.keywords so that portage can install gentool. For example, for x86:

$ echo "app-admin/gentool  ~x86" >> /etc/portage/package.keywords

Now you can emerge gentool:

$ emerge -av gentool

Finally, you'll need to edit /etc/gentool/config.sh. Just read the instructions in the file. Carefully.

$ nano /etc/gentool/config.sh

Did you read all the instructions carefully? Well alright then.

Getting Started

The info command shows the active and backup partitions:

$ gentool info

 /boot/ active: /dev/sda1 --> inactive: /dev/sda3
 /      active: /dev/sda2 --> inactive: /dev/sda4

It's a good idea to run this after installing gentool. The script will carry out some sanity checks and will try to warn you about any configuration problems.

You can mount all the OS & apps partitions with one command if you need to do some kind of maintenance task:

$ gentool mount

The active /boot partition will be mounted as per /etc/fstab. The backup root and /boot partitions will be mounted on /mnt/gentoo and /mnt/gentoo/boot respectively.

Unmount them all:

$ gentool unmount

Someone's bound to try some time, so this works as well:

$ gentool umount

Updating OS & Apps

Prior to an emerge world, do a backup (as root or sudo):

$ gentool copy

Note that subsequent copy commands will only copy what has changed.

Now for the latest package updates:

$ emerge --sync && layman -S && emerge -auND world

If something isn't working after the emerge, we can immediately switch to the last working system:

$ gentool switch

Gentool will do most of the switching behind the scenes but you'll also have to manually update the MBR with a couple of grub commands. A message is printed to explain how to do this (the numbers may be different on your system):

To switch to the inactive disks you must manually update the MBR:

$ grub
grub>root (hd0,2)
grub>setup (hd0)
grub>quit

Once you've finished with grub, reboot:

$ reboot

..and now you're up and running again with a fully-functional system :)

The next task is to try to fix the problem.

You can switch back and forward between the active/backup partitions at any time with the "gentoo switch" command.

Often it's easier to stay in the known working system and chroot into the broken one. If you can't remember all the details, gentool has a convenient command for that:

$ gentool chroot

Note that switch breaks the backup cycle. You now have two system versions and eventually need to choose which one you want to keep. Hopefully you'll manage to fix the software problems but, if not, you'll have to abandon the updates.

The procedure is the same in either case: all you have to do is boot from the system you want to keep and then start doing gentool copy's again to back it up.

The gentool copy command always copies the active partitions, whatever they might be, to the inactive ones. Anything on the backup partitions will be overwritten.

The first copy after a switch always starts a new backup cycle. The system you chose to discard will be overwritten with a backup of the one you chose to keep, and this backup will be refreshed with each subsequent copy.

Choose wisely: gentool cannot stop you overwriting a vital backup with a broken system, or a repaired system (which you just spent a couple of hours fixing..) with an older, disposable backup.

Finally, note that the copy command has a "pretend" option which will list the files to be copied without actually copying anything.

$ gentool copy --pretend

Also a "dest" arg to copy the system files anywhere you like, including network paths like "foo@bar:/path/to/dir" (it's rsync under the bonnet).

$ gentool copy --dest="/path/to/dir"

Building a Kernel

Gentool can help build a new kernel by automating as much of the process as possible. For example, many people will have modules to rebuild and so "module-rebuild rebuild" will be run. See http://www.gentoo.org/doc/en/kernel-upgrade.xml for info how to set this up.

You may want to do a backup first, if you think you might need to revert back to a working system:

$ gentool copy

Now run gentool kernel and simply follow the instructions printed on screen:

$ gentool kernel

Other Commands

Gentool can update the system clock from whichever webserver you named in the config file /etc/gentool/config.sh.

$ gentool clock

If you're too lazy to type: "layman -S && emerge --sync && emerge -puND world" just enter an easier-to-remember:

$ gentool sync

Or if you want to find something in portage (same as "equery list -i -o -p *foo*"):

$ gentool find foo