From nobody@FreeBSD.org  Thu Feb 12 23:10:36 2004
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 3FB4716A4CE
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 12 Feb 2004 23:10:36 -0800 (PST)
Received: from www.freebsd.org (www.freebsd.org [216.136.204.117])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 3965643D1D
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 12 Feb 2004 23:10:36 -0800 (PST)
	(envelope-from nobody@FreeBSD.org)
Received: from www.freebsd.org (localhost [127.0.0.1])
	by www.freebsd.org (8.12.10/8.12.10) with ESMTP id i1D7AZ72035781
	for <freebsd-gnats-submit@FreeBSD.org>; Thu, 12 Feb 2004 23:10:35 -0800 (PST)
	(envelope-from nobody@www.freebsd.org)
Received: (from nobody@localhost)
	by www.freebsd.org (8.12.10/8.12.10/Submit) id i1D7AZ5d035780;
	Thu, 12 Feb 2004 23:10:35 -0800 (PST)
	(envelope-from nobody)
Message-Id: <200402130710.i1D7AZ5d035780@www.freebsd.org>
Date: Thu, 12 Feb 2004 23:10:35 -0800 (PST)
From: Alain Hoang <hoanga@alum.rpi.edu>
To: freebsd-gnats-submit@FreeBSD.org
Subject: static_routes needs an example in /etc/defaults/rc.conf
X-Send-Pr-Version: www-2.0

>Number:         62772
>Category:       conf
>Synopsis:       static_routes needs an example in /etc/defaults/rc.conf
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bms
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Feb 12 23:20:16 PST 2004
>Closed-Date:    Tue Nov 02 07:03:56 GMT 2004
>Last-Modified:  Tue Nov 02 07:03:56 GMT 2004
>Originator:     Alain Hoang
>Release:        FreeBSD 5.2.1-RC i386
>Organization:
Doctor M
>Environment:
FreeBSD worcester.kannai.doctorm.jp 5.2.1-RC FreeBSD 5.2.1-RC #0: Sat Jan 31 05:36:22 GMT 2004 root@cypress.btc.adpatec.com:/usr/obj/usr/src/sys/GENERIC i386
>Description:
The documentation for static_routes in /etc/rc.conf is extremely unfriendly to someone
without a background in how the system is supposed to work.   There is no examples
in /etc/defaults/rc.conf that can be used by a newbie to figure out this works
without actually looking at /etc/rc.d/networking and noticing how static_routes
actually works.
>How-To-Repeat:
Find someone who has never configured a static route under FreeBSD and ask them
to figure out how to configure a static route using the /etc/rc.conf manpage and
/etc/defaults/rc.conf file and the Handbook only.
>Fix:
An example in /etc/defaults/rc.conf showing the usage would greatly benefit clarifying
how to setup a static route.

Example snippet:
# Static routes is a list of strings seperated by a space
# Each of these strings will point to a another
# configuration directive labeled route_...
# The following example shows an example of two
# static routes being configured.  They are labeled
# net1 and net2 and point to configuration directives
# route_net1 and route_net2 respectively.
static_routes="net1 net2"
route_net1="-net 192.168.0.0 192.168.0.1"
route_net2="-net 192.168.1.0 192.168.1.1"
>Release-Note:
>Audit-Trail:

From: Kris Kennaway <kris@obsecurity.org>
To: Alain Hoang <hoanga@alum.rpi.edu>
Cc: freebsd-gnats-submit@FreeBSD.org
Subject: Re: conf/62772: static_routes needs an example in /etc/defaults/rc.conf
Date: Thu, 12 Feb 2004 23:28:59 -0800

 On Thu, Feb 12, 2004 at 11:10:35PM -0800, Alain Hoang wrote:
 
 > The documentation for static_routes in /etc/rc.conf is extremely unfriendly to someone
 > without a background in how the system is supposed to work.   There is no examples
 > in /etc/defaults/rc.conf that can be used by a newbie to figure out this works
 > without actually looking at /etc/rc.d/networking and noticing how static_routes
 > actually works.
 
 The documentation is (surprise!) in the manpage.
 
      static_routes
                  (str) Set to the list of static routes that are to be added
                  at system boot time.  If not set to ``NO'' then for each
                  whitespace separated element in the value, a route_<element>
                  variable is assumed to exist whose contents will later be
                  passed to a ``route add'' operation.
 
 Is that really unclear enough to require an example?
 
 Kris

