Documentation on rc.conf.local lacks important warning

classic Classic list List threaded Threaded
23 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Documentation on rc.conf.local lacks important warning

VaZub
Hi all,

There is a small nuisance I've stumbled upon during my first
experiments with OpenBSD.

Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
(10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
it to /etc/rc.conf.local and edit afterwards. Yet it seems both fail
to mention, that in order to prevent your system from going ballistic
after doing this, you should also comment out or delete a particular
line of code in /etc/rc.conf.local, namely this one:
"[ -f /etc/rc.conf.local ] && . /etc/rc.conf.local". Not good,
especially for those who do follow official instructions and still
suddenly find themselves with a broken system on their hands for no
apparent reason.

This might seem like a trivial issue for old-timers, and one is sure
to find the appropriate solution with a little bit of deeper googling,
but having short relevant notices in the aforementioned manuals could
save newcomers some introductory frustration. What do you think? Is
there anyone among those looking after the official documentation up
to consider such a suggestion?

Regards,
Vasyl Zubko

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Kenneth Westerback
rc.conf(8) says "create and edit a rc.conf.local". Not copy rc.conf.
I'm not sure what the FAQ says but I'd think it would be similar
advice.

.... Ken

On 9 February 2014 13:28, VaZub <[hidden email]> wrote:

> Hi all,
>
> There is a small nuisance I've stumbled upon during my first
> experiments with OpenBSD.
>
> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
> it to /etc/rc.conf.local and edit afterwards. Yet it seems both fail
> to mention, that in order to prevent your system from going ballistic
> after doing this, you should also comment out or delete a particular
> line of code in /etc/rc.conf.local, namely this one:
> "[ -f /etc/rc.conf.local ] && . /etc/rc.conf.local". Not good,
> especially for those who do follow official instructions and still
> suddenly find themselves with a broken system on their hands for no
> apparent reason.
>
> This might seem like a trivial issue for old-timers, and one is sure
> to find the appropriate solution with a little bit of deeper googling,
> but having short relevant notices in the aforementioned manuals could
> save newcomers some introductory frustration. What do you think? Is
> there anyone among those looking after the official documentation up
> to consider such a suggestion?
>
> Regards,
> Vasyl Zubko

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Rogier Krieger
In reply to this post by VaZub
Though I looked on a 5.3 system, rc.conf(8) suggests the following:
"It is advisable to leave rc.conf untouched, and instead create and edit a
new rc.conf.local file."

That's rather different from creating a copy. From a brief look at CVS,
it's the same for -current.

Regards,

Rogier


On Sun, Feb 9, 2014 at 7:28 PM, VaZub <[hidden email]> wrote:

> Hi all,
>
> There is a small nuisance I've stumbled upon during my first
> experiments with OpenBSD.
>
> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
> it to /etc/rc.conf.local and edit afterwards. Yet it seems both fail
> to mention, that in order to prevent your system from going ballistic
> after doing this, you should also comment out or delete a particular
> line of code in /etc/rc.conf.local, namely this one:
> "[ -f /etc/rc.conf.local ] && . /etc/rc.conf.local". Not good,
> especially for those who do follow official instructions and still
> suddenly find themselves with a broken system on their hands for no
> apparent reason.
>
> This might seem like a trivial issue for old-timers, and one is sure
> to find the appropriate solution with a little bit of deeper googling,
> but having short relevant notices in the aforementioned manuals could
> save newcomers some introductory frustration. What do you think? Is
> there anyone among those looking after the official documentation up
> to consider such a suggestion?
>
> Regards,
> Vasyl Zubko
>
>


--
If you don't know where you're going, any road will get you there.

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Bret S. Lambert-2
In reply to this post by VaZub
On Sun, Feb 09, 2014 at 08:28:43PM +0200, VaZub wrote:

> Hi all,
>
> There is a small nuisance I've stumbled upon during my first
> experiments with OpenBSD.
>
> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
> it to /etc/rc.conf.local and edit afterwards. Yet it seems both fail
> to mention, that in order to prevent your system from going ballistic
> after doing this, you should also comment out or delete a particular
> line of code in /etc/rc.conf.local, namely this one:
> "[ -f /etc/rc.conf.local ] && . /etc/rc.conf.local". Not good,
> especially for those who do follow official instructions and still
> suddenly find themselves with a broken system on their hands for no
> apparent reason.
>
> This might seem like a trivial issue for old-timers, and one is sure
> to find the appropriate solution with a little bit of deeper googling,
> but having short relevant notices in the aforementioned manuals could
> save newcomers some introductory frustration. What do you think? Is
> there anyone among those looking after the official documentation up
> to consider such a suggestion?

You've probably confused rc.conf.local for rc.local, but it's impossible
to tell, given that you've delivered a polemic, and not a description
of what you tried to do, and how it didn't end up as you expected.

>
> Regards,
> Vasyl Zubko

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Barry Grumbine-2
In reply to this post by Kenneth Westerback
The FAQ says the same:
"We strongly suggest you do not alter /etc/rc.conf itself. Instead,
create or edit the file /etc/rc.conf.local, copy just the lines you
need to change from /etc/rc.conf and adjust them as you like."

rc.conf is gives a good hint as well:
# To select the service options you desire, please override these
# options in the file /etc/rc.conf.local

To "override" options in rc.conf, I often do something like:
# grep tftp /etc/rc.conf >> /etc/rc.conf.local

Which gives me something nice to work with:
tftpd_flags=NO          # for normal use: "[chroot dir]"
tftpproxy_flags=NO      # for normal use: ""


-Barry

On Sun, Feb 9, 2014 at 11:44 AM, Kenneth Westerback
<[hidden email]> wrote:

> rc.conf(8) says "create and edit a rc.conf.local". Not copy rc.conf.
> I'm not sure what the FAQ says but I'd think it would be similar
> advice.
>
> .... Ken
>
> On 9 February 2014 13:28, VaZub <[hidden email]> wrote:
>> Hi all,
>>
>> There is a small nuisance I've stumbled upon during my first
>> experiments with OpenBSD.
>>
>> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
>> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
>> it to /etc/rc.conf.local and edit afterwards. Yet it seems both fail
>> to mention, that in order to prevent your system from going ballistic
>> after doing this, you should also comment out or delete a particular
>> line of code in /etc/rc.conf.local, namely this one:
>> "[ -f /etc/rc.conf.local ] && . /etc/rc.conf.local". Not good,
>> especially for those who do follow official instructions and still
>> suddenly find themselves with a broken system on their hands for no
>> apparent reason.
>>
>> This might seem like a trivial issue for old-timers, and one is sure
>> to find the appropriate solution with a little bit of deeper googling,
>> but having short relevant notices in the aforementioned manuals could
>> save newcomers some introductory frustration. What do you think? Is
>> there anyone among those looking after the official documentation up
>> to consider such a suggestion?
>>
>> Regards,
>> Vasyl Zubko

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Kirill Bychkov
In reply to this post by VaZub
On Sun, February 9, 2014 22:28, VaZub wrote:
> Hi all,
>
> There is a small nuisance I've stumbled upon during my first
> experiments with OpenBSD.
>
> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
> it to /etc/rc.conf.local and edit afterwards. Yet it seems both fail

Hi. In FAQ it's suggested to copy needed strings, not the file itself:
"We strongly suggest you do not alter /etc/rc.conf itself. Instead, create or
edit the file /etc/rc.conf.local, copy just the lines you need to change from
/etc/rc.conf and adjust them as you like. "

> to mention, that in order to prevent your system from going ballistic
> after doing this, you should also comment out or delete a particular
> line of code in /etc/rc.conf.local, namely this one:
> "[ -f /etc/rc.conf.local ] && . /etc/rc.conf.local". Not good,
> especially for those who do follow official instructions and still
> suddenly find themselves with a broken system on their hands for no
> apparent reason.
>
> This might seem like a trivial issue for old-timers, and one is sure
> to find the appropriate solution with a little bit of deeper googling,
> but having short relevant notices in the aforementioned manuals could
> save newcomers some introductory frustration. What do you think? Is
> there anyone among those looking after the official documentation up
> to consider such a suggestion?
>
> Regards,
> Vasyl Zubko

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Peter N. M. Hansteen-3
In reply to this post by VaZub
VaZub <[hidden email]> writes:

> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
> it to /etc/rc.conf.local and edit afterwards.

rc.conf(8) says


     It is advisable to leave rc.conf untouched, and instead create and edit a
     new rc.conf.local file.  Variables set in this file will override
     variables previously set in rc.conf.

I suppose it's possible to interpret that as an instruction to copy
/etc/rc.conf, but I think this is the first time I've heard anybody
admit to doing that.  

Leaving rc.conf alone is good advice, it's a "treat as binary"
file. When its content changes some variable the startup scripts
depend on has been added or changed, it's for a good reason that you
will find documented in the man pages, release notes and the FAQ.

It never occured to me to create rc.conf.local by copying the entire
rc.conf, mainly because it makes perfect sense that a file with
override values only needs to contain your local customizations,
anything else is noise that is likely to be a source of trouble
later. This may or may not have been due to actually reading rc.conf
and finding the line sourcing rc.conf.local at some point, but anyway
it's been a while since my first contact with any of this.  Once you
have actually read rc.conf (if not earlier) it should be fairly
obvious that rc.conf.local only needs to contain the variables you
actually need to change from the default values.

> Yet it seems both fail to mention, that in order to prevent your
> system from going ballistic after doing this, you should also
> comment out or delete a particular line of code in
> /etc/rc.conf.local, namely this one: "[ -f /etc/rc.conf.local ] &&
> . /etc/rc.conf.local". Not good, especially for those who do follow
> official instructions and still suddenly find themselves with a
> broken system on their hands for no apparent reason.

You did not in fact read the FAQ too carefully, did you?
http://www.openbsd.org/faq/faq10.html says

  "We strongly suggest you do not alter /etc/rc.conf itself. Instead,
   create or edit the file /etc/rc.conf.local, copy just the lines you
   need to change from /etc/rc.conf and adjust them as you like. This
   makes future upgrades easier -- all the changes are in the one file
   that isn't touched during upgrade."

"copy just the lines you need" -- how can this be made any clearer?

- Peter

--
Peter N. M. Hansteen, member of the first RFC 1149 implementation team
http://bsdly.blogspot.com/ http://www.bsdly.net/ http://www.nuug.no/
"Remember to set the evil bit on all malicious network traffic"
delilah spamd[29949]: 85.152.224.147: disconnected after 42673 seconds.

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

VaZub
Sorry, my bad - I assumed that it was only natural for newcomers to
copy the file and edit it afterwards instead of creating it from
scratch to override some values. Obviously, this assumption was based
on my ignorance and therefore wrong. You are also right to point out
that to "copy the lines" is not the same as "copy the whole file" - I
must have missed this particular distinction.

The only thing I can put in my defense is that I might have been
mislead to some extent by a particular piece of text -
http://www.openbsd.org/faq/upgrade47.html#rc.conf. Of course, it is
outdated and should not be taken for granted in regards to version
5.4, but it was one of few leads I've found when trying to fix my
problem with rc.conf.local file.
Nevertheless, please forgive me for my foolish assumptions and for
taking your time. And thanks for clearing things up.

V.



On Sun, Feb 9, 2014 at 9:14 PM, Peter N. M. Hansteen <[hidden email]> wrote:

> VaZub <[hidden email]> writes:
>
>> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
>> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
>> it to /etc/rc.conf.local and edit afterwards.
>
> rc.conf(8) says
>
>
>      It is advisable to leave rc.conf untouched, and instead create and edit a
>      new rc.conf.local file.  Variables set in this file will override
>      variables previously set in rc.conf.
>
> I suppose it's possible to interpret that as an instruction to copy
> /etc/rc.conf, but I think this is the first time I've heard anybody
> admit to doing that.
>
> Leaving rc.conf alone is good advice, it's a "treat as binary"
> file. When its content changes some variable the startup scripts
> depend on has been added or changed, it's for a good reason that you
> will find documented in the man pages, release notes and the FAQ.
>
> It never occured to me to create rc.conf.local by copying the entire
> rc.conf, mainly because it makes perfect sense that a file with
> override values only needs to contain your local customizations,
> anything else is noise that is likely to be a source of trouble
> later. This may or may not have been due to actually reading rc.conf
> and finding the line sourcing rc.conf.local at some point, but anyway
> it's been a while since my first contact with any of this.  Once you
> have actually read rc.conf (if not earlier) it should be fairly
> obvious that rc.conf.local only needs to contain the variables you
> actually need to change from the default values.
>
>> Yet it seems both fail to mention, that in order to prevent your
>> system from going ballistic after doing this, you should also
>> comment out or delete a particular line of code in
>> /etc/rc.conf.local, namely this one: "[ -f /etc/rc.conf.local ] &&
>> . /etc/rc.conf.local". Not good, especially for those who do follow
>> official instructions and still suddenly find themselves with a
>> broken system on their hands for no apparent reason.
>
> You did not in fact read the FAQ too carefully, did you?
> http://www.openbsd.org/faq/faq10.html says
>
>   "We strongly suggest you do not alter /etc/rc.conf itself. Instead,
>    create or edit the file /etc/rc.conf.local, copy just the lines you
>    need to change from /etc/rc.conf and adjust them as you like. This
>    makes future upgrades easier -- all the changes are in the one file
>    that isn't touched during upgrade."
>
> "copy just the lines you need" -- how can this be made any clearer?
>
> - Peter
>
> --
> Peter N. M. Hansteen, member of the first RFC 1149 implementation team
> http://bsdly.blogspot.com/ http://www.bsdly.net/ http://www.nuug.no/
> "Remember to set the evil bit on all malicious network traffic"
> delilah spamd[29949]: 85.152.224.147: disconnected after 42673 seconds.

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Donald Allen
On Sun, Feb 9, 2014 at 2:32 PM, VaZub <[hidden email]> wrote:

> Sorry, my bad - I assumed that it was only natural for newcomers to
> copy the file and edit it afterwards instead of creating it from
> scratch to override some values. Obviously, this assumption was based
> on my ignorance and therefore wrong. You are also right to point out
> that to "copy the lines" is not the same as "copy the whole file" - I
> must have missed this particular distinction.
>
> The only thing I can put in my defense is that I might have been
> mislead to some extent by a particular piece of text -
> http://www.openbsd.org/faq/upgrade47.html#rc.conf. Of course, it is
> outdated and should not be taken for granted in regards to version
> 5.4, but it was one of few leads I've found when trying to fix my
> problem with rc.conf.local file.
> Nevertheless, please forgive me for my foolish assumptions and for
> taking your time. And thanks for clearing things up.

You made a mistake, it got explained to you, you acknowledged it, all
fine. I would only add this: one of the things that is particularly
outstanding about OpenBSD is the documentation. You may have been
trained (badly) by documentation for other operating environments that
is either inaccurate or incomplete, and so did not read carefully.
OpenBSD is different in this respect -- the people who develop it take
unusual care in making sure it is well-documented, so the
documentation is worth reading and reading carefully.

/Don Allen

>
> V.
>
>
>
> On Sun, Feb 9, 2014 at 9:14 PM, Peter N. M. Hansteen <[hidden email]> wrote:
>> VaZub <[hidden email]> writes:
>>
>>> Both the man page for rc.conf(8) as well as the official OpenBSD FAQ
>>> (10.3) suggest to avoid editing /etc/rc.conf directly and instead copy
>>> it to /etc/rc.conf.local and edit afterwards.
>>
>> rc.conf(8) says
>>
>>
>>      It is advisable to leave rc.conf untouched, and instead create and edit a
>>      new rc.conf.local file.  Variables set in this file will override
>>      variables previously set in rc.conf.
>>
>> I suppose it's possible to interpret that as an instruction to copy
>> /etc/rc.conf, but I think this is the first time I've heard anybody
>> admit to doing that.
>>
>> Leaving rc.conf alone is good advice, it's a "treat as binary"
>> file. When its content changes some variable the startup scripts
>> depend on has been added or changed, it's for a good reason that you
>> will find documented in the man pages, release notes and the FAQ.
>>
>> It never occured to me to create rc.conf.local by copying the entire
>> rc.conf, mainly because it makes perfect sense that a file with
>> override values only needs to contain your local customizations,
>> anything else is noise that is likely to be a source of trouble
>> later. This may or may not have been due to actually reading rc.conf
>> and finding the line sourcing rc.conf.local at some point, but anyway
>> it's been a while since my first contact with any of this.  Once you
>> have actually read rc.conf (if not earlier) it should be fairly
>> obvious that rc.conf.local only needs to contain the variables you
>> actually need to change from the default values.
>>
>>> Yet it seems both fail to mention, that in order to prevent your
>>> system from going ballistic after doing this, you should also
>>> comment out or delete a particular line of code in
>>> /etc/rc.conf.local, namely this one: "[ -f /etc/rc.conf.local ] &&
>>> . /etc/rc.conf.local". Not good, especially for those who do follow
>>> official instructions and still suddenly find themselves with a
>>> broken system on their hands for no apparent reason.
>>
>> You did not in fact read the FAQ too carefully, did you?
>> http://www.openbsd.org/faq/faq10.html says
>>
>>   "We strongly suggest you do not alter /etc/rc.conf itself. Instead,
>>    create or edit the file /etc/rc.conf.local, copy just the lines you
>>    need to change from /etc/rc.conf and adjust them as you like. This
>>    makes future upgrades easier -- all the changes are in the one file
>>    that isn't touched during upgrade."
>>
>> "copy just the lines you need" -- how can this be made any clearer?
>>
>> - Peter
>>
>> --
>> Peter N. M. Hansteen, member of the first RFC 1149 implementation team
>> http://bsdly.blogspot.com/ http://www.bsdly.net/ http://www.nuug.no/
>> "Remember to set the evil bit on all malicious network traffic"
>> delilah spamd[29949]: 85.152.224.147: disconnected after 42673 seconds.

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

dc@genunix.com
<snippage>
>
> You made a mistake, it got explained to you, you acknowledged it, all
> fine. I would only add this: one of the things that is particularly
> outstanding about OpenBSD is the documentation.

Question .. where do I get all the man pages?  I have some of them
but then others are absent :


# man reboot
REBOOT(8)               OpenBSD System Manager's Manual              REBOOT(8)

NAME
     reboot, halt - stopping and restarting the system

SYNOPSIS
     halt [-dnpq]
     reboot [-dnq]

DESCRIPTION
     The halt and reboot utilities flush the file system cache to disk,
     execute the rc.d(8) scripts specified by the pkg_scripts variable defined
     in rc.conf(8) in a reverse order, run the system shutdown script, send
     all running processes a SIGTERM (and subsequently a SIGKILL), and,
     respectively, halt or restart the system.  The action is logged,
     including entering a shutdown record into the login accounting file.

     The options are as follows:

     -d      Causes system to create a dump before rebooting.  This option is
             useful for debugging system dump procedures or capturing the
             state of a corrupted or misbehaving system.  See savecore(8) for
             information on how to recover this dump.

     -n      Prevent file system cache from being flushed.  This option should
             probably not be used.

     -p      Causes the system to power down, if it is being halted, and the
             hardware supports automatic power down.

             See also the description of powerdown, below.

     -q      Quick.  The system is halted or restarted quickly and
             ungracefully, and only the flushing of the file system cache is
             performed.  This option should probably not be used.

     Normally, the shutdown(8) utility is used when the system needs to be
     halted or restarted, giving users advance warning of their impending
     doom.

FILES
     /etc/rc.shutdown  Script which is run at shutdown time.  If it sets the
                       variable powerdown to ``YES'', halt will attempt to
                       power down the machine after it has halted.

SEE ALSO
     reboot(2), utmp(5), boot_alpha(8), boot_amd64(8), boot_hp300(8),
     boot_hppa(8), boot_hppa64(8), boot_i386(8), boot_luna88k(8),
     boot_macppc(8), boot_mvme68k(8), boot_mvme88k(8), boot_sparc(8),
     boot_sparc64(8), boot_vax(8), boot_zaurus(8), rc.d(8), rc.shutdown(8),
     savecore(8), shutdown(8), sync(8)

HISTORY
     A reboot command appeared in Version 6 AT&T UNIX.

OpenBSD 5.4                      June 20, 2012                     OpenBSD 5.4
#

# man boot_amd64
man: no entry for boot_amd64 in the manual.
# man boot_i386
man: no entry for boot_i386 in the manual.
# man boot_sparc
man: no entry for boot_sparc in the manual.
#

dc

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Philip Guenther-2
On Sun, Feb 9, 2014 at 3:02 PM, [hidden email] <[hidden email]> wrote:
> Question .. where do I get all the man pages?  I have some of them
> but then others are absent :
>
>
> # man reboot
> REBOOT(8)               OpenBSD System Manager's Manual              REBOOT(8)
...
> SEE ALSO
>      reboot(2), utmp(5), boot_alpha(8), boot_amd64(8), boot_hp300(8),
>      boot_hppa(8), boot_hppa64(8), boot_i386(8), boot_luna88k(8),
>      boot_macppc(8), boot_mvme68k(8), boot_mvme88k(8), boot_sparc(8),
>      boot_sparc64(8), boot_vax(8), boot_zaurus(8), rc.d(8), rc.shutdown(8),
>      savecore(8), shutdown(8), sync(8)

Hmm, that may be incorrect notation for the pages which are
architecture specific: the boot_*(8) manpages are in the architecture
specific sections.  They can be seen on all platforms using the -S
option to man, ala:

    man -S i386 boot_i386
    man -S sparc boot_sparc
...etc

By default, man uses the architecture that you're running, so if
you're running on i386, you should be able to just say
    man boot_i386

I'm not 100% sure if the cross-references in the SEE ALSO section
should be indicating that; I could have sworn that I saw syntax like
"whatever(8/i386)" elsewhere.  Jason, Ingo, what the Right Thing here?


> # man boot_amd64
> man: no entry for boot_amd64 in the manual.
> # man boot_i386
> man: no entry for boot_i386 in the manual.
> # man boot_sparc
> man: no entry for boot_sparc in the manual.
> #

Hmm, you never actually came out and said it (no dmesg, ahem), but I'm
guessing that you're running on sparc64?


Philip Guenther

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Ted Unangst-6
In reply to this post by VaZub
On Sun, Feb 09, 2014 at 18:02, [hidden email] wrote:
> # man boot_amd64
> man: no entry for boot_amd64 in the manual.
> # man boot_i386
> man: no entry for boot_i386 in the manual.
> # man boot_sparc
> man: no entry for boot_sparc in the manual.

man -S sparc boot_sparc

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

dc@genunix.com
In reply to this post by Philip Guenther-2
> Hmm, you never actually came out and said it (no dmesg, ahem), but I'm
> guessing that you're running on sparc64?


Coming from the Solaris world I am clearly operating on a pile of
wrong assumptions. Imagine my surprise where I saw that things like
psrinfo and such are absent.  OKay, not really surprised. However
the MBR data has me perplexed and the data kicked out by "fdisk sd0"
is just insane.

This is the wrong thread for that topic however.

dc

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Nick Holland
In reply to this post by VaZub
On 02/09/14 14:31, VaZub wrote:
> Sorry, my bad - I assumed that it was only natural for newcomers to
> copy the file and edit it afterwards instead of creating it from
> scratch to override some values.

If you can figure out how to help me write documentation to override
people's assumptions, please let me know.  I feel a Get Rich Quick
coming on if you can...

> Obviously, this assumption was based
> on my ignorance and therefore wrong. You are also right to point out
> that to "copy the lines" is not the same as "copy the whole file" - I
> must have missed this particular distinction.
>
> The only thing I can put in my defense is that I might have been
> mislead to some extent by a particular piece of text -
> http://www.openbsd.org/faq/upgrade47.html#rc.conf. Of course, it is
> outdated and should not be taken for granted in regards to version
> 5.4, but it was one of few leads I've found when trying to fix my
> problem with rc.conf.local file.

And if you noticed the CONTEXT (you have in the past edited the wrong
file) and the warning part in italics (delete the line that re-invokes
this same file -- there twice, in slightly different wording!), it would
have been quite useful today, too.

> Nevertheless, please forgive me for my foolish assumptions and for
> taking your time. And thanks for clearing things up.

There's an art to getting people to read what is on the page and not
what is in their mind.  I may be better than some at this, but
obviously, I have a long way to go. :)

