Warning Livedoc is no longer being updated and will be deprecated shortly. Please refer to https://documentation.tjhsst.edu.

Gentoo Workstation Image

From Livedoc - The Documentation Repository
Jump to: navigation, search


  • The lab's workstations now run the Gentoo distribution of GNU/Linux. Prior to May 2007 they had run Debian.
  • SystemImager is used for installing and updating the systems. The "golden client" is Boson, a Sun Ultra 24 workstation from the '07-'08 AEG. It has an Intel Core 2 Quad processor and probably emerges stuff as fast as hydrogen could apt-get stuff.
  • The current image server is running "bare metal" on logan, a sparc server. Running it as an LDOM (VM) was not possible because (?? there was a reason that I don't recall). "imageserver" should always work either as an alias (cname) or a service IP.
  • The current workstation administrators are Tom Georgiou and Chris Reffett.


  • Golden client history:
    • meson: Sun Ultra 24; current golden client, was used to develop the 64-bit image, which is now the only workstation image in production.
    • boson: Sun Ultra 24; imaged from jett; was the 32-bit image. No longer produces images.
    • jett: Guitarist; chosen for its large hard drives; installed from clapton image when clapton got flaky
    • clapton: '07-'08; Guitarist; installed by Andy Street. Also had testing images including Fedora.
    • deuterium: old Gateway box - former Element?; pun on hydrogen. Installed by Jacob Welsh. See below
    • tess: '06-'07; Tragic Hero; Debian image; installed or at least maintained by Lee Burton
    • hydrogen: '05-'06; Element. Administered by Alfie Parthum and other '06 admins (??)
  • Trivia: Due to the general lack of communication in the 2006-2007 school year, there ended up being two Gentoo images: deuterium, created by Jacob Welsh '08, and clapton, created by Andy Street '07. Deuterium (one of the old Gateways) had been in development longer and was more fully configured for the syslab; clapton was the officially sanctioned image. The conflict was resolved by a coin toss, and the deuterium customizations were quickly merged into the clapton image.
  • Image server history:
    • logan, a sparc server from the '07-'08 AEG. Slowish disks and no chrooting (sad), but gigabit ethernet (happy). SystemImager directories migrated from planck into /big/imageserver and symlinked appropriately.
    • planck, an OpenVZ-based VM on King. Set up by Jacob Welsh and Michael Lowman for the deuterium image in 2007 after a period of not having an imageserver.
    • King was formerly the lab's image server, however it had disk/IDE failures following a power outage and was redeployed as a VM server (2006-2007).


A changelog is maintained on the image at /usr/csl/etc/changelog. Check there to see if a change you requested has been implemented, or if you just want to stay informed. Major changes should be posted here.

I (jwelsh) updated this rigorously in my time as the workstation admin (clapton/deuterium/jett/boson image). It might serve as a good reference for 'how-to-fix-XYZ-random-problem-that-came-up-again' or 'how-he-did-that-nifty-thing'. It might also provide an interesting view of senioritis if the timestamps are somehow plotted ;)

Tips & Tricks

Gentoo is a very admin-friendly distro (i.e. easy to customize in a clean way). The more you learn about Portage, as well as Unix/Linux in general, the more you can improve things. Some intermediate to advanced topics that are useful to understand:

  • revdep-rebuild (part of gentoolkit). Not really advanced, but listed here because you absolutely must know it. When a library is updated to a version with ABI changes, all binaries built against it break and must be rebuilt. This is both a pro and con of a source-based distro: maintainers don't have to worry about maintaining ABI compatibility, but it sucks for you (and your users) if you forget to revdep-rebuild. After every system/world update is a good habit to get into.
    • Note: it can sometimes get confused and think something is broken when it isn't, and rebuilding won't help. In this case, do "revdep-rebuild -- -pv"; it will give you the breakage listing and then you emerge as you see fit. Don't forget the --oneshot or -1 flag, to avoid polluting your world file.
  • /etc/portage/package.{use,keywords,mask,unmask} are the package-specific controls for USE flags, keywords and masking. They are your friends. They use "package atoms" which are fairly straightforward; they unambiguously indicate packages and versions, and can be inequalities (=, >=, >, <=, <) or use slots (=foo/bar:2 instead of >=foo/bar-2.3.5)
  • Overlays (/portage-overlay) are an easy way to revert upstream (Gentoo) changes that you don't like, apply patches that aren't yet in Gentoo, or add new packages. You will want to mask the non-overlay packages, and merge your overlay if a new version comes out.
    • Standard overlays (hosted by gentoo but still unofficial use-at-your-own-risk) are in /usr/portage/local and are fetched by "layman".
  • eix: a fast, C, indexed, colorful, regexp-enabled search tool for portage. Absolutely indispensable.
  • q (portage-utils): A set of nice utilities. Just use "q" to get a listing. My favorites, along with their rough Debian equivalents: qlist (dpkg -L), qfile (dpkg -S), qsearch (like eix but more compact output), qlop (wonderful for answering the question "when or why did XYZ break?")
  • equery (part of gentoolkit): mainly useful for the "depends" subcommand, which searches for reverse dependencies (what depends on this?)
  • euse (part of gentoolkit): quickly answer the question "what does this USE flag do?". Hopefully you get something more helpful than "the foo flag enables support for foo". Using this judiciously along with emerge -av/pv is a powerful customization habit. Can also do things like "Enable this USE flag for me!" without the massive effort of vimming /etc/make.conf.
  • Binary packages. Gentoo can build (and install, with all the file tracking capabilities of Portage) .tbz2 packages for you. Can be nice for building stuff on a fast box and quickly deploying on a slow box, or installing stuff quickly from a script such as when a different version is needed (nvidia drivers come to mind). They live in /usr/portage/packages. Commands you should know: emerge -b/B, emerge -k/K, quickpkg.
  • ELOG: enable these options in make.conf to enable logging of the more important messages produced by ebuilds to /var/log/portage. Useful if you don't want to sit around while stuff builds but still don't want to miss important information (or if it scrolled by too fast).
  • Config file protection. All files in directories listed in $CONFIG_PROTECT (but NOT in $CONFIG_PROTECT_MASK) will not be overwritten by new versions etc. Usually you can just use the new version; sometimes the changes are trivial and you want to keep your customized version; sometimes it's changed a lot and you need to merge the versions. I recommend dispatch-conf for this task; it's a bit smarter that etc-update (and keeps an archive of old versions; not sure if etc-update does).
    • CONFIG_PROTECT and CONFIG_PROTECT_MASK are defined in /etc/make.globals and possibly other places; you can add to them in make.conf.
  • Environment variable management. This is a very nice Gentoo feature; no more mucking around with /etc/profile and such wondering if your changes will really take effect.
    • Variables are grouped together in prioritized files in /etc/env.d, and accumulate across files. (think PATH and ROOTPATH). Running "env-update" will parse these files and put the results into /etc/profile.env and /etc/profile.csh, which are in turn sourced by the appropriate shell startup files.
    • Caveat 1: /etc/env.d is in CONFIG_PROTECT_MASK so you may lose any customizations you make to preexisting files. AFAIK the only way around that is to violate the instructions and edit /etc/make.globals.
    • Caveat 2: There are some situations where the environment files won't be sourced no matter what, i.e where there is no shell involved. For example, in "ssh foohost barcommand", barcommand may not be found since PATH is entirely at the mercy of sshd.

