[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
location. Such file systems are <e>pseudo file systems</e> and do not require
any storage on the disk.
</p>

<ul>
  <li>
    The <e>proc</e> file system represents kernel information (like
    statistics, hardware settings, process information, memory data, ...) as
    regular files on the file system. You can read from those files to obtain
    the information you need, but these files are never actually written to
    disk. Every time you read them, the information is recalculated.
  </li>
  <li>
    The <e>tmpfs</e> file system is storage located entirely in memory. Although
    it is extremely fast, it is also volatile meaning that it loses its content
    when you reboot the system. The <e>tmpfs</e> file system is often used for
    temporary file storage (hence the name), but in the previously given
    <path>/etc/fstab</path> example it serves as a storage point for certain 
    applications who want to share memory without using the shared memory
    functionality offered by the c library.
  </li>
  <li>
    The <e>sysfs</e> file system (not shown in the example as Gentoo mounts
    <path>/sys</path> automatically when it is present) is the successor of the
    proc file system. It servers the same purpose, but is restructured so it
    scales well in larger environments.
  </li>
</ul>

</body>
</subsection>
<subsection>
<title>Edit /etc/fstab</title>
<body>

<p>
Don't forget to edit <path>/etc/fstab</path> to suit your environment. You can
use <c>nano</c> to open the file:
</p>

<pre caption="Editing /etc/fstab">
# <i>nano -w /etc/fstab</i>
</pre>

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

<section>
<title>System logging</title>
<subsection>
<title>Purpose of logging</title>
<body>

<p>
The system logger is an important <e>daemon</e> on the system. A daemon is a
tool that runs in the background; you can't work with it interactively.
</p>

<p>
The job of the system logger is to obtain information from various processes
(and in certain configurations even from remote processes) like logon events,
web server requests, security events, kernel messages, ... and write them down
in separate files: log files.
</p>

<p>
Such log files can then be used to resolve issues on the machine (hardware
errors are usually quite verbose), generate usage statistics (for instance for
web servers), backtrack logon events (for security purposes), etc.
</p>

</body>
</subsection>
<subsection>
<title>Installing a system logger</title>
<body>

<p>
Gentoo provides various system loggers, each of them with their own pros and
cons: <c>metalog</c>, <c>newsyslog</c>, <c>socklog</c>, <c>sysklogd</c> and
<c>syslog-ng</c>. Which one you choose is up to you, but it is quite important
that you pick one: if you do not install a system logger, all events will be
displayed on your terminal, cluttering up your screen instead of nicely
archiving the events in files.
</p>

<pre caption="Installing a system logger">
# <i>emerge &lt;systemlogger&gt;</i>
</pre>

<p>
Next you'll need to add the system logger of your choice to the default run
level:
</p>

<pre caption="Adding the system logger to the default runlevel">
<comment>(First find out how the init script is called)</comment>
# <i>ls /etc/init.d</i>

<comment>(Then, add it to the default runlevel)</comment>
# <i>rc-update add &lt;initscript&gt; default</i>
</pre>

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

<section>
<title>System information</title>
<subsection>
<title>Root password</title>
<body>

<p>
With the <c>passwd</c> tool you can set or change any user account password. At
first, you need to set the <e>root</e> user his password. Run <c>passwd</c> and
enter the new password. The tool will ask you to confirm the password by
reentering it after which the password is updated.
</p>

<pre caption="Setting the root user password">
# <i>passwd</i>
</pre>

<p>
You might want to verify that your keyboard settings are correct before you
enter the root password. If the keyboard settings deviate a bit from what you
expect them to be, your root password might actually differ from the one you
thought you have entered. As the <c>passwd</c> tool does not echo the characters
on screen, you can not verify the password by just looking at it.
</p>

<p>
On most Gentoo installations, the password itself will be stored in a hashed
format in <path>/etc/shadow</path> which is only readable by the root user.
Hashed means that the password itself is not shown, but a mathematical result
based on the password. A hash gives a theoretically unique value based on
certain input (here: the password) but from which you can not revert (i.e. you
can not use the hash to obtain the password).
</p>

<p>
The <path>/etc/passwd</path> file, which contains user account information, is
readable by any user. Note though that this file does not always contain your
user account information - larger networks will probably store this information
on a central server (for instance an LDAP server). Where to look for the account
information is stored in <path>/etc/nsswitch.conf</path> at the <c>passwd</c>
field.
</p>

</body>
</subsection>
<subsection>
<title>User account</title>
<body>

<p>
Next, it is <e>heavily</e> recommended to create a user account for daily tasks.
The root user is all-powerful; any mistyped command can severely damage your
system. Running your applications as the root user also exposes you to security
breaches - although not many Linux viruses exist, the damage that a virus can do
depends on the privileges it obtains, and it obtains the privileges from the
tool whose flaw it has exploited.
</p>

<p>
To create a user, use <c>useradd</c> and pass on the <c>-m</c> option so that
the user's home directory (<path>/home/username</path> for the <e>username</e>
user) is created. Also add the groups to which you want to make the user part
of:
</p>

<pre caption="Creating a user">
# <i>useradd -m -g users -G wheel,audio,cdrom,games,users,portage john</i>
</pre>

<p>
Most groups are self-explanatory, the <e>wheel</e> and <e>portage</e> groups
might need a small introduction.
</p>

<p>
The <e>wheel</e> group contains all users who can run <c>su</c> to switch from
one user to another (including the root user). Only put trusted users in this
group. A better alternative to the <e>wheel</e> access (since it still requires
the user to know the passwords of the accounts it wants to switch to) is to use
<c>sudo</c> of which an excellent <uri
link="http://www.gentoo.org/doc/en/sudo-guide.xml">guide</uri> exists on the
Gentoo web site.
</p>

<p>
The <e>portage</e> group contains all users who should be allowed to run
<c>emerge</c> and other portage-related tools for <e>querying</e> the database.
This doesn't allow those users to install or uninstall software though, you
still need to be root for that, or have equivalent access.
</p>

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

<section>
<title>Networking information</title>
<subsection>
<title>Introduction</title>
<body>

<p>
To configure your wired network, Gentoo uses the <path>/etc/conf.d/net</path>
file. Its syntax might seem a bit strange at first - you'll find 
well-documented examples at <path>/etc/conf.d/net.example</path> - but allows
you to configure your entire network easily.
</p>

</body>
</subsection>
<subsection>
<title>Automatic IP retrieval</title>
<body>

<p>
If your network interface(s) should retrieve their configuration automatically
(using DHCP) you don't need to do anything in this file - you can leave it
empty. You will find that Gentoo gives a cosmetical warning that it assumes DHCP
since you haven't provided anything. If you don't want any warning, explicitly
enable DHCP for each interface:
</p>

<pre caption="Specifying DHCP for eth0">
config_eth0=( "dhcp" )
</pre>

<p>
Don't forget to install a DHCP client. Available ones are <c>dhcpcd</c>,
<c>dhclient</c> (in the <c>dhcp</c> package), <c>udhcpc</c> (in the <c>udhcp</c>
package) and <c>pump</c>.
</p>

<pre caption="Installing a DHCP client">
# <i>emerge dhcpcd</i>
</pre>

<p>
If you want to pass additional options to the DHCP client (we refer you to the
man page of each DHCP client for more information about the available options)
use the <c>&lt;client&gt;_&lt;interface&gt;</c> directive. For instance, to set
the time out to 10 seconds (the default for most clients is 1 minute) for the
<c>dhcpcd</c> client:
</p>

<pre caption="Setting the DHCP time out">
dhcpcd_eth0="-t 10"
</pre>

</body>
</subsection>
<subsection>
<title>Static IP address</title>
<body>

<p>
If your interface should be configured with a static IP address, you need to
provide the following information:
</p>

<ul>
  <li>the IP address, </li>
  <li>
    the gateway (where the network packets for different networks should hop
    to first) address, and
  </li>
  <li>
    the domain name server(s) (which translate hostnames to IP addresses)
  </li>
</ul>

<p>
For instance, suppose that your IP address is 192.168.0.2 and you're part of a
network where all IP addresses start with 192.168.0, then you specify:
</p>

<pre caption="eth0 configuration for a static IP address in /etc/conf.d/net">
config_eth0=( "192.168.0.2/24" )
</pre>

<p>
The <c>/24</c> tells the configuration that the first three numbers (each number
uses 8 bits, so 24 bits in total) define the network and the last number the
host. If all of your IP addresses start with 192.168, then the configuration
would read <c>192.168.0.2/16</c>.
</p>

<p>
Next, we need to define where all network packets should go to if they aren't
meant for the internal network: the <e>gateway</e>. For instance, if 192.168.0.1
would be the gateway:
</p>

<pre caption="Adding routing information">
route_eth0=( "default via 192.168.0.1" )
</pre>

<p>
The last setting defines where the domain name service servers are. These DNS
addresses translate hostnames (such as <c>www.google.com</c>) to an IP address
(such as <c>66.249.93.104</c>). Save <path>/etc/conf.d/net</path> first and then
open <path>/etc/resolv.conf</path>:
</p>

<pre caption="Example /etc/resolv.conf">
<comment># Substitute the IP addresses with your DNS server addresses
# Contact your network administrator or ISP if you don't know what to enter.</comment>
nameserver 195.130.130.133
nameserver 195.130.131.10
</pre>

</body>
</subsection>
<subsection>
<title>The hosts file</title>
<body>

<p>
The <path>/etc/hosts</path> file is a small table the system uses to make
immediate translations between hostnames and IP addresses. This file should
at least contain one line:
</p>

<pre caption="Important line in /etc/hosts">
127.0.0.1       localhost
</pre>

<p>
All other lines should be set under that line using the following syntax:
</p>

<pre caption="Syntax for /etc/hosts">
&lt;ip address&gt; &lt;fully qualified hostname&gt; &lt;aliases&gt;
</pre>

<p>
For instance, if you want to assing the host name <c>gentoobox</c> to your eth0
interface address (for instance, 192.168.0.2):
</p>

<pre caption="Example /etc/hosts line">
192.168.0.2     gentoobox
</pre>

<p>
If you use a domainname for your network (like <c>boxes</c>, but it can also be
a real reserved domain name like <c>company.com</c>), you should set it like so:
</p>

<pre caption="Example /etc/hosts line for named network">
192.168.0.2     gentoobox.boxes     gentoobox
</pre>

<p>
Next to the host names assigned to your interfaces, you can also add in the IP
address and hostname information for the other hosts on your system if they
aren't known to the DNS servers you've specified (in
<path>/etc/resolv.conf</path>, perhaps automatically with DHCP).
</p>

</body>
</subsection>
<subsection>
<title>Automatically starting the network at boot</title>
<body>

<p>
With the configuration in place, your next step would be to assure that the
configuration is loaded when you boot your system. Go to
<path>/etc/init.d</path> and make symbolic link from the <path>net.lo</path>
init script to the interfaces you need. For instance, if you have one interface
(called <c>eth0</c>):
</p>

<pre caption="Automatically starting the eth0 interface at boot">
# <i>cd /etc/init.d</i>
# <i>ln -s net.lo net.eth0</i>
# <i>rc-update add net.eth0 default</i>
</pre>

<p>
These commands might need some explanation:
</p>

<ul>
  <li>
    The <c>ln</c> command makes a named link to a file (in this case,
    <path>net.lo</path>) called <path>net.eth0</path>. This file shouldn't exist
    before you run this command. There are two types of links one can make:
    <ul>
      <li>
        <e>symbolic</e> links merely point to a file or directory. If you remove
        the destination (like <path>net.lo</path>) then the file is really gone
        - the symbolic link will point to a non-existing file. You can create a
        symbolic link using the <c>-s</c> option to the <c>ln</c> command.
      </li>
      <li>
        <e>hard</e> links don't just point to a file, they are actually a second
        name for the same file. If you remove the destination file, the hard
        link still contains the content of that file. More technically, if you
        create a file, you actually reserve some space on a device and create a
        hard link to it. <c>ln</c> just makes a second hard link to it.
      </li>
    </ul>
    The advantage to using hard links should be obvious - if you remove one, the
    content still remains accessible through the other link. However, hard links
    have one disadvantage to symbolic links: they can not point to files on a
    different file system. Symbolic links can.
  </li>
  <li>
    The <c>rc-update</c> command configures the boot sequence Gentoo Linux goes
    through when starting the system. By using the <c>add</c> option, you tell
    the system that the given script (in this case, <path>net.eth0</path>)
    should be added to the <c>default</c> runlevel.
    <ul>
      <li>
        A <e>runlevel</e> is a name for a certain set of scripts that need
        to be started in order for the system to function. By default, Gentoo
        calls its default runlevel ... default. Others are <c>nonetwork</c>
        (which doesn't start network related scripts), <c>boot</c> (important
        scripts that <e>must</e> be started) and <c>single</c> (where only those
        scripts are started that are needed for an administrator to be able to
        fix a broken system).
      </li>
      <li>
        The script <path>net.eth0</path> is an <e>init script</e>. Such scripts
        are written using a specific syntax and reside in
        <path>/etc/init.d</path>.
      </li>
    </ul>
  </li>
</ul>

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

<section>
<title>Various configuration settings</title>
<subsection>
<title>The /etc/rc.conf file</title>
<body>

<p>
The <path>/etc/rc.conf</path> file contains system-wide settings for the entire
system. You will find lots of variables already defined in the file, accompanied
with lots of documentation.
</p>

<p>
The first variable you'll see is the <c>UNICODE</c> variable. Unicode (also
known as UTF-8) is the new standard for character encoding. Character encoding
tells the system what sequence of bits resembles what character. Well-known
encodings are ASCII, ISO-8859-1, etc. The UTF-8 or Unicode encoding is important
because it is able to provide encodings for every possible language (including
special characters like €, but also chinese characters, etc.).
</p>

<p>
If you are interested in using Unicode on your system, please read the <uri
link="http://www.gentoo.org/doc/en/utf-8.xml">UTF-8 Guide</uri> on the Gentoo 
web site.
</p>

<p>
Another variable of importance is the <c>DISPLAYMANAGER</c>. A display manager
is a tool which shows a graphical logon screen after having booted your system.
Most display managers even allow you to automatically log on as a specific user.
If you want to use a display manager, you need to install one, add the
<c>xdm</c> init script to the default runlevel and make sure that this variable
points to the display manager of your choice.
</p>

<p>
Together with the <c>DISPLAYMANAGER</c> variable you'll find the <c>XSESSION</c>
one. This tells the display manager what graphical environment it should load by
default if the user didn't specify one explicitly. Well-known graphical
environments are KDE, GNOME, XFCE, fluxbox, ... For specific instructions on how
this variable influences the graphical logon process please read the comments in
the <path>rc.conf</path> file.
</p>

</body>
</subsection>
<subsection>
<title>Select keyboard language</title>
<body>

<p>
If you aren't using a US Qwerty keyboard, you'll need to edit the
<path>/etc/conf.d/keymaps</path> file to tell the Gentoo system what keyboard
layout it should use. 
</p>

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

</sections>



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

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-kernel.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-kernel.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-kernel.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-kernel.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Kernel configuration procedure</title>
<subsection>
<title>Introduction</title>
<body>

<p>
The Linux kernel is the core of the Linux Operating System. It takes care of
resource management (processes, memory, ...), hardware support, networking, file
systems, ... and is therefore one of the most vital parts of the system.
</p>

<p>
Gentoo offers various kernel sources. Each source is based on the <e>vanilla</e>
kernel source (the one developed by the main kernel developers) and adds in
additional features, hardware support, experimental features, etc. You can pick
whatever kernel source you like for your system (as long as your profile allows
it of course).
</p>

<p>
When the source code is installed on your system, you still need to configure
and build the kernel before you can use it. The kernel configuration is the
trickiest part since a mistake can lead to an unusable kernel, but trying to
build in too much leads to irrelevant code in your kernel which you'll never
use, take space and might even cause troubles later when there is a kernel bug
in that code.
</p>

<p>
Luckily, Gentoo offers a tool called <c>genkernel</c> which configures, builds
and installs a kernel automatically. This might be of interest to you if you
have no idea about configuring kernels, you want a basic kernel configuration
for all your systems, or you require a kernel that can deal with a majority of
hardware.
</p>

<p>
After configuring the kernel, it is built into an image which your computer
loads in memory when you boot the system. 
</p>

</body>
</subsection>
<subsection>
<title>Picking a kernel source</title>
<body>

<p>
Gentoo maintains a list of <uri link="/doc/en/gentoo-kernel.xml">supported
kernel sources</uri> which contains a small introduction about the kernel tree.
You can make your choice from this guide, although you can very well pick a
fairly generic one right now and use a different kernel later on - the kernel is
completely interchangeable on a Linux environment so you don't have to decide on
the kernel right here, right now.
</p>

<p>
The most default, generic kernel source is the <c>vanilla-sources</c>. This
kernel tree is the one released by the Linux Kernel Developers, unmodified.
Gentoo offers a patched version itself called <c>gentoo-sources</c>. Using these
sources has the advantage that Gentoo can release a new kernel tree whenever it
deems it necessary.
</p>

<p>
If you have made your choice, install the kernel sources using <c>emerge</c>.
Just add the kernel source name as an argument to <c>emerge</c> and
<c>emerge</c> will download and extract the kernel sources on your system:
</p>

<pre caption="Installing the kernel sources">
# <i>emerge &lt;kernelsources&gt;</i>
</pre>

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

<section>
<title>Building the kernel</title>
<subsection>
<title>Automated build process</title>
<body>

<p>
If you don't want all the hassle surrounding the kernel installation, you can
install <c>genkernel</c> and then have <c>genkernel</c> configure, build and
install the Linux kernel for you. This process is quite simple:
</p>

<pre caption="Using genkernel">
# <i>emerge genkernel</i>
# <i>genkernel all</i>
</pre>

<p>
However, <c>genkernel</c> is a lot more powerful than this. With this tool, you
can maintain your personal kernel configuration and let the tool rebuild newer
kernel versions with your settings. You can enable specific features (like
bootsplash, lvm2, evms2, raid, ...) and tweak the compiler settings used during
the kernel build process (which <e>differs</e> from the settings placed in
<path>make.conf</path>!).
</p>