Nick.

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Jason McIntyre-2
In reply to this post by Philip Guenther-2
On Sun, Feb 09, 2014 at 03:19:36PM -0800, Philip Guenther wrote:

> On Sun, Feb 9, 2014 at 3:02 PM, [hidden email] <[hidden email]> wrote:
> > Question .. where do I get all the man pages?  I have some of them
> > but then others are absent :
> >
> >
> > # man reboot
> > REBOOT(8)               OpenBSD System Manager's Manual              REBOOT(8)
> ...
> > SEE ALSO
> >      reboot(2), utmp(5), boot_alpha(8), boot_amd64(8), boot_hp300(8),
> >      boot_hppa(8), boot_hppa64(8), boot_i386(8), boot_luna88k(8),
> >      boot_macppc(8), boot_mvme68k(8), boot_mvme88k(8), boot_sparc(8),
> >      boot_sparc64(8), boot_vax(8), boot_zaurus(8), rc.d(8), rc.shutdown(8),
> >      savecore(8), shutdown(8), sync(8)
>
> Hmm, that may be incorrect notation for the pages which are
> architecture specific: the boot_*(8) manpages are in the architecture
> specific sections.  They can be seen on all platforms using the -S
> option to man, ala:
>
>     man -S i386 boot_i386
>     man -S sparc boot_sparc
> ...etc
>
> By default, man uses the architecture that you're running, so if
> you're running on i386, you should be able to just say
>     man boot_i386
>
> I'm not 100% sure if the cross-references in the SEE ALSO section
> should be indicating that; I could have sworn that I saw syntax like
> "whatever(8/i386)" elsewhere.  Jason, Ingo, what the Right Thing here?
>