From: <hoanga@alum.rpi.edu>
To: <kris@obsecurity.org>
Cc: <freebsd-gnats-submit@FreeBSD.org>
Subject: Re: conf/62772: static_routes needs an example in /etc/defaults/rc.conf
Date: Fri, 13 Feb 2004 01:06:20 -0800

 This is a multi-part message in MIME format.
 
 ------=_NextPart_000_15C4D_01C3F1CD.973860F0
 Content-Type: text/plain;
 	charset="iso-8859-1"
 Content-Transfer-Encoding: 7bit
 
 Hi there,
 
 > The documentation is (surprise!) in the manpage.
 
 > static_routes
 > (str) Set to the list of static routes that are to be added
 > at system boot time. If not set to ``NO'' then for each
 > whitespace separated element in the value, a route_
 > variable is assumed to exist whose contents will later be
 > passed to a ``route add'' operation.
 
 >Is that really unclear enough to require an example?
 
 Thanks for the quick response. I had read the documentation
 in the manpage as well and misinterpreted 'Set to the list of static
 routes'
 as 'please insert your static route here' rather than 'please
 put a list of identifiers that are space seperated that will be used as
 a 
 reference to route_ that containts all the options 
 you need to feed to the route command to add the route'.
 I understand that this is documented if you read this very carefully
 however I don't feel it's crystal clear to people who are slow to
 read these manpages (like me).
 After a reboot and realizing I was making a mistake I started
 looking for an example to clarify exactly what the manpage meant.
 (I personally like looking at examples to clarify manpage explanations).
 In the end I just looked at /etc/rc.d/routing (after tracing the system
 startup scripts) and and figured out how static_routes was parsed
 and its relation to route_. This process took me about
 a few hours of looking at the documentation, trying my own examples and
 finally looking at the shell scripts for what I assumed was a 15 minute 
 change and check. So yes, I feel this is unclear. Considering the
 large amount of examples and documentation that went into making 
 an IPv6 static route, a few lines for creating a static IPv4 route
 wouldn't 
 hurt for someone else in the future.
 
 Best regards,
 Alain 
 
 ------=_NextPart_000_15C4D_01C3F1CD.973860F0
 Content-Type: text/html
 Content-Transfer-Encoding: 7bit
 
 <HTML>
 <BODY>
 Hi there,<br>
 <br>
 > The documentation is (surprise!) in the manpage.<br>
 <br>
 >     static_routes<br>
 >                 (str) Set to the list of static routes that are to be added<br>
 >                 at system boot time.  If not set to ``NO'' then for each<br>
 >                 whitespace separated element in the value, a route_<element><br>
 >                 variable is assumed to exist whose contents will later be<br>
 >                 passed to a ``route add'' operation.<br>
 <br>
 >Is that really unclear enough to require an example?<br>
 <br>
 Thanks for the quick response.   I had read the documentation<br>
 in the manpage as well and misinterpreted 'Set to the list of static routes'<br>
 as 'please insert your static route here' rather than 'please<br>
 put a list of identifiers that are space seperated that will be used as a <br>
 reference to route_<identifier> that containts all the options <br>
 you need to feed to the route command to add the route'.<br>
 I understand that this is documented if you read this very carefully<br>
 however I don't feel it's crystal clear to people who are slow to<br>
 read these manpages (like me).<br>
    After a reboot and realizing I was making a mistake I started<br>
 looking for an example to clarify exactly what the manpage meant.<br>
 (I personally like looking at examples to clarify manpage explanations).<br>
 In the end I just looked at /etc/rc.d/routing (after tracing the system<br>
 startup scripts) and and figured out how static_routes was parsed<br>
 and its relation to route_<netid>.  This process took me about<br>
 a few hours of looking at the documentation, trying my own examples and<br>
 finally looking at the shell scripts for what I assumed was a 15 minute <br>
 change and check.  So yes, I feel this is unclear.   Considering the<br>
 large amount of examples and documentation that went into making <br>
 an IPv6 static route, a few lines for creating a static IPv4 route wouldn't <br>
 hurt for someone else in the future.<br>
 <br>
 Best regards,<br>
 Alain
 </BODY></HTML>
 
 ------=_NextPart_000_15C4D_01C3F1CD.973860F0--
 

From: Kris Kennaway <kris@obsecurity.org>
To: hoanga@alum.rpi.edu
Cc: kris@obsecurity.org, freebsd-gnats-submit@FreeBSD.org
Subject: Re: conf/62772: static_routes needs an example in /etc/defaults/rc.conf
Date: Fri, 13 Feb 2004 01:22:28 -0800

 On Fri, Feb 13, 2004 at 01:06:20AM -0800, hoanga@alum.rpi.edu wrote:
 > Hi there,
 > 
 > > The documentation is (surprise!) in the manpage.
 > 
 > > static_routes
 > > (str) Set to the list of static routes that are to be added
 > > at system boot time. If not set to ``NO'' then for each
 > > whitespace separated element in the value, a route_
 > > variable is assumed to exist whose contents will later be
 > > passed to a ``route add'' operation.
 > 
 > >Is that really unclear enough to require an example?
 > 
 > Thanks for the quick response. I had read the documentation
 > in the manpage as well and misinterpreted 'Set to the list of static
 > routes'
 > as 'please insert your static route here' rather than 'please
 > put a list of identifiers that are space seperated that will be used as
 > a 
 > reference to route_ that containts all the options 
 > you need to feed to the route command to add the route'.
 
 The second sentence says precisely that, although perhaps it can be
 clarified..I don't think an example is needed here, but I'll leave it
 up to the manpage people to decide.
 
 Kris

