[gentoo-doc-cvs] cvs commit: handbook.xml

[swift]

swift       06/01/06 20:05:08

  Added:       xml/htdocs/doc/en/handbook/draft/complete handbook.xml
                        hb-admin-centralised.xml hb-admin-logs.xml
                        hb-admin-portage.xml hb-app_arch-x86.xml
                        hb-desktop-collaboration.xml
                        hb-desktop-graphical.xml hb-desktop-plugnplay.xml
                        hb-enterprise-backups.xml hb-enterprise-lvm.xml
                        hb-enterprise-printing.xml hb-enterprise-swraid.xml
                        hb-install-bootprocess.xml hb-install-building.xml
                        hb-install-configure.xml hb-install-kernel.xml
                        hb-install-media.xml hb-install-minenv.xml
                        hb-install-network.xml hb-install-next.xml
                        hb-install-storage.xml hb-intro-choice.xml
                        hb-intro-linux.xml hb-intro-next.xml
                        hb-intro-resources.xml hb-intro-support.xml
                        hb-intro-user_fhs.xml hb-intro-versions.xml
                        hb-tuning-io.xml hb-tuning-network.xml
                        hb-tuning-profiling.xml hb-tuning-rendering.xml
                        hb-tuning-userinput.xml
  Log:
  Humpty dumpty sitting in the tree... a framework for a large project?

Revision  Changes    Path
1.1                  xml/htdocs/doc/en/handbook/draft/complete/handbook.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/handbook.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/handbook.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: handbook.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/handbook.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<book link="handbook.xml" lang="en">
<title>the Complete Gentoo/Linux handbook</title>

<author title="Author">
  <mail link="swift@g.o">Sven Vermeulen</mail>
</author>

<abstract>
This handbook tries to extend on various subjects regarding Linux and the Gentoo
Linux operating system. It is written with the casual user in mind who wants to
learn about Linux rather than just follow instructions to the letter. Although I
hope this handbook will eventually be complete, it currently lacks so many
important subjects that it is far from ready yet to be officially published.
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>0.0</version>
<date>2005-06-09</date>

<part>
<title>Introduction to Linux</title>
<abstract>
Linux is a great concept. It is a wonderful kernel and has wonderful userland
utilities making it a perfect operating system. But for most people, it is quite
new and too exciting to just dive in. This part tries to cover Linux: what is
it, how does it work, what can you expect etc.
</abstract>

<chapter>
<title>What is Linux?</title>
<abstract>
What is Linux exactly? How does this all fit in "Free Software"? What is a
distribution and why would you care? How is Linux developed? What can you expect
from it? All that is covered in this chapter.
</abstract>
  <include href="hb-intro-linux.xml"/>
</chapter>

<chapter>
<title>Users and the Linux file system</title>
<abstract>
Linux is built upon the UNIX knowledge and concepts. This means it is fairly
robust and uses a very logical approach to files, users and such. But for most
people, this logical approach is just what seems the most illogical since they
are not used to it. In this chapter, we try to inform those users about how
Linux sees a multi-user environment and what the Linux file system is structured
like.
</abstract>
  <include href="hb-intro-user_fhs.xml"/>
</chapter>

<chapter>
<title>Freedom, support and finances</title>
<abstract>
The most powerful asset of the Linux operating system is the freedom it gives
you. But many folks are afraid that this freedom comes with a price: no support,
no company backing up Linux. This is all FUD (Fear, Uncertainty, Doubt) and well
explained in this chapter.
</abstract>
  <include href="hb-intro-support.xml"/>
</chapter>

<chapter>
<title>Staying up to date</title>
<abstract>
With the decentralised development model that Linux uses, keeping a system up to
date might seem like a huge effort. Indeed, it is, but it is covered by the
various distributions (such as Gentoo). However, because of the openness that
the development model imposes, users have conflicting feelings about stability
and the differences between all version models. This chapter explains what all
the differences between version models are.
</abstract>
  <include href="hb-intro-versions.xml"/>
</chapter>

<chapter>
<title>Making a choice</title>
<abstract>
Now that most non-technical stuff is covered, it is time for you to make
choices. Will you use Linux? What distribution? What graphical environment? What
mail client? In this chapter we discuss the various differences between
major distributions and explain that, once you have picked a distribution, all
other choices are reversible.
</abstract>
  <include href="hb-intro-choice.xml"/>
</chapter>

<chapter>
<title>Finding information</title>
<abstract>
You have a lot of resources at your disposal, but you need to know where to look
for them. In this chapter we provide you a quick overview on the available
resources, how to use them for your queries and what you can do to contribute to
them.
</abstract>
  <include href="hb-intro-resources.xml"/>
</chapter>

<chapter>
<title>So far so good</title>
<abstract>
Now that the introduction to Linux has ended, we will talk about the next few
parts and the syntax we use throughout this document.
</abstract>
  <include href="hb-intro-next.xml"/>
</chapter>
</part>

<part>
<title>Installing Gentoo</title>
<abstract>
So you decided to install Gentoo. That's great, so how to continue? Installing
Gentoo is a breeze, but not a soft one. You need to have a fair knowledge of the
Linux environment if you want to get it right from the first time. In this part,
we discuss how to install Gentoo using the available Gentoo media. 
</abstract>

<chapter>
<title>Versions, media and installation concerns</title>
<abstract>
Gentoo provides installation media, with specific versions, for specific
architectures, for specific installation methods. This chapter informs you how
to pick the right media for your system.
</abstract>
  <include href="hb-install-media.xml"/>
</chapter>

<chapter>
<title>Starting from a minimal environment</title>
<abstract>
The start of every Gentoo installation process begins with a minimal Linux
environment, allowing you to extract a basic Gentoo environment on your disk.
Regardless of what minimal environment you are in, you need to know a few basic
things about the system. This chapter covers the use of important tools.
</abstract>
  <include href="hb-install-minenv.xml"/>
</chapter>

<chapter>
<title>Preparing the network</title>
<abstract>
When you are known to the minimal environment, it is time to get the network up
and running. We will inform you how a network is set up, what TCP/IP is and how
to deal with networking on Linux, including wireless networks.
</abstract>
  <include href="hb-install-network.xml"/>
</chapter>

<chapter>
<title>Putting the minimal environment in place</title>
<abstract>
In this chapter we prepare your disk(s) to store the Gentoo Linux environment.
We will cover a few additional storage concepts (LVM2, RAID) but the real use of
these technologies is postponed for later. Next, we store a minimal Gentoo
environment on your disks.
</abstract>
  <include href="hb-install-storage.xml"/>
</chapter>

<chapter>
<title>Building the system</title>
<abstract>
Once the minimal environment was available, we took the dive and chrooted in it.
Now, we'll set up the basic configuration directives, build the Gentoo
system until it is bootstrapped and has the core system packages available.
</abstract>
  <include href="hb-install-building.xml"/>
</chapter>

<chapter>
<title>Building the Linux kernel</title>
<abstract>
The core of any Linux Operating System is the kernel. Configuring a kernel might
seem like a difficult task, but once you get to know how it works, it hardly is
a challenge anymore. In this chapter we will discuss how to configure and build
your kernel, either automatically using genkernel, or manually with the kernel
configuration dialog.
</abstract>
  <include href="hb-install-kernel.xml"/>
</chapter>

<chapter>
<title>Configuring the boot process</title>
<abstract>
The next step is to configure the boot process. The boot process covers the boot
loader tool, which loads the Linux kernel in memory, and the init process which
governs all the applications and processes that should start on a Linux system.
</abstract>
  <include href="hb-install-bootprocess.xml"/>
</chapter>