we use 8/i386 notation in man -k (apropos) output, not in man pages,
though you can use 8/i386 instead of just 8, and mandoc won;t complain.
i suspect ingo will tell us it'll break other tools.

in this case it seems clear the intent is to list all the boot_ pages and
assume the reader will understand. it's a fair assumption.

the alternative is to remove all the platform dependent cross
references.

i don;t really have a problem with its current format. we do have other
pages that reference (by neccesity) platform dependent pages, though
they themselves are usually platform dependent.

jmc

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Giancarlo Razzolini-3
In reply to this post by Nick Holland
Em 10-02-2014 00:53, Nick Holland escreveu:

> On 02/09/14 14:31, VaZub wrote:
>> Sorry, my bad - I assumed that it was only natural for newcomers to
>> copy the file and edit it afterwards instead of creating it from
>> scratch to override some values.
> If you can figure out how to help me write documentation to override
> people's assumptions, please let me know.  I feel a Get Rich Quick
> coming on if you can...
>
>> Obviously, this assumption was based
>> on my ignorance and therefore wrong. You are also right to point out
>> that to "copy the lines" is not the same as "copy the whole file" - I
>> must have missed this particular distinction.
>>
>> The only thing I can put in my defense is that I might have been
>> mislead to some extent by a particular piece of text -
>> http://www.openbsd.org/faq/upgrade47.html#rc.conf. Of course, it is
>> outdated and should not be taken for granted in regards to version
>> 5.4, but it was one of few leads I've found when trying to fix my
>> problem with rc.conf.local file.
> And if you noticed the CONTEXT (you have in the past edited the wrong
> file) and the warning part in italics (delete the line that re-invokes
> this same file -- there twice, in slightly different wording!), it would
> have been quite useful today, too.
>
>> Nevertheless, please forgive me for my foolish assumptions and for
>> taking your time. And thanks for clearing things up.
> There's an art to getting people to read what is on the page and not
> what is in their mind.  I may be better than some at this, but
> obviously, I have a long way to go. :)
>
> Nick.
>
The main issue here is, that, the human brain, although being this
wonderful machine, makes a lot of assumptions to fill in the gaps, even
when there are *no *gaps to be filled. I don't know if the documentation
needs to be clearer in this specific case. Perhaps we could use the same
text from the faq, since it is a little more explicit on what you need
to do. I'll write a patch and send it to tech@.

