Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 213988 - [TRACKER] OpenRC / baselayout-2 documentation changes
Summary: [TRACKER] OpenRC / baselayout-2 documentation changes
Status: RESOLVED FIXED
Alias: None
Product: [OLD] Docs on www.gentoo.org
Classification: Unclassified
Component: Other documents (show other bugs)
Hardware: All Linux
: High normal (vote)
Assignee: Docs Team
URL:
Whiteboard:
Keywords: Tracker
: 246119 260761 266785 366603 368169 368793 369013 369367 369935 370955 372219 373593 373597 374773 374993 (view as bug list)
Depends on: 218593 269349 275003 295613 348724 366603 367145 369841 376087 377309 378119 378495 382373 382525
Blocks: 212696 218141 218859 219038 260761
  Show dependency tree
 
Reported: 2008-03-20 05:10 UTC by Doug Goldstein
Modified: 2011-12-26 15:00 UTC (History)
38 users (show)

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


Attachments
Patch to update gentoo-freebsd (gentoo-freebsd.patch,1.22 KB, patch)
2011-09-09 21:51 UTC, Francisco Blas Izquierdo Riera
Details | Diff
Fixed doc discarding the timezone variable (gentoo-freebsd.patch,1.24 KB, patch)
2011-09-09 21:57 UTC, Francisco Blas Izquierdo Riera
Details | Diff
Fix the handbook so it properly refers to the clock variable and discards the TIMEZONE=" (hb-install-config.patch,1.11 KB, patch)
2011-09-09 22:46 UTC, Francisco Blas Izquierdo Riera
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Doug Goldstein gentoo-dev 2008-03-20 05:10:32 UTC
This bug is intended to track any and all documentation changes that need to happen to successfully land OpenRC into Gentoo. It's also a meta bug for a migration guide that I would like to write with a member of the docs team. I've already shot an e-mail off to nightmorph about that.
Comment 1 Doug Goldstein gentoo-dev 2008-04-15 05:57:09 UTC
softlevel= as a kernel parameter will be replaced by rc_runlevel= in OpenRC 0.2.2 and higher
Comment 2 Wolfram Schlich (RETIRED) gentoo-dev 2008-04-15 08:19:50 UTC
(In reply to comment #1)
> softlevel= as a kernel parameter will be replaced by rc_runlevel= in OpenRC
> 0.2.2 and higher

Will softlevel= still work until some version X (backward compatibility)?
Comment 3 SpanKY gentoo-dev 2008-04-15 13:36:33 UTC
of course
Comment 4 Doug Goldstein gentoo-dev 2008-04-15 18:15:07 UTC
When I said "replaced", I meant in a documentation stand point that we should be promoting this as a the default parameter to set.

I'm just trying to keep notes on this bug rather then in my head or on a piece of paper or a file that only I can access. That way, if I miss something.. or I get something wrong.. someone else can contribute.
Comment 5 nm (RETIRED) gentoo-dev 2008-04-17 21:49:02 UTC
We only mention softlevel in two documents:

http://www.gentoo.org/doc/en/power-management-guide.xml, which has two related open bugs already (bug #205117 and bug #209258) -- this definitely needs some fixes, which no one's coherently provided thus far.

http://www.gentoo.org/doc/en/handbook/hb-working-rcscripts.xml

Please look through these docs and figure out what needs to be changed to what. Our documentation will *not* be split into "stable baselayout-1" and "~arch openrc" bits. I'd prefer to just default all instructions to OpenRC once it's stable, since it doesn't look like baselayout-1 will be maintained after that point.

All that being said, we're closer to fixing this tracker bug, as the openrc migration guide is complete.
Comment 6 Matthew Schultz 2008-04-24 15:25:34 UTC
The documentation net.example in particular needs to be updated.  Apparently comments inside /etc/conf.d/net commands foul them up.

Example:

pppd_ppp0="
#       maxfail 0       # WARNING: It's not recommended you use this
#                       # if you don't specify maxfail then we assume 0
#       updetach        # If not set, "/etc/init.d/net.ppp0 start" will return
"

"/etc/init.d/net.ppp0 start" will cause it to not parse properly.

Also could you add documentation on what the syntax is for setting up two phone numbers for dial up?

#phone_number_ppp0="12345689" # Maximum 2 phone numbers are supported

Used to be: 

phone_number_ppp0=( "12345689 "12345678")


Is it now this?

phone_number_ppp0="'12345689' '12345678'"

or?

phone_number_ppp0="12345689 12345678"
Comment 7 Matthew Schultz 2008-04-24 15:26:40 UTC
Sorry old style syntax was this:

phone_number_ppp0=( "12345689" "12345678" )

Comment 8 Duncan 2008-04-24 17:27:00 UTC
(In reply to comment #6)
> The documentation net.example in particular needs to be updated.

(This is a tracker so being brief.)  Note that the network config is still in flux.  As the current GMN announcement states, this is ~arch for a reason.  GMANE link to discussion thread with the details: 

http://thread.gmane.org/gmane.linux.gentoo.devel/55824
Comment 9 Kundai Midzi 2008-05-05 08:53:33 UTC
Does anyone know where I can find the (official) developer docs for openrc. I'm trying to find out the purpose of all the directories in /lib/rc/init.d. I'm not sure about things such as "exclusive", "scheduled", etc.
Comment 10 Doug Goldstein gentoo-dev 2008-05-05 13:49:14 UTC
Not the bug for this..
Comment 11 Peter Volkov (RETIRED) gentoo-dev 2008-10-15 17:41:37 UTC
May be bug 240984 could became addition here. At least part on
"The cold/hotplugging has now been moved into one variable - rc_hotplug"
Comment 12 Doug Goldstein gentoo-dev 2008-12-22 23:00:41 UTC
*** Bug 246119 has been marked as a duplicate of this bug. ***
Comment 13 nm (RETIRED) gentoo-dev 2009-04-15 06:54:01 UTC
*** Bug 260761 has been marked as a duplicate of this bug. ***
Comment 14 nm (RETIRED) gentoo-dev 2009-04-19 19:25:39 UTC
*** Bug 266785 has been marked as a duplicate of this bug. ***
Comment 15 Rick Leijssen 2009-11-18 09:02:39 UTC
Not sure wether this is the right place for this (otherwise please point me to the right place). 

I noticed in the gentoo handbook, the page on configuring your system (http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=8) still mentions that rc.conf has the EDITOR and DISPLAYMANAGER variables.

Also, the migration guide mentions to set the EDITOR variable in /etc/env.d while the comments in /etc/profile suggest setting a system default for this in /etc/profile.d.
Comment 16 William Hubbs gentoo-dev 2009-12-19 23:42:24 UTC
Can we have an update on this bug?

Is it here to trackthe work on the migration guide only, or what else is
supposed to be tracked here?

Thanks,

William

Comment 17 William Hubbs gentoo-dev 2010-01-09 01:38:11 UTC
Docs team,

I need status please?  Is this bug resolved?

Thanks,

William

Comment 18 nm (RETIRED) gentoo-dev 2010-01-09 02:14:11 UTC
As far as I know we keep this bug open so that as new config issues come up we can handle them quickly. As OpenRC upstream doesn't seem to have a set config syntax, it changes often enough either on the upstream side or the Gentoo side that the doc needs updates fairly often.

More to the point, we keep this bug open because when/if OpenRC and baselayout-2 go stable, we'll need to apply all the changes in this bug to the rest of our documentation. Right now only the migration guide has anything -- every single other doc is setup for baselayout-1 and the "usual" initscripts.
Comment 19 William Hubbs gentoo-dev 2010-01-09 04:23:19 UTC
(In reply to comment #18)
> As far as I know we keep this bug open so that as new config issues come up we
> can handle them quickly. As OpenRC upstream doesn't seem to have a set config
> syntax, it changes often enough either on the upstream side or the Gentoo side
> that the doc needs updates fairly often.
> More to the point, we keep this bug open because when/if OpenRC and
> baselayout-2 go stable, we'll need to apply all the changes in this bug to the
> rest of our documentation. Right now only the migration guide has anything --
> every single other doc is setup for baselayout-1 and the "usual" initscripts.

In that case, shouldn't the stabilization tracker block this bug instead of the other way around like it is  now?

Thanks,

William
Comment 20 nm (RETIRED) gentoo-dev 2010-01-09 06:55:27 UTC
(In reply to comment #19)
> In that case, shouldn't the stabilization tracker block this bug instead of the
> other way around like it is  now?

I'd rather not. Converting all our documentation to use OpenRC/baselayout-2 is a massive undertaking -- I'd like to have it done immediately prior to stabilization, or at the same time. We need time to get it all documented. It should be a simultaneous stabilization/doc effort by the package maintainers and the GDP, otherwise our users will be very, very unhappy.
Comment 21 David Abbott gentoo-dev 2010-01-09 21:17:40 UTC
The documentation is going to depend if we stay with the current /etc/conf.d/net with /etc/init.d/net.bla or go with the new /etc/conf.d/network
Comment 22 William Hubbs gentoo-dev 2010-01-10 23:24:08 UTC
(In reply to comment #21)
> The documentation is going to depend if we stay with the current
> /etc/conf.d/net with /etc/init.d/net.bla or go with the new /etc/conf.d/network

I'm not sure this has to be a one or the other situation.  We will need to document the new network scriptss and tell users how to switch over to them if they want to, but for now at least, we are supporting both afaik.
Comment 23 SpanKY gentoo-dev 2010-08-07 22:53:15 UTC
i dont think anything is changing with /etc/init.d/net* stuff.  the default is still /etc/init.d/net.${iface} like it always has been.

since Roy is no longer driving things, i suggest we quietly mothball /etc/init.d/network and forget about the "old" vs "new" net stuff.
Comment 24 David J Cozatt 2010-11-25 04:16:26 UTC
*bump* this seems to be the only bug blocking bug #295613

Is the doc team on the cc list here? Closing this bug would have a nice domino affect 
Comment 25 Christian Faulhammer (RETIRED) gentoo-dev 2010-11-25 07:49:42 UTC
(In reply to comment #24)
> Is the doc team on the cc list here? Closing this bug would have a nice domino
> affect 

 The docs team is the assignee of the bug. :) Problem is, someone has to do the work to be able to close this bug.
Comment 26 nm (RETIRED) gentoo-dev 2010-11-25 10:01:45 UTC
This is a tracker bug, so it stays open until all our docs have been migrated to OpenRC/baselayout-2, which won't be happening until they go stable on all arches, and are present in our installation media.

In the future, please send inqueries of this nature via IRC or email lists, rather than adding comments to the bug. Thanks.
Comment 27 Sebastian Pipping gentoo-dev 2010-11-29 10:33:20 UTC
(In reply to comment #26)
> This is a tracker bug, so it stays open until all our docs have been migrated
> to OpenRC/baselayout-2, which won't be happening until they go stable on all
> arches, and are present in our installation media.

Isn't that a chicken and egg problem?  If you document it, it can go stable faster.  Also, you would have saved both Mike and me bug #346783 altogether.
What's the problem with a note on ~arch and OpenRC?
Comment 28 nm (RETIRED) gentoo-dev 2010-11-30 00:15:20 UTC
(In reply to comment #27)
> Also, you would have saved both Mike and me bug #346783 altogether.

Please read the OpenRC migration guide; it already covers kernel module configuration.

> What's the problem with a note on ~arch and OpenRC?

We will not document ~arch packages in our handbook. That is our policy, and it is not going to change. If you want to know why we won't fork our documentation, please read all the similar threads on the gentoo-doc mailing list, and even check the forums for posts by myself and other GDP members. Your question has already been answered -- it comes up every now and then, and our response has not changed.

No one has said a word to the GDP in recent months about any realistic plan or schedule for stabilizing OpenRC/baselayout-2 across all arches. Until then, the only place we'll document those packages is in the migration guide.

Again, please refrain from posting unnecessary comments. This bug is for monitoring individual documents that need updating. Anything else just adds more spam to everyone's inboxes, and make it harder to keep track of actual problems for the GDP to fix.
Comment 29 nm (RETIRED) gentoo-dev 2010-11-30 00:16:11 UTC
Removing a non-blocking bug per its comment 17. Nothing the GDP can take care of.
Comment 30 Robin Johnson archtester Gentoo Infrastructure gentoo-dev Security 2011-01-12 23:00:14 UTC
I'm working on some parts of this now.
Comment 31 nm (RETIRED) gentoo-dev 2011-05-09 17:50:24 UTC
*** Bug 366603 has been marked as a duplicate of this bug. ***
Comment 32 Mike Thompson 2011-05-14 22:24:30 UTC
I had a lot of trouble figuring out how to make a static route work out until I happened on one little clue.  The advice given in Code Listing 2.11 ought to work, but it didn't.  It turns out that, contrary to some of the old comments--including the openrc-0.8.2-r1/README.newnet.bz2 file--I do not need to set up /etc/conf.d/staticroute.

Code Listing 2.11 indicates that the new style for /etc/conf.d/net should have
config_eth0="192.168.1.37 netmask 255.255.255.0 brd 192.168.1.255"

When I did things this way, I kept getting an SIOCADDRT error message about a process not being found.

When I changed things to the form shown in openrc-0.8.2-r1/net.example, my static route worked great.  The key is to omit the broadcast address.  I also changed things to the CIDR form, as the example shows:

config_eth0="192.168.1.37/27"

I had no trouble with the routes_eth0 line.
Comment 33 nm (RETIRED) gentoo-dev 2011-05-20 20:22:36 UTC
*** Bug 368169 has been marked as a duplicate of this bug. ***
Comment 34 Claude Juif 2011-05-26 12:06:28 UTC
Hi, 
I'm following this bug because i've noticed some weird things in the installation process (gentoo handbook)

It seems that latest stage3 tarball (stage3_amd64_20110520) mix baselayout1 and baselayout2. For example : 

Doc stat that : modify /etc/conf.d/clock but in this stage tarball the right file is /etc/conf.d/hwclock. But  at the same time, /etc/conf.d/net is still the right file for configuring network

Same for timezone (/etc/timezone ????).

Complaining here because it's really confusing for new user to follow things clearly. (i'm installing gentoo since many years so it's not really a problem for me, but i always recommend Gentoo to my friends and a lot of them complaining about diffculties to achieve installation, cause of this openRC migration)

Gentoo handbook say this : 

Stage3 tarballs can be downloaded from releases/amd64/autobuilds/current-stage3/ on any of the Official Gentoo Mirrors and are not provided on the LiveCD. 

And i think this is THE sentence confusing everyone.

Maybe you should just build a baselayout1 final tarball and point to it in the handbook. So you can wait for OpenRC migration to complete.

I hope you understand that this minor bug can be a critical bug for community

Best regards,
Comment 35 nm (RETIRED) gentoo-dev 2011-05-27 04:31:15 UTC
*** Bug 368793 has been marked as a duplicate of this bug. ***
Comment 36 nm (RETIRED) gentoo-dev 2011-05-28 14:53:19 UTC
*** Bug 369013 has been marked as a duplicate of this bug. ***
Comment 37 Florian Philipp 2011-05-30 09:08:16 UTC
(In reply to comment #34)
> Hi, 
> I'm following this bug because i've noticed some weird things in the
> installation process (gentoo handbook)
[...]
> Doc stat that : modify /etc/conf.d/clock but in this stage tarball the right
> file is /etc/conf.d/hwclock. But  at the same time, /etc/conf.d/net is still
> the right file for configuring network
> 
> Same for timezone (/etc/timezone ????).
[...]

Same issues are in the Localization Guide.
Comment 38 nm (RETIRED) gentoo-dev 2011-05-30 20:07:33 UTC
*** Bug 369367 has been marked as a duplicate of this bug. ***
Comment 39 nm (RETIRED) gentoo-dev 2011-06-03 23:23:45 UTC
*** Bug 369935 has been marked as a duplicate of this bug. ***
Comment 40 nm (RETIRED) gentoo-dev 2011-06-10 03:22:51 UTC
*** Bug 370955 has been marked as a duplicate of this bug. ***
Comment 41 nm (RETIRED) gentoo-dev 2011-06-19 03:23:52 UTC
*** Bug 372219 has been marked as a duplicate of this bug. ***
Comment 42 Jean-Claude Gervais 2011-06-28 19:15:49 UTC
The item I would like to add is simply an ordering-swap:

In both the cases of the x86 and amd64 documentation, creation of the network device(s) must be performed BEFORE adding the device(s) to the default runlevel.

As it is currently in the manual, the steps are inverted.

The latest stage tarballs of both x86 and amd64 do NOT contain an net.eth0 nor an net.wlan0 or other except for net.lo (which is correct).

Please refer to the relevant portion of the (amd64) manual:
http://www.gentoo.org/doc/en/handbook/handbook-amd64.xml?part=1&chap=8#doc_chap2

Basically,

Code Listing 2.9: Creating [extra] initscripts

should come before

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

Perhaps a line prefacing the two explaining that the user must choose the network devices that will be used by the system.

Thank you.
Comment 43 nm (RETIRED) gentoo-dev 2011-07-01 03:41:12 UTC
*** Bug 373597 has been marked as a duplicate of this bug. ***
Comment 44 nm (RETIRED) gentoo-dev 2011-07-01 03:59:36 UTC
*** Bug 373593 has been marked as a duplicate of this bug. ***
Comment 45 Jean-Marc Beaune 2011-07-06 09:32:13 UTC
Not sure if it's the right place but x86 handbook still refers to old style modules autoloading: http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=7

This should be updated with using /etc/conf.d/modules
Comment 46 Jean-Marc Beaune 2011-07-06 10:19:16 UTC
Also clock setup located at http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=1&chap=8 should be updated with using /etc/conf.d/hwclock
Comment 47 Sven Vermeulen 2011-07-06 16:55:28 UTC
btw, the module stuff fix is part of bug #369841
Comment 48 nm (RETIRED) gentoo-dev 2011-07-11 23:53:22 UTC
*** Bug 374773 has been marked as a duplicate of this bug. ***
Comment 49 Alex Legler (RETIRED) archtester Gentoo Infrastructure gentoo-dev Security 2011-07-12 18:48:56 UTC
*** Bug 374993 has been marked as a duplicate of this bug. ***
Comment 50 nm (RETIRED) gentoo-dev 2011-08-02 02:31:43 UTC
*** Bug 377309 has been marked as a duplicate of this bug. ***
Comment 51 Francisco Blas Izquierdo Riera gentoo-dev 2011-09-09 21:51:19 UTC
Created attachment 286007 [details, diff]
Patch to update gentoo-freebsd

This patch updates the old path in the guide.

I'm working on patching some other docs too.
Comment 52 Francisco Blas Izquierdo Riera gentoo-dev 2011-09-09 21:57:22 UTC
Created attachment 286009 [details, diff]
Fixed doc discarding the timezone variable
Comment 53 Francisco Blas Izquierdo Riera gentoo-dev 2011-09-09 22:46:10 UTC
Created attachment 286015 [details, diff]
Fix the handbook so it properly refers to the clock variable and discards the TIMEZONE="

There is an issue in the handbook using old variables and adding a TIMEZONE=" in /etc/timezone which shouldn't be there.
Comment 54 Francisco Blas Izquierdo Riera gentoo-dev 2011-09-10 16:49:37 UTC
*** Bug 382525 has been marked as a duplicate of this bug. ***
Comment 55 Nikolay Antonov 2011-11-30 18:41:32 UTC
Please add "Changelog" file to openrc-xxx.tar.bz
Comment 56 Sven Vermeulen (RETIRED) gentoo-dev 2011-12-10 15:21:44 UTC
Nikolay: what do you mean with adding ChangeLog to openrc-xxx.tar.bz2?

You mean that the tarball (sources) of OpenRC should contain a ChangeLog file? If so, then please create a separate bug report on that, this tracker is for documentation changes.
Comment 57 Sven Vermeulen (RETIRED) gentoo-dev 2011-12-26 15:00:11 UTC
No open issues. Please report any findings as new bugs.