You see? It's really quite simple!

CSL Customizations

Gentoo packages tend to be rather "stock"; that is to say, Gentoo developers customize only in the form of patches and configure/make flags (abstracted to the sysadmin as USE flags), as opposed to binary systems which are often heavily customized by the distributor, either for interoperability among packages or to accomodate someone's twisted notion of how things should be done. This can be both a good and bad thing. Recall Debian's OpenSSL disaster, or the debacle with Firefox/Iceweasel. You will find more inconsistencies between packages and annoying defaults on Gentoo. Take the time to figure them out and fix them, and Gentoo will likely end up fitting your needs far better than a prebaked binary system.

The changelog is a good place to find all the gory details of Syslab customization (at least under the jwelsh regime); discussions about how to resolve some of the more complex issues can be found on Bugzilla. Here are some of the most important ones, including potential show-stoppers, Really Neat Stuff, and things you will likely run into again at some point as packages update (or if a new image is created). Some of this will also be useful for non-CSL Gentoo systems, and even other distributions.

[note: this is currently a 'top-of-my-head' list, and needs to be fleshed out and expanded.]

  • GDM scripts and default sessions (there are many locations). Neglect this and users could get TWM'd or GNOME'd, both of which occurrences are verrry baaaad.
  • Terminfo and configuration for xterm and other $TERM types -- see bugzilla. Bad things can happen, like ^? or ^H getting printed instead of text getting deleted.
  • XTerm settings, controlled via X resources, preferably in app-defaults (although gnome can do yucky things with overriding these). My "ideal" minimal set of xterm customizations, arrived at after plenty of trial and error and a bit of research (presence of the XTerm prefix depends on where you put them):
 XTerm*background: black
 XTerm*foreground: white
 XTerm*altIsNotMeta: true 
 XTerm*altSendsEscape: true
 XTerm*metaSendsEscape: true
 XTerm*backarrowKey: false    ; NOTE: ncurses terminfo should be edited accordingly
 XTerm*scrollKey: true
 XTerm*scrollTtyOutput: false
  • Fluxbox menu -- Debian's method is really the only sane thing to do
  • Bash completion -- in addition to the standard tab completion for program and file names, bash can load completion scripts to do "smart" completions. Examples include simple things such as restricting filename completion to files associated with the program in question; more advanced things like available man page name completion, program options completion, or "make" target completion; to wild (and possibly slow) completions like package names for emerge or remote file listings for scp (yes it really does, if you have publickey or gssapi working).
    • Gentoo: install bash-completion and put "source /etc/profile.d/bash-completion.sh" in /etc/bash/bashrc
      • package-specific completions: USE +bash-completion, along with "eselect bashcomp ..."
    • Debian: install bash-completion and put "source /etc/bash_completion" in /etc/bash.bashrc or possibly /etc/profile
    • Caveat: Some completion routines can be slow; you probably don't want to enable this on really old machines
  • Vim syntax highlighting, etc. -- colorscheme, set background=, filetype plugins and indent
  • Emacs syntax highlighting -- it's called 'font-lock-mode' IIRC, needs to be enabled via yucky lisp customizations, doesn't support many file types (out of the box), and doesn't work too well. Nobody loves Emacs in these parts anyway. Don't worry about it. Just thought I'd mention it.
  • Totem overlay to use Xine backend (the one that actually works)
  • More stuff that I'll add later
  • Fun stuff like /etc/issue, /etc/motd, tty10-12, XDM and backdrops

NOTE: This doesn't cover the CSL imaging system, a bunch of homegrown scripts living in /usr/csl. That is documented in SystemImager.