Cheers,

--
Giancarlo Razzolini
GPG: 4096R/77B981BC

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Ingo Schwarze
Hi,

Giancarlo Razzolini wrote on Mon, Feb 10, 2014 at 03:18:39PM -0200:

> The main issue here is, that, the human brain, although being this
> wonderful machine, makes a lot of assumptions to fill in the gaps, even
> when there are *no *gaps to be filled. I don't know if the documentation
> needs to be clearer in this specific case.

Even though the misunderstanding does not seem to occur often,
it does seem somewhat unsurprising because a lot of other software
encourages the (imho questionable) practice of copying example
configuration files.

So here is what i came up with to make this clearer without
making it longer or more redundant.

OK?
  Ingo


Index: rc.conf.8
===================================================================
RCS file: /cvs/src/share/man/man8/rc.conf.8,v
retrieving revision 1.20
diff -u -r1.20 rc.conf.8
--- rc.conf.8 17 Mar 2012 14:46:40 -0000 1.20
+++ rc.conf.8 12 Feb 2014 09:40:09 -0000
@@ -49,9 +49,9 @@
 .Nm rc.conf
 untouched, and instead create and edit a new
 .Nm rc.conf.local
-file.
-Variables set in this file will override variables previously set in
-.Nm rc.conf .
+file, setting just those variables whose
+.Nm rc.conf
+default values are intended to be overridden.
 .Pp
 Some variables are used to turn features on or off.
 For example, whether the system runs the

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Giancarlo Razzolini-3
Em 12-02-2014 07:48, Ingo Schwarze escreveu:

> Hi,
>
> Giancarlo Razzolini wrote on Mon, Feb 10, 2014 at 03:18:39PM -0200:
>
>> The main issue here is, that, the human brain, although being this
>> wonderful machine, makes a lot of assumptions to fill in the gaps, even
>> when there are *no *gaps to be filled. I don't know if the documentation
>> needs to be clearer in this specific case.
> Even though the misunderstanding does not seem to occur often,
> it does seem somewhat unsurprising because a lot of other software
> encourages the (imho questionable) practice of copying example
> configuration files.
>
> So here is what i came up with to make this clearer without
> making it longer or more redundant.
>
> OK?
>   Ingo
>
>
> Index: rc.conf.8
> ===================================================================
> RCS file: /cvs/src/share/man/man8/rc.conf.8,v
> retrieving revision 1.20
> diff -u -r1.20 rc.conf.8
> --- rc.conf.8 17 Mar 2012 14:46:40 -0000 1.20
> +++ rc.conf.8 12 Feb 2014 09:40:09 -0000
> @@ -49,9 +49,9 @@
>  .Nm rc.conf
>  untouched, and instead create and edit a new
>  .Nm rc.conf.local
> -file.
> -Variables set in this file will override variables previously set in
> -.Nm rc.conf .
> +file, setting just those variables whose
> +.Nm rc.conf
> +default values are intended to be overridden.
>  .Pp
>  Some variables are used to turn features on or off.
>  For example, whether the system runs the
HI Ingo,

    I've sent a patch on tech@, and there was a discussion about it, but
