Please check out the Gentoo Wiki for
documentation, guides, howto articles and other information.

Important:
We are slowly moving our existing documentation to the Gentoo Wiki. If you do
not find a document here that used to be listed, it is most likely integrated in
the wiki, or already obsoleted by a wiki article.

2.
Gentoo Linux Documentation

Installation Related Resources

Installation Guides

Gentoo Handbook
The Gentoo Handbook is an effort to centralise documentation into a coherent
handbook. This handbook contains the installation instructions for
internet-based installation approaches and parts about working with Gentoo and
Portage.

Gentoo Linux x86 Quick Install Guide
The Quick Install guide covers the Gentoo install process in a non-verbose
manner. Its purpose is to allow users to perform a stage3 install in no time.
Users should already have prior experience with installing Gentoo Linux if they
want to follow this guide.

Gentoo Linux x86 with Software Raid and LVM2 Quick Install Guide
The Quick Install guide covers the Gentoo install process in a non-verbose
manner. Its purpose is to allow users to perform a stage3 install with software
RAID and LVM2 in no time. Users should already have prior experience with
installing Gentoo Linux if they want to follow this guide.

TeX Live 2008 guide
This guide aims to show you how to install TeX Live 2008 on Gentoo,
more specifically what you need to take care of if you already have a
TeX distribution installed (like tetex or TeX Live 2005).

Gentoo System Documentation

Portage and Related Documentation

A Portage Introduction
This chapter explains the "simple" steps a user definitely needs to know to
maintain the software on his system.

Portage Features
Discover the features Portage has, such as support for distributed compiling,
ccache and more.

Working with Portage
"Working with Portage" provides an in-depth coverage of Portage, Gentoo's
Software Management Tool.

USE flags
USE flags are a very important aspect of Gentoo. In this chapter, you learn to
work with USE flags and understand how USE flags interact with your system.

Environment Variables
With Gentoo you can easily manage the environment variables for your system.
This chapter explains how you do that, and also describes frequently used
variables.

Initscripts
Gentoo uses a special initscript format which, amongst other features, allows
dependency-driven decisions and virtual initscripts. This chapter explains all
these aspects and explains how to deal with these scripts.

Troubleshooting Apache
This document covers a number of ways to figure out how to fix your Apache
installation when things are not working correctly.

Upgrading Apache
This document describes the procedure end-users should follow to safely
upgrade their apache installation.

Gentoo Development Documentation

Gentoo Development Policies

Gentoo Linux Documentation Policy
This document contains the Gentoo Documentation Policy, which is the
base document which all Gentoo Documentation developers and
Contributors should know and exercise.

Gentoo Devmanual
The Gentoo Devmanual is a technical manual for developers which covers
topics such as writing ebuilds and eclasses, and also covers policies
that developers should be abiding by.

Gentoo Developer Handbook
This is the Gentoo Developer Handbook, a continuing effort to
centralize development policies across Gentoo and to also outline
Gentoo's development systems and procedures.

Gentoo GuideXML Guide
This guide shows you how to compose web documentation using the new lightweight
Gentoo GuideXML syntax. This syntax is the official format for Gentoo
documentation, and this document itself was created using GuideXML. This guide
assumes a basic working knowledge of XML and HTML.

Gentoo Embedded Handbook
The Gentoo Embedded Handbook is the center point for all Embedded work done
with Gentoo. It aims to cover just about all aspects of the process -- from
theory to design to practice.

Gentoo Developer Handbook
This is the Gentoo Developer Handbook, a continuing effort to
centralize development policies across Gentoo and to also outline
Gentoo's development systems and procedures.

Documentation Project Documentation

Gentoo Linux Documentation Policy
This document contains the Gentoo Documentation Policy, which is the
base document which all Gentoo Documentation developers and
Contributors should know and exercise.

Translators Howto for Gentoo Documentation
A frequently asked question is how to become a translator and what actions
should be performed both to become one and to act as one. This document tries to
explain all this.