<chapter>
<title>Configuring the system</title>
<abstract>
Most of the system's configuration is stored inside /etc. In this almost final
chapter we describe what you should configure prior to rebooting (such as the 
file system table, networking stuff, user accounts, ...). It is important to 
read this entire chapter completely.
</abstract>
  <include href="hb-install-configure.xml"/>
</chapter>

<chapter>
<title>Finishing off</title>
<abstract>
Now that everything is (hopefully) configured correctly, we reboot in the Gentoo
Linux Operating System to discover that we have a nice running minimal
environment. Now, where to go from here? You obviously can't work immediately
since nothing is installed yet...
</abstract>
  <include href="hb-install-next.xml"/>
</chapter>
</part>

<part>
<title>Gentoo Linux for the desktop user</title>
<abstract>
Most Gentoo users have a Gentoo-powered desktop system, yet are often unaware of
the massive tools and helpful features that Linux offers to increase their
desktop experience. In this part you'll find pointers to various tips and
tricks, but also best practices for desktop users.
</abstract>

<chapter>
<title>Graphical Linux</title>
<abstract>
Linux is not an operating system where command-line utilities must be used. Once
the system is installed, any user should be able to use it without any knowledge
of command-line utilities. Indeed, this is perfectly possible, but requires some
configuration. This chapter covers the setup of a graphical desktop.
</abstract>
  <include href="hb-desktop-graphical.xml"/>
</chapter>

<chapter>
<title>Plug and play</title>
<abstract>
Your laptop detects an open wireless network and authenticates itself
immediately. You plug in your USB key which gets mounted immediately so you can
download the latest Gentoo release on it. While you are at it, your calendar
synchronises with your friends while your laptop tries to consume as little
power as possible because it is working on batteries. No, this is no utopia...
</abstract>
  <include href="hb-desktop-plugnplay.xml"/>
</chapter>

<chapter>
<title>Software collaboration</title>
<abstract>
Open standards allow for easy integration of different software tools. However,
the race for the best open standard hasn't been won, so various tools only work
with one standard while other tools use a different one. This chapter gives a 
quick overview of the various collaboration-related standards and the 
applications (or libraries which they use) that make use of them.
</abstract>
  <include href="hb-desktop-collaboration.xml"/>
</chapter>

</part>

<part>
<title>Gentoo Linux for enterprise environments</title>
<abstract>
Enterprises require more than just a stable Operating System. Depending on their
requirements, a system should be high-available, have a high throughput, connect
with legacy systems, have a low maintenance cost, requires zero manual
configuration steps, etc. This part will attempt to discuss various interesting
topics that might help you get more out of Gentoo Linux.
</abstract>

<chapter>
<title>Software RAID</title>
<abstract>
If you need a very low-cost system but still want redundancy, using software
RAID is a minimal requirement. In this chapter we will describe how to use
software RAID within Gentoo Linux.
</abstract>
  <include href="hb-enterprise-swraid.xml"/>
</chapter>

<chapter>
<title>Logical Volume Management</title>
<abstract>
With LVM, storage concerns can be tackled easily since your files are located on
top of a specific layer, able to hide the complexity of storage from the file
system. Learn how to store files across various file systems, moving data
without the need to put the system in a frozen state, take live backups without
having your data touched while you are busy, ... and all that using LVM2.
</abstract>
  <include href="hb-enterprise-lvm.xml"/>
</chapter>

<chapter>
<title>Backup systems</title>
<abstract>
You don't want to lose your files, but eventually you will. Having backups at
hand is a prerequisite for good system householding, but is also often
overlooked or deemed less important. This chapter will cover a few basics on
backups and proposes a few solutions that will help you keep your data safe.
</abstract>
  <include href="hb-enterprise-backups.xml"/>
</chapter>

<chapter>
<title>Print server</title>
<abstract>
High quality printing is a requirement for every office. Linux makes a fine
print server, capable of interacting with all possible applications and
operating systems.
</abstract>
  <include href="hb-enterprise-printing.xml"/>
</chapter>

</part>

<part>
<title>System Administration</title>
<abstract>
Once your system is set up, your next concern is to decide how to administer the
system. Some people have made system administration their full-time job. We'll
try to keep the administration to a minimum without losing flexibility.
</abstract>

<chapter>
<title>Software management</title>
<abstract>
Gentoo's Portage is a powerful software management tool with lots of features.
Not only can you easily install and remove software, rebuild tools when they are
affected by changes or update your system entirely, it also supports prebuilt
packages and different repositories.
</abstract>
  <include href="hb-admin-portage.xml"/>
</chapter>

<chapter>
<title>Log files</title>
<abstract>
Not many resources talk about log files. Most documents assume that log files
are mentioned by the application documentation, yet many applications just
inform you what information you can find in the logs and that isn't sufficient
for a good log management policy. Log rotation, event filtering, summary
creation, ... are all aspects that this chapter covers.
</abstract>
  <include href="hb-admin-logs.xml"/>
</chapter>

<chapter>
<title>Centralised system management</title>
<abstract>
When you administer more than one system, it might be beneficial to set up and
maintain your environment from a single location. You can use SSH to log on to
other systems, but more advanced tools exist that offer a wide variety of
features.
</abstract>
  <include href="hb-admin-centralised.xml"/>
</chapter>

</part>

<part>
<title>Performance tuning</title>
<abstract>
No system is equal, so many systems have one or more performance bottlenecks due
to general settings that aren't as optimal for their systems as they are for
others. You can increase your systems performance on many areas as long as you
understand why they are bottlenecks and what sacrifices you need to make to
increase the throughput.
</abstract>

<chapter>
<title>Input/output performance</title>
<abstract>
Storage performance. If there is one device in your system that has the highest
importance but one of the lowest access times, it is your storage. Disks aren't
fast, network storage isn't much better and memory disks are generally too small
to contain your entire system. So what can you do to increase the IO
performance?
</abstract>
  <include href="hb-tuning-io.xml"/>
</chapter>

<chapter>
<title>Network performance</title>
<abstract>
If you are on a 28.8 kbps network, you'll always find that it is slow. Many
people still think their network is slow while they're using a 1 Gbps network.
By identifying the bottlenecks in your network and designing a good topology,
you can increase the performance of your network to a good level.
</abstract>
  <include href="hb-tuning-network.xml"/>
</chapter>

<chapter>
<title>Rendering performance</title>
<abstract>
A gamers wet dream: screens and graphical cards that render 3D images so
detailed and so fast that it seems that you're looking through a window. Of
course, this isn't achievable yet, but it is possible to tune the 3D performance
of your card. Of course, we'll take a look at 2D rendering as well.
</abstract>
  <include href="hb-tuning-rendering.xml"/>
</chapter>

<chapter>
<title>Software profiling</title>
<abstract>
Programmers don't always write the most performant code; perhaps because they
rely on the compiler to enhance the machine code or because they want to write
clean and maintainable code, setting their priorities elsewhere. Using profiling
tools, you can find out where in the software the performance bottlenecks may
lie.
</abstract>
  <include href="hb-tuning-profiling.xml"/>
</chapter>

<chapter>
<title>User-observed performance</title>
<abstract>
Lately, developers have come to the conclusion that even the fastest solution
can lose against a less performant system - at least if a human being is to
observe and judge. Many interesting projects have emerged where design
patterns and guidelines are discussed that try to embrace the users thoughts on
speed and performance.
</abstract>
  <include href="hb-tuning-userinput.xml"/>
</chapter>

</part>


<part>
<title>Appendix: architecture specific information</title>
<abstract>
Not all aspects of a Gentoo Linux system are similar on all architectures. Some
small differences come up during and after the installation. This part will
cover all architecture-specific information, nicely divided in separate chapters
for each architecture.
</abstract>