<p>
For more information on <c>genkernel</c>, please read the <uri
link="/doc/en/genkernel.xml">Genkernel Guide</uri>.
</p>

</body>
</subsection>
<subsection>
<title>Manual build process</title>
<body>

<p>
The manual build process consists out of three steps:
</p>

<ul>
  <li>configuring the kernel, </li>
  <li>building the kernel, and</li>
  <li>installing the kernel</li>
</ul>

<p>
To configure the kernel, go to <path>/usr/src/linux</path> and run
<c>make&nbsp;menuconfig</c>. You will get a dialog-based interface where you can
configure your kernel.
</p>

<p>
Configuring a kernel isn't hard if you know what hardware you have and what
features you want - but then again, if all this is new to you, finding out what
features you want or need can be time consuming.
</p>

<p>
The kernel configuration dialogs has a good <e>Help</e> built-in which even
includes search functionality (very useful if you want to search for the
location of that network card you have but can't seem to place in the
configuration structure). 
</p>

<p>
It is not our intention to describe the kernel configuration process for
you - there are several guides about this topic on the Internet and if you
really aren't able to succesfully configure a kernel, use <c>genkernel</c> for
the time being.
</p>

<p>
When you're finished with the configuration part, build the kernel by running
<c>make</c> (hold on, we'll do this together with the next step). <c>make</c> 
is a tool that reads in a script called <path>Makefile</path>
in the directory you are in. <path>Makefile</path>s are very powerful when used
for building software since they are able to only (re)build those parts that
need to be (re)build instead of building the entire software over and over
again.
</p>

<p>
To finish the kernel build process, you need to copy over the resulting kernel
image to the boot partition and install the kernel modules you have selected.
The location of the kernel image depends on the architecture you're using. The
following table gives an overview of possible kernel images with the commands
needed to build and install the kernel:
</p>

<table>
<tr>
  <th>Architecture</th>
  <th>Image Location</th>
  <th>Build Command</th>
</tr>
<tr>
  <ti>alpha</ti>
  <ti><path>arch/alpha/boot/vmlinux.gz</path></ti>
  <ti>
    <c>make &amp;&amp; make modules_install &amp;&amp; make boot</c>
  </ti>
</tr>
<tr>
  <ti>amd64</ti>
  <ti><path>arch/x86_64/boot/bzImage</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
<tr>
  <ti>hppa</ti>
  <ti><path>vmlinux</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
<tr>
  <ti>mips</ti>
  <ti><path>vmlinux</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
<tr>
  <ti>ppc Apple/IBM</ti>
  <ti><path>vmlinux</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
<tr>
  <ti>ppc Pegasos</ti>
  <ti><path>arch/ppc/boot/images/zImage.chrp</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
<tr>
  <ti>ppc64</ti>
  <ti><path>vmlinux</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
<tr>
  <ti>sparc32</ti>
  <ti><path>arch/sparc/boot/image</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
<tr>
  <ti>sparc64</ti>
  <ti><path>arch/sparc64/boot/image</path></ti>
  <ti><c>make &amp;&amp; make image modules_install</c></ti>
</tr>
<tr>
  <ti>x86</ti>
  <ti><path>arch/i386/boot/bzImage</path></ti>
  <ti><c>make &amp;&amp; make modules_install</c></ti>
</tr>
</table>

<p>
The build command is divided in two parts - the <c>make</c> instruction we've
discussed before and a specific instruction to finish off with some additional
steps. The separation is made with the <c>&amp;&amp;</c> string. This is a
specific operator to the shell, telling the system to continue with the next
command <e>if</e> the previous one didn't fail. A similar operator is <c>||</c>
which tells the system to execute the next command if the previous one
<e>did</e> fail.
</p>

<p>
Now, execute the build command to create the kernel image. When the process has
finished, copy over the file to <path>/boot</path>. It is wise to give the
kernel image file a good name in <path>/boot</path> so that you can distinguish
one kernel from another. A common used naming scheme is
<path>kernel-&lt;version&gt;</path>. The next example copies over
an x86 kernel image to <path>/boot/kernel-2.6.12-gentoo-r6</path>:
</p>

<pre caption="Copying over the kernel image to /boot">
# <i>cp arch/i386/boot/bzImage /boot/kernel-2.6.12-gentoo-r6</i>
</pre>

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

</sections>



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

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-media.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-media.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-media.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-media.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>About the Gentoo releases</title>
<subsection>
<title>Gentoo versions</title>
<body>

<p>
One of Gentoo's major advantages is that it does not really know
<e>versions</e>. Once installed, you have a Gentoo installation, not a Gentoo
2005.1 or 2004.3 installation. Therefore you will continue to benefit from the
Gentoo development with every system update you perform - there is no need to
run through a specific upgrade procedure every time Gentoo makes a new release.
</p>

<p>
Yes, Gentoo does <e>release</e> often - twice a year to be exact. Such a release
brings you an up to date installation CD with the latest hardware drivers and
features that might improve your installation experience. It can also contain a
set of prebuilt packages, helping you to install Gentoo quickly and efficiently.
</p>

<p>
When you hear someone talk about a specific Gentoo release (<e>Gentoo 2005.1</e>
for instance) they are talking about the installation CDs and set of prebuilt
packages, not about the state Gentoo is at at a certain point in time. Gentoo
evolves on a daily basis, but can't develop, package, test and release new
installation CDs and prebuilt packages every time Gentoo changes...
</p>

</body>
</subsection>
<subsection>
<title>Gentoo release media</title>
<body>

<p>
By default, Gentoo releases installation CDs: bootable CDs allowing you to
immediately boot in a Gentoo Linux environment containing the necessary tools to
help you install Gentoo on your system. Such CDs shouldn't be read from any
other operating system but immediately booted from.
</p>

<p>
For each architecture (see the note below) you will find two installation CDs: 
a <e>minimal</e> installation CD and a <e>universal</e> one. They both contain
the same hardware support drivers (Linux kernel and additional kernel modules)
and tools; the universal installation CD however also contains the necessary 
files to allow any user to install Gentoo without requiring a working Internet
connection.
</p>

<p>
It is important to understand that:
</p>

<ol>
  <li>
    the Gentoo installation procedure is a <e>manual</e> procedure, requiring
    lots of input from the administrator
  </li>
  <li>
    there is support for a networkless installation <e>if</e> you use the
    universal installation CD and the stage-3 installation approach (which will
    be discussed later), but that Gentoo should not be considered if you don't
    have a working Internet connection
  </li>
</ol>

<p>
You will also find a <e>packages</e> CD. As the name implies, this CD contains
prebuilt packages you can quickly install to get a working Gentoo installation
without going through much software building. 
</p>

<p>
<e>However</e>, these software packages are only available for those who perform
a networkless installation and are not maintained by the Gentoo project at all:
they are only meant for use during the initial installation of Gentoo. Once
installed, your system is not different from any other Gentoo installation.
</p>

<p>
This part will not talk about the networkless installation. We have decided to
postpone any information regarding prebuilt packages to a later stage because of
the following reasons:
</p>

<ul>
  <li>
    The networkless installation instructions are limiting the user's choices.
    Only a fraction of the software which a user can (and should) install during
    installation is available and the user might not be able to deviate from the
    standard installation routine.
  </li>
  <li>
    The set of prebuilt software is quickly outdated. As Gentoo does not offer a
    continuously maintained repository of prebuilt packages, any user who does a
    networkless installation might be facing an installation with insecure
    software for the time between the (quick) installation and (slower)
    upgrading.
  </li>
  <li>
    The available prebuilt software differs from architecture to architecture,
    from release to release. If one wants to have pseudo-static documentation on
    the Gentoo installation procedure, such variable information should be 
    eliminated.
  </li>
</ul>    

<note>
An architecture is a family of CPUs who support the same instructions. The most
known architecture in the desktop world is <e>x86</e>, referring to the
Intel-compatible systems. Others are <e>sparc</e>, <e>ppc</e>, <e>mips</e>, ...
<e>amd64</e> is also an architecture although it has additional Intel
compatibility. If you are not sure what architecture to pick, don't hesitate to
ask. <br/>
Incidentally, <e>amd64</e> is the most common answer to that question,
followed by <e>x86</e> :)
</note>

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

<section>
<title>Gentoo installation approaches</title>
<subsection>
<title>Introduction</title>
<body>

<p>
You should understand that the Gentoo installation procedure - at least the
officially publicised one - is quite different from most other Linux
distributions: where other distributions try to perform most steps for you,
Gentoo Linux asks you politely (but firmly) to do things yourself.
</p>

<p>
Getting the hardware up and running, configuring the network, partitioning your
disk(s), copying over the initial files, building additional software (including
the kernel), ... all these steps should be performed before you can finally boot
in a minimal Gentoo environment. Not that all these steps can't be automated
(Gentoo even offers tools to automate a few of those steps and you'll find a lot
of unofficial installers that automate most - if not all - steps) but by
documenting these steps in great detail Gentoo almost forces you to learn
various Linux-related procedures.
</p>

<p>
Another advantage of letting the user perform all steps himself is that the user
can now decide himself how he wants to install Gentoo - the options are there,
the user needs to make a choice, over and over again. By clearly identifying the
options and documenting the possible roads Gentoo hopes that the user is not
scared but rather impressed.
</p>

<p>
For instance, Gentoo offers the user with three initial system states where the
user can start from to install Gentoo. These states are called <e>stages</e>:
stage-1, stage-2 and stage-3.
</p>

</body>
</subsection>
<subsection>
<title>Easy and fast: stage-3</title>
<body>

<p>
The stage-3 system state starts from a minimal Gentoo environment, containing
the core system utils that anyone would need to get Gentoo up and running. This
is the preferred initial state for most users and also the quickest way to
install Gentoo. From this stage onward, the user installs the additional tools
he requires (such as certain networking tools for automated IP information
retrieval, cron jobs for scheduled process execution, system logger for keeping
track of all log events, ...) and builds a Linux kernel to boot from.
</p>

<p>
When you want to install Gentoo without a working Internet connection (the
networkless installation approach) you must use the stage-3 approach since the
universal installation CD only contains source code for the additional tools you
should install - not for the tools already available in the stage file.
</p>

<p>
Although the stage-3 system state is the most full-featured one, many users
often take this as a bloated stage thinking they can't tweak as much as they can
with the other stages. This is wrong, as you can easily rebuild the entire
system with new (compiler and <c>USE</c>) settings - and in many occasions 
faster too!
</p>

</body>
</subsection>
<subsection>
<title>Tweaking the system: stage-2</title>
<body>

<p>
The stage-2 system state contains a built and functional toolchain but no system
utilities. This is an intermediate state between a stage-1 and stage-3 and also
the least often used approach to install Gentoo with. Those who do consider
using this stage often alter their profile with respect to base system 
packages and perform major tweaks with the <c>CFLAGS</c>, <c>CXXFLAGS</c>
and <c>USE</c> variables.
</p>

<p>
Although Gentoo offers a stage-2 initial system state, you should consider
performing a stage-2 installation with a stage-3 initial system state. This will
preserve you from possible circular dependency issues that are inherent with the
stage-2 build.
</p>

</body>
</subsection>
<subsection>
<title>Tweaking the bootstrapping procedure: stage-1</title>
<body>

<p>
The stage-1 system state contains a non-optimized toolchain with no system
utilities. This is the state where Gentoo Release Engineering developers start
from to move to a stage-3 state by rebuilding the toolchain for the specific
architecture (migrating to a stage-2) and using this newly rebuilt toolchain to
install the system core utilities (migrating to a stage-3).
</p>

<p>
This state is only interesting for those attempting to change the bootstrapping
procedure (by changing the <path>bootstrap.sh</path> script) or want to build a
non-default Gentoo environment (for instance using a completely different
toolchain). 
</p>

<p>
Although Gentoo offers a stage-1 initial system state, you should consider
performing a stage-1 installation with a stage-3 initial system state. This will
preserve you from possible circular dependency issues and bootstrapping failures
inherent with the stage-1 procedure (which is quite complex).
</p>

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

<section>
<title>Download, burn and boot</title>
<subsection>
<title>Download the media</title>
<body>

<p>
With the information handed to you in the previous sections you should have an
idea what CD(s) you need to download. Gentoo provides the CDs both as an
<uri link="http://www.gentoo.org/main/en/mirrors.xml">FTP/HTTP download</uri> 
or through the <uri link="http://torrents.gentoo.org">BitTorrent</uri>
peer-to-peer network. Pick the latest version available (as that one contains
the most up-to-date hardware support and additional features) although this is
not mandatory: you can easily install a (current) Gentoo from an older
installation CD. 
</p>

<p>
As the directory structure on the FTP/HTTP mirrors suggests, you'll find the 
CDs in the <path>releases/</path> directory.
</p>

<p>
Each CD is fully contained within an ISO file. Such a file contains all the
content of a CD and should be burned on the CD using a specific (but well
supported) procedure. Most CD/DVD burning tools call it <e>Burn ISO</e> or
<e>Raw burning</e>; it differs from the regular burning methods used that it
burns the content of the file on the CD, not the file as-is (i.e. the end result
is not that you just see the single file on the burnt CD).
</p>

<p>
If you want, you can verify the downloaded ISO file using the <path>.md5</path>
file we provide. This file contains an Message Digest 5 checksum of the file, a
known mathematical result of the entire CD that is practically unique to every
file. In other words, you won't find a file anywhere with the same checksum
unless that file is identical. Under Linux, you can use the <c>md5sum</c> tool
to verify the checksum.
</p>

<p>
We also provide a digital signature of the file made with our private Release
Engineering key. This digital signature can be used to validate the origin of
the ISO file: if the digital signature matches the public key of the Release
Engineering team, then the file is authentic. Under Linux, you can use the
<c>gpg</c> tool to verify the checksum.
</p>

</body>
</subsection>
<subsection>
<title>Booting the CD</title>
<body>

<p>
To get in the initial Gentoo environment, you need to boot from the installation
CD. How to achieve this depends on the architecture you are using. The first
appendix in this book covers the various architecture-specific aspects of a
Linux system, including booting CDs.
</p>

<p>
Once booted, you will see that the installation CD already tried to load the
necessary drivers and hands you over to a <e>root prompt</e>, indicating that
the system is waiting for further input:
</p>

<pre caption="Resulting prompt after a succesful boot">
root ~#
</pre>

<p>
This is the command-line prompt. You are now booted in the initial Gentoo
environment, ready to continue. 
</p>

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

</sections>



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

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-minenv.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-minenv.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-minenv.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-minenv.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

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

<p>
The prompt you are now looking at is all-powerful, but a bit daunting at first.
If you know how the Linux command line works, this chapter will give you no
further surprises and you can easily jump to the next chapter, <e>Preparing 
the Network</e>.
</p>

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

<section>
<title>Basic navigation</title>
<subsection>
<title>Working command-line</title>
<body>

<p>
At the prompt you can enter <e>commands</e> to the Gentoo Linux environment.
Basic commands are just single words, like <c>ls</c> or <c>ps</c>. Most commands
however often require additional words to be added, like <c>cd&nbsp;/var</c> or
<c>man&nbsp;ls</c>. These added characters are called <e>arguments</e>.
</p>

<p>
More often, these arguments represent certain <e>options</e> to the command. For
instance, the <c>ls</c> command (used to list the content of a directory) can
take several options, like <c>-l</c> (for a lengthy description of each found
file), <c>-a</c> (to include hidden files), etc.
</p>

<p>
In the next Code Listing you'll see this terminology explained. The command
shown will list the content of the <path>/var/tmp</path> directory (a temporary
location) showing additional information about each file found, including hidden
files.
</p>

<pre caption="Command, arguments and options">
root ~# <i>ls -la /var/tmp</i>
&lt;--+--&gt;&lt;+&gt; &lt;+&gt; &lt;---+--&gt;
   |    |   |      `- Argument, in this case the target directory to list
   |    |   `- Argument, also two options: lengthy description + hidden files
   |    `- Command (list in this case)
   `- Prompt
</pre>

<p>
After having constructed a command, you can execute it by pressing the return
key. Your shell (the command-line environment you are currently "in" which
interprets commands and helps you navigate through the Linux environment) will
then execute the command and show you the results.
</p>

<p>
The next section will give you a crash course in certain Linux commands that
will help you explore your current minimal Gentoo environment. We won't go in
much detail - there are plenty guides and books available online that will
inform you about the basic Linux tools (<uri
link="http://http://www.chongluo.com/books/rute/">Rute's
Unix Tutorial Exposed</uri> is one of the more famous, freely available books).
</p>

</body>
</subsection>
<subsection>
<title>Navigating up and down</title>
<body>

<p>
We have already covered how a Linux file system looks like (the hierarchical
structure, remember?). To help you out we'll give you a quick overview on the
most common tools you might need to navigate on your Gentoo Linux system:
</p>

<table>
<tr>
  <th>Command</th>
  <th>Description</th>
  <th>Example</th>
</tr>
<tr>
  <ti><c>ls</c></ti>
  <ti>
    List the content of a given directory, or the current directory if no
    directory is given.
  </ti>
  <ti><c>ls&nbsp;/mnt/cdrom</c></ti>
</tr>
<tr>
  <ti><c>pwd</c></ti>
  <ti>
    Show the current working directory; this is the full pathname of the
    directory you are currently in.
  </ti>
  <ti><c>pwd</c></ti>
</tr>
<tr>
  <ti><c>cd</c></ti>
  <ti>
    Change the current working directory to a different location. If no
    directory is given, go to the user's home directory.
  </ti>
  <ti><c>cd&nbsp;/mnt/gentoo</c></ti>
</tr>
<tr>
  <ti><c>less</c></ti>
  <ti>
    Show the content of a given file on the screen. You can navigate with the
    up and down arrows through the file and quit the application by pressing
    'q'.
  </ti>
  <ti><c>less&nbsp;install.txt</c></ti>