Gentoo Metadoc XML Guide
This guide informs developers how to use the Metadoc XML format that allows the
Gentoo Documentation Project to keep its documentation in a hierarchical manner
and allow more information to be stored about each document.

Making the distribution, Part 1
Each of us has a story to tell about our experiences with Linux. This is
Daniel Robbins' Linux story. In this first of three articles, he talks about
how he became a Stampede Linux developer, and why he eventually left Stampede
to start his own distribution called Enoch.

Making the distribution, Part 2
In his previous article, Daniel Robbins told the story of how he became a
Stampede Linux developer and why he eventually left Stampede to start the Enoch
Linux distribution. In this go-round he lets you in on the strange events that
happened after the Enoch development team discovered a little-known, blazingly
fast compiler.

Making the distribution, Part 3
This article concludes his story -- about how he ended up creating his own
distribution called Gentoo Linux. He wraps up the series by telling how he
left the Linux world to move to FreeBSD, and then came back to the Linux world,
restarting Gentoo Linux development with a fresh perspective. In addition to
comparing Linux and FreeBSD in a number of areas, he also describe current
Gentoo Linux development progress and share a future vision for the
distribution.

Learning Linux Articles

Bash by example, Part 1
By learning how to program in the bash scripting language, your day-to-day
interaction with Linux will become more fun and productive, and you'll be able
to build upon those standard UNIX constructs (like pipelines and redirection)
that you already know and love. In this three-part series, Daniel Robbins will
teach you how to program in bash by example. He'll cover the absolute basics
(making this an excellent series for beginners) and bring in more advanced
features as the series proceeds.

Bash by example, Part 2
In his introductory article on bash, Daniel Robbins walked you through some of
the scripting language's basic elements and reasons for using bash. In this, the
second installment, Daniel picks up where he left off and looks at bash's basic
constructs like conditional (if-then) statements, looping, and more.

Bash by example, Part 3
In his final Bash by example article, Daniel Robbins takes a good look at the
Gentoo Linux ebuild system, an excellent example of the power of bash. Step by
step, he shows you how the ebuild system was implemented, and touches on many
handy bash techniques and design strategies. By the end of the article, you'll
have a good grasp of what's involved in producing a full-blown bash-based
application, as well as a start at coding your own auto-build system.

LPI certification 101 (release 2) exam prep, Part 1
In this tutorial, we'll introduce you to bash (the standard Linux shell), show
you how to take full advantage of standard Linux commands like ls, cp, and mv,
explain inodes and hard and symbolic links, and much more. By the end of this
tutorial, you'll have a solid grounding in Linux fundamentals and will even be
ready to begin learning some basic Linux system administration tasks.

LPI certification 101 (release 2) exam prep, Part 2
In this tutorial, you will learn how to use regular expressions to search files
for text patterns, how to locate files on your system, and how to take full
control of Linux processes. You'll even get a whirlwind introduction to shell
pipelines, redirection, and text processing commands. By the end of this
tutorial, you'll have a solid grounding in basic Linux administration and will
be ready to begin learning more advanced Linux system administration skills in
the follow-on tutorial.

LPI certification 101 (release 2) exam prep, Part 3
In this tutorial we'll introduce you the Linux system documentation. We will
teach you how to change permissions and how to manage with Linux accounts. At
the end you'll learn how to tune your enviroment.

LPI certification 101 (release 2) exam prep, Part 4
In this tutorial, we'll introduce all popular filesystem on Linux. We'll teach
you how to mount and unmount devices. In next chapter you'll know how to boot
the system and how to work with runlevels. In next section of this tutorial,
we'll introduce filesystem quotas, we will teach you how to set them and how to
configure them. By the end of this tutorial you'll know a system logs.