<chapter>
<title>The x86 Architecture</title>
<abstract>
The x86 architecture covers all 32-bit Intel and Intel-clones, such as the 
various AMD processors (the K-series and Athlon/Duron), VIA and Cyrix. The CPU
types range from the old (but functional) i386 to the latest Intel Pentium IV
and AMD Athlons.
</abstract>
  <include href="hb-app_arch-x86.xml"/>
</chapter>
</part>

</book>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-admin-centralised.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-centralised.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-centralised.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-admin-centralised.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-centralised.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title></title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-admin-logs.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-logs.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-logs.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-admin-logs.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-logs.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title></title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-admin-portage.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-portage.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-portage.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-admin-portage.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-admin-portage.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Software maintenance</title>
</section>

<section>
<title>Using prebuilt software packages</title>
</section>

<section>
<title>Understanding ebuilds</title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-app_arch-x86.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-app_arch-x86.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-app_arch-x86.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-app_arch-x86.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-app_arch-x86.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Booting CDs</title>
<subsection>
<title>BIOS</title>
<body>

<p>
The BIOS (Basic Input/Output System) is the first system started when you power
on your computer. It first performs a POST (Power-On Self Test) to verify if
your hardware is still in good shape. When the POST gives the BIOS an okay, the
BIOS will load the boot loader from the boot device configured in its memory.
This boot loader then fires up the operating system and the entire system dance
starts...
</p>

<p>
To boot from a CD, you need to configure your BIOS so that the CD-ROM device is
the first boot device. Reboot your system and fire up the BIOS. You will be
informed about what key to press right after (or during) the POST to get in the
BIOS setup. Most BIOSses use <c>Esc</c>, <c>F1</c>, <c>F2</c>, <c>DEL</c> or
<c>F8</c>.
</p>

<p>
Once you are inside the BIOS setup, search for the setting where you can change
the boot device sequence. Some BIOSses place it beneith <e>CMOS Setup</e>, but
there isn't a standard - each BIOS has its differences. Change the order so that
the CD-ROM device is mentioned first before the first hard disk (HD-0). Such a
setting will allow you to boot from a bootable CD if there is one in the CD-ROM
drive, or boot from the hard drive otherwise.
</p>

</body>
</subsection>
</section>

<section>
<title>Partitioning the disks</title>
<subsection>
<title>Partition layout</title>
<body>

<p>
Each disk on an x86 system should have at most <e>four</e> primary partitions.
This is a remnesence of the old days where four partitions were found enough.
Each primary partition has its identification inside the first sector on the
disk (the <e>boot record</e>). When you want more than four partitions, you
should configure one of the primary partitions to contain all the non-primary
partitions. This large primary partition is called the <e>extended</e> partition
and the partitions inside it are called <e>logical</e> partitions.
</p>

<p>
The de-facto standard device naming convention tells us that the primary
partitions for a disk are numbered as 1 to 4 while the logical ones are 5
and higher, regardless of how many primary partitions you use. The naming
convention also tells us how the disks themselves are called.
</p>

<ul>
  <li>
    IDE device names start with <path>hd</path> followed by an alphabetic
    character which resembles the location of the disk in the system: the
    primary master<sup>1</sup> is <path>hda</path>, the primary slave
    <path>hdb</path>, the secundary master <path>hdc</path>, etc.
  </li>
  <li>
    SCSI device names (and most Serial ATA ones as well) start with
    <path>sd</path> followed by an alphabetic character which resembles the
    position of the disk in the disk chain: the first one is <path>sda</path>,
    the second one <path>sdb</path>, etc.
  </li>
</ul>

<p>
Device files are located inside <path>/dev</path>, so if you want to identify
the primary master IDE drive you would state <path>/dev/hda</path>. 
</p>

<note>
<sup>1</sup> IDE drives are controlled by an IDE controller. Each controller can
govern two IDE devices at most: a master and a slave. The master drive has
higher priority when both drives are attempting to send or receive data. A
standard x86 system has two controllers, a primary one (<path>ide0</path>) and a
secundary one (<path>ide1</path>). 
</note>

</body>
</subsection>
<subsection>
<title>Partitioning using cfdisk</title>
<body>

<p>
The <c>cfdisk</c> tool allows you to quickly partition your disks and is a lot
easier to use than <c>fdisk</c>. When you have fired up <c>cfdisk</c> (which
selects <path>/dev/hda</path> by default - you can use a different disk by
giving the device file name as an argument) you will get an overview of the
available partitions, each one listed with the device name, partition type, file
system type and size.
</p>

<p>
When you take a look at the interface, you'll notice that it is quite
self-explanatory:
</p>

<ul>
  <li>
    When you select a free space region, you can add new partitions by pressing
    <c>New</c>. <c>cfdisk</c> will ask you what kind of partition you want
    (primary or logical) and its size after which the partition is added to the
    overview pane.
  </li>
  <li>
    When you select a partition entry, you can change the file system type. Just
    select <c>Type</c> and search for the type you are interested in (probably
    82 - Linux swap / Solaris, or 83 - Linux).
  </li>
  <li>
    Since some BIOSses require the partition that stores the boot loader for the
    operating system to be marked as bootable, there is also an option of doing
    so.
  </li>
</ul>

<p>
You should create your partitions, not forgetting to mark at least one of them
for swap usage. Even though swap files are supported by Linux, it is not
recommended since they have some impact on the system's performance.
</p>

<p>
A frequently asked question is how to partition the disk. There is no satisfying
answer to that, and any attempt to obtain one will result in a cataclystic
series of flamewars. So we stick with one advise: it doesn't hurt to use two
partitions: one for the entire Linux system and one for the swap space. You'll
get to know your own preferences when you are more experienced with Linux.
</p>

</body>
</subsection>
</section>

<section>
<title>The make.conf file</title>
<subsection>
<title>Introduction</title>
<body>

<p>
The information given in this section is not meant to be exhaustive. We provide
you with the settings Gentoo supports. If you use different settings we don't
say that Gentoo doesn't support it, but it is possible. We list the settings by
subarchitecture - a set of machine instructions supported by a range of x86
systems. All subarchitectures are derived from older, <e>compatible</e>
subarchitectures. If at any time you are uncertain which one to pick, you should
use the oldest subarchitecture. Picking one that is more recent than the one
your system supports will result in segmentation faults or internal errors.
</p>

<p>
The <c>CXXFLAGS</c> setting is never shown, you should set it to the
<c>CFLAGS</c> one:
</p>

<pre caption="Setting the CXXFLAGS variable">
CFLAGS="..."
<i>CXXFLAGS="${CFLAGS}"</i>
</pre>

</body>
</subsection>
<subsection>
<title>The generic x86 subarchitecture</title>
<body>

<p>
The next settings work on every x86 system (apart from the i286 and lower):
</p>

<pre caption="Generic x86 settings">
CHOST="i386-pc-linux-gnu"
CFLAGS="-march=i386 -O2 -pipe"
</pre>

</body>
</subsection>
<subsection>
<title>The ix86 series</title>
<body>

<p>
The ix86 series (i486, i586, i686) all refer to Intel- and Intel compatible
CPUs. The i586 instruction set is also known as the <e>Pentium</e> and the i686
one as the <e>Pentium Pro</e>, the predecessor of the <e>Pentium MMX</e>.
</p>

<pre caption="ix86 Series">
<comment>(Substitute i486 with i586 or i686 accordingly)</comment>
CHOST="i486-pc-linux-gnu"
CFLAGS="-march=i486 -O2 -pipe"
</pre>

<p>
You can also substitute the <c>i486</c> value <e>inside the CFLAGS</e> setting
(and <e>not</e> the CHOST one) with <c>pentium</c> or
<c>pentium-pro</c> for such systems.
</p>

</body>
</subsection>
<subsection>
<title>Intel CPUs</title>
<body>

<p>
Additional support is available for various Intel CPUs, such as
<c>pentium-mmx</c>, <c>pentium2</c> (including Celeron), <c>pentium3</c> and
<c>pentium4</c>:
</p>