</tr>
<tr>
  <ti><c>rm</c></ti>
  <ti>
    Remove a file from the system (if you have the required privileges). To
    remove a directory with all files in it, use the <c>-r</c> option. Be 
    careful with this command though, it won't warn you when you are about 
    to destroy all your data.
  </ti>
  <ti><c>rm&nbsp;portage.tar</c></ti>
</tr>
</table>

</body>
</subsection>
<subsection>
<title>Concurrent terminals</title>
<body>

<p>
Gentoo's installation CDs allow you to use a couple of terminals simultaneously.
That means you can work in one, browse the internet in another and chat on a
third. To switch between terminals, type <c>Alt+F#</c> (with <c>F#</c> one of
the function keys). You will notice that your current session is at <c>F1</c>.
</p>

<p>
You can also work in a terminal and then put your working session in the
background using a powerful tool called <c>screen</c>. With <c>screen</c> you
can even let other people work on your terminal while you are watching every
step they perform.
</p>

<pre caption="Working with screen">
<comment>(Starting a screen session:)</comment>
$ <i>screen -S mySession</i>
<comment>(To detach a screen session, type 'Ctrl-A' followed by a 'd')</comment>

<comment>(Reattach to a screen session:)</comment>
$ <i>screen -x mySession</i>

<comment>(To quit a screen session, just type 'exit':)</comment>
$ <i>exit</i>
</pre>

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

<section>
<title>Networking utilities</title>
<subsection>
<body>

<p>
Gentoo offers a few utilities on the installation CDs which you can use to 
surf on the Internet, download files, chat on the IRC network, etc. We will
cover a few of them in this section, but you can't use them until you have
configured your network (and Internet connection) which is described in the next
chapter.
</p>

</body>
</subsection>
<subsection>
<title>Surfing on the Internet</title>
<body>

<p>
Because no documentation can be perfect and no two environments are alike, you
will often search for additional information and help on the Internet. Websites
such as the main <uri link="http://www.gentoo.org/doc/en/index.xml">Gentoo
documentation repository</uri> or powerful search engines like <uri
link="http://www.google.com">Google</uri> are a welcome resource during your
installation quest.
</p>

<p>
To browse through these sites you need a browser. Because the Gentoo
installation CDs don't contain a graphical environment you need to use either a
different system, a different installation medium or ... a non-graphical
browser. The Gentoo installation CDs offer at least one of the following console
browsers:
</p>

<ul>
  <li>
    <c>lynx</c>, a general purpose web site browser which operates key-driven
    (for instance 'D' for downloading, 'G' to go to a different site, ...).
  </li>
  <li>
    <c>links2</c>, a featureful browser with support for frames, limited
    JavaScript, svgalib/framebuffer, background downloading, ... which operates
    both menu-driven (press 'Escape' to open the menu) as key-driven.
  </li>
</ul>

<p>
Both browsers support proxy servers, although the first one uses the standard
way (setting an <c>HTTP_PROXY</c> environment variable) while the second one
requires you to enter the proxy server in the browser.
</p>

<pre caption="Example surfing information with proxy support">
<comment>(For lynx - ignore the export command if no proxy is needed:)</comment>
$ <i>export HTTP_PROXY="http://myproxy.server.tld:8080"</i>
$ <i>lynx http://www.gentoo.org</i>

<comment>(For links2 - ignore the -http-proxy option if no proxy is needed:)</comment>
$ <i>links2 -http-proxy http://myproxy.server.tld:8080 http://www.gentoo.org</i>
</pre>

</body>
</subsection>
<subsection>
<title>Chatting on an IRC network</title>
<body>

<p>
When you can't find useful information on the Internet, you can always ask your
question on the <uri
link="irc://irc.freenode.net/gentoo-install">#gentoo-install</uri> or <uri
link="irc://irc.freenode.net/gentoo">#gentoo</uri> IRC channels on FreeNode.
Gentoo delivers a terminal-based, yet extremely powerful chat client called
<c>irssi</c>.
</p>