Partitioning in action, Part 1
In this new series of tips, Daniel Robbins shows you how to change partition
layout on a running system. He'll also cover several tricks of the trade to
minimize downtime and avoid making costly mistakes. In this particular tip,
he'll show you how to move /home to another partition.

Partitioning in action, Part 2
In this second tip on changing partition layout on a running system, Daniel
Robbins shows you how to move /tmp and /var to their own shared partition. He
also covers several tricks of the trade to minimize downtime and avoid making
costly mistakes.

Partition planning tips
Organizing your partitions correctly can be fun and rewarding. This collection
of tips will help you to use those sectors wisely.

Maximum swappage
Learn how to improve the swap performance on your Linux server by several
orders of magnitude. Author Daniel Robbins takes you through this quick tip on
getting the most from your server.

Learning Linux LVM, Part 1
In this article, Daniel introduces you to the concepts behind Linux LVM
(Logical Volume Management) and shows you how to get the latest kernel patches
and tools installed on your system. LVM allows you to create logical volumes
out of the physical storage resources on your machine. However, unlike physical
volumes, the logical volumes can be expanded and shrunk while the system is
still running, providing Linux system administrators with the storage
flexibility that they've until now only dreamed of.

Learning Linux LVM, Part 2
In this article, Daniel shares his experiences converting cvs.gentoo.org's
/home filesystem to an LVM logical volume. After the transition, we get to see
the benefits of LVM when cvs.gentoo.org's /home partition is dynamically
resized in real-time, without rebooting, unmounting /home, or even dropping to
runlevel 1. All processes continue to work without any interruption. Daniel's
step-by-step details of the conversion will help anyone interested in peforming
a similar transition on their own machine.

Software RAID in the new Linux 2.4 kernel, Part 1
In his two-part series on the Linux 2.4 Software RAID, Daniel Robbins
introduces the new technology that's used to increase disk performance
and reliability by distributing data over multiple disks. This first
installment covers Software RAID setup (kernel and tools installation)
and shows you how to create linear and RAID-0 volumes.

Software RAID in the new Linux 2.4 kernel, Part 2
In this two-part series, Daniel Robbins introduces you to Linux 2.4
Software RAID, a technology used to increase disk performance and
reliability by distributing data over multiple disks. In this article,
Daniel explains what software RAID-1, 4, and 5 can and cannot do for
you and how you should approach the implementation of these RAID
levels in a production environment. In the second half of the article,
Daniel walks you through the simulation of a RAID-1 failed drive
replacement.

Compiling the Linux kernel
Daniel Robbins introduces the Linux kernel, and then walks you through locating
and downloading sources, configuring the kernel, compiling and installing the
kernel, and boot configuration.

Prompt magic
Why stick with the standard boring shell prompt when you can easily make it
colorful and more informative? In this tip, Daniel Robbins will show you how to
get your shell prompt just the way you like it, as well as how to dynamically
update your X terminal's title bar.

OpenSSH key management, Part 1
In this series, you'll learn how RSA and DSA authentication work, and see how
to set up passwordless authentication the right way. In the first article of
the series, Daniel Robbins focuses on introducing the RSA and DSA
authentication protocols and showing you how to get them working over the
network.

OpenSSH key management, Part 2
Many developers use the excellent OpenSSH as a secure, encrypted replacement
for the venerable telnet and rsh commands. One of OpenSSH's more intriguing
features is its ability to authenticate users using the RSA and DSA
authentication protocols, which are based upon a pair of complementary
numerical "keys". One of the main appeals of RSA and DSA authentication is the
promise of being able to establish connections to remote systems without
supplying a password. In this second article, Daniel introduces ssh-agent (a
private key cache) and keychain, a special bash script designed to make
key-based authentication incredibly convenient and flexible.

OpenSSH key management, Part 3
In this third article in a series, Daniel Robbins shows you how to take
advantage of OpenSSH agent connection forwarding to enhance security. He also
shares recent improvements to the keychain shell script.