<pre caption="Intel CPU series">
<comment>(Substitute the pentium-mmx value in CFLAGS with the value you need)</comment>
CHOST="i686-pc-linux-gnu"
CFLAGS="-march=pentium-mmx -O2 -pipe"
</pre>

</body>
</subsection>
<subsection>
<title>AMD CPUs</title>
<body>

<p>
AMD CPU users can use any of the following settings for <c>-march</c>:
<c>athlon-xp</c>, <c>athlon-mp</c>, <c>athlon-tbird</c>, <c>athlon</c>,
<c>k6</c>, <c>k6-2</c> or <c>k6-3</c>.
</p>

<pre caption="AMD CPU series">
<comment>(Substitute the athlon-xp value in CFLAGS with the value you need)</comment>
CHOST="i686-pc-linux-gnu"
CFLAGS="-march=athlon-xp -O2 -pipe"
</pre>

</body>
</subsection>
</section>

<section>
<title>Bootloaders</title>
<subsection>
<title>GRUB</title>
<body>

<p>
The <c>grub</c> bootloader is a powerful application, able to boot various
operating systems, including Microsoft Windows. One of its most powerful
features is its ability to understand various file systems, which makes it
possible for <c>grub</c> to aide you in your boot setup, especially when there
are some issues you need to fix.
</p>

<p>
For instance, you can browse a file system looking for files, reading different
<c>grub</c> configurations, using various Linux kernels, locate files on the
system (and view their contents), but also hide partitions, boot from a network 
using BOOTP (a simple file transfer protocol, very often used to send boot 
images to various systems), change the partition table, ...
</p>

</body>
</subsection>
<subsection>
<title>GRUB: configuration</title>
<body>

<p>
To use <c>grub</c>, you need to install it first (from within the chrooted
environment):
</p>

<pre caption="Installing GRUB">
# <i>emerge grub</i>
</pre>

<p>
Next, edit (or create) the <path>/boot/grub/grub.conf</path> file. 
We'll first give you a simple example of a <path>grub.conf</path> file:
</p>

<pre caption="Example grub.conf file">
default 0
timeout 5

title=Gentoo Linux
root (hd0,5)
kernel /kernel-2.6.14-gentoo-r2 root=/dev/sda8
</pre>

<p>
<c>grub</c> always starts counting from zero. For instance, to boot the first
entry by default, we state <c>default&nbsp;0</c>. The other line,
<c>timeout&nbsp;5</c>, tells GRUB to wait 5 seconds before it actually boots the
entry pointed to by the <c>default</c> setting.
</p>

<p>
This is of course not the most difficult part of GRUB. The entries themselves
however are. In the given example, there are three commands given to GRUB:
</p>

<ol>
  <li>
    The <c>title</c> entry tells GRUB what to display to the user when he is
    asked to make his selection.
  </li>
  <li>
    The <c>root</c> entry informs GRUB where his own files are stored. This is
    <brite>not</brite> the Linux root file system (it can be, but this isn't
    always true). If you have <path>/boot</path> (where GRUB stores its files)
    as a separate partition, you point this directive to that partition.
  </li>
  <li>
    The <c>kernel</c> entry is used by GRUB to know what Linux kernel to boot
    (relative to the file system where <c>root</c> points to) and what boot
    parameters to add.
  </li>
</ol>

<p>
Many users often make a mistake when they configure the <c>root</c> parameter.
That's mostly because the syntax used by GRUB to identify partitions is
different from what they're used to work with. Its syntax is quite simple:
</p>

<pre caption="GRUBs partition syntax">
(hd<i>harddisk-#</i>,<i>partition-#</i>)
</pre>

<p>
The <c>harddisk-#</c> is the hard disk number, starting from 0. If you only have
one hard disk, it is <c>0</c>, regardless of where the disk is at. If you have
several disks, start counting from the one which your system checks first. For
instance, if you only have IDE disks, your system will probably start with the
primary master, then primary slave, then secundary master, ... 
</p>

<p>
The <c>partition-#</c> is the partition number, starting from 0, and uses the
same logic used with the partitioning you did earlier. The first four partitions
(0-3) are the primary partitions. The logical partitions start from the number
4. So, in the above example, the GRUB files are stored on the second logical
partition on the first disk (also known as <path>/dev/sda6</path>).
</p>

<p>
You'll find more information about GRUB (including nicely commented
configuration examples) in the GRUB info pages:
</p>

<pre caption="Retrieving GRUB information">
# <i>info grub</i>
</pre>

</body>
</subsection>
<subsection>
<title>GRUB: installation</title>
<body>

<p>
You still have to install <c>grub</c> in the MBR (Master Boot Record) though, so
that your BIOS is able to find and start it. Otherwise, your system will inform
you that no operating system is found...
</p>

<p>
The recommended method uses <c>grub-install</c> to setup GRUB. Yet this tool
relies on some information not present on your system yet: the
<path>/etc/mtab</path> file, a cache file which contains information about the
mounted file systems. Create one that makes <c>grub-install</c> happy, you only
need to enter the file system for your root partition (<path>/</path>) and, if
you have one, for your boot partition (<path>/boot</path>):
</p>

<pre caption="Example /etc/mtab file">
/dev/sda8   /       ext3   rw,noatime   0 0
/dev/sda6   /boot   ext2   rw,noatime   0 0
</pre>

<p>
Then, run <c>grub-install</c> with the device that resembles your first
disk that the system will boot. For instance, if that first disk is
<path>/dev/sda</path>:
</p>

<pre caption="Installing GRUB in the MBR using grub-install">
<comment>(grub-install also supports the (hd0) notation)</comment>
# <i>grub-install /dev/sda</i>
</pre>

<p>
The <c>grub-install</c> tool will then search through <path>/etc/mtab</path> to
find out where the GRUB files are stored and install a minimal boot loader in
the MBR whose only job is to find and start the rest of the GRUB files.
</p>

<p>
If you come to the conclusion that the installation has failed, you can try to
perform the <c>grub-install</c> steps manually. Run <c>grub</c>, then enter the
configuration commands <c>root</c> (where are the GRUB files located - same as 
the one in the configuration file <path>grub.conf</path>),  <c>setup</c> (where 
to install GRUB - <path>(hd0)</path> is most likely) and <c>quit</c> (to exit 
the GRUB installation):
</p>

<pre caption="Performing the GRUB installation steps manually">
<comment>(The following is just an example)</comment>
# <i>grub</i>
grub&gt; <i>root (hd0,5)</i>
grub&gt; <i>setup (hd0)</i>
grub&gt; <i>quit</i>
</pre>

</body>
</subsection>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-collaboration.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-collaboration.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-collaboration.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-desktop-collaboration.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-collaboration.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Interoperable data formats</title>
<subsection>
<title>Chosing the file type wisely</title>
<body>

</body>
</subsection>
<subsection>
<title>Converting files</title>
<body>

</body>
</subsection>
<subsection>
<title>Using legacy formats</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Drag and drop</title>
<subsection>
<title>The underlying widgets</title>
<body>

</body>
</subsection>
<subsection>
<title>Trolltech Qt</title>
<body>

</body>
</subsection>
<subsection>
<title>GNOME GTK</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Team collaboration</title>
<subsection>
<title>Concurrent access and versioning</title>
<body>

</body>
</subsection>
<subsection>
<title>Wrappers</title>
<body>

<!-- Wrapper to open files (rcs, cvs, svn, ...) -->

</body>
</subsection>
<subsection>
<title>Plug-ins</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Message busses</title>
<subsection>
<title>Theory</title>
<body>

</body>
</subsection>
<subsection>
<title>DBus</title>
<body>