<p>
Its use is quite simple. First, connect to the IRC network. Then, join the
channel(s) you want to participate in. You can use Alt+F# to switch between
channels (or type in <c>/window&nbsp;#</c> if the key combination fails). To
exit the application, type <c>/quit</c>.
</p>

<pre caption="Getting online with irssi">
$ <i>irssi -c irc.freenode.net YourNickName</i>
<comment>(Wait until the connection is made)</comment>
[irssi #] <i>/join #gentoo</i>
</pre>

</body>
</subsection>
<subsection>
<title>Remote shell access</title>
<body>

<p>
The Gentoo installation CD contains an <e>SSH daemon</e>, which is a tool to
allow others to securely connect to your system so they can help you install
Gentoo. This service isn't started by default, but if you want to use it you
should:
</p>

<ol>
  <li>get the Internet connection up and running</li>
  <li>create a user account</li>
  <li>give the root account a password</li>
  <li>start the SSH daemon</li>
</ol>

<p>
If you trust the other person, you can give him your root password, but we
advise you to only give limited access to the other person - they should help
you identify errors and tell you how to resolve them, not fix the errors
themselves. Otherwise you won't learn :)
</p>

<pre caption="Steps to get the SSH service running">
<comment>(First get the Internet connection up and running, then...)</comment>
# <i>useradd -m -G users myuser</i>
# <i>passwd myuser</i>
<comment>(Give the 'myuser' user a password)</comment>
# <i>passwd</i>
<comment>(Give the 'root' user a (different) password)</comment>
# <i>/etc/init.d/sshd start</i>
</pre>

<p>
The passwords you set here are limited to the Gentoo installation CD environment
and only until you reboot. They are not used for your final Gentoo installation!
</p>

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



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

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-network.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-network.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-network.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-network.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Introduction</title>
<subsection>
<title>Why you need it ...</title>
<body>

<p>
Not everyone requires a working Internet connection, but if you <e>can</e> it is
best if you do - this part of the book only covers installations with a
working Internet connection because it is highly advantageous. Not only can 
you immediately install the latest versions of all
the Gentoo packages, it also allows you to go on the Internet to seek help and
support, or to chat while your system is installing Gentoo.
</p>

<p>
In this chapter we cover one specific network type: Ethernet. An
Ethernet network connection is often referred to as the <e>wired network</e>,
using a RJ-45 network plug. Wireless networking, also known as <e>WiFi</e> or
<e>IEEE 802.11x</e>, is also supported from the Gentoo installation CDs but not
covered in this chapter (you will find more information about it further in this
book).
</p>

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

<section>
<title>Recognizing the hardware</title>
<subsection>
<title>Auto-detection</title>
<body>

<p>
You first need to configure your system to support your network card. Chances
are that the card is already found and supported - to verify this, use the
<c>ifconfig</c> tool. This tool will tell you what interfaces are available on
your system. Interfaces are where Linux can assign IP address information to. It
can represent a networking device but doesn't have to: there are interfaces for
the local system (<e>localhost</e>, which doesn't need a network card), network
tunnels, bridges, etc.
</p>

<pre caption="Showing all available interfaces">
# <i>ifconfig -a</i>
</pre>

<p>
The above command will display statistics about each interface found on your
system. The interfaces that start with <e>eth</e> are the ones that interest us
the most. Those interfaces represent the network cards. If you have one network
card, it will probably be called <e>eth0</e>. If you have two, they would be 
called <e>eth0</e> and <e>eth1</e>, etc.
</p>

<p>
If you have several network cards, you can't tell right now what interface
represents what network card. There are several ways to find this out, but the
easiest method is to assume that eth0 is the one you are interested in - and if
it turns out your network doesn't work, try switching the cable :)
</p>

<p>
Now, if you have seen eth-interfaces then your hardware is found and 
supported and you can continue with the next section (<uri 
link="#net_config_type">DHCP or Static IP Address?</uri>). Otherwise you need to
find out what chipset your network card uses and load the necessary hardware 
support.
</p>

</body>
</subsection>
<subsection>
<title>Manual hardware discovery</title>
<body>

<p>
With <c>lspci</c> you can get an overview of all PCI devices found on your
system. The interesting part of this tool is that it shows the function of the
device <e>and</e> the brand and type, making it excellent to discover what you
have under the hood of your system.
</p>

<p>
We are interested in the <e>Ethernet controller</e> or <e>Network 
controller</e>, so we filter out the output of the <c>lspci</c> command using 
the <c>grep</c> tool, only giving us those lines that have 'Ethernet controller'
or 'Network controller' in it:
</p>

<pre caption="Showing all Ethernet controller devices">
<comment>(Substitute with 'Network controller' if this doesn't give satisfying results)</comment>
# <i>lspci | grep 'Ethernet controller'</i>
0000:06:00.0 Ethernet controller: Realtek Semiconductor Co., Ltd. RTL-8169 
  Gigabit Ethernet (rev 10)
</pre>

<p>
With this information, you can start searching for the <e>kernel module</e> that
offers support for your Ethernet card. In the above example, the 
module is <path>r8169.ko</path>. Although there is a quite efficient way to 
find out what kernel module exists for what chipset (search through the Linux 
kernel menu configuration information) we can't use this from the Gentoo 
installation CD as you don't have this configuration information available yet.
</p>

<p>
You are not left in the dark though. You can try digging through all the
available kernel modules that support network cards, hoping to find any
reference of the chipset you have. An easy method is to 'dump' a list of all
kernel modules and filter out those that contain a good identifier in their
name.
</p>

<p>
For instance, the above example could lead to the discovery of the
<path>r8169.ko</path> module using the following method:
</p>

<pre caption="Filtering the list of kernel modules">
# <i>find /lib/modules | grep -i '8169'</i>
</pre>

<p>
The <c>-i</c> tells the <c>grep</c> tool to behave case insensitive. Okay, it
doesn't matter for the example since we're asking <c>grep</c> to filter out a
number - which isn't affected by case sensitivity - but this is quite important
for different filters.
</p>

<p>
You can try out various terms that occur in the chipset name as well, either as
separate jobs, or by providing <c>grep</c> with an entire list of terms you want
to filter on. This can be accomplished by adding the <c>-E</c> option and
handing it a list, separated by '|' signs and contained within '(' and ')'. The
<c>-E</c> tells <c>grep</c> to interprete the filter as a <e>regular
expression</e>:
</p>

<pre caption="Filtering the list of kernel modules on a regular expression">
# <i>find /lib/modules | grep -iE '(8169|realtek|rtl)'</i>
</pre>

<p>
Once you have found a possible kernel module for your network card, you can try
to load it in memory using <c>modprobe</c>. This tool will search for the
module, query for possible depending modules (some modules require another
module to be loaded first) and then load the module in memory. For instance, 
for the <path>r8169.ko</path> module:
</p>

<pre caption="Loading a kernel module in memory">
<comment>(Notice that we have dropped the ".ko" suffix!)</comment>
# <i>modprobe r9169</i>
</pre>

<p>
If this command didn't fail out, try <c>ifconfig&nbsp;-a</c> again to see if you
have a working interface. If not, keep trying...
</p>

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

<section id="net_config_type">
<title>DHCP or static IP address?</title>
<subsection>
<title>Setting the IP address information</title>
<body>

<p>
Now we need to configure the interface to obtain an IP address, a unique
address that identifies your system in the network (<e>Internet Protocol
address</e>). In most environments, this can be obtained automatically using 
DHCP (<e>Dynamic Host Configuration Protocol</e>). This protocol
allows interfaces to send out a request for an IP address on the network and
receive IP address and routing information from the DHCP server (which is often
found in home routers or in enterprise environments as a stand-alone service).
</p>

<note>
TCP, the other part of the TCP/IP combo, stands for <e>Transfer Control
Protocol</e> and is responsible for the applicative communication between two
systems. It has no recollection of system addresses (that's the IP's job) but
uses <e>ports</e> instead to distinguish one communication session from another.
</note>

<p>
If you have a DHCP service on your network, you need to run a DHCP client for
your interface. With Gentoo, you have <c>dhcpcd</c> at your disposal. Other
clients exists as well though, such as <c>dhclient</c> and <c>pump</c>. To
automatically obtain an IP address for the eth0 interface, run
<c>dhcpcd&nbsp;eth0</c> after which you can continue with <uri
link="#network_testing">Testing the Network</uri>.
</p>

<pre caption="Obtaining an IP address">
# <i>dhcpcd eth0</i>
</pre>

<p>
If your network card was automatically detected by Gentoo and your network
supports DHCP, you'll probably receive a warning telling you that an instance of
<c>dhcpcd</c> is already running. That's okay, it means that the installation
already had the network configured for you.
</p>

<p>
If you need to configure your network using a static IP address, you have to
know:
</p>

<ul>
  <li>which IP address you can use,</li>
  <li>what IP address your <e>gateway</e> listens to, and</li>
  <li>
    what part of the IP address is reserved for the network
    identification
  </li>
</ul>

<p>
A <e>gateway</e> is a system that acts as the connection between your network
and the outside world. If you have a PC that shares an Internet connection
(which often uses NAT - Network Address Translation) it is most likely that its
IP address is your gateway IP address.
</p>

<p>
The network part of the IP address is what separates your IP address from an
outside IP address. For instance, if your IP address is 192.168.1.12 and all IP
addresses in your network are in the range of 192.168.1.1 to 192.168.1.255, then
the network part of the IP address are the first three numbers. This is
identified by a <e>netmask</e> 255.255.255.0.
</p>

<p>
To configure your interface with a static IP address you can use the
<c>ifconfig</c> application which we have already seen when we tried to discover
what interfaces were available on your system.
</p>

<p>
The <c>ifconfig</c> tool requires you to pass it the interface, the IP address
and the netmask of the network. Suppose that 192.168.1.12 is your IP address and
255.255.255.0 your netmask:
</p>

<pre caption="Running the ifconfig tool">
# <i>ifconfig eth0 192.168.1.12 netmask 255.255.255.0 up</i>
</pre>

<p>
Next we need to configure the system to pass on requests for the Internet to the
gateway. With the <c>route</c> command you can set up the <e>default
gateway</e>, which is the default location where requests that are for an
unknown network are passed to. Assuming that 192.168.1.1 is the gateway IP
address:
</p>

<pre caption="Setting up the default gateway">
# <i>route add default gw 192.168.1.1</i>
</pre>

<p>
We are almost there. You should be able to get on the Internet ... if you knew
all the IP addresses of all the servers by heart. To be able to use hostnames as
well, you need to tell the system where the <e>name servers</e> are: systems
that can translate hostnames to IP addresses. Your Internet Service Provider
or network administrator should be able to tell you what the IP addresses for
the name servers are.
</p>

<p>
You need to place these IP addresses in the <path>/etc/resolv.conf</path> file
which sole purpose is to configure anything related to name configuration,
including where the name servers are located. 
</p>

<p>
To edit this file, you can use <c>nano</c>, a simple text editor for the command
line. Other editors that might be available are <c>vi</c> and <c>emacs</c>.
<c>nano</c> however is certainly available, so we will use <c>nano</c> as an
example. Assuming that the name servers are 123.45.67.89 and 123.45.67.90:
</p>

<pre caption="Editing /etc/resolv.conf">
# <i>nano /etc/resolv.conf</i>
<comment>(Change the content of the file to contain the name servers:)</comment>
nameserver 123.45.67.89
nameserver 123.45.67.90
</pre>

<p>
Now that's done, you should test your network connectivity.
</p>

</body>
</subsection>
<subsection id="network_testing">
<title>Testing the network</title>
<body>

<p>
With the <c>ping</c> tool you can send small requests to servers around the
Internet (but also on your network) and ask them to reply back. This makes
<c>ping</c> a perfect tool to check if a system is reachable. We'll use this
tool to verify the network connectivity.
</p>

<p>
First, we will try to reach a <uri link="http://www.google.com">Google</uri> web
server. We'll send it three requests - if they come back, your network (and
Internet connection) is working great and you can continue with the next
chapter.
</p>

<pre caption="Sending three requests to www.google.com">
# <i>ping -c 3 www.google.com</i>
</pre>

<p>
If you are not able to ping this system by name, you should try to ping an
Internet server by its IP address. In the following example, we send three
requests to 66.249.93.104, which is an IP address for a Google server. However, 
IP addresses might change so it is easier if you first verify that this IP 
address is really functional on a different system which has a working Internet
connection.
</p>

<pre caption="Sending three requests to 66.249.93.104">
# <i>ping -c 3 66.249.93.104</i>
</pre>

<p>
If this works, then the problem is with the name resolving. Verify that your
<path>/etc/resolv.conf</path> contains the correct IP addresses for the name
servers. Those IP addresses should be reachable (you can ping those as well to
verify). Also verify that <path>/etc/nsswitch.conf</path> has a line that starts
with 'hosts' and contains 'dns' as a keyword. This file tells your system where
to look for various resources, such as name resolving information. The 'dns'
keyword tells the system that <path>/etc/resolv.conf</path>'s name servers
should be used. The 'files' keyword tells the system that
<path>/etc/hosts</path> contains a few IP address with hostnames which should be
used as well.
</p>

<pre caption="Verifying the /etc/nsswitch.conf file">
# <i>grep -E '^hosts' /etc/nsswitch.conf</i>
hosts:       files dns
</pre>

<p>
Suppose that 66.249.93.104 wasn't reachable as well, you might have an issue 
with the gateway being malconfigured. Verify if your gateway is set correctly by
running <c>route&nbsp;-n</c>: the gateway IP address is the one mentioned right
next to the 0.0.0.0 destination. In the next example, we use the <c>awk</c> tool
to filter the output of the <c>route</c> command: of the line that starts with
0.0.0.0 we only show the second 'word' (which, in this case, is the gateway IP
address):
</p>

<pre caption="Verifying the configured gateway IP address">
# <i>route -n | awk '/^0.0.0.0/ {print $2}'</i>
</pre>

<p>
If the gateway IP address seems correct, try to ping it to see if you can reach
it. If you can, then the gateway itself is either blocking your Internet 
connections (perhaps a firewall issue) or the system isn't the gateway at all
but just another host on your network.
</p>

<p>
If you can't reach the gateway IP address but you are confident that the IP
address is correct and doesn't have a firewall that is dropping all your
requests (including the ping requests), then your interface is malfunctioning.
Make sure the network cable is plugged in and the cable is meant for the
connection type you are using (the straight versus crossed UTP cable debacle).
</p>

</body>
</subsection>

</section>
</sections>



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

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-next.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-next.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-next.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-next.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Rebooting the system</title>
<subsection>
<title>Exiting the chrooted environment</title>
<body>

<p>
The base Gentoo installation is almost finished. Right now, you'll need to exit
from the chrooted environment, unmount all mounted file systems from the system
and reboot. Then we'll find out if the boot procedure settings are correct: if
you can log on to your system, great. If not, well, no worries - you don't need
to redo everything all over again :)
</p>

<p>
To exit the chrooted environment, type <c>exit</c>. When you get back at the
installation CD environment, find out what file systems are mounted at the
<path>/mnt/gentoo</path> location and unmount them one by one. You can't unmount
a file system that still has mounted file systems in it, meaning that you can't
unmount <path>/mnt/gentoo</path> before <path>/mnt/gentoo/proc</path> and others
are unmounted.
</p>

<pre caption="Exiting the chrooted environment and unmounting the file systems">
# <i>exit</i>
# <i>mount | grep '/mnt/gentoo'</i>
/dev/sda3 on /mnt/gentoo type ext3 (rw,noatime)
proc on /mnt/gentoo/proc type proc (rw)
/dev/sda1 on /mnt/gentoo/boot type ext2 (rw,noatime)
# <i>umount /mnt/gentoo/boot /mnt/gentoo/proc /mnt/gentoo</i>
</pre>

<p>
Next, reboot the system and hope for the best...
</p>

<pre caption="Rebooting the system">
# <i>reboot</i>
</pre>

<p>
Don't forget to remove the installation media from the system, otherwise you'll
boot right into the installation environment again.
</p>

</body>
</subsection>
<subsection>
<title>Boot failed?</title>
<body>

<p>
If the reboot failed, you need to dig through the error messages you receive to
find out what went wrong. You'll find that the <uri
link="http://forums.gentoo.org">Gentoo Forums</uri> represent a wonderful
Knowledge Base with solutions to many problems. 
</p>

<p>
To help you get back, we'll explain how to return to the installation
environment so that you can fix whatever fault is causing the error.
</p>

<ol>
  <li>
    Reinsert the installation medium and reboot your system so that you are back
    inside the installation environment, just like you were in the beginning of
    the Gentoo installation.
  </li>
  <li>
    Load up any drivers you need and configure your network just like you did
    with the Gentoo installation.
  </li>
  <li>
    Instead of taking a stab at the storage configuration, immediately mount all
    your file systems at <path>/mnt/gentoo</path>. Don't forget to mount the
    <c>proc</c> file system as well. You never know when you'll need it and it
    is often forgotten.
  </li>
  <li>
    Chroot into the Gentoo installation (<c>chroot /mnt/gentoo</c>), run
    <c>env-update</c> and <c>source /etc/profile</c> so that your session
    environment is configured correctly.
  </li>
  <li>
    Now fix whatever needs to be fixed.
  </li>
  <li>
    Exit the chrooted environment, unmount the partitions and reboot to retry.
  </li>
</ol>
</body>
</subsection>
</section>

<section>
<title>Finishing off the base installation</title>
<subsection>
<title>USE flag changes and rebuilding</title>
<body>

<p>
If you didn't alter your USE flags during the installation, this is a good time
to do it. Log onto your system as root (using the password you supplied
previously) and edit the <c>USE</c> variable inside <path>/etc/make.conf</path>
using your favorite editor (<c>nano</c> is available by default) and reread the
information we gave you about USE flags earlier in this book in the chapter on
<e>Building the System</e>.
</p>

<p>
Once you've updated your USE flags, we'll tell Portage that it needs to rebuild
the tools that are affected by your USE flag change. To verify what Portage
wants to do, we'll first ask it to show it to us without actually performing the
rebuild. The <c>emerge</c> command has an option called <c>--pretend</c> (or
<c>-p</c> in short) that does exactly that. When we add the <c>--verbose</c> (or
<c>-v</c> in short) option we'll also ask it to display <e>why</e> it wants to
rebuild the packages. And of course, we need to ask Portage to do all that just
for the packages that are affected by the USE flag change (<c>--newuse</c>, or
<c>-N</c> in short):
</p>

<pre caption="Rebuilding packages affected by USE flag change">
<comment>(In this example, we've changed the nls USE flag:)</comment>
# <i>emerge --pretend --verbose --newuse world</i>

These are the packages that I would merge, in order:

Calculating world dependencies ...done!
[ebuild   R   ] sys-apps/man-pages-2.11  <i>-nls*</i> 0 kB 
[ebuild   R   ] sys-apps/grep-2.5.1-r8  -build <i>-nls*</i> +pcre -static 0 kB 
[ebuild   R   ] media-sound/alsa-utils-1.0.10_rc3  <i>-nls*</i> 0 kB 
<comment>(...)</comment>
</pre>

<p>
If you are okay with whatever Portage proposes, drop the <c>--pretend</c> so
that the packages can be rebuilt.
</p>

</body>
</subsection>
<subsection>
<title>Orphaned packages</title>
<body>

<p>
Some packages are installed on your system as dependencies of a tool if certain
USE flags are set. When you unset the affecting USE flag, Portage will
<e>not</e> unmerge the dependency even though the original package is rebuilt.
Such dependencies which aren't needed by any package on the system anymore but
are stil present are called <e>orphaned packages</e>.
</p>

<p>
You can ask Portage to find such orphaned packages and remove them from the
system. The method is called <e>depclean</e> (which stands for dependency
cleaning):
</p>

<pre caption="Running depclean on the system">
# <i>emerge --pretend --depclean</i>
</pre>

<p>
Take a look at the packages Portage wants to remove. If you want to scroll
through the list, try pressing <c>Ctrl-PgUp</c> or filter the list through the
<c>less</c> utility:
</p>

<pre caption="Using 'less' for the depclean output">
# <i>emerge --pretend --depclean | less</i>
</pre>

<p>
If you're satisfied with the list, drop the <c>--pretend</c> and let Portage
sort the packages out.
</p>

</body>
</subsection>
<subsection>
<title>Updating the system</title>
<body>

<p>
Finally, update your system so it uses the latest versions of all packages.
First, let Portage obtain a more recent snapshot of the Portage tree:
</p>

<pre caption="Updating the Portage tree">
# <i>emerge --sync</i>
</pre>

<p>
Next, ask Portage to update the packages that have a more recent version
available. We'll use the <c>--update</c> argument for <c>emerge</c> to inform
Portage that we want to update them, but also the <c>--deep</c> argument so that
not only those packages you have installed (using
<c>emerge&nbsp;&lt;packagename&gt;</c>) and their immediate dependencies are
updated, but also the dependencies of the dependencies. You'll also notice we
use the <c>--newuse</c> argument again. That is because Gentoo might add a USE
flag to the default USE set, either because of a profile update, or because you
installed a package that "provides" a USE flag.
</p>

<pre caption="Updating the packages on the system">
# <i>emerge --update --deep --newuse world</i>
</pre>

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

<section>
<title>Installing additional software</title>
<subsection>
<title>Some recommendations...</title>
<body>

<p>
Now that your base system is available, you'll still left in the dark as you
don't have many tools at your disposal. No graphical environment for the desktop
users, no services for the servers, so development tools (apart from the
toolchain) for the developers.
</p>

<p>
Your next stop should be to investigate the Portage tree for software you want
to have. You can just browse through <path>/usr/portage</path> and use
<c>emerge</c> for every tool you want, but better would be to follow one or
more <uri link="http://www.gentoo.org/doc/en/index.xml">guides</uri> from our
web site that help you install <e>and</e> configure the tool.
</p>

<p>
For instance, Gentoo has a nice <uri
link="http://www.gentoo.org/doc/en/xorg-config.xml">Xorg Configuration
Guide</uri> for those who want to set up their Gentoo installation as a
graphical environment desktop or workstation. The <c>xorg-x11</c> tool is the
service that provides windowing features and other graphical possibilities to
the various desktop environments.
</p>

<p>
Possible desktop environments are KDE, GNOME or fluxbox who also have
configuration guides at the Gentoo web site (<uri
link="http://www.gentoo.org/doc/en/kde-config.xml">KDE Configuration
Guide</uri>, <uri link="http://www.gentoo.org/doc/en/gnome-config.xml">GNOME
Configuration Guide</uri> and <uri
link="http://www.gentoo.org/doc/en/fluxbox-config.xml">Fluxbox Configuration
Guide</uri>).
</p>

<p>
For those interested more in services should take a look at the <uri
link="http://www.gentoo.org/doc/en/security">Gentoo Security Guide</uri> which
helps you harden your system configuration.
</p>

<p>
Other interesting resources are the <uri link="http://forums.gentoo.org">Gentoo
Forums</uri>, <uri link="http://www.gentoo.org/main/en/irc.xml">Gentoo IRC
channels</uri> and <uri
link="http://www.gentoo.org/main/en/lists.xml">mailinglists</uri>.
</p>

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

</sections>



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

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-install-storage.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-storage.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-install-storage.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-storage.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Storage</title>
<subsection>
<title>Introduction</title>
<body>

<p>
A difficult job of any Linux installation is to prepare the partitions to house
the Operating System. Each person has a different taste as to what should be on
a different partition and what shouldn't, or what file system to use. 
</p>

<p>
The idea behind partitioning is to make some sort of separation between one set
of data and another. For instance, people have their <path>/boot</path>
separated from the root file system because they want to be able to hide the
<path>/boot</path> content from the system during regular operations. Or they
want to have <path>/home</path> separate because that would allow them to store
all user-specific information, settings and data on a different disk so they are
able to easily retrieve the data after an Operating System reinstallation.
</p>

<p>
You can also choose to have a separate partition because you want to improve
performance by using a different file system tweaked to the use of the data
stored on the partition.
</p>

<p>
Deciding on the partition scheme requires intimate knowledge of the file system:
</p>

<ul>
  <li>What files are stored where?</li>
  <li>How often are the files used? Read or written?</li>
  <li>What is the function of the system you are building?</li>
  <li>What features do the various file systems have?</li>
</ul>

<p>
Because this is something that comes with age (err, experience ;) your first,
second, third, ... attempt for a perfect scheme will undoubtedly fail. Lots of
people therefore opt for a simple partitioning scheme (like everything on a
single partition, with a separate partition for the swap<sup>1</sup> 
information). Others attempt to use a more dynamical approach and use 
<e>Volume Management</e>. 
</p>

<p>
With Volume Management, you place a layer in between the partitions on the disk
and the file systems that hold your data. This layer can be used to combine
multiple partitions as if they were just a single one, or to use several logical
divisions on a single partition. Of course, Volume Management is much more than
that: it makes it easier to move data across partitions, shrink or grow file
systems, etc.
</p>

<note>
<sup>1</sup> Swap space is a specific location on the disk where the Linux 
kernel can store memory pages (regions of data in memory, assigned for use by 
processes or by the kernel itself) that will most likely not be used in a while.
The Linux kernel will, once your memory is completely filled (not sooner!), 
move such memory pages to the swap location, thereby freeing internal memory 
for other, more important memory pages.
</note>

</body>
</subsection>
<subsection>
<title>Designing a scheme</title>
<body>

<p>
You should start designing a partitioning scheme for your system. Telling you
what partitioning scheme is best for you is impossible, but here are some
pointers:
</p>

<ul>
  <li>
    For each partition you want to create, ask around how much space the
    partition might get given the tools and services you want to install. Make
    sure you design each partition to be larger than the size given by others:
    growing a file system is <e>not</e> without danger.
  </li>
  <li>
    Not all Linux file system locations are partitionable:
    <ol>
      <li>
        The <path>/etc</path>, <path>/lib</path>, <path>/bin</path> and
        <path>/sbin</path> locations must stay on the root file system as they
        are required by the Operating System under any circumstances. This is
        because they are needed to be able to mount other partitions on the file
        system.
      </li>
      <li>
        Only directories can be separated from a file system. Each separation
        automatically includes all subdirectories.
      </li>
      <li>
        You can not separate two different locations and still store them on a
        single partition (logical, that is - with Volume Management physical
        partitions <e>can</e> hold several logical ones), so you can't put both
        <path>/usr</path> and <path>/opt</path> on a single location.
      </li>
    </ol>
    Some locations also require special attention:
    <ol>
      <li>
        The <path>/dev</path> location will already be separated from the main
        file system by the device manager, so you don't need to devote a
        specific partition for <path>/dev</path>.
      </li>
      <li>
        The <path>/tmp</path> and <path>/var/tmp</path> locations are used for
        temporary file storage. Although the content of these locations is slim
        in most situations, it can grow exponentially. For instance, during the
        installation of software through Portage, <path>/var/tmp/portage</path>
        is used and can require up to a few gigabytes (!) of space.
      </li>
    </ol>
  </li>
  <li>
    Ask yourself if you really need that nifty file system feature: using Volume
    Management or (Software) RAID does require more work. Without much guidance,
    you might lose too much time stabbing at storage related problems.
  </li>
  <li>
    Many backup solutions are file system independant, but some of them aren't.
    If the backup storage is limited but you are using a file system dependant
    solution, make sure that the total amount of data that it will backup
    doesn't exceed the dedicated backup storage size.
  </li>
</ul>

<p>
We will discuss the more advanced storage solutions in more detail in a
different part of this book, but to make you aware of the possibilities we'll
give a quick rundown of those features first. We won't integrate these solutions
with the installation procedure though as that would complicate things too much.
</p>

</body>
</subsection>
<subsection id="raid_arrays">
<title>RAID arrays</title>
<body>

<p>
RAID stands for <e>Redundant Array of Inexpensive Disks</e> and is a well-known
way of putting disks together. There are several RAID levels defined:
</p>

<ul>
  <li>
    <e>RAID-Linear</e> places two (or more) disks next to each other and let the
    user view them as if those disks were a single one. At first, all data is
    written to the first disk. Once that disk is filled, the second disk is
    used, etc.
  </li>
  <li>
    <e>RAID-0</e> is also called <e>striping</e>: unlike with RAID-Linear data
    is first partitioned after which each 'stripe' of data is written to a disk.
    Therefore data written to a RAID-0 array is stored across all disks.
  </li>
  <li>
    <e>RAID-1</e>, also known as <e>mirroring</e>, places all data written to
    the array on <e>all disks</e>. In other words, each member of the RAID-1
    array is an exact copy of the others.
  </li>
  <li>
    <e>RAID-5</e> requires at least three disks. We'll explain its inner
    workings for three disks, but more than three is perfectly possible as well.
    When data is sent to the array, it is partitioned. For each two parts of
    data, a simple <e>checksum</e> is created, so we have three data segments.
    Those three segments are then stored to a disk. If one of the segments is
    lost, it can be retrieved from the other two segments if necessary.
  </li>
</ul>

<p>
Other RAID levels exists but are less frequently used.
</p>

<p>
RAID arrays are interesting when you need high availability of your data. For
instance, with RAID-1, if one of the disks crashes, the other one takes over.
Something similar happens with RAID-5: if one of the disks crashes, the other
disks can work together to generate the data that was stored on the
malfunctioning disk.
</p>

<p>
If you have a true hardware RAID card, using RAID within Linux (or any other
Operating System for that matter) does not require any input at all: the
operating system does not handle anything RAID-related. You only see the result,
the hardware RAID card handles all the rest.
</p>

<p>
Pseudo-hardware RAID cards offer various RAID-related services but still require
some (or a lot) of operating system input. Such cards therefore require a good
working driver and perhaps even a few tools. Although they aren't as transparent
as true hardware RAID cards, they still beat the software RAID.
</p>

<p>
Software RAID allows users to benefit from most of the RAID functionality
without requiring any specific hardware. This does require the operating system
to handle all the RAID-related tasks, requiring some computing time.
</p>

<p>
Information about using Software RAID is discussed further in this book.
</p>

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

<p>
Unlike RAID, which is most often used for redundancy, LVM allows the user to
maximise the flexibility of his storage. Basically LVM (actually, LVM2) should
be seen as a layer in between the physical storage (the disks) and the logical
view (the file system).
</p>

<p>
With LVM, you create <e>logical volumes</e> (partitions) which hold the file 
systems. One or more logical volumes are stored on a <e>volume group</e> which 
is nothing more than a collection of <e>physical volumes</e> (partitions). A
physical volume is an entire disk, or a partition, controller by LVM.
</p>

<p>
The LVM software offers services on top of this intermediate layer. For
instance, you can `spread' data across several partitions (like RAID-Linear or
RAID-0), or have several logical partitions on a single physical one. But that's
not it. LVM allows you to add (or remove) physical volumes from a volume group
without affecting the logical volumes (unless of course the logical volumes
require more space than the volume group has to offer), move data from one disk
to another without requiring any manual copy procedure or take a snapshot of an
entire file system without really having to take a full copy of the system.
</p>

<p>
These (and more) features make LVM a powerful tool of many system
administrators.
</p>

<p>
Information about LVM2 is discussed further in this book.
</p>

</body>
</subsection>
<subsection>
<title>Preparing the devices</title>
<body>

<p>
Before you can start creating the necessary partitions, you need to make sure
that the Linux Operating System can work with your hardware. If the installation
CD that you used to boot didn't automatically detect your hardware, you will
need to load the appropriate support manually.
</p>

<p>
Although we can start by educating you how the Linux kernel addresses the disks
(like <path>/dev/hd*</path> for IDE, <path>/dev/sd*</path> for SCSI and Serial
ATA, ...) and what logic is behind it, we will leave this for another document
(or perhaps a later chapter :) and immediately tell you how to discover where
your disks are.
</p>

<p>
If your disks are SCSI or Serial ATA (although some SATA disks are treated as
native IDE disks, most of them are using a SCSI-like driver), run <c>dmesg</c>
and filter out any occurrence of 'disk'. IDE disk users should filter out 'ide'
and 'hd':
</p>

<pre caption="Finding out what disk(s) you have">
<comment>(For SCSI or SATA:)</comment>
# <i>dmesg | grep -i disk</i>
Attached scsi disk sda at scsi0, channel 0, id 0, lun 0

<comment>(For IDE:)</comment>
# <i>dmesg | grep -i ide | grep -i hd</i>
TODO insert IDE output
</pre>

<p>
In the above example we discover that our SCSI (or SATA) disk is at
<path>/dev/sda</path> and our IDE disks are at TODO. If this does not reflect
the setup you have, you will need to load the appropriate drivers. Otherwise
continue with the next section on <uri link="#raid_arrays">RAID Arrays</uri>.
</p>

<p>
Your Linux system can tell you what controllers you have and what chipset they
use. This information is vital if you need to load additional drivers. The
combination of the <c>lspci</c> tool and the <c>grep</c> filter proves to be
quite efficient.
</p>

<p>
For instance, if you have an IDE controller but it wasn't loaded by default, try
filtering for 'ide'. Similar actions should be performed for Serial ATA ('sata')
or SCSI ('scsi'):
</p>

<pre caption="Findout out what IDE controllers are available on a system">
# <i>lspci | grep -iE '(ide|sata)'</i>
0000:00:1f.1 IDE interface: Intel Corporation 82801FB/FBM/FR/FW/FRW (ICH6 Family) 
  IDE Controller (rev 04)
0000:00:1f.2 Class 0106: Intel Corporation 82801FBM (ICH6M) SATA Controller 
  (rev 04)
</pre>

<p>
Based on this information you can try searching for the appropriate support
drivers. A quick <c>grep</c> on the content of the <path>/lib/modules</path>
directory (which stores all the additional kernel modules):
</p>

<pre caption="Searching for support drivers">
# <i>find /lib/modules | grep -iE '(82801|ich6)'</i>
TODO
</pre>

<p>
If you found a matching kernel module, load it in memory and rediscover where
your disks are:
</p>

<pre caption="Loading the kernel module">
# <i>modprobe TODO</i>
</pre>

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

<section>
<title>Partitioning</title>
<subsection>
<title>Architecture-specific</title>
<body>

<p>
Partitioning is architecture-dependant as partitions are generally tagged for
some function. The <e>type</e> of a distribution is therefore a very important
setting. Two important types are:
</p>

<dl>
  <dt>82 (Linux Swap)</dt>
  <dd>The partition holds swap information</dd>
  <dt>83 (Linux)</dt>
  <dd>The partition holds a Linux file system</dd>
</dl>

<p>
The partition structure is also architecture-dependant. Some architectures only
allow a few partitions (sometimes also called <e>slices</e>) to be available,
others have some weird solution to get over a very narrow limit causing
confusion in the numbering scheme of the partitions. There are even
architectures where certain partition numbers are reserved for a specific use.
</p>

<p>
You will find architecture-specific partitioning information in the first 
Appendix of this book, together with an example partition layout which you can
use to get started with Gentoo Linux.
</p>

</body>
</subsection>
<subsection>
<title>Create them, now!</title>
<body>

<p>
Read the partitioning information for your architecture <e>now</e> and create
the partitions you'll use to store Gentoo Linux on. 
</p>

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

<section>
<title>Filesystems</title>
<subsection>
<title>Overview</title>
<body>

<p>
Partitions alone aren't sufficient to store data (unless the partition for a
specific purpose, like raw access for databases). You need to apply some
structure to the partition so that Linux knows where files and directories are
stored, what permissions are set to the file, what security attributes are
applied, etc.
</p>

<p>
This is the task of the file system. A <e>file system</e> is a standard way of
storing and retrieving information from a partition. It dictates where the files
data is stored and how to get access to the file <e>metadata</e> (everything
about a file except the content, like name, creation date, owner, ...). 
</p>

<p>
Linux supports quite a lot file systems, but not all of them are functional
enough to store Linux files. For instance, the FAT-family (FAT12 for floppies,
FAT16 for small partitions and FAT32 for larger ones) has no concept of
permissions while the NTFS-family (all the dozen versions that Microsoft has
released thus far) is too complex (partially due to its closed-source nature)
and not fully supported.
</p>

<p>
We will describe the most known file systems that you can use to hold your Linux
Operating System together with some information on the tools associated with the
file system.
</p>

</body>
</subsection>
<subsection>
<title>Extended 3</title>
<body>

<p>
Extended 3 is the <e>journaled</e> version of Extended 2, the older (but proven)
file system which is the first real Linux file system ever developed for Linux
(before ext2, the Minix file system was used - but that was a long, long time
ago). Extended 3 is currently the most used file system as well.
</p>

<p>
As a <e>journaled</e> file system, ext3 can make sure that the entire file
system is consistent at any time. In other words, if your system would ever
crash (for instance due to a power interruption), the file system would never
contain garbled data - if you were busy writing data to the disk, either the old
data is there, or the new data, but not a partial write.
</p>

<p>
You can choose between no journaling (which basically means that the file system
should be seen a an Extended 2), metadata journaling (where only the metadata is
consistent across time) where you can choose between writeback (first metadata
write, then data) and ordered (first data write, then metadata) and full
journaling. The ordered metadata journaling is the default.
</p>

<p>
Extended 3 supports access control lists and is therefore a candidate file
system for more security enhanced Linux kernels who require ACLs to be available
for the file system.
</p>

<p>
To write an ext3 file system on a device, use the <c>mke2fs</c> tool with the
<c>-j</c> option (for <e>journaling</e>):
</p>

<pre caption="Writing an ext3 file system on /dev/hda3">
# <i>mke2fs -j /dev/hda3</i>
</pre>

<p>
The <c>mke2fs</c> command has a few interesting options as well:
</p>

<ul>
  <li>
    Writing a file system to the disk is quite fast. If you want to check the 
    device for bad blocks during the file system write, add a <c>-c</c> option.
    If you specify this option twice, a full read-write test is performed 
    instead of a read-only test.
  </li>
  <li>
    To speed up lookups in large directories, you can enable directory indexing
    by adding <c>-O dir_index</c>. 
  </li>
  <li>
    Large file systems might free more space by adding <c>-O sparse_super</c>.
    This will decrease the percentage of blocks used as backups for the file
    metadata.
  </li>
</ul>
    
</body>
</subsection>
<subsection>
<title>The swap file system</title>
<body>

<p>
Although you can't 'use' the swap space directly, it does use a specific file
system to store the memory pages. To create a swap file system on the swap
partition, use <c>mkswap</c>:
</p>

<pre caption="Creating a swap file system on /dev/hda2">
# <i>mkswap /dev/hda2</i>
</pre>

<p>
Unlike the other file system creation tools, <c>mkswap</c> hardly takes
additional options for tuning purposes.
</p>

</body>
</subsection>
<subsection>
<title>Create the file systems</title>
<body>

<p>
Create the file systems on your partitions <e>now</e> and don't forget to create
the swap file system as well.
</p>

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

<section>
<title>Getting in the minimal environment</title>
<subsection>
<title>Mounting the partitions</title>
<body>

<p>
The next step is to <e>mount</e> the file systems in the Linux file system
hierarchy so that you can use it. As we have said in the previous part, mounting
attaches the file system to the current hierarchy at a specified location.
</p>

<p>
On the Gentoo installation CD, a directory <path>/mnt/gentoo</path> is available
to mount your root file system in spe. Let us suppose that the file system is at
<path>/dev/hda3</path>, then the <c>mount</c> command would be:
</p>

<pre caption="Mounting the root file system at /mnt/gentoo">
# <i>mount /dev/hda3 /mnt/gentoo</i>
</pre>

<p>
You'll also need to mount the other file systems at the correct place. Because
your root file system doesn't contain any directories yet, you'll need to create
them. For instance, if you have a separate <path>/boot</path> (at
<path>/dev/hda1</path> and <path>/usr</path> (at <path>/dev/hda4</path>) file 
system:
</p>

<pre caption="Creating mount points prior to mounting the file systems">
# <i>mkdir /mnt/gentoo/boot /mnt/gentoo/usr</i>
# <i>mount /dev/hda4 /mnt/gentoo/usr</i>
# <i>mount /dev/hda1 /mnt/gentoo/boot</i>
</pre>

<p>
You will also need to activate the swap partition. This is accomplished using
the <c>swapon</c> command:
</p>

<pre caption="Activating the swap space">
<comment>(Example for a swap file system at /dev/hda2)</comment>
# <i>swapon /dev/hda2</i>
</pre>

</body>
</subsection>
<subsection>
<title>Preparing the stage tarball</title>
<body>

<p>
A Gentoo stage tarball contains a minimal Gentoo environment. If you are booted
from a Gentoo universal installation CD you might find the stage of your choice
on the CD (probably at <path>/mnt/cdrom/stages</path>). If not, you can download
one from one of our <uri
link="http://www.gentoo.org/main/en/mirrors.xml">mirrors</uri>. They are stored
in the appropriate release directory under the name <path>stages/</path>.
</p>

<p>
A <e>tarball</e> is an archive, usually compressed using Lempel-Ziv coding
(LZ77 - <c>gzip</c>) or Burrows-Wheeler compression with Huffman coding
(<c>bzip2</c>). Uncompressed, you will have a single file (a tar<sup>2</sup> 
file) that contains all the files in the archive, nicely appended one after 
another.
</p>

<p>
To download such a stage tarball, <e>first</e> go to <path>/mnt/gentoo</path>.
This is required so that, once you start downloading the file, it is stored on
the disk and not in memory (the Gentoo installation CD creates a virtual 'disk'
in memory so that you can use the CD without requiring any pre-installed Linux
system).
</p>

<pre caption="Downloading a stage tarball">
# <i>cd /mnt/gentoo</i>
# <i>lynx http://www.gentoo.org/main/en/mirrors.xml</i>
</pre>

<p>
Next, extract the tarball to the <path>/mnt/gentoo</path> location. Use the
<c>tar</c> tool with <c>xjpf</c> as options and the tarball as argument:
</p>

<ul>
  <li>e<b>x</b>tract the files from the archive</li>
  <li>
    use <c>bunzip2</c> to decompress the archive (<b>j</b> due to shortage of
    available options :)
  </li>
  <li><b>p</b>reserve the permissions that were stored in the tarball</li>
  <li>use the next <b>f</b>ile as the archive</li>
</ul>

<pre caption="Extracting the stage tarball">
# <i>tar xjpf &lt;file&gt;</i>
</pre>

<p>
If your stage tarball is stored on the CD, just use the path to the file for
<path>&lt;file&gt;</path>.
</p>

<note>
<sup>2</sup>: the name <e>tar</e> comes from Tape ARchive. The <c>tar</c> tool
was (and still is) commonly used for backing up files to tapes which only have
linear access (unlike digital media where you can quickly jump from one location
to another). Because of this limitation, all files are aligned after another
with a table of contents stored in the beginning of the tape. The <c>tar</c>
tool is still a very popular tool for creating archives.
</note>

</body>
</subsection>
<subsection>
<title>Extracting a Portage snapshot</title>
<body>

<p>
We need to extract another tarball, namely a <e>portage snapshot</e>. Portage is
the software management system Gentoo uses. The package information itself is
stored in what we call the <e>Portage tree</e>. A <e>portage snapshot</e>
is a Portage tree taken at a certain point in time. 
</p>

<p>
On a universal installation CD, you might find such a snapshot at
<path>/mnt/gentoo/snapshot</path>, but you can always download a snapshot from
the Internet as well. Go to one of our <uri
link="http://www.gentoo.org/main/en/mirrors.xml">mirrors</uri> and locate the
most recent portage snapshot in the <path>snapshots/</path> directory.
</p>

<pre caption="Downloading a Portage tree snapshot">
# <i>lynx http://www.gentoo.org/main/en/mirrors.xml</i>
</pre>

<p>
We don't need any specific permission information from the snapshot, so the
<c>tar</c> command only requires <c>xjf</c> as options. However, the snapshot
<e>must</e> be extracted inside <path>/mnt/gentoo/usr</path>. We could do the
same as we did with the stage tarball and first go to
<path>/mnt/gentoo/usr</path> before we run the extraction command, but you can
also use <c>-C &lt;location&gt;</c> (with a capital C) to inform <c>tar</c> that
the <path>/mnt/gentoo/usr</path> location is the destination:
</p>

<pre caption="Extracting a Portage tree snapshot">
# <i>tar xjf &lt;snapshot&gt; -C /mnt/gentoo/usr</i>
</pre>

</body>
</subsection>
<subsection>
<title>Preparing the minimal Gentoo environment</title>
<body>

<p>
As you might have guessed already, we are trying to have 
<path>/mnt/gentoo</path> contain a fully functional Linux environment. To finish
this off, we need to mount a specific <e>pseudo file system</e> called proc at
<path>/mnt/gentoo/proc</path>. This is not a file system stored on a disk, but
rather an interface to the Linux kernel showing kernel information as regular
files. This allows you to retrieve kernel (and system) information by just
reading files instead of requiring specific tools.
</p>

<pre caption="Mounting the proc file system">
# <i>mount -t proc none /mnt/gentoo/proc</i>
</pre>

<p>
To be able to use the network you have defined (if applicable), you need to copy
over the <path>/etc/resolv.conf</path> file to the new Linux environment:
</p>

<pre caption="Copying over the name resolving information file">
# <i>cp /etc/resolv.conf /mnt/gentoo/etc</i>
</pre>

</body>
</subsection>
<subsection>
<title>Changing the root from CD to the new environment</title>
<body>

<p>
The final step now is to change the root of your file system from the one
provided by the CD to the one you just set up, namely <path>/mnt/gentoo</path>.
Using the <c>chroot</c> tool, your terminal session will not see anything
outside <path>/mnt/gentoo</path> unless you finish the <c>chroot</c> itself.
Because you need a shell to navigate, we run <path>/bin/bash</path> (the Bourn
Again SHell) right after changing the root:
</p>

<pre caption="Changing the root to /mnt/gentoo">
# <i>chroot /mnt/gentoo /bin/bash</i>
</pre>

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

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-intro-choice.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-intro-choice.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-intro-choice.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-intro-choice.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-intro-choice.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Distributions</title>
<subsection>
<title>Differences</title>
<body>

<p>
Now that you know a bit about Linux and Free Software, you need to make a choice
about the distribution you want to use. As you already know, a distribution
makes it easy for a user to install and maintain software. But a distribution
does a lot more than this. In the next few sections we describe various topics
which are filled in differently by distributions.
</p>

</body>
</subsection>
<subsection>
<title>Architectures</title>
<body>

<p>
For a system to become functional, the source code of an application must be
translated to machine instructions. These instructions differ from CPU to CPU. A
set of machine instructions for a certain brand of CPUs (and its clones) is
called the <e>architecture</e>. The best known architecture is the <c>x86</c>
architecture, but several others exist, such as alpha, sparc, ppc, ...
</p>

<p>
Not all distributions support all possible architectures. Some distributions
even limit their support to a single architecture, others take pride in the fact
that they support quite a lot architectures.
</p>

<p>
Gentoo supports quite a few architectures: alpha, amd64, hppa, ia64, mips, ppc,
ppc64, sparc, x86 and even has unofficial support for arm, m68k, s390, sh, ...
</p>

</body>
</subsection>
<subsection>
<title>Package building</title>
<body>

<p>
There are many ways a software title can be packaged. Some distributions do not
prebuilt the software (so that the system still needs to compile the source code
prior to installing it to the system), but most do. Prebuilt software can be
packaged in an RPM file (RedHat Package Manager), a DEB file (Debian Package),
... Each of those package formats has its advantages and disadvantages.
</p>

<p>
By default Gentoo lets the system built the software. The format Gentoo uses is
called an <e>ebuild</e> which contains instructions for Portage, the Gentoo
software manager, to built the software for the user.
</p>

</body>
</subsection>
<subsection>
<title>Provided software</title>
<body>

<p>
Some distributions only provide a few software titles because they aim on a very
particular niche (like embedded Linux, a Linux terminal server, ...) while
others provide a plethora on software titles. This is quite different from other
Operating Systems where you need to acquire additional software, or at least
have to locate, download and install it separately. With Linux, this process is
often embedded in the distribution which makes it a lot easier for the user.
</p>

<p>
Gentoo provides more than 9500 packages.
</p>

</body>
</subsection>
<subsection>
<title>Preconfiguration</title>
<body>

<p>
When you install software, the distribution can try to preconfigure the
software for you. Some distributions go quite far so that the user hardly needs
to know how to configure anything - for the common user, everything works out of
the box. Other distributions do not try to configure most packages and leave it
to the user. After all, the user knows best what he needs and what not.
</p>

<p>
Gentoo mainly stays with the configuration as provided by the software project
and informs its users how to configure the software through excellent
step-by-step documentation.
</p>

</body>
</subsection>
<subsection>
<title>System maintenance</title>
<body>

<p>
A Linux system is not only a collection of installed software, the software
needs to work well (configuration) and should be manageable. System maintenance
is a job where you make sure that the system works as it should. You can
maintain your entire system through a single software package (like
<c>webmin</c>) or through a collection of software titles.
</p>

<p>
While some distributions try to provide an all-in-one maintenance solution, most
distributions opt for a decentralised maintenance with specific tools for
specific jobs. 
</p>

<p>
Gentoo does not offer any configuration tools - the user should configure his
system through the standard Linux tools.
</p>

</body>
</subsection>
<subsection>
<title>Branding</title>
<body>

<p>
When a system is <e>branded</e> it is beautified: logo's are added, backgrounds
changed, behaviour altered, ... so that the system feels as if it was developed
and released by a single entity instead of several ones. Not all distributions
like branding because it removes the default look and feel that the individual
software projects have given to their software. They leave it as-is out of
respect for the software projects.
</p>

<p>
Gentoo does not brand applications by default.
</p>

</body>
</subsection>
<subsection>
<title>Installation</title>
<body>

<p>
Whereas several distributions have a similar or even identical way of installing
software, almost no distribution has the same installation method. Some
distributions provide an installation where you hardly need to provide any
information, others require you to perform every single step yourself. And all
the other distributions are situated somewhere between those extremes.
</p>

<p>
Gentoo lets you perform every single installation step yourself, making a great
learning school for Linux internals. 
</p>

</body>
</subsection>
<subsection>
<title>Policies</title>
<body>

<p>
Albeit this is less visible in most distributions, some have a policy they
adhere to. For instance, some distributions might have a policy that they don't
allow non-free software in their distribution. Therefore such distributions will
always be free to use with no restrictions whatsoever (apart from those governed
by the free software license(s) they use).
</p>

<p>
Gentoo has a policy, written down in their <uri
link="http://www.gentoo.org/main/en/contract.xml">Social Contract</uri>. It is
less strict than the one mentioned in the previous paragraph, informing the user
that Gentoo will never depend on non-free software. In other words, you will
always have the ability to use a completely free Operating System with no
crippled features whatsoever. Gentoo <e>does</e> offer non-free software through
Portage - at least, it offers the instructions on how to integrate it
succesfully on your system. It will never allow you to install software against
the spirit of the license which it is released under.
</p>


</body>
</subsection>
</section>
<section>
<title>Software choices</title>
<subsection>
<title>Why it doesn't matter</title>
<body>

<p>
When you are starting with Linux (and Gentoo Linux) you will undoubtedly find it
difficult to know what software to install. How is the best e-mail client
called? Can you run Windows applications on Linux? How is the support for the
many Word documents you might have? How can you edit pictures?
</p>

<p>
There are many, many tools available for Gentoo Linux. They offer a plethora of
possibilities and functions. It is not mandatory for you to know what software
you will use now: when you install Gentoo Linux, you first install a minimal,
bare-boned system. When you have this, you can start finding out what software
you would like to use.
</p>

<p>
Since all software is freely available, the best way to know what software to
use is to try and test them out until you find one that suits you the best. Of
course, it is often wise to build upon the knowledge of others: ask around what
the best software would be for your needs. 
</p>

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



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-intro-linux.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-intro-linux.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-intro-linux.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-intro-linux.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-intro-linux.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Linux: concept and history</title>
<subsection>
<title>What is Linux?</title>
<body>

<p>
Linux is a free operating system, consisting of the Linux kernel, libraries 
and utilities which allow the user to interact with his system.
</p>

<p>
The <uri link="http://www.kernel.org/">Linux kernel</uri> is the core of the 
Linux Operating System. It is responsible for all hardware interaction, 
process management, memory management, network protocol support and file 
system support. We probably forgot a few other responsibilities as well, 
but it is obvious that the kernel has many important responsibilities. All these
tasks are handled in the background: as the core of the system, the user has no
direct interaction with the kernel.
</p>

<p>
The core library on a Linux system is the <uri
link="http://www.gnu.org/software/libc/libc.html">GNU C library</uri>, called 
<c>glibc</c>. This library provides an interface between the Linux kernel, 
which operates almost independently, and the user applications. The library 
contains <e>system call</e> definitions and basic features to facilitate
the application development for the Linux Operating System.
</p>

<p>
The core utilities on a Linux Operating System provide you, the user, with a way
to interact with the system. These utilities allow you to create and manipulate
files, navigate around on your system, start and stop processes, etc. There is
no "single" core utility package: the Linux Operating System contains a dozen
different packages and two Linux systems can have different utilities.
</p>

<p>
The most well-known and used utilities however (such as those for navigating on
the system) are generally called the <uri 
link="http://www.gnu.org/software/coreutils/">GNU Core Utilities</uri>. GNU is a
project devoted to the development of a completely free (as in 'free speech')
Unix-like environment. Because GNU plays an important role on most Linux 
systems, many people talk about GNU/Linux. 
</p>

</body>
</subsection>
<subsection>
<title>So... what is Linux?</title>
<body>

<p>
While the above explanation is quite technical, the Linux Operating System is 
built upon the <uri link="http://www.unix.org/">UNIX</uri> idea, delivering
UNIX-like features and stability. But it is more than just a UNIX clone. It is 
developed by several thousand developers who work on the operating system in 
their free time (although many of them also work on Linux on a paid-for basis).
</p>

<p>
The development of Linux is decentralised: each part of the Linux Operating
System (kernel, libraries, tools, graphical environments, office suites, server
software, ...) is developed by its own project which works independently of 
the other projects. Unlike what many people think, this does <e>not</e> mean 
that the projects do not work well with each other. Each software title that 
interacts with another uses <e>standards</e>. A standard is an established or 
widely recognized technical explanation to accomplish something. The best 
standards are open standards.
</p>

<p>
An <e>open standard</e> is a freely available and sufficiently documented 
technical explanation that allows any developer to write software that operates
as the document dictates or supports the communication described by the
standard. Therefore it can flawlessly interact with other software titles that 
adhere to the document as well. The document and its technical implications 
are free of any juridical limits (like patents, licenses, ...) and the 
document is accepted by a standards organisation (like ISO, ANSI, ...).
</p>

<p>
Examples of such open standards are the various network protocols (like TCP/IP,
HTTP, ...), character encodings (ASCII, UTF-8, ...), etc.
Because the applications use standards, interoperability amongst the various
applications is guaranteed.
</p>

<p>
The Linux Operating System is characterised by freedom and choice. Freedom,
because the software is free (although non-free software exists for Linux as
well). Choice, because you will have the choice between several applications 
for each action you want to perform.
</p>

</body>
</subsection>
<subsection>
<title>Where can I find Linux?</title>
<body>

<p>
You should not be searching for Linux sensu stricto as you'll only find the 
Linux kernel which you can't use without additional libraries and tools. What 
you need to look for is a distribution. A distribution is a project
that combines the Linux kernel, libraries and tools in a coherent software
package. With a distribution you can install, configure and use a Linux 
system easily.
</p>

<p>
Next to the distribution, you might need to install additional software. If you
can not install it through your distribution (most distributions offer thousands
of software titles out of the box) or you do not know any software title by
name, then you can visit one of the many free software repositories
around. Known repositories are <uri
link="http://www.freshmeat.net">Freshmeat</uri>, <uri
link="http://www.icewalkers.com">Icewalkers</uri>, <uri
link="http://www.sourceforge.net">SourceForge</uri>, etc.
</p>

<p>
Known distributions are <uri link="http://fedora.redhat.com">Fedora</uri>, <uri
link="http://www.mandriva.com">Mandriva</uri>, <uri
link="http://www.novell.com/linux/suse/">SuSE</uri>, <uri
link="http://www.debian.org">Debian</uri>, <uri
link="http://www.ubuntu.org">Ubuntu</uri> and of course <uri
link="http://www.gentoo.org">Gentoo</uri>, but many others exist as well.
</p>

</body>
</subsection>
<subsection>
<title>Linux' history</title>
<body>

<p>
Linus Thorvalds, the creator of the Linux kernel, made a first posting about his
hobby project on August 25th, 1991. People could download his code and use it,
modify it and redistribute it. Linus also made a few ports available to make it
possible for others to run a Linux operating system. Of course, in those days,
the operating system contained only a few applications and hardware support was
very limited.
</p>

<p>
In the next few years, the Linux kernel grew and expanded: support for
networking, SCSI disks, specific file systems, ... was added and bugs were
quickly fixed. Yet installing a Linux Operating System still was difficult as
there were no easy installation methods yet. That changed when the first
distribution got out.
</p>

<p>
Early distributions were hardly maintained so no real good candidate for
continuous usage. In 1993 Slackware was created, and others followed suit
shortly after. Nowadays, several hundred distributions exist. 
</p>

</body>
</subsection>
</section>
<section>
<title>Free software model</title>
<subsection>
<title>Freedom of speech</title>
<body>

<p>
As mentioned previously, Linux is Free Software. The "Free" here should be read
as "Freedom of Speech", not "Free beer". The <uri link="http://www.fsf.org">Free
Software Foundation</uri> defines the freedom as:
</p>

<ol>
  <li>
    freedom to run the program for any purpose,
  </li>
  <li>
    freedom to study how the program works, and to adapt it to your needs, 
  </li>
  <li>
    freedom to redistribute copies of the program, and
  </li>
  <li>
    freedom to improve the program, and release your improvements to the public
    so that the entire community benefits
  </li>
</ol>

<p>
The Free Software Foundation has prepared and released a specific license that 
embraces the abovementioned freedom. Their license is called the <uri
link="http://www.fsf.org/licensing/licenses/gpl.html">GPL</uri> and is used by
the Linux kernel and various other applications. The Free Software Model builds
upon this freedom. 
</p>

</body>
</subsection>
<subsection>
<title>The role of distributions</title>
<body>

<p>
Distributions play an important role: they bundle the free software in a 
coherent package. A distribution allows you to install a Linux Operating
System easily and maintain the software installed on your system. Thanks to
distributions, you don't need to know how to build packages, what toolchains
are and other packaging-related tasks.
</p>

<p>
One role of a distribution in the free software model is that of the quality
analysis and marketing. Distributions take the source code of many projects and
bundle it together. They test the software and provide feedback to the
developers of the individual projects. When they are happy with the end result,
they present their distribution to the world: it is this end result that the
users will install on their system.
</p>

</body>
</subsection>
<subsection>
<title>Development model</title>
<body>

<p>
Most free software is developed on a volunteer basis. A free software project
generally has some infrastructure at its disposal:
</p>

<ul>
  <li>
    a <e>code repository</e>: a location where several people can work on the
    source code simultaneously. When you hear about CVS or SVN then the topic of
    the discussion is most likely code repositories or the tools to manage them.
    A versioning tool allows developers to deal with collaborative source code 
    development. Such tools keep track of all changes made to the project.
  </li>
  <li>
    a web site, displaying news and information about the project. The web site
    will probably include download and installation instructions, documentation,
    etc.
  </li>
  <li>
    a mailinglist where developers and users discuss the future of the project,
    changes and change requests, bugs, etc.
  </li>
  <li>
    a <e>bug tracking system</e> where users can submit bug reports and
    enhancement requests. Such bug tracking systems allow the developers to
    keep track of bugs easily. 
  </li>
</ul>

<p>
Most free software projects are ran by volunteers. These people put their
knowledge of programming, documentation writing, infrastructure, ... in the
project. The motivation that drives these developers makes free software
evolve quite fast: why else would someone work on a project in his free time if
he wasn't motivated?
</p>

<p>
Because a project is mostly ran by volunteers, there is no limit to the amount
of developers that can work on the project. The Gentoo distribution has more
than 350 developers, the Linux kernel has several hundred developers. Many
updates to a project are made by contributors as well: people who have found and
fixed an issue but are not part of the development base of the project.
</p>

<p>
The entire development process is open to the public (everyone can see
how the project evolves), so there is a lot of feedback from the users. Users
participate in discussions on the mailinglists or through IRC (lots of projects 
have a chat channel). In many cases, active users are asked to join the
development team because they provide valuable feedback.
</p>

</body>
</subsection>
</section>
<section>
<title>Is Linux your thing?</title>
<subsection>
<title>Expectations</title>
<body>

<p>
So what can you expect from Linux? 
</p>

<p>
Linux is a very stable platform that can be used in every area you can be
interested in: desktop, workstation, server, programming, embedded, ...
Stability is a core concern with Linux. The Linux kernel for instance is a 
separate entity in the Operating System and not integrated in the shell or
hidden from the user. Any instability of an application will cause the
application to fail but not the kernel, so the system remains functional.
</p>

<p>
Because of the development model used, Linux is a fast moving operating system.
With Linux you can expect frequent updates with lots of new features. You will
notice that as you update your system, the system will remain recent and
completely up-to-date with the latest developments. Some distributions 
(Gentoo included) don't even require you to upgrade your system: once 
installed, you will always have the latest release. Such an approach is quite
unique and you can't find this in operating systems like Microsoft Windows.
</p>

<p>
Programmers will find that Linux offers them the best development platform they
can imagine. An Operating System where you can learn a lot from the inner
workings of the system, where you can find a plethora of (free) development
tools for languages such as C#, C++, Java, C, PHP, ... where communities help
each other in the development of peer projects. 
</p>

<p>
Home users will find Linux to be extremely interesting, with lots of documents
available to help you find your way through this new and exciting system. Yes,
documentation is a powerful asset: you have sites devoted to the ongoing 
development of good, professional and clear documents about various 
Linux-related subjects. Documents are not only available in English but
in various languages and this international approach is also taken within the 
Linux software products themselves: most applications are available in several 
languages. You can have your entire system available in your native language!
</p>

<p>
Lots of developers are security-aware. Therefore you will find that most
applications are written with a high sense of secure defaults. E-mail clients 
are not that likely to be easily trapped by viruses; the system only allows you
to alter files you have created, leaving system-wide files intact; free updates
lessen the chance that an exploitable bug remains on your system; firewalls and
other security-related software is freely available and easy to install. Do not
read this as if Linux is secure by default, but it does stress security more
than some other operating systems.
</p>

<p>
A Linux Operating System is quite cheap. Many distributions are freely available
(free as in free beer), others are available for a small price compared to what
they have to offer. To understand how the Free Software Model is sustainable we
will discuss this in <uri link="?part=1&amp;chap=3">Freedom, Support and
Finances</uri>. You are also not forced to stay with a single vendor since most
applications use standards which improve interoperability.
</p>

<p>
You will find that Linux is extremely flexibel. You can use Linux as a desktop,
as a workstation, as a TV receiver/recorder, ... You can save disk space by
installing just the applications you need without any additional stuff, you can
install an entire desktop suite or just the tools you need. You can optimize
your installation for your system, or use a generic installation to speed up the
installation of hundreds of desktops you administer. You can choose amongst
various applications that offer the same functionality but use different ways 
to achieve their goals. You can do whatever you want, the way you want.
</p>

</body>
</subsection>
</section>
<section>
<title>Linux is not...</title>
<subsection>
<title>... a Microsoft Windows look-a-like</title>
<body>

<p>
Do not expect Linux to behave like Windows, to run Windows programs, to be
compatible with everything Windows offers. Linux is a completely different
Operating System with its own way of dealing with things. It is completely
different by design, by development model, by community, ... and will most
likely stay different.
</p>

</body>
</subsection>
<subsection>
<title>... secure by default</title>
<body>

<p>
Security is a major concern with Linux, but "Secure by Default" is something
completely different. You should not expect that your Linux environment will
always be untouchable; security lays in the hands of whoever controls the
system.
</p>

<p>
Keeping your system up to date is a prerequisite: if you do not update your
system regularly, you will eventually have applications on your system that have
known exploitable bugs in them. Having a clear policy is important as well: do
not trust everyone on the Internet, do not use empty or easy-to-guess passwords,
do not use applications from untrusted sources, etc. Know what you do on your
system: badly configured services can be the weakest link in someone's security.
</p>

</body>
</subsection>
<subsection>
<title>... an alternative</title>
<body>

<p>
The word "alternative" is often used for a less powerful but "sufficient"
solution. Linux is <e>more</e> powerful and different. It is not an alternative
for any other operating system, but a different operating system.
</p>

<p>
Forget what you know about the operating system you currently use. Linux is
different and you <e>will</e> need to learn it. It will take a while but it is
definitely worth it.
</p>

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



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-intro-next.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-intro-next.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-intro-next.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-intro-next.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-intro-next.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Handbook syntax</title>
<subsection>
<title>Used symbols and colors</title>
<body>

<p>
Okay, we are now at the end of this first part. As you might have seen, the
previous sections suddenly started using some Linux-specific commands. I will
quickly explain how this handbook uses those Code&nbsp;Listings and other
syntax.
</p>

</body>
</subsection>
<subsection>
<title>Code listings</title>
<body>

<p>
A Code&nbsp;Listing can be a command that needs to be executed. When this is the
case, the command is prepended with a symbol that refers to the <e>prompt</e>.
</p>

<p>
A prompt is a short string given by the system to the user, telling that the
user can give a command. By default, the prompt for a regular user would look
like so on a system with hostname "localhost" and username "john":
</p>

<pre caption="Example prompt">
john@localhost ~ $
</pre>

<p>
When you are the root user, the prompt will look like so:
</p>

<pre caption="Example prompt for the root user">
root@localhost ~ #
</pre>

<p>
As you can see, it differs not only by the user name, but also the ending
character: regular users have a prompt that ends at <c>$</c>, but the root user
has an ending character of <c>#</c>. For this reason, we will use this single
character throughout the rest of the document to refer to the prompt. When the
character is a <c>$</c> you can (should) execute the command as a regular user.
When the character is a <c>#</c> you can (should) execute the command as the
root user.
</p>

<p>
For instance, the <c>ls</c> command (which lists the content of the current
working directory) can very well be ran as a regular user, but to install a
package (like <c>bzip2</c>) you need to be root:
</p>

<pre caption="Example Code Listing usage for commands">
$ <i>ls</i>
# <i>emerge bzip2</i>
</pre>

<p>
As you can see, the command itself is highlighted. When there is output from the
command to the screen that you do not need to type, it will be in plain text.
When we add some comments, you will notice that it has a different layout. For
instance, to change your password:
</p>

<pre caption="Changing the current user his password">
$ <i>passwd</i>
Old password: <comment>(Enter your old password)</comment>
New password: <comment>(Enter the new password)</comment>
Re-enter new password: <comment>(Re-enter the new password to verify)</comment>
Password changed.
</pre>

<p>
We will also use Code&nbsp;Listings to show the contents of a file.
</p>

</body>
</subsection>
<subsection>
<title>Warnings</title>
<body>

<p>
When the information in this handbook is incorrect due to a bug or a temporary
issue, I use a warning to inform you about this temporary setback. I prefer to
do it this way than to fix the content itself because I feel that documentation
should not be used to fix bugs (or provide workarounds).
</p>

<p>
An example warning would look like so:
</p>

<warn>
Due to a <uri link="https://bugs.gentoo.org/show_bug.cgi?id=100456">bug</uri> in
the Evolution ebuild you can not install version 2.2.3-r2 for the time being.
Please use 2.2.3-r1 until a fix has been found.
</warn>

<p>
A more permanent warning will look like so:
</p>

<p>
<brite>Warning!</brite> Do <e>not</e> set the <c>USE</c> variable on the command
line as a variable. This will temporarily assume that those USE flags are given,
but the next time your system is updated this information is forgotten.
</p>

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

<p>
When we want to stress out something important, we will normally put this in the
paragraphs using <e>emphasised text</e> or <b>bold text</b>. However, when it is
quite urgent and would require a larger rewrite, we will temporarily use an
importancy-box like so:
</p>

<impo>
Make sure <path>/etc/hostname</path> is removed afterwards. Otherwise the error
will remain since the <c>baselayout</c> package first checks this file prior to
<path>/etc/conf.d/hostname</path>.
</impo>

</body>
</subsection>
<subsection>
<title>Notes</title>
<body>

<p>
At the end of a chapter we might add a few notes, either as a certain type of
footnote or a reference to another resource. If the amount of notes aren't too
large, we will use a note box like so:
</p>

<note>
The <uri link="http://www.tldp.org">Linux Documentation Project</uri> has a 
few guides on networking as well. Definitely worth a read.
</note>

</body>
</subsection>
</section>
<section>
<title>What can you expect</title>
<subsection>
<title>Installing Gentoo</title>
<body>

<p>
In the next part, we will give you lots and lots of Linux technical information
to allow you to install Gentoo Linux on your system. Unlike with the <uri
link="http://www.gentoo.org/doc/en/handbook">Gentoo Handbook</uri> we will try
to be <e>more verbose</e> (yes, that's possible :) but less step-by-step.
</p>

<p>
Why? Because you should be able to install Gentoo the way you like it without
the need to take a look at the step by step decriptions. Not that the Gentoo
Handbook is written badly (hey, I wrote the most of it :p) but just...
differently :)
</p>

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



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-intro-resources.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-intro-resources.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-intro-resources.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-intro-resources.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-intro-resources.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>People</title>
<subsection>
<title>Friends and colleagues</title>
<body>

<p>
When you are searching for information, the best place to look for is amongst
your friends and colleagues. They might not describe everything in full detail
as you would expect from a book or technical document, but they are interactive
meaning that you can ask more questions as they come along. Another advantage is
that they might reword their answers if you don't understand them.
</p>

<p>
Having friends and colleagues to ask questions to is a major advantage,
especially if they also use the distribution you want to use. They might even
give you on-site help: think of a private tutor :) Make sure that this person
doesn't mind you asking a lot of questions though.
</p>

<p>
When you are advanced in a certain topic, remember that other people helped you
when you were still a novice and share your knowledge with other people. Be open
for questions and help your friends and colleagues. Don't think you know all the
answers though, even Einstein made mistakes.
</p>

</body>
</subsection>
<subsection>
<title>User groups</title>
<body>

<p>
When you can't find your answer amongst your friends or colleagues (or they
aren't immediately available for help) your best bet would be to ask in <e>User
Groups</e>. A Linux User Group (abbreviated to LUG) is a group of Linux users
who gather to discuss Linux, give Linux-related presentations, etc.
</p>

<p>
User Groups are often a good place to start as well since they give you a
friendly neighbourhood-like environment where you can ask questions, as simple
as they might be, without being seen as a "dull newbie". A User Group is also a
good place to find distributions so you can get the latest and greatest
distribution for a small fee (most likely the costs of an empty CD/DVD) so you
don't need to download it yourself.
</p>

<p>
In many User Groups you will often find events such as <e>Install Fests</e>. An
install festival is a social event where you can bring your computer to and
where other people will help you install your favorite distribution. Even
better, they will help you tweak it, making it more performant, up to date and
tailored to your needs.
</p>

</body>
</subsection>
<subsection>
<title>Virtual forums</title>
<body>

<p>
Often called virtual user groups are the web site forums, places where you can
find literally hundreds of people willing to help you in any way possible. On
these forums (of which the <uri link="http://forums.gentoo.org">Gentoo
Forums</uri> are probably a perfect example) you can ask everything you want (as
long as it remains on-topic).
</p>

<p>
Forums have a big advantage: you can always consult them, 24/7, and you will
often find that they react quite fast. They also work as a great knowledge base
where you can search through, hopefully finding someone who has posed your
question before and has received all the information he needed. In that case,
you don't need to re-ask (it is even considered rude to ask questions that have
been answered not long ago).
</p>

<p>
Forums are also a great way to make friends: if you are very helpful yourself,
you will undoubtedly get noticed. More than often will you find out that others
live near you and share the same hobbies and interests. What better incentive do
you need to get out to a pub and get a beer :)
</p>

</body>
</subsection>
</section>
<section>
<title>Books and guides</title>
<subsection>
<title>Online guides</title>
<body>

<p>
For specific subjects you might find that online guides prove to be a better
resource. Such guides explain a single topic in great extend, often in a
step-by-step construction, guiding you through the topic.
</p>

<p>
When you consult one of the more interactive resources (like forums) you will
often be referred to an online guide which covers your subject. More than often
provide those guides the best answer to your question, so don't be upset when
the people don't answer your question but refer you to such a guide.
</p>

<p>
Gentoo has quite a lot of those <uri
link="http://www.gentoo.org/doc/en/">helpful guides</uri>. If you think Gentoo
is missing an interesting subject, don't hesitate to ask for one or even write
one. Most documentation is written by volunteering contributors, so why not try
and contribute :)
</p>

<p>
You will also find such guides, often in the form of a HOWTO, at the <uri
link="http://www.tldp.org/docs.html#howto">Linux Documentation Project</uri>.
</p>

</body>
</subsection>
<subsection>
<title>Books</title>
<body>

<p>
When you want to learn more about a broader subject (like Gentoo in general) or
in more detail than any guide could offer, you might want to buy (or download) a
full book instead. <uri link="http://www.oreilly.com">O'Reilly</uri> has several
dozens of books available covering a lot of subjects. A book is probably the
most ultimate help you can find for self-teaching, but mind you, books often get
outdated and aren't replaced as fast as online guides.
</p>

<p>
Some books are available online. More than often are they grown from a small
guide to a larger one, eventually changing their layout from a guide to a book.
This has happened with the <uri
link="http://www.gentoo.org/doc/en/handbook">Gentoo Handbook</uri> and <uri
link="http://www.gentoo.org/doc/en/security">Gentoo Security Handbook</uri>.
Once they were only a few pages long. Now they span over a hundred pages.
</p>

<p>
You can find online books at <uri link="http://www.tldp.org/guides.html">the
Linux Documentation Project</uri>.
</p>

</body>
</subsection>
<subsection>
<title>Massive collaboration guides</title>
<body>

<p>
Unlike the books, who don't get much updates, and the guides who do get updates
if the maintainer is active, there are special kinds of online information pages
that do get a lot of updates: massive collaboration guides, often in the form of
so-called <e>WiKi</e> projects.
</p>

<p>
Pages like these can be updated by any user who wishes so, making it quite easy
to quickly fix issues and expand the document. But this fast updating has one
major setback: people can easily sneak in more errors in the guide, or provide
you with a step-by-step trail that is against the spirit of the subject you are
interested in.
</p>

<p>
There is an unofficial <uri link="http://www.gentoo-wiki.com">Gentoo Wiki</uri>
filled with guides written by several hundreds of users. 
</p>

</body>
</subsection>
</section>
<section>
<title>Online help</title>
<subsection>
<title>Manual pages</title>
<body>

<p>
Manual pages are documentation pages that cover a single command. A manual page
is a reference document that explains all possible options you can give at a
command. Unlike guides they do not provide you with a step-by-step explanation
on the subject and are therefore not interesting for guided help. They are
however very important once you know the tool but want to know it better.
</p>

<p>
When you are inside a Linux system, you can obtain the manual page for a
specific command or subject by typing <c>man&nbsp;&lt;subject&gt;</c>. For 
instance, to get the manual page for the <c>emerge</c> command often used on 
Gentoo:
</p>

<pre caption="Getting the emerge manual page">
$ <i>man emerge</i>
</pre>

<p>
Almost every possible command has a manual page on your system.
</p>

</body>
</subsection>
<subsection>
<title>Info pages</title>
<body>

<p>
Another commonly used format to display information is the GNU Info browser.
Whereas the man pages are a single resource containing a quick and dirty
overview of the command (and its options), the info pages are a more extensive
resource, dividing information in chapters, sections, ... and allowing you to
browse from one subject to another.
</p>

<p>
To view an info page for a command, type <c>info&nbsp;&lt;command&gt;</c>.
You'll be greeted by the info browser where you can navigate up and down using
your arrow keys (line by line) or <c>PageUp</c> and <c>PageDown</c> (screen by
screen). When you encounter a link (visualized by a <c>*</c> in front of it and
<c>::</c> after) press <c>Enter</c> to go to the page.
</p>

<p>
Using the keys <c>u</c> (up), <c>n</c> (next) and <c>p</c> (previous) you can
navigate through the documentation easily. To quit, press <c>q</c>.
</p>

</body>
</subsection>
<subsection>
<title>Added documentation</title>
<body>

<p>
Lots of software tools add documentation to your Linux system. This
documentation can be in the form of a PDF document, HTML pages or plain text. In
most cases, this documentation is stored in
<path>/usr/share/doc/&lt;software&nbsp;title&gt;</path>.
</p>

<p>
For instance, the <c>bzip2</c> compression utility has a manual (in PDF format)
stored inside <path>/usr/share/doc/bzip2-1.0.3-r4</path> (the version might be
different on your system).
</p>

</body>
</subsection>
<subsection>
<title>Immediate help</title>
<body>

<p>
Most tools have immediate help available when you run the tool with
<c>--help</c> or <c>-h</c> as one of its arguments. Do not hope to find much
information here: in most cases the help provided is just a short summary of the
available options. 
</p>

<p>
For instance, for the <c>emerge</c> command (which does list quite a lot of
detailed information):
</p>

<pre caption="Getting immediate help for the emerge program">
$ <i>emerge --help</i>
</pre>

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



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-intro-support.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-intro-support.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-intro-support.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-intro-support.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-intro-support.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Priceless</title>
<subsection>
<title>Userbase</title>
<body>

<p>
Free Software has a very active user community, filled with people who are eager
to help you install, configure and maintain free software. <e>Help your
neighbour</e> has never been as succesful as with Free Software.
</p>

<p>
Take the <uri link="irc://irc.freenode.net/#gentoo">#gentoo</uri> support
channel as an example. It has over 800 users who help any Gentoo user or
interested party with whatever question he or she might have. Or the <uri
link="http://forums.gentoo.org">Gentoo Forums</uri> which has over 2'000 posts
per day.
</p>

<p>
You can and will find support for the Free Software you want, support given by
users of that software, who believe the software is the best in its field and
have good experiences with the software. Of course, there is a trade: this
support is on a volunteer basis, so don't expect someone to answer your question
immediately - if you are not friendly, you will undoubtedly be ignored or even
removed from the support channels.
</p>

</body>
</subsection>
<subsection>
<title>Developer base</title>
<body>

<p>
When you have feature requests, or you have found a bug in the software, the
developers are always happy to hear from you. Most projects even have public
bugtracking systems where you can submit bugreports to or ask for software
enhancements.
</p>

<p>
As a user, you deal with the developers personally and not with some obscure
phone number with a robotic voice on the other end, or an automated reply server
who thanks you for your submission only to never hear from it again. These
developers are devoted in bringing you the best software available and hope that
you can help them improve it. 
</p>

<p>
Those developers live all over the world, in all possible timezones, so when you
mail a developer or talk with him directly (for instance over IRC), do not
expect him to be available all the time. Not only can he be very sleepy because
it is 03.00 on his side, he can also be unavailable due to real-life issues, 
phone calls, etc. Remember, most developers work on the software in their free 
time.
</p>

</body>
</subsection>
</section>
<section>
<title>Timeless</title>
<subsection>
<title>Archives</title>
<body>

<p>
Free Software is timeless. Most projects keep older releases around and some
projects even archive free software for various reasons (such as allowing people
to find out how old a certain feature is). 
</p>

<p>
You will also find archives of the mailinglists used by the project, sometimes
even daily IRC logs. Support channels like the bugtracking system or the forums
keep all posts and information around in case you would ever need it.
</p>

</body>
</subsection>
<subsection>
<title>Stalled software</title>
<body>

<p>
When a software project "dies" (for instance because the developer(s) are too
busy with real-life or just dropped interest in the project), it does not
disappear. Such projects are only <e>stalled</e> and ready to be picked up by
someone who wants to devote some of his time to the project. Nothing of the
project gets lost: the software itself remains, documentation remains, ...
</p>

<p>
This is one of the major advantages of Free Software: unlike propriatary
software which might get dropped by the company, the software does <e>not</e>
disappear. If you require long time support for any type of software, you can
only trust Free Software - you can never know when the propriatary software is
discontinued. In the worst case with Free Software, you will need to
take on development of the software on your own or hire someone to do it for
you.
</p>

</body>
</subsection>
</section>
<section>
<title>Immortal</title>
<subsection>
<title>Freedom</title>
<body>

<p>
Because the software is free, you can not kill it. The software can not be taken
over by another company. When the project is turned over to an organisation that
you do not like, you can just take the software and <e>fork</e> it (a term
used to denote that two or more projects develop software based on the same
code, but do this independently with their own goals and development accents).
</p>

<p>
The author of the software can not revoke the rights he has given to you first:
once the software is free, it remains free. 
</p>

</body>
</subsection>
<subsection>
<title>Paid support</title>
<body>

<p>
If you are not satisfied with the support you receive, you can obtain paid
support (contracts with a certain support level attached to it) if you want.
In many cases, this paid support isn't given by the project itself but by a
third party that is well known to the software code base and maintenance.
</p>

<p>
On certain occasions, you can obtain paid support from the software project
itself as well. 
</p>

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



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-intro-user_fhs.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-intro-user_fhs.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-intro-user_fhs.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-intro-user_fhs.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-intro-user_fhs.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Why multi-user?</title>
<subsection>
<title>Separation of privileges</title>
<body>

<p>
One of the advantages of a multi-user operating system like Linux is that the
privileges are separated. Each process runs with specific privileges and can
only execute a limited number of tasks. As long as the process does not run
as the <c>root</c> user (the allmighty administrator privilege) it can only deal
with files and tasks that are assigned to that particular user.
</p>

<p>
This separation of privileges provides a small but working security wall: as
long as all your users use the system with their user account and not with the
<c>root</c> account, the worst that can happen is that the user removed his own
files - the system itself is left untouched.
</p>

<p>
For this reason, you will always hear not to use the <c>root</c> account. 
</p>

</body>
</subsection>
<subsection>
<title>System accounts</title>
<body>

<p>
To enforce the separation of privileges, specific system accounts are created
for each task. If you run a mail server on your system, that mail server will
have a user account on your system. 
</p>

<p>
These accounts are not usable by regular users: you can not log in on your
system using those accounts. They exist only to allow the specific processes to
run with their own permissions and privileges.
</p>

</body>
</subsection>
</section>
<section>
<title>Users and permissions</title>
<subsection>
<title>The user ID</title>
<body>

<p>
To identify a system account, a unique <e>user identification</e> is used: the
UID. This is a number used by the Linux kernel and other applications as 
numbers are easier to deal with than names (strings). However, Linux is 
intelligent enough to immediately translate the UID to a user name and vice 
versa, so in most cases you will only see or use the user name instead of the 
UID.
</p>

</body>
</subsection>
<subsection>
<title>The process ID</title>
<body>

<p>
When your Linux system is up and running, it will have started various processes
already. Each process is an application (or part of an application) and receives
a unique <e>process identifier</e> (which is also a number): the PID. 
</p>

<p>
PIDs play an important role in the administration of a running Linux system:
you need the PID of a specific process to be able to terminate it (in case it
behaves badly), change priorities or receive specific system usage statistics
regarding a particular application.
</p>

<p>
For regular Linux usage however, the PID is less important: you still need to
understand what a PID is, but you will probably not encounter any use of it
until you administer your system.
</p>

</body>
</subsection>
<subsection>
<title>Privileges</title>
<body>

<p>
Each process obtains privileges based on the user account it uses. By default, 
a process runs with the privileges of the user that started the
process. For instance, if you start <c>firefox</c> it will run with your
privileges.
</p>

<p>
However, some processes have a specific flag set that tells the Linux kernel not
to run the process as the user that executed it, but as a specific user
instead. This flag is called the <e>set user id</e> (SetUID or SUID) and tells 
the Linux kernel to run this application with the privileges of the 
<e>owner</e> of that application instead of the <e>executor</e>.
</p>

<p>
Most tools that have the SUID bit set are owned by the <c>root</c> user and
therefore start running with the privileges of the <c>root</c> user. Because
this is a security thread (remember, running things as <c>root</c> can be
dangerous) most tools have a feature called <e>privilege separation</e>: when
they are started, they first run the tasks they have to run as <c>root</c> after
which they automatically decrease their own privileges to a less powerful state.
</p>

</body>
</subsection>
</section>
<section>
<title>Linux file system hierarchy</title>
<subsection>
<title>Structure of a file system</title>
<body>

<p>
The most pertinent change Linux users will have to be comfortable with is the
file system structure which is quite different from the file system structure
operating systems like Microsoft Windows use.
</p>

<p>
In Linux, the entire file system is structured as one huge tree. You start with
the root of the tree and traverse down until you reach your goal. The next Code
Listing shows you the first depth of a Linux file system:
</p>

<pre caption="Incomplete example of a Linux File System">
/        <comment>(The root)</comment>
+- bin/  <comment>(Executable programs needed to get the system up and running)</comment>
+- boot/ <comment>(Files related to the boot loader and Linux kernel)</comment>
+- dev/  <comment>(Device files)</comment>
+- etc/  <comment>(Configuration files)</comment>
+- home/ <comment>(User home directories)</comment>
+- lib/  <comment>(Libraries needed to get the system up and running)</comment>
+- mnt/  <comment>(Location for mount points)</comment>
+- opt/  <comment>(Contains large package installations not part of a regular install)</comment>
+- proc/ <comment>(Kernel-provided information)</comment>
+- root/ <comment>(Home directory for the root user)</comment>
+- sbin/ <comment>(System administration executables to get the system up and running)</comment>
+- sys/  <comment>(Kernel-provided information)</comment>
+- tmp/  <comment>(Temporary files)</comment>
+- usr/  <comment>(Applications for day-to-day system usage)</comment>
`- var/  <comment>(Variable information like log-files, caches, ...)</comment>
</pre>

<p>
Suppose you want to navigate to the CUPS error logs (CUPS is a printing service
frequently used on Linux systems) which are located inside
<path>/var/log/cups</path> you will find the following tree:
</p>

<pre caption="Expanded tree to /var/log/cups">
<i>/</i>
+- bin/
<comment>(...)</comment>
+- usr/
`- <i>var/</i>
   +- cache/
   +- db/
   +- lock/
   +- <i>log/</i>
   |  +- <i>cups/</i>
   |  |  +- access_log
   |  |  +- error_log
   |  |  `- page_log
   |  +- dmesg
   |  +- emerge.log
   |  +- lastlog
   |  `- messages
   +- run/
   +- spool/
   +- state/
   `- tmp/
</pre>

<p>
Each location has its purpose as defined in the <uri
link="http://www.pathname.com/fhs">Linux File System Hierarchy Standard</uri>.
As said before, Linux builds upon standards and the file system structure is no
exception. Each Linux distribution adheres to this standard (although a few
deviations are known). If you want to learn more about the file system
structure, please read this standard. A short summary can also be found on your
Linux system in the <c>hier</c> manual ("hier" is short for "hierarchy").
</p>

</body>
</subsection>
<subsection>
<title>Scattered files</title>
<body>

<p>
One often frowned upon result of this file system structure is that applications
scatter their files around on the system. Indeed, the locations for executable
files, data files, documentation files, configuration files, ... are defined in
the hierarchy standard but result in files being scattered throughout the file
system instead of at a single location.
</p>

<p>
For instance, for a regular application the executable files will be stored in
<path>/usr/bin</path>, data files in 
<path>/usr/share/&lt;application&nbsp;name&gt;/</path>, documentation files in 
<path>/usr/share/man</path> (for the manuals) or in the data file location, 
configuration files in <path>/etc</path>, libraries in <path>/usr/lib</path>, 
etc.
</p>

<p>
It is up to the distribution to keep track of the files that belong to a
particular package. The software management system of a distribution is
therefore a very important tool and is often the application that distinguishes
one distribution from the others. For Gentoo, the software management system is
called Portage.
</p>

</body>
</subsection>
<subsection>
<title>System administration versus system usage</title>
<body>

<p>
When you are using your Linux system for daily tasks you should be logged on as
a regular user. This user will only have write-access to his personal <e>home
directory</e>, located in <path>/home</path>, and have read access to most
other places on the system (except where sensitive information is stored). 
</p>

<p>
This user will be able to execute most applications that are stored in the
regular executable locations (<path>/bin</path>, <path>/usr/bin</path> and a few
other places). Whenever the user wants to run an application, the system will
search through those directories for a matching application: it will not 
search through the entire system.
</p>

<p>
The administrative user (<c>root</c>) however has access to every location on
the system. When he wants to execute an application, the system will search
through <e>system administration locations</e> such as <path>/sbin</path> and
<path>/usr/sbin</path> as well. Those locations contain tools that should only
be ran by the <c>root</c> user. The <c>root</c> user can also read and write to
every location on the system (although particular kernel projects exist that
allow for more access control, limiting even the <c>root</c> user's
capabilities).
</p>

</body>
</subsection>
<subsection>
<title>The role of hardware</title>
<body>

<p>
Within the tree structure there does not seem to be any room for the hardware 
(like disks, CD-ROMs, USB sticks or network mounts). Of course, hardware is 
important - where else would you store your files on if you do not have a hard 
disk? The use of such hardware however happens transparent to the user.
</p>

<p>
Storing files in Linux happens in a layered structure. At the bottom of the
layer, you have the actual storage (most likely the partition or removable
media). On top of the actual storage you have the file system. A file system can
be spanned across several storage devices but most users will have one partition
per file system. The file system is <e>mounted</e> in the Linux file system
structure. Such mount always happens at a certain directory.
</p>

<p>
By default, you will have at least one file system for the root of your file
system. If you only want to use a single file system, you can have your entire
Linux system on a single partition. If you want to use several partitions, you
need to think about what directory (and its subdirectories) you want to store 
on a different file system. 
</p>

<p>
For instance, you might want to have <path>/home</path> stored on a separate
file system which allows you to have all the users their data on a single
partition (or drive). What happens is that you create a file system on that
partition (or drive) and then <e>mount</e> this at <path>/home</path>.
</p>

<p>
If you do not mount it at <path>/home</path>, the <path>/home</path> and all its
contents will be stored on the file system that contains the root of the file
system. If you do mount it at <path>/home</path>, <path>/home</path> and all its
contents will be stored on the other file system.
</p>

<p>
This mounting does have an important implication: if you forget to mount a file
system at a certain location, the Linux file system structure will look as if
that location contains no files. You will be able to add files to that location
of course, but they will then be stored on the root file system instead of on
the file system you forgot to mount.
</p>

<p>
In the next Code Listing we show you an example layered approach. The root file
system is stored on <path>/dev/hda1</path> which represents the first partition
on the first IDE disk in your system. The <path>/home</path> location is stored
on a separate file system (which happens to be the same <e>kind</e> of file
system: an ext3 one). This file system is stored on a <e>meta device</e> (a 
device that actually consists of multiple devices - in this case two 
partitions).
</p>

<pre caption="Example layered approach for the Linux file system">
+--------------------+----------------------------+
|   / (root)         |   /home (home directories) |  <comment>&lt;- location</comment>
+--------------------+----------------------------+
|   ext3 instance    |   ext3 instance            |  <comment>&lt;- file system</comment>
+--------------------+--------------+-------------+
|                    |        /dev/md/0           |
|   /dev/hda1        +--------------+-------------+  <comment>&lt;- devices</comment>
|                    |  /dev/hdb1   |  /dev/hdc1  | 
+--------------------+--------------+-------------+
</pre>

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



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-intro-versions.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-intro-versions.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-intro-versions.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-intro-versions.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-intro-versions.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Versioning</title>
<subsection>
<title>The role of freedom</title>
<body>

<p>
When you are allowed to do anything you want, whenever you want and wherever you
want, you will probably think total chaos is but a few inches away. Yet with
Free Software we see that people work together closely, forming hierarchies
built upon knowledge and expertise instead of popularity: most projects are
governed as a <e>meritocracy</e> instead of a <e>democracy</e>.
</p>

<p>
In a meritocacry, the power goes to the people who have shown that they are
superior in their field above most others. The hierarchies formed within a
larger software project are chosen based on the abilities of the
developers and not their charisma or any political decision.
</p>

<p>
In such projects, the lead developers decide when software is ready. There are
generally five states where we can pin software on: in-development, tagged,
development release, stable release and revised. We explain those states in the
next few sections.
</p>

</body>
</subsection>
<subsection>
<title>State: in-development</title>
<body>

<p>
Software that is in-development is software where the developers work on
constantly. When you have software installed on your system that is
in-development, your software will already be outdated by the time you use it
(unless the project isn't quite active of course).
</p>

<p>
Such software has the latest version of everything: every feature, every bug and
every file that has been started is available in the software. Of course, this
does mean that there is hardly any quality assurance on the software apart from
the quality measures taken by the developers themselves. 
</p>

<p>
Think as if you bought a painting where the painter was still busy painting: you
will probably see it isn't finished yet.
</p>

<p>
If you are interested in such software, you might very well be a good candidate
to become a developer for that software. In-development software is often
referred to as the software available through the verioning system, such as CVS
or SVN. Some distributions allow you to install such software despite it being
unfinished. For instance, within Gentoo you can install <c>cinelerra-cvs</c>,
the in-development version of the Cinelerra Video Editor. In this case, you will
install the software that was in-development at the moment of installing. Every
time you reinstall it, the latest in-development program code is used.
</p>

<p>
Most users however are not interested in the in-development version of any
software. Distributions that allow installing such software therefore also
protect their users by making sure the user knows what he is doing before he can
install such software. In case of Gentoo, you must configure Portage to allow
the installation of <e>untested</e> software.
</p>

</body>
</subsection>
<subsection>
<title>State: tagged and static</title>
<body>

<p>
When the developers know that the in-development software code works, or they
want it as a reference for future development, they <e>tag</e> the software.
Such tagged software is often called a <e>snapshot</e> of the in-development
code and is given a specific name (most likely the date when the snapshot was
taken). 
</p>

<p>
This occurs often when the project does not allow outsiders to use the
in-development code straight from the versioning system (for instance because
the versioning system is not powerful enough to handle user requests or because
they want a subproject to control the quality of the code before it is handed to
contributors and interested parties).
</p>

<p>
Using such snapshots is often preferred to the in-development code because the
distributions who use the software can ask the user who uses the snapshot which
snapshot they took. Then the developers can install that specific snapshot
themselves and see if they can reproduce the problem. When using in-development
code, the developer would need to know exactly when the user has installed the
in-development code.
</p>

<p>
Take Gentoo as an example: various (untested) packages are snapshots.
<c>gentoo-syntax-20050325</c> is the snapshot taken on March 25th, 2005 of the
<c>gentoo-syntax</c> package which provides syntax hilighting and indentation
settings for <c>vim</c> (a popular command-line editor) for editing Gentoo 
related files.
</p>

</body>
</subsection>
<subsection>
<title>State: development release</title>
<body>

<p>
When the developers feel that the software is in a quite good shape, they will
tag it again but instead of having it as a snapshot, they will make it a
<e>development release</e>. In most cases, such a release is more than just a
snapshot: it is made simultaneously with documentation updates, project web site
updates and after meeting quality assurance. The project advises people who want
to contribute to the development of the project to use at least the development
release.
</p>

<p>
Because of this, such releases are given a specific version. Sometimes you can
see that it is a development release by the name. For instance,
<c>kdoc-2.0_alpha54</c> is a development release (because it contains the atom
<c>alpha</c>) of <c>kdoc</c>, a KDE documentation processing/generation tool.
</p>

<p>
There are three atoms generally used to denote development releases: 
<c>alpha</c> (quite new, far from ready for production use), <c>beta</c> (should
give a nice idea how the program will look and behave like when it is officially
released to the public) and <c>rc</c> (<e>release candidate</e> - already
contains all the features the final release will have, only bug fixes are
accepted).
</p>

<p>
Previously, lots of projects made development releases. However, we notice that
lately most projects have stepped down and only make official releases and
in-development code. Distributions are now taking on the job of making snapshots
and (although in lesser extend) development releases. Only when <e>major</e>
releases are made projects make development releases to make sure the final
release is really bugfree.
</p>

</body>
</subsection>
<subsection>
<title>State: stable release</title>
<body>

<p>
The real release is the stable release. Such releases are generally governed by
a specific subproject of the software project and are made simultaneously with
documentation updates, web site updates, and public release information.
</p>

<p>
If you are not interested in contributing to the project, you should use the
stable releases of a project since these releases are very stable (they have
undergone a lot of testing), have the most support (user and development 
community), documentation, etc.
</p>

<p>
For instance, <c>kde-meta-3.4.1</c> is an official release of the KDE project
(version 3.4.1). You will find that the KDE project itself has written a <uri
link="http://www.kde.org/announcements/announce-3.4.1.php">Press Release</uri>:
this is an official statement by the project meant for various news sites,
editors, distributions and interested users to inform them a new release is
made. It contains pointers about the new features and enhancements that are put
in the software and where you can download the software release.
</p>

<p>
The given example, <c>kde-meta-3.4.1</c>, is a great example for us to inform
you about versioning numbers. The <c>3</c> is the <e>major version</e>. This
number only changes when <e>very big changes</e> have happened since the
previous release. The <c>4</c> is a <e>minor version</e>, informing people that
the release has <e>big</e> updates but that they don't warrant a major version
bump (a <e>bump</e> means to increase a number by one). The <c>1</c> is a
<e>release revision</e> (although many people will also say it is a minor
version). New releases that only differ in the revision number have small
changes that improve stability, resolve security issues and bug fixes, but have
relatively minor feature enhancements.
</p>

</body>
</subsection>
<subsection>
<title>State: revised</title>
<body>

<p>
While the official project makes stable releases, it is the distribution that
makes sure that regular users can install the software on their system. Of
course, you can install the software straight from the official project, but
then you don't have the advantages that the distribution offers you with respect
to software management.
</p>

<p>
The distribution takes the official release and makes some minor changes to it
so that it installs flawlessly on your system. It might add in some eye-candy,
add in some additional features that are highly asked upon by the community or
change the location or names of some files to make the installation easier to
manage.
</p>

<p>
Sometimes, the distribution finds a bug in the software (based on feedback it
has received by users of the distribution or by the developers themselves).
Quite often, the distribution will fix the issue for the users of the
distribution and release it: in such cases, a <e>revision update</e> is made.
</p>

<p>
Take <c>gdm-2.6.0.9-r3</c> as an example. The official release is <c>2.6.0.9</c>
(if you think this is a dull version, check out <c>binutils-2.15.94.0.2.2</c>)
but Gentoo has made three revision releases since: the first revision
(<c>-r1</c>) added Gentoo-specific PAM support. The second revision made the
package stable for various architectures (different kind of systems). The third
revision fixed some IPv6 issues.
</p>

</body>
</subsection>
</section>
<section>
<title>Forks</title>
<subsection>
<title>Same software, different software</title>
<body>

<p>
We have touched the idea of a <e>fork</e> previously. A fork happens when one
group of developers is not satisfied with another group of developers and start
developing the same software, but differently. This occurs on occasion in the 
Free Software world.
</p>

<p>
For instance, one group of developers might not easily accept new features while
there is a huge demand for it. This has happened with <c>blackbox</c>: its
developers did not accept certain feature enhancements so a group of developers
forked the code. They started <c>fluxbox</c> which was essentially the same as
<c>blackbox</c> but its development was different as were the end goals. As of
today, both projects still exist.
</p>

</body>
</subsection>
</section>
<section>
<title>The role of distributions</title>
<subsection>
<title>Ease of use</title>
<body>

<p>
Whereas regular software releases can still be quite difficult a distribution
makes it very easy to install software. When you want to install software as
released by the projects, you still need to know <e>how</e> to install it and
what options you need to enable. You need to know <e>what</e> you should have 
installed prior to installing the software (the dependencies).
</p>

<p>
When you install software using the distribution, the distribution does all this
for you. It will automatically resolve dependencies and conflicts, use the
correct installation options and merge the software on your system, registering
every file it installs so that uninstallations are easy as cake.
</p>

</body>
</subsection>
<subsection>
<title>Protecting users from themselves</title>
<body>

<p>
Because projects have development releases and even snapshots and in-development
code, distributions help their users by making sure novice users can not shoot
themselves in the foot by installing such software while retaining the
possibility of using such releases by more advanced users.
</p>

<p>
Distributions also register every file installation. If a user wants to install
software that overwrites a file, the distribution will make sure this cannot
happen or that the changes are reversible. A distribution will also make sure
that two packages that interfere can not be both installed on the system.
</p>

</body>
</subsection>
<subsection>
<title>Feedback to upstream</title>
<body>

<p>
One of the most important roles of distributions is to provide feedback to the
original software projects about how their software functions within the
totality of a Linux system. The distributions inform the software projects about
bugs that users reported to the distribution and they provide valuable
enhancement requests <e>with</e> contributions based on the revision updates
they have made themselves.
</p>

<p>
Quite often distributions have developers working for them who also work on the
software projects. It goes without saying that this only improves the
cooperation between the two projects.
</p>

</body>
</subsection>
<subsection>
<title>Taking care of updates</title>
<body>

<p>
A distribution also takes care of informing the user about updates. Updates can
happen for various reasons. The most important ones are <e>security updates</e>.
In this case, the distribution warns the user that he needs to update (or accept
the pending updates) because there are security issues with his current system.
</p>

<p>
Other updates are mostly new versions (new features, lots of bug fixes) made by
the software project itself (in other words, new releases) or
distribution-specific updates (new revision releases by the distribution).
</p>

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



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-io.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-io.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-tuning-io.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-tuning-io.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-tuning-io.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Know what to measure</title>
<subsection>
<title>Benchmarks</title>
<body>

</body>
</subsection>
<subsection>
<title>Usage sessions</title>
<body>

</body>
</subsection>
<subsection>
<title>Gut feeling</title>
<body>

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

<section>
<title>Understanding the chain</title>
<subsection>
<title>System calls</title>
<body>

</body>
</subsection>
<subsection>
<title>Kernel driver</title>
<body>

</body>
</subsection>
<subsection>
<title>Hardware</title>
<body>

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

<section>
<title>Tuning the system calls</title>
</section>

<section>
<title>Tuning the kernel drivers</title>
</section>

<section>
<title>Tuning the hardware</title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-network.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-network.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-tuning-network.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-tuning-network.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-tuning-network.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Network cards and drivers</title>
</section>

<section>
<title>Ethernet network</title>
</section>

<section>
<title>Connected Internet</title>
</section>

<section>
<title>Wireless networks</title>
</section>

<section>
<title>Virtual private networks</title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-profiling.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-profiling.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-tuning-profiling.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-tuning-profiling.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-tuning-profiling.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>Execution profiling</title>
</section>

<section>
<title>Memory profiling</title>
</section>

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

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-rendering.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-rendering.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-tuning-rendering.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-tuning-rendering.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-tuning-rendering.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

<section>
<title>All about drivers</title>
</section>

<section>
<title>nVidia-based graphical cards</title>
</section>

<section>
<title>ATI-based graphical cards</title>
</section>

<section>
<title>Render engines</title>
</section>

</sections>



1.1                  xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-userinput.xml

file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/handbook/draft/complete/hb-tuning-userinput.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-tuning-userinput.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo

Index: hb-tuning-userinput.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-tuning-userinput.xml,v 1.1 2006/01/06 20:05:07 swift Exp $ -->

<sections>

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

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

<section>
<title>Parallel execution</title>
</section>

<section>
<title>Gradual detailing</title>
</section>

</sections>



-- 
gentoo-doc-cvs@g.o mailing list