there wasn't a consensus. I encourage you to join tech and the
discussion. Send your proposal there too.

Cheers,

--
Giancarlo Razzolini
GPG: 4096R/77B981BC

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

Ingo Schwarze
In reply to this post by Jason McIntyre-2
Hi Jason,

Jason McIntyre wrote on Mon, Feb 10, 2014 at 08:29:24AM +0000:
> On Sun, Feb 09, 2014 at 03:19:36PM -0800, Philip Guenther wrote:
>> On Sun, Feb 9, 2014 at 3:02 PM, [hidden email] <[hidden email]> wrote:

>>> Question .. where do I get all the man pages?  I have some of them
>>> but then others are absent :
>>>
>>> # man reboot
>>> REBOOT(8)          OpenBSD System Manager's Manual         REBOOT(8)
>>> [...]
>>> SEE ALSO
>>>    reboot(2), utmp(5), boot_alpha(8), boot_amd64(8), boot_hp300(8),
>>>    boot_hppa(8), boot_hppa64(8), boot_i386(8), boot_luna88k(8),
>>>    boot_macppc(8), boot_mvme68k(8), boot_mvme88k(8), boot_sparc(8),
>>>    boot_sparc64(8), boot_vax(8), boot_zaurus(8), rc.d(8), rc.shutdown(8),
>>>    savecore(8), shutdown(8), sync(8)