</body>
</subsection>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-graphical.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-graphical.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-graphical.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-desktop-graphical.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-graphical.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>The X server</title>
<subsection>
<title>Introduction</title>
<body>

</body>
</subsection>
<subsection>
<title>Configuration</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Desktop Environments</title>
<subsection>
<title>KDE</title>
<body>

</body>
</subsection>
<subsection>
<title>GNOME</title>
<body>

</body>
</subsection>
<subsection>
<title>XFCE</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Window Managers</title>
<subsection>
<title>WMs are no desktop environments</title>
<body>

</body>
</subsection>
<subsection>
<title>Fluxbox</title>
<body>

</body>
</subsection>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-plugnplay.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-plugnplay.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-plugnplay.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-desktop-plugnplay.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-desktop-plugnplay.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Identify your needs</title>
<subsection>
<title>Nothing is automated at first</title>
<body>
</body>
</subsection>
</section>

<section>
<title>Removable media</title>
</section>

<section>
<title>Network detection</title>
</section>

<section>
<title>Data synchronisation</title>
</section>

<section>
<title>Power consumption</title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-backups.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-backups.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-backups.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-enterprise-backups.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-backups.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Purpose of your files</title>
<subsection>
<title>Know what to backup</title>
<body>

</body>
</subsection>
<subsection>
<title>User versus system files</title>
<body>

</body>
</subsection>
<subsection>
<title>Immediately recoverable or not?</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Backing up on a per-file basis</title>
</section>

<section>
<title>Backing up file systems</title>
</section>

<section>
<title>Backing up an entire system</title>
</section>

<section>
<title>Backup strategies</title>
<subsection>
<title>Full backups</title>
<body>

</body>
</subsection>
<subsection>
<title>Incremental backups</title>
<body>

</body>
</subsection>
<subsection>
<title>Individual backups</title>
<body>

</body>
</subsection>
<subsection>
<title>Backup locations</title>
<body>

</body>
</subsection>
<subsection>
<title>Verify the backups</title>
<body>

</body>
</subsection>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-lvm.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-lvm.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-lvm.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-enterprise-lvm.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-lvm.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Logical Volume Management</title>
<subsection>
<title>Introduction</title>
<body>

</body>
</subsection>
<subsection>
<title>Physical, group and logical</title>
<body>

</body>
</subsection>
<subsection>
<title>Configuring the kernel</title>
<body>

</body>
</subsection>
<subsection>
<title>Installing the tools</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Configuring LVM</title>
<subsection>
<title>Creating the meta devices</title>
<body>

</body>
</subsection>
<subsection>
<title>Choosing a file system</title>
<body>

<!-- Think file system resizing -->

</body>
</subsection>
<subsection>
<title>Automatical activation during system boot</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Maintaining LVM</title>
<subsection>
<title>Adding or removing physical extends</title>
<body>

</body>
</subsection>
<subsection>
<title>Creating a snapshot</title>
<body>

</body>
</subsection>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-printing.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-printing.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-printing.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-enterprise-printing.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-printing.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title></title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-swraid.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-swraid.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-swraid.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-enterprise-swraid.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-enterprise-swraid.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Software RAID</title>
<subsection>
<title>Introduction</title>
<body>

<!-- Supports partitions as well, we'll only use disks since
     partition crash = disk crash -->

</body>
</subsection>
<subsection>
<title>Advantages</title>
<body>

</body>
</subsection>
<subsection>
<title>Disadvantages</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Setting up software RAID</title>
<subsection>
<title>Installing the tools</title>
<body>

</body>
</subsection>
<subsection>
<title>Using software RAID</title>
<body>

</body>
</subsection>
<subsection>
<title>Software RAID for root file system</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Managing software RAID</title>
<subsection>
<title>Adding and removing disks</title>
<body>

</body>
</subsection>
</section>

<section>
<title>Further resources</title>
<subsection>
<title>Online</title>
<body>

</body>
</subsection>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-install-bootprocess.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-bootprocess.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-bootprocess.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-bootprocess.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-install-bootprocess.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Loading the kernel in memory</title>
<subsection>
<title>Introduction to bootloaders</title>
<body>

<p>
When your system is powered on, your system will first perform some sanity
checks against its own components. When all tests succeed, the system loads the
kernel image which you have built previously in memory. This action is performed
by the boot loader.
</p>

<p>
Since loading files in memory is very architecture specific, you should consult
the architecture specific information for your architecture now to find out 
how to install and configure a boot loader. 
</p>

</body>
</subsection>
</section>

<section>
<title>Configuring the kernel</title>
<subsection>
<title>Kernel parameters</title>
<body>

<p>
Inside the configuration file of your boot loader you can enter specific
instructions for the Linux kernel. These parameters allow you to tweak and
change the kernel behaviour at boot-time.
</p>

</body>
</subsection>
<subsection>
<title>Important parameters</title>
<body>

<p>
<b>Root File System Location</b>
</p>

<p>
The first parameter we'll discuss is the <c>root</c> parameter. This tells the
Linux kernel where the root file system of the Linux system is located. You
really should provide this parameter as the Linux kernel will otherwise not know
where the Linux installation is.
</p>

<pre caption="Example root parameter">
<comment>(The root file system in this example is at /dev/sda3)</comment>
root=/dev/sda3
</pre>

<p>
<e>However</e>, you can only specify the root file system <e>if</e> you are
certain that the kernel image (not through separate kernel modules, but really
inside the kernel image) has support for:
</p>

<ul>
  <li>
    the device controller that governs your disk (for instance the SATA
    controller if you use SATA disks), and
  </li>
  <li>
    the file system that the partition uses (for instance ext3 support)
  </li>
</ul>

<p>
If this isn't the case, then you have probably made an initialized RAM disk
which allows the Linux kernel to load the appropriate kernel modules in memory
before it continues with the Gentoo boot-up. Users of the <c>genkernel</c> tool
have indeed made such an <e>initrd</e> file, perhaps without their knowledge.
</p>

<p>
To use such an initrd file, you need to specify <path>/dev/ram0</path> as the
root file system and the real root file system with the <c>real_root=</c>
parameter<sup>1</sup>. It is also adviseable to inform the kernel about the
amount of memory you want to reserve for the RAM disk. 
</p>

<p>
You also need to tell the boot loader where the initrd file is. This is boot
loader specific so we don't mention that here - consult the information for your
boot loader for more information. 
</p>

<p>
For instance:
</p>

<pre caption="Example kernel parameters for initrd users">
root=/dev/ram0 ramdisk=8192 real_root=/dev/sda3
</pre>

<p>
<b>The Initial Program</b>
</p>

<p>
When the kernel has finished its own procedures and mounted the root file
system, it hands over the control to the system to the <c>init</c> process. This
process then takes care of the rest of the boot sequence. By default, the kernel
looks for this tool at <path>/sbin/init</path>. You can however define another
initial program if you like using the <c>init=</c> parameter.
</p>

<p>
For instance, to get a Unix shell immediately, use <c>init=/bin/sh</c>. This
is often used to allow you to remount your partitions and make fixes that 
prevent your system from booting regularly (or when you forgot your root
password).
</p>

<p>
<b>Single User Mode</b>
</p>

