Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 368793 - Critical handbook bug!!! needs urgent fix!!!11
Summary: Critical handbook bug!!! needs urgent fix!!!11
Status: RESOLVED DUPLICATE of bug 213988
Alias: None
Product: [OLD] Docs on www.gentoo.org
Classification: Unclassified
Component: Installation Handbook (show other bugs)
Hardware: All Linux
: Highest blocker (vote)
Assignee: Docs Team
URL: http://forums.gentoo.org/viewtopic-t-...
Whiteboard:
Keywords: Bug
Depends on:
Blocks:
 
Reported: 2011-05-26 14:47 UTC by Armada
Modified: 2011-05-27 04:31 UTC (History)
0 users

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Armada 2011-05-26 14:47:36 UTC
hello all,

First off I don't wanna sound like a whinner or a pricky nuisance but the handbook has a major flaw currently. Actually two. I was installing Gentoo when I came across the first bug on this section:

8. Configuring your System

Quote:
Code Listing 2.8: Adding net.eth0 to the default runlevel

# rc-update add net.eth0 default

If you have several network interfaces, you need to create the appropriate net.eth1, net.eth2 etc. initscripts for those. You can use ln to do this:

Code Listing 2.9: Creating extra initscripts

# cd /etc/init.d
# ln -s net.lo net.eth1
# rc-update add net.eth1 default



What's wrong with the above section? It tells to add something to the default run-level without actually creating it. My installation DID NOT have /etc/init.d/net.eth0 nor was automatically symlinked to /etc/init.d/net.lo. The second mistake is that it only mentions creating a second interface ln -s net.lo net.eth1 without the first. I would correct the above section as follows:
Quote:
Code Listing 2.8: Creating net.eth0 and adding it to the default runlevel

# cd /etc/init.d
# ln -s net.lo net.eth0
# rc-update add net.eth0 default

If you have several network interfaces, you need to create the appropriate net.eth1, net.eth2 etc. initscripts for those. You can use ln to do this:

Code Listing 2.9: Creating extra initscripts

# cd /etc/init.d
# ln -s net.lo net.eth1
# rc-update add net.eth1 default


This bug could actually explain the hordes of n00bs spamming #gentoo about their network interface not being brought up upon boot.

The next handbook bug is even more alarming, from the same section:
8. Configuring your System
Quote:
Gentoo uses /etc/conf.d/clock to set clock options. Edit it according to your needs.

What? The file /etc/conf.d/clock neither its /etc/init.d/clock are currently used by Gentoo as I found out through un-official sources. The correct file is in /etc/conf.d/hwclock which has its corresponding /etc/init.d/hwclock. Next the section gives a description how to do it:

Quote:
Code Listing 3.4: Opening /etc/conf.d/clock

# nano -w /etc/conf.d/clock

If your hardware clock is not using UTC, you need to add CLOCK="local" to the file. Otherwise you will notice some clock skew.

You should define the timezone that you previously copied to /etc/localtime so that further upgrades of the sys-libs/timezone-data package can update /etc/localtime automatically. For instance, if you used the GMT timezone, you would add TIMEZONE="GMT"

When you're finished configuring /etc/conf.d/clock, save and exit.


So here the entire section is incorrect because /etc/conf.d/clock doesn't exist!! Currently Gentoo uses /etc/conf.d/hwclock in which case an updated version would read as follows:

Quote:
Code Listing 3.4: Opening /etc/conf.d/hwclock

# nano -w /etc/conf.d/hwclock

If your hardware clock is not using UTC, you need to add CLOCK="local" to the file. Otherwise you will notice some clock skew.

You should define the timezone that you previously copied to /etc/localtime so that further upgrades of the sys-libs/timezone-data package can update /etc/localtime automatically. For instance, if you used the GMT timezone, you would add TIMEZONE="GMT"

When you're finished configuring /etc/conf.d/hwclock, save and exit.


In addition in this section would be a good idea to explain "If your hardware clock is not using UTC, you need to add CLOCK="local" to the file. Otherwise you will notice some clock skew. " Which kind of hardware would NOT use UTC? Why would a hardware NOT use UTC? How would some be able to tell whether their hardware use UTC or something else?? So the difference between "UTC" and using "local" isn't entirely clear.

The Gentoo handbook has an update timestamp off "Updated May 9, 2011" which is full 20 days without being fixed, and certainly ever since the the switch from /etc/conf.d/clock to /etc/conf.d/hwclock. And who knows how long it has been. However the handbook got 35 editors I am positive the two bugs can be fixed in a pronto fashion. I'll give it maximum 2 hours from this post until my next refresh of Gentoo handbook page.

Please don't think I am beeotching or anything, just trying to keep a first class meta-distro with a first class, error-free, handbook :D

Thanks in advanced!!


Reproducible: Always

Steps to Reproduce:
1.Go to www.gentoo.org
2.Navigate to the handbook
3.Read the handbook section "8. Configuring your System" (http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?style=printable&full=1#book_part1_chap8)
Comment 1 Armada 2011-05-26 18:24:15 UTC
The corrected clock section should read:

--- start ---

Gentoo uses /etc/conf.d/hwclock to set clock options. Edit it according to your needs.

Code Listing 3.4: Opening /etc/conf.d/hwclock

# nano -w /etc/conf.d/hwclock

If your hardware clock is not using UTC, you need to add CLOCK="local" to the file. Otherwise you will notice some clock skew.

You should define the timezone that you previously copied to /etc/localtime so that further upgrades of the sys-libs/timezone-data package can update /etc/localtime automatically. For instance, if you used the GMT timezone, you would add TIMEZONE="GMT"

When you're finished configuring /etc/conf.d/hwclock, save and exit.

--- end ---

Also would then be "clock options" or "hwclock options"?

plz comment!!
Comment 2 Armada 2011-05-26 18:31:27 UTC
oops sorry again, just realized that the copy/pasta from the forums isn't completely clear here. The corrected net.eth0 part should read:

--- start ---

Code Listing 2.8: Creating net.eth0 and adding it to the default runlevel

# cd /etc/init.d
# ln -s net.lo net.eth0
# rc-update add net.eth0 default

If you have several network interfaces, you need to create the appropriate
net.eth1, net.eth2 etc. initscripts for those. You can use ln to do this:

Code Listing 2.9: Creating extra initscripts

# cd /etc/init.d
# ln -s net.lo net.eth1
# rc-update add net.eth1 default

--- end ---

Again apologies and I hope this gets a prompt fix as I wasted almost a day with it and filing forum/bugzilla post.
Comment 3 nm (RETIRED) gentoo-dev 2011-05-27 04:31:15 UTC

*** This bug has been marked as a duplicate of bug 213988 ***