>> Hmm, that may be incorrect notation for the pages which are
>> architecture specific: the boot_*(8) manpages are in the architecture
>> specific sections.  They can be seen on all platforms using the -S
>> option to man, ala:
>>
>>     man -S i386 boot_i386
>>     man -S sparc boot_sparc
>> ...etc
>>
>> By default, man uses the architecture that you're running, so if
>> you're running on i386, you should be able to just say
>>     man boot_i386
>>
>> I'm not 100% sure if the cross-references in the SEE ALSO section
>> should be indicating that; I could have sworn that I saw syntax like
>> "whatever(8/i386)" elsewhere.  Jason, Ingo, what the Right Thing here?

> we use 8/i386 notation in man -k (apropos) output, not in man pages,
> though you can use 8/i386 instead of just 8, and mandoc won;t complain.
> i suspect ingo will tell us it'll break other tools.

Actually, both mandoc and groff would be happy with stuff like

  .Xr boot_alpha 8/alpha

and off the top of my head, i don't see which tools might break.
Certainly not our Perl makewhatis(8), it doesn't parse that deeply.
And mandocdb(8) does the right thing out of the box, using it,
you can even search for pages containing arch-specific .Xrs:

   $ ./obj/apropos Xr=/alpha
  halt(8), reboot(8) - stopping and restarting the system
   $ ./obj/apropos -O Xr Xr=/alpha
  halt(8), reboot(8) - [...] # rc.conf(8) # boot_alpha(8/alpha) # [...]