Advanced filesystem implementor's guide, Part 8
With the 2.4 release of Linux come many new filesystem possibilities,
including Reiserfs, XFS, GFS, and others. These filesystems sound cool, but
what exactly can they do, what are they good at, and exactly how do you go
about safely using them in a production Linux environment? Daniel Robbins
answers these questions by showing you how to set up these new advanced
filesystems under Linux 2.4. In this installment, Daniel continues his look
at ext3, a new improved version of ext2 with journaling capabilities. He
reveals all the inside information on ext3, and demonstrates some shockingly
good ext3 data=journal interactive performance numbers.

DeveloperWorks Common Threads

Dynamic iptables firewalls
Firewalls are good and fun, but what do you do when you need to make rapid,
complex changes to your firewall rules? Easy. Use Daniel Robbins' dynamic
firewall scripts that are demonstrated in this article. You can use these
scripts to increase your network security and responsiveness, and to inspire
your own creative designs.

Sed by example, Part 1
In this series of articles, Daniel Robbins will show you how to use the very
powerful (but often forgotten) UNIX stream editor, sed. Sed is an ideal tool for
batch-editing files or for creating shell scripts to modify existing files in
powerful ways.

Sed by example, Part 2
Sed is a very powerful and compact text stream editor. In this article, the
second in the series, Daniel shows you how to use sed to perform string
substitution; create larger sed scripts; and use sed's append, insert, and
change line commands.

Sed by example, Part 3
In this conclusion of the sed series, Daniel Robbins gives you a true taste of
the power of sed. After introducing a handful of essential sed scripts, he'll
demonstrate some radical sed scripting by converting a Quicken .QIF file into a
text-readable format. This conversion script is not only functional, it also
serves as en excellent example of sed scripting power.

Awk by example, Part 1
Awk is a very nice language with a very strange name. In this first article of a
three-part series, Daniel Robbins will quickly get your awk programming skills
up to speed. As the series progresses, more advanced topics will be covered,
culminating with an advanced real-world awk application demo.

Awk by example, Part 2
In this sequel to his previous intro to awk, Daniel Robbins continues to explore
awk, a great language with a strange name. Daniel will show you how to handle
multi-line records, use looping constructs, and create and use awk arrays. By
the end of this article, you'll be well versed in a wide range of awk features,
and you'll be ready to write your own powerful awk scripts.

Awk by example, Part 3
In this conclusion to the awk series, Daniel introduces you to awk's important
string functions, and then shows you how to write a complete
checkbook-balancing program from scratch. Along the way, you'll learn how to
write your own functions and use awk's multidimensional arrays. By the end of
this article, you'll have even more awk experience, allowing you to create more
powerful scripts.

POSIX threads explained, part 1
POSIX (Portable Operating System Interface) threads are a great way to increase
the responsiveness and performance of your code. In this series, Daniel Robbins
shows you exactly how to use threads in your code. A lot of behind-the-scenes
details are covered, so by the end of this series you'll really be ready to
create your own multithreaded programs.

POSIX threads explained, part 2
POSIX threads are a great way to increase the responsiveness and performance of
your code. In this second article of a three-part series, Daniel Robbins shows
you how to protect the integrity of shared data structures in your threaded code
by using nifty little things called mutexes.

POSIX threads explained, part 3
In this article, the last of a three-part series on POSIX threads, Daniel takes
a good look at how to use condition variables. Condition variables are POSIX
thread structures that allow you to "wake up" threads when certain conditions
are met. You can think of them as a thread-safe form of signalling. Daniel wraps
up the article by using all that you've learned so far to implement a
multi-threaded work crew application.

Advanced Filesystem Implementor's Guide : Introducing ext3
With the 2.4 release of Linux come a host of new filesystem possibilities,
including Reiserfs, XFS, GFS, and others. These filesystems sound cool, but
what exactly can they do, what are they good at, and exactly how do you go
about safely using them in a production Linux environment? Daniel Robbins
answers these questions by showing you how to set up these new advanced
filesystems under Linux 2.4. In this installment, Daniel takes a look at ext3,
a new improved version of ext2 with journaling capabilities.