<p>
To inform the system to boot up in the single user mode (which is the
<c>single</c> run level we've talked about in the previous chapter), simply add
an <c>S</c>.
</p>

<note>
<sup>1</sup> The <c>real_root</c> parameter is not really a kernel parameter but
is intended for a script inside the initrd file. However, the parameter is used
just like kernel parameters which is why we list it here.
</note>

</body>
</subsection>
<subsection>
<title>Hardware related parameters</title>
<body>

<p>
<b>ACPI Support</b>
</p>

<p>
Not all hardware devices are conform the ACPI specification, even though they
think they are. This sometimes results in unstable behaviour of the device, or
of other devices influenced by the device.
</p>

<p>
You can specifically disable ACPI support using the <c>acpi=off</c> parameter.
</p>

<p>
<b>Disabling IDE Controllers</b>
</p>

<p>
When one of your IDE disks is broken, your system might not be able to boot even
though the system itself is stored on a disk controlled by a different IDE
controller. If this is the case, you can explicitly disable a controller using
<c>ide0=noprobe</c>.
</p>

<p>
<b>Disabling Multi-Processing</b>
</p>

<p>
If you have an SMP system (Synchronous MultiProcessor), you can tell the Linux
kernel to only use one CPU by setting <c>nosmp</c>.
</p>

<p>
<b>Disabling USB Support</b>
</p>

<p>
To disable USB support, use <c>nousb</c>
</p>

</body>
</subsection>
<subsection>
<title>More parameters</title>
<body>

<p>
More extensive information about available kernel parameters can be found at
<path>/usr/src/linux/Documentation/kernel-parameters.txt</path>.
</p>

</body>
</subsection>
</section>

<section>
<title>The boot sequence</title>
<subsection>
<title>Init</title>
<body>

<p>
When the Linux kernel has almost finished with its boot process (where it
initializes the memory structures, loads drivers, etc.) it mounts the root file
system (given by the <c>root</c> parameter) and then starts the <c>init</c>
process (which is default at <c>/sbin/init</c> but can be configured).
</p>

<p>
The <c>init</c> process is responsible for the rest of the system boot sequence.
It looks for the <path>/etc/inittab</path> file which contains the instructions
how to further boot the system. At first, it fires up the command that is
assigned to the <e>boot</e> and <e>bootwait</e> entries which are, in Gentoo's
case:
</p>

<pre caption="Bootwait entry">
rc::bootwait:/sbin/rc boot
</pre>

<p>
Where <c>init</c> is rather distribution-independant (and quite simple in its
use too), <c>/sbin/rc</c> is quite distribution-specific, especially the
<c>rc</c> that Gentoo offers. Its task is to make sure that the scripts in a run
level are started well or take appropriate action if they aren't.
</p>

<p>
Once the boot runlevel has succeeded, the <c>init</c> process goes on by
executing the command for the specified runlevel. By default, the runlevel
entered at the <e>initdefault</e> part of <path>/etc/inittab</path> is started,
but you can ask <c>init</c> to start a different run level by specifying its
corresponding number as a boot parameter (entirely similar to how you add kernel
parameters).
</p>

<pre caption="Default run level and corresponding command">
id:3:initdefault:
<comment>(...)</comment>
l3:3:wait:/sbin/rc default
</pre>

<p>
When this run level has also finished starting its required scripts, the
<c>init</c> process starts the terminal processes at the various ttys (the
Alt+F# locations where you get a logon prompt):
</p>

<pre caption="Example terminal processes for Alt-F1 till F6">
c1:12345:respawn:/sbin/agetty 38400 tty1 linux
c2:2345:respawn:/sbin/agetty 38400 tty2 linux
c3:2345:respawn:/sbin/agetty 38400 tty3 linux
c4:2345:respawn:/sbin/agetty 38400 tty4 linux
c5:2345:respawn:/sbin/agetty 38400 tty5 linux
c6:2345:respawn:/sbin/agetty 38400 tty6 linux
</pre>

</body>
</subsection>
<subsection>
<title>Managing runlevels</title>
<body>

<p>
You can manage the runlevels using the <c>rc-update</c> tool. Its syntax is
quite simple:
</p>

<pre caption="rc-update syntax">
# <i>rc-update &lt;add | del&gt; &lt;initscript&gt; &lt;runlevel&gt;</i>
</pre>

<p>
All the init scripts that you can use are located inside
<path>/etc/init.d</path>. You will most likely use at least the runlevels
<e>boot</e> and <e>default</e>.
</p>

<ul>
  <li>
    The <e>boot</e> runlevel makes sure that the most important init scripts,
    which are required for every succesful system boot, are started properly.
    Any init script that is added to the boot runlevel may not require any
    service offered by the init scripts in the default runlevel (as it is
    started later). It may depend on other scripts in the boot runlevel though,
    Gentoo's <c>rc</c> is smart enough to tackle dependencies.
  </li>
  <li>
    The <e>default</e> runlevel contains all init scripts which should be
    started during normal system operation. This is the runlevel where you will
    probably add most of the init scripts.
  </li>
</ul>

</body>
</subsection>
</section>


</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-install-building.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-building.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-building.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-building.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-install-building.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>Configuring the Gentoo environment</title>
<subsection>
<title>The build configuration file</title>
<body>

<p>
As Gentoo is primarily a <e>build the software</e>-distribution it requires a
bit more configuration directives than most other distributions. The first and
foremost configuration file is <path>/etc/make.conf</path> (remember, we are now
inside the chrooted environment - outside it would be
<path>/mnt/gentoo/etc/make.conf</path>). Open up the file with <c>nano</c>, an
easy to use editor. We add the <c>-w</c> option to turn off word wrapping since
this might harm the configuration itself.
</p>

<pre caption="Editing /etc/make.conf">
# <i>nano -w /etc/make.conf</i>
</pre>

<p>
Inside this configuration file you can define various configuration directives
that affect Portage' behavior or the software building process. We will only 
discuss a few here - others exist as well, but are not that important at the 
beginning of the installation procedure.
</p>

<p>
Each directive is a variable with some specific content. Variables are often
used throughout Linux (and this is even more so within Gentoo). To set a certain
variable, you define its name followed by an equal sign and then the content of
the variable.
</p>

<pre caption="Example variable definition">
MYVARIABLE="value of the variable"
</pre>

</body>
</subsection>
</section>

<section>
<title>Compiler directives</title>
<subsection>
<title>The compiler flags</title>
<body>

<p>
The first directives that we'll discuss are the compiler flags. A compiler is a
tool that builds executable code from source code and one of the benefits of
using Gentoo is that you can define how the compiler should behave. More
precisely, you can tell the compiler to use certain optimizations on your
system. Although a compiler can take a lot more options than just optimization
options, most Gentoo users only use the optimization options.
</p>

<p>
The GNU Compiler Collection, the compiler toolchain used by most architectures,
supports more than hundred optimization flags. Some of them are interesting,
others hardly used. Some of them are harmless, others quite intrusive. We must
warn you that <brite>using anything beyond the Gentoo-recommended optimization
flags is not supported</brite>.
</p>

</body>
</subsection>
<subsection>
<title>CFLAGS and CXXFLAGS</title>
<body>

<p>
The <c>CFLAGS</c> and <c>CXXFLAGS</c> directives are immediately passed to the
C and C++ compilers respectively as command line arguments. They are often used
to inform the compiler about the destination architecture and optimization
settings.
</p>

<p>
Quite often, the <c>CXXFLAGS</c> is told to contain the same setting as the
<c>CFLAGS</c> variable:
</p>

<pre caption="Setting CXXFLAGS">
CXXFLAGS="${CFLAGS}"
</pre>

<p>
The GNU Compiler Collection has lots of possible directives. The first directive
that most users will want to set is the destination CPU type. This is
configurable with the <c>-march=&lt;CPU-TYPE&gt;</c> setting. For most people,
finding out what CPU-TYPE to pick is quite a challenge and indeed, it is not
possible to document what you should use. What we can tell you is that it is
safe to pick an older type while a more recent type can cause malformed software
on your system.
</p>

<p>
To obtain a list of valid <c>-march=</c> settings, please consult the GCC Manual
or the GCC Info pages:
</p>

<pre caption="Consulting the gcc info pages">
# <i>info gcc</i>
Select <i>GCC Command Options</i>,
       <i>Submodel Options</i>,
and pick your architecture.
</pre>

<p>
A second often used compiler setting is the optimization setting. By adding a
<c>-O</c> followed by a number you can ask the compiler to optimize the code in
various degrees. Gentoo recommends <c>-O2</c> (that is "O" for "Optimization",
not "0" like in "007"). The highest possible value is <c>-O3</c> - if you want
even stronger optimization settings you'll need to add them to the variable.
</p>

<p>
If you don't want to optimize the code for speed but for size, use <c>-Os</c>.
</p>

<p>
The third option we add is <c>-pipe</c> which tells GCC that it can use process
pipes instead of temporary files for communication between the various stages of
compilation. This considerably improves compiling performance on systems with
sufficient memory.
</p>

</body>
</subsection>
<subsection>
<title>CHOST</title>
<body>

<p>
The <c>CHOST</c> variable is an identifier for the target host for which the
compiler should build software. It is vital that this variable identifies your
system, but it is even more vital that you <brite>do not edit this variable if
you are not performing a bootstrap installation</brite>. If you alter this
variable, any toolchain rebuild will cause the toolchain to be in an
intermediate state, possibly producing malfunctioning libraries.
</p>

</body>
</subsection>
<subsection>
<title>So your settings would be ...</title>
<body>

<p>
At the end of this handbook you will find architecture-specific chapters. For
each architecture, precise (and valid) examples for various systems are listed
so that you can pick one of those if the above explanation isn't sufficient.
</p>

</body>
</subsection>
</section>

<section>
<title>Gentoo directives</title>
<subsection>
<title>USE</title>
<body>

<p>
The <c>USE</c> variable is probably the most important setting of all inside
<path>/etc/make.conf</path>. With this variable you define what purposes your
system serves. Each flag set in the <c>USE</c> variable enables or disables
specific support in one or more packages.
</p>

<p>
The idea is pretty simple: if your system has a DVD reader, you'll probably set
<c>dvd</c> as one of the <c>USE</c> flags to add support for DVD readers. When
you want to play DVDs as well, <c>dvdread</c> should be added. Writing DVDs will
require the <c>dvdr</c> setting.
Similar, if your system will host an IBM DB2 server (or any application you'll
use connects to such a server) you'll probably want <c>db2</c> as a <c>USE</c>
flag.
</p>

<p>
A list of all possible USE flags can be found in
<path>/usr/portage/profiles/use.desc</path>. This is a plain text file which is
also reproduced online at the <uri
link="http://www.gentoo.org/dyn/use-index.xml">Gentoo web site</uri>. But
starting to dig through this list is cumbersome as many USE flags will have no
clear description (which is <e>not</e> because we want to remain vague on the
subject, but because the USE flag is either used by different applications for
slightly different purposes, or because the topic itself is too technical).
</p>

<p>
To resolve this issue, Gentoo provides you with a default <c>USE</c> setting. To
find out what the default setting is, run <c>emerge&nbsp;--info</c> and filter
out the line that starts with <c>USE</c>:
</p>

<pre caption="Checking the default USE setting">
# <i>emerge --info | grep -E ^USE</i>
</pre>

<p>
Any setting you place in <path>/etc/make.conf</path> is <e>added</e> to the USE
flag - you don't substitute the default setting but embrace and extend it.
Therefore you need to place a hyphen in front of the USE flags you do not want.
For instance, the <c>arts</c> USE flag (which enables support for the aRts sound
daemon) might be set by default. To deselect it, use <c>-arts</c>. As an example
we'll select support for the Enlightened Sound Daemon and disable support for
aRts:
</p>

<pre caption="Example USE flag">
USE="-arts esd"
</pre>

<p>
There are also USE flags that are specific to a single package. Such USE flags
are called <e>local USE flags</e>. Although you can set those USE flags in
<path>/etc/make.conf</path>, it is wiser to enable or disable those USE flags on
a per-package basis. We'll refrain from explaining how to do this here - you
don't need to set USE flags during the installation, Portage is intelligent
enough to handle USE flag changes after an installation.
</p>

<p>
Before we go on with the next setting there are four remarks we want to make
regarding USE flags:
</p>

<ol>
  <li>
    Changing the USE flag in this stage of the installation might result in
    Portage downloading tools you don't want to install at this point yet.
    A frequently occurring issue is where a USE flag combination triggers the
    installation of <c>kde-base/kdebase</c> which is a quite huge build. You
    should consider altering the USE flags at any point later and ask Portage 
    to just rebuild those tools that are affected by the USE flag change.
  </li>
  <li>
    USE flags allow Gentoo to make decisions regarding <e>optional</e> support
    and features. If any feature or support is not optional but mandatory or
    inherent to the package, the respective USE flags are ignored. A good
    example here is the <c>qt</c> USE flag. If a package can (but doesn't have
    to) support the Qt Graphical Widget library, it uses the <c>qt</c> USE flag
    to decide whether or not to build in support for Qt. If the package requires
    Qt to function, it'll install Qt regardless of USE flag.
  </li>
  <li>
    Some packages override the default USE flag settings (not the one you
    specify in <path>/etc/make.conf</path> though) if you install them. For
    instance, the <c>tetex</c> USE flag is not set by default, but when you
    install the TeX distribution, Gentoo will automatically enable the 
    <c>tetex</c> USE flag so that other programs can now be built with
    TeX support if they can handle it.
  </li>
  <li>
    If you want to hard-set a custom USE flag listing regardless of the default
    USE flags, you can start with deactivating all USE flags and then list those
    you want to enable. This can be accomplished using
    <c>USE="-*&nbsp;flag1&nbsp;flag2&nbsp;..."</c>.
  </li>
</ol>

</body>
</subsection>
<subsection>
<title>The Gentoo Portage repository</title>
<body>

<p>
Any Gentoo package information is stored inside an ebuild. That is a small text
file which contains some metadata about the package (like the description, home
page, source code location, ...) and instructions for Gentoo on how to
succesfully build and deploy the package on your system.
</p>

<p>
The complete set of all supported ebuilds is stored inside the Gentoo Portage
Tree, also known as the Gentoo Portage Repository. You will find a snapshot of
this repository at <path>/usr/portage</path> where all the ebuilds are
categorised by function and name. Gentoo Portage, Gentoo's software management
tool, builds decisions such as "What packages should be updated" or "What
software is available for installation" based on the content of the repository
snapshot <e>on your disk</e>. 
</p>

<p>
It is therefore quite important that you regularly update the snapshot on your
disk with the latest Gentoo Portage Repository content released by the Gentoo
Developers. By default, Gentoo Portage chooses a random mirror<sup>1</sup> but
it is more efficient to use a mirror that is either close to you or fastest for
your environment. The <c>SYNC</c> variable is where you put the location of the
Gentoo Portage Repository where you want to take a snapshot of.
</p>

<p>
Because you can't know what mirrors are available, Gentoo provides an easy to
remember naming scheme for the mirrors. The default setting picks a random
mirror. The country-based still picks a random mirror, but only of a pool of
mirrors inside that country. The single mirror syntax always picks the mirror
you define.
</p>

<pre caption="Mirror syntax">
<comment>(Default)</comment>       rsync://rsync.gentoo.org/gentoo-portage
<comment>(Country-based)</comment> rsync://rsync.${COUNTRYCODE}.gentoo.org/gentoo-portage
<comment>(Single mirror)</comment> rsync://rsync#.${COUNTRYCODE}.gentoo.org/gentoo-portage
</pre>

<p>
An example setting for <path>/etc/make.conf</path> could be:
</p>

<pre caption="Setting the SYNC variable">
SYNC="rsync://rsync3.us.gentoo.org/gentoo-portage"
</pre>

<note>
<sup>1</sup> A mirror is a location on a server on the Internet where the exact
content of another server location is replicated. The idea behind mirrors is to
decrease the stress put on a single server by allowing clients to retrieve the
data from various sources.
</note>

</body>
</subsection>
<subsection>
<title>Gentoo source code location</title>
<body>

<p>
Most Gentoo ebuilds inform Gentoo about the original location of the source
code. This could be a mirror set (like with the many sourceforge hosted
projects) or a fixed URL. Some ebuilds can't point to this location for whatever
possible reason. If this is the case, the source code is pushed on the Gentoo
mirrors in a specific location called the <path>distfiles/</path> directory.
</p>

<p>
The <c>GENTOO_MIRRORS</c> variable declares what mirrors Gentoo Portage should 
check to find the required source code. Each mirror declared in this variable
should point to the parent location of the mirror (i.e. not the
<path>distfiles/</path> directory but one level higher). A list of possible
mirrors can be found <uri
link="http://www.gentoo.org/main/en/mirrors.xml">online</uri>.
</p>

</body>
</subsection>
</section>

<section>
<title>Bootstrapping</title>
<subsection>
<title>What is bootstrapping?</title>
<body>

<p>
A bootstrap procedure prepares a system with the c library and compiler
specifically for a certain environment. This procedure is very sensitive for
problems which is why you shouldn't touch the bootstrap script (called
<path>bootstrap.sh</path> inside <path>/usr/portage/scripts</path>).
</p>

<p>
And because you shouldn't really touch it, you also don't really need to perform
a bootstrap yourself: if you are using a stage-2 or stage-3 tarball, the
bootstrapping has already been done. If you do want to rebuild your system (for
instance, because you altered your compiler directives), you should follow the
method explained next.
</p>

</body>
</subsection>
<subsection>
<title>Bootstrapping your system from stage 3</title>
<body>

<p>
If you are performing a bootstrap installation where you don't alter the
<path>bootstrap.sh</path> script, the procedure should perform the following
steps:
</p>

<ol>
  <li>Use your current toolchain to rebuild itself using the new settings</li>
  <li>
    Use the new toolchain to rebuild itself again. Unlike the previous time,
    your toolchain is now built, not only with the new settings, but also by a
    toolchain built with those settings.
  </li>
  <li>
    Use the new toolchain to build the rest of the packages using the new
    settings.
  </li>
  <li>
    Rebuild the packages again to make sure that all packages are built against
    rebuilt libraries. If you don't have any circular dependencies, this won't
    be necessary, but as you will probably not know if this is the
    case<sup>1</sup> it is better to perform this step anyway.
  </li>
</ol>

<p>
These steps can all be performed using the following commands:
</p>

<pre caption="Bootstrapping the system">
# <i>emerge -e system</i>
# <i>emerge -e world</i>
# <i>emerge -e world</i>
</pre>

<p>
To be honest, the last <c>emerge -e world</c> will rebuild some tools that don't
need to be rebuilt: the <e>world</e> collection (all packages that should be
installed on your system) contains the <e>system</e> collection (all packages
that are vital for your system) as well, so that the system collection is built
three times where it only needs to be built twice. 
</p>

<p>
Since in this stage of the installation you don't have any differences between
the system collection and the world one, performing <c>emerge -e system</c>
twice instead of the system-world-world combination is sufficient.
</p>

<note>
<sup>1</sup> Although Portage can detect circular dependencies, it only detects
those on metadata level. That means that it depends on the content of the
ebuild, written by the package maintainer, and not on the <e>real</e>
dependencies that the package has (the maintainer can always miss one or two
that are almost always met) so Portage doesn't know that it needs to rebuild the
dependency before the package.
</note>

</body>
</subsection>
<subsection>
<title>Bootstrapping your system from stage 1</title>
<body>

<p>
When you need to bootstrap your system different from the procedure set forth in
the <path>bootstrap.sh</path> script, you can use any tarball you like,
including a stage1. You can base your bootstrap procedure from the one
documented in the <path>bootstrap.sh</path> script but you don't have to.
However, make sure that the toolchain you build it built with Portage (using
<c>emerge</c>), otherwise the Portage database will be inconsistent.
</p>

<pre caption="Bootstrapping the toolchain">
# <i>/usr/portage/scripts/bootstrap.sh</i>
</pre>

</body>
</subsection>
</section>

<section>
<title>Progressing from a bootstrapped system</title>
<subsection>
<title>Installing core system packages</title>
<body>

<p>
A bootstrapped system doesn't offer much beyond some libraries and compiler. You
will need additional core system packages before you can actually work on your
system. Gentoo Portage obtains a list of core system packages from your profile
and installs them on your system after building them with the bootstrapped
toolchain.
</p>

<p>
The list of core system packages is available as the <e>system</e> keyword for
<c>emerge</c>. <c>emerge</c> is Gentoo's command-line interface to Gentoo
Portage, Gentoo's software management system. 
</p>

<p>
If you have bootstrapped your system previously, or you are installing Gentoo
through a stage-2 tarball, or you are installing Gentoo through a stage-3
tarball but want to rebuild your packages with the configuration directives
you've set in your <path>make.conf</path> previously, run the following command
to build all core system packages for your profile:
</p>

<pre caption="Building core system packages">
# <i>emerge -e system</i>
</pre>

<p>
Remember, most users will not need to perform this step: the stage3 tarball
provided by Gentoo already contains a prepared system.
</p>

</body>
</subsection>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-install-configure.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-configure.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-configure.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-configure.xml
===================================================================
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/draft/complete/hb-install-configure.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

<version>0.0</version>
<date>2005-06-19</date>

<section>
<title>File system information</title>
<subsection>
<title>The fstab file</title>
<body>

<p>
<path>fstab</path> stands for <e>file system table</e>; when you would take a
look at a fully configured <path>/etc/fstab</path> file you can easily see why:
</p>

<pre caption="Example fstab file">
/dev/sda8               /             ext3    defaults,noatime          0 0
/dev/sda5               none          swap    sw                        0 0
/dev/sda6               /boot         ext2    noauto,noatime            0 0
/dev/sda7               /home         ext3    defaults,noatime,noexec   0 0
/dev/cdroms/cdrom0      /media/cdrom  auto    defaults,user,noauto      0 0

none                    /proc         proc    defaults                  0 0
none                    /dev/shm      tmpfs   defaults                  0 0
</pre>

<p>
Each line declares what storage location (first field) is mounted at a certain
location (second field) using a file system (third field) and mounted with
one or more options (fourth field). The last two numbers are not that actively
used anymore so you can safely set them to <path>0 0</path>.
</p>

<p>
It is vital that your <path>/etc/fstab</path> file is a reflection of your
environment. By default, Gentoo offers an almost empty <path>/etc/fstab</path>
file with illegal storage locations (such as <path>/dev/BOOT</path> and
<path>/dev/ROOT</path>). Any user should change the file, otherwise the system
might not boot.
</p>

<p>
The <path>fstab</path> file is used during the system boot procedure to find out
what file systems should be mounted, but also during regular system operation.
For instance, when you insert a CD in your CD-ROM player, Linux ought to know
where it should mount the CD so that you (and perhaps other users) can reach it.
</p>

</body>
</subsection>
<subsection>
<title>Mount options</title>
<body>

<p>
The mount options which you can place in the fourth field in
<path>/etc/fstab</path> are well documented in the <c>mount</c> manual page:
</p>

<pre caption="Reading the mount manual page">
# <i>man mount</i>
</pre>

<p>
Each set of mount options is documented in a section pertaining to the file
system used (for instance, ext2, reiserfs, ...). Some of them are available to
all file systems, such as <c>defaults</c>, <c>auto</c> or <c>noauto</c>
(automatically mount file system or not).
</p>

</body>
</subsection>
<subsection>
<title>Special file systems</title>
<body>

<p>
Some lines in the <path>/etc/fstab</path> file have a <e>none</e> as the storage
2527