Given that neither groff_mdoc(7) nor mdoc(7) mention this possibility,
i'm not 100% sure all exotic tools will cope, but i don't consider
problems very likely.  Most tools are quite lenient when parsing
macro arguments, roff and groff traditionally do almost no validation,
and most other tools refrain from parsing random content macros,
anyway.

So if you see value in making this explicit, i'd suggest asking on
the groff list whether anybody else expects problems, and if not,
documenting and using it.

> in this case it seems clear the intent is to list all the boot_ pages and
> assume the reader will understand. it's a fair assumption.

For boot_alpha(8), it's nearly obvious; but stuff like inb(2) may
confuse readers quite a bit unless the arch is made explicit.

> the alternative is to remove all the platform dependent cross
> references.

That seems like a bad idea.

> i don;t really have a problem with its current format. we do have other
> pages that reference (by neccesity) platform dependent pages, though
> they themselves are usually platform dependent.

Sure, that mitigates the issue.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: Documentation on rc.conf.local lacks important warning

patrick keshishian
In reply to this post by Giancarlo Razzolini-3
On 2/12/14, Giancarlo Razzolini <[hidden email]> wrote:

> Em 12-02-2014 07:48, Ingo Schwarze escreveu:
>> Hi,
>>
>> Giancarlo Razzolini wrote on Mon, Feb 10, 2014 at 03:18:39PM -0200:
>>
>>> The main issue here is, that, the human brain, although being this
>>> wonderful machine, makes a lot of assumptions to fill in the gaps, even
>>> when there are *no *gaps to be filled. I don't know if the documentation
>>> needs to be clearer in this specific case.
>> Even though the misunderstanding does not seem to occur often,
>> it does seem somewhat unsurprising because a lot of other software
>> encourages the (imho questionable) practice of copying example
>> configuration files.
>>
>> So here is what i came up with to make this clearer without
>> making it longer or more redundant.
>>
>> OK?
>>   Ingo
>>
>>
>> Index: rc.conf.8
>> ===================================================================
>> RCS file: /cvs/src/share/man/man8/rc.conf.8,v
>> retrieving revision 1.20
>> diff -u -r1.20 rc.conf.8
>> --- rc.conf.8 17 Mar 2012 14:46:40 -0000 1.20
>> +++ rc.conf.8 12 Feb 2014 09:40:09 -0000
>> @@ -49,9 +49,9 @@
>>  .Nm rc.conf
>>  untouched, and instead create and edit a new
>>  .Nm rc.conf.local
>> -file.
>> -Variables set in this file will override variables previously set in
>> -.Nm rc.conf .
>> +file, setting just those variables whose
>> +.Nm rc.conf
>> +default values are intended to be overridden.
>>  .Pp
>>  Some variables are used to turn features on or off.
>>  For example, whether the system runs the
> HI Ingo,
>
>     I've sent a patch on tech@, and there was a discussion about it, but
> there wasn't a consensus. I encourage you to join tech and the
> discussion. Send your proposal there too.

maybe some people should lurk more.

--patrick

12