Introduction to Samba, Part 1
Samba is an incredible tool for anyone who uses both Unix and Windows. By
implementing the SMB/CIFS protocol for Unix, Samba allows Unix systems to share
their resources with standard Windows clients. In this introductory article,
Daniel Robbins introduces you to what Samba can do. The focus will be on key
concepts. (He'll step you through the setup process in his next article.) By the
end of this article, you'll have a good understanding of what Samba does, and
how it goes about doing it.

Introduction to Samba, Part 2
In his previous article, Daniel introduced you to what Samba can do. Now it's
time to get it running on your system. In this article, he'll walk you through
the process of compiling, installing, and initially configuring Samba (version
2.0.7) so that it works in your environment.

Introduction to Samba, Part 3
In his previous article, Daniel Robbins guided you through the process of
setting up Samba for the first time. Now it's time to configure Samba so that it
does everything that you want it to do.

The gentoo.org redesign, Part 1: A site reborn
Have you ever woken up one morning and suddenly realized that your cute little
personal development Web site isn't really that great? If so, you're in good
company. In this series, Daniel Robbins shares his experiences as he redesigns
the www.gentoo.org Web site using technologies like XML, XSLT, and Python.
Along the way, you may find some excellent approaches to use for your next Web
site redesign. In this article, Daniel creates a user-centric action plan and
introduces pytext, an embedded Python interpreter.

The gentoo.org redesign, Part 2: A site reborn
Have you ever woken up in the morning to the realization that your personal
development Web site isn't really that great? If so, you're in good company. In
this series, Daniel Robbins shares his experiences as he redesigns the
www.gentoo.org Web site using technologies like XML, XSLT, and Python. Along
the way, you may find some excellent approaches to use in your next Web site
redesign. In this, the second installment, Daniel shows off the new
documentation system and sets up a daily CVS-log mailing list.

The gentoo.org redesign, Part 3: A site reborn
Have you ever woken up one morning and suddenly realized that your cute little
personal development Web site isn't really that great? If so, you're in good
company. In this series, Daniel Robbins shares his experiences as he redesigns
the www.gentoo.org Web site using technologies like XML, XSLT, and Python.
Along the way, you may find some excellent approaches to use for your next Web
site redesign. In this installment, Daniel creates a new look for the site as a
whole.

The gentoo.org redesign, Part 4: A site reborn
Have you ever woken up one morning and suddenly realized that your cute little
personal development Web site isn't really that great? If so, you're in good
company. In this series, Daniel Robbins shares his experiences as he redesigns
the Gentoo Linux Web site using technologies like XML, XSLT, and Python. This
article: Daniel completes the conversion to XML/XSLT, fixes a host of Netscape
4.x browser compatibility bugs, and adds an auto-generated XML Changelog to the
site.

Miscellaneous Articles

Best practices with autotools
This article covers some of the most common errors people make when using
autotools and ways to achieve better results.

Linux hardware stability guide, Part 1
In this article, Daniel Robbins shows you how to diagnose and fix CPU
flakiness, as well as how to test your RAM for defects. By the end of this
article, you'll have the skills to ensure that your Linux system is as stable
as it possibly can be.

Linux hardware stability guide, Part 2
In this article, Daniel Robbins shares his experiences in getting his NVIDIA
TNT graphics card working under Linux using NVIDIA's accelerated drivers. As he
does, he'll show you how to diagnose and fix IRQ and PCI latency timer issues
-- techniques you can use to ensure that your systems don't experience
lock-ups, inconsistent behavior, or data loss.

Gentoo Social Contract
This document contains a pledge to the Gentoo community about the freedom of
Gentoo's software, the openness of Gentoo's development process and the feedback
we give back to the free software community.