From: "Simon L. Nielsen" <simon@FreeBSD.org>
To: Jerry McAllister <jerrymc@clunix.cl.msu.edu>
Cc: kris@obsecurity.org, Alain Hoang <hoanga@alum.rpi.edu>,
	freebsd-gnats-submit@FreeBSD.org
Subject: Re: conf/62772: static_routes needs an example in
Date: Sat, 14 Feb 2004 14:36:45 +0100

 --y0ulUmNC+osPPQO6
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
 Content-Transfer-Encoding: quoted-printable
 
 On 2004.02.13 10:45:31 -0500, Jerry McAllister wrote:
 > >=20
 > > The following reply was made to PR conf/62772; it has been noted by GNA=
 TS.
 > >=20
 > > From: Kris Kennaway <kris@obsecurity.org>
 > > To: hoanga@alum.rpi.edu
 > > Cc: kris@obsecurity.org, freebsd-gnats-submit@FreeBSD.org
 > > Subject: Re: conf/62772: static_routes needs an example in /etc/default=
 s/rc.conf
 > > Date: Fri, 13 Feb 2004 01:22:28 -0800
 > >=20
 > >  > Thanks for the quick response. I had read the documentation
 > >  > in the manpage as well and misinterpreted 'Set to the list of static
 > >  > routes'
 > >  > as 'please insert your static route here' rather than 'please
 > >  > put a list of identifiers that are space seperated that will be used=
  as
 > >  > a reference to route_ that containts all the options=20
 > >  > you need to feed to the route command to add the route'.
 > > =20
 > >  The second sentence says precisely that, although perhaps it can be
 > >  clarified..I don't think an example is needed here, but I'll leave it
 > >  up to the manpage people to decide.
 >=20
 > I have always been of the opinion that examples are always in order.
 > Language is a funny thing - especially English and can be misunderstood
 > regardless of how clear the writer thinks the text is.   An example
 > or two tends to clear away a lot of potential fog (for both the writer=20
 > and the reader) even in the simplest situation.   At least it can give=20
 > the reader - who is reading it because [s]he doesn't already know
 > the information - some comfort and that has value too.
 
 While I generally agree that examples are a very good thing, I don't
 think it's a good idea to put on in either defaults/rc.conf or the
 rc.conf(5) manual page, since both are already very big files.
 
 I think the best solution would be for someone to write a section about
 this for the Handbook (section '19.2 Gateways and Routes' seems the
 right place).  Any takes ? :-)
 
 --=20
 Simon L. Nielsen
 FreeBSD Documentation Team
 
 --y0ulUmNC+osPPQO6
 Content-Type: application/pgp-signature
 Content-Disposition: inline
 
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.2.3 (FreeBSD)
 
 iD8DBQFALiRmh9pcDSc1mlERAv6IAKCgZoizqdLRdgmMh4tUq6B1Khd/4wCeNeaA
 cb4PbYkBpvhUf277nyoDqL4=
 =pIQr
 -----END PGP SIGNATURE-----
 
 --y0ulUmNC+osPPQO6--
State-Changed-From-To: open->patched 
State-Changed-By: bms 
State-Changed-When: Fri Jun 18 01:27:04 GMT 2004 
State-Changed-Why:  
An example has been committed to rc.conf(5) in -CURRENT. As this 
manual page has already had considerable additions because of the 
introduction of jails and suchlike, my personal feeling is that 
this doesn't cause much bloat. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=62772 
Responsible-Changed-From-To: freebsd-bugs->bms 
Responsible-Changed-By: bms 
Responsible-Changed-When: Fri Jun 18 01:29:36 GMT 2004 
Responsible-Changed-Why:  
I'll hoover this up 

http://www.freebsd.org/cgi/query-pr.cgi?pr=62772 
State-Changed-From-To: patched->closed 
State-Changed-By: bms 
State-Changed-When: Tue Nov 2 07:03:31 GMT 2004 
State-Changed-Why:  
RELENG_5 has now been branched as -STABLE 


http://www.freebsd.org/cgi/query-pr.cgi?pr=62772 
>Unformatted:
