From gshapiro@gshapiro.net  Thu Apr  4 19:44:58 2002
Return-Path: <gshapiro@gshapiro.net>
Received: from horsey.gshapiro.net (horsey.gshapiro.net [209.220.147.178])
	by hub.freebsd.org (Postfix) with ESMTP id 00ADD37B416
	for <FreeBSD-gnats-submit@freebsd.org>; Thu,  4 Apr 2002 19:44:58 -0800 (PST)
Received: from horsey.gshapiro.net (gshapiro@localhost [127.0.0.1])
	by horsey.gshapiro.net (8.12.3/8.12.3) with ESMTP id g353ivCD038206
	(version=TLSv1/SSLv3 cipher=EDH-RSA-DES-CBC3-SHA bits=168 verify=NO)
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 4 Apr 2002 19:44:57 -0800 (PST)
Received: (from gshapiro@localhost)
	by horsey.gshapiro.net (8.12.3/8.12.3/Submit) id g353ivXL038205;
	Thu, 4 Apr 2002 19:44:57 -0800 (PST)
Message-Id: <200204050344.g353ivXL038205@horsey.gshapiro.net>
Date: Thu, 4 Apr 2002 19:44:57 -0800 (PST)
From: Gregory Neil Shapiro <gshapiro@freebsd.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Unclear/inconsistent instructions in Handbook section 19.4.3
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         36773
>Category:       docs
>Synopsis:       Unclear/inconsistent instructions in Handbook section 19.4.3
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    keramida
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Apr 04 19:50:01 PST 2002
>Closed-Date:    Sat May 11 17:52:46 PDT 2002
>Last-Modified:  Sat May 11 17:52:46 PDT 2002
>Originator:     Gregory Neil Shapiro
>Release:        FreeBSD 4.5-STABLE i386
>Organization:
>Environment:
System: FreeBSD horsey.gshapiro.net 4.5-STABLE FreeBSD 4.5-STABLE #6: Fri Mar 1 21:45:03 PST 2002 gshapiro@horsey.gshapiro.net:/src/FreeBSD/RELENG_4/obj/src/sys/HORSEY i386

>Description:

Here are excerpts and my commentary (indented) on section 19.4.3 of the
handbook:

19.4.3 Update /etc/group

   : The title of the section is "Update /etc/group".  However, the
   : section describes the need for certain usernames and groups to
   : exist for a make world to succeed.  The title of the section is
   : misleading as it only mentions the group file.

There have been occasions when the installation part of ``make world''
has expected certain usernames or groups to exist. When performing
an upgrade it is likely that these groups did not exist. This caused
problems when upgrading.
   
   : Not only ``make world'', but also ``make installworld''

   : The first sentence says "usernames or groups".  The second sentence
   : only mentions "groups".  Missing usernames cause just as many
   : problems as missing groups.

The most recent example of this is when the ``ppp'' group (later renamed
``network'') was added. Users had the installation process fail for them
when parts of the ppp subsystem were installed using a non-existent (for
them) group name.

   : The new most recent example is the ``smmsp'' username
   : and group, both of which are needed for mtree to create
   : /var/spool/clientmqueue/.

The solution is to examine /usr/src/etc/group and compare its list of
groups with your own. If there are any groups in the new file that are
not in your file then copy them over. Similarly, you should rename any
groups in /etc/group which have the same GID but a different name to
those in /usr/src/etc/group.

   : You should also document merging /usr/src/etc/master.passwd using
   : vipw (so the database files are regenerated properly after the
   : users manually merge the new accounts).

>How-To-Repeat:
>Fix:
   
See commentary above.
>Release-Note:
>Audit-Trail:

From: Giorgos Keramidas <keramida@freebsd.org>
To: Gregory Neil Shapiro <gshapiro@freebsd.org>
Cc: bug-followup@freebsd.org
Subject: Re: docs/36773: Unclear/inconsistent instructions in Handbook section 19.4.3
Date: Sat, 11 May 2002 12:17:47 +0300

 On 2002-04-04 19:44, Gregory Neil Shapiro wrote:
 >
 > >Description:
 >
 > Here are excerpts and my commentary (indented) on section 19.4.3 of the
 > handbook:
 
 > 19.4.3 Update /etc/group
 >
 >    : The title of the section is "Update /etc/group".  However, the
 >    : section describes the need for certain usernames and groups to
 >    : exist for a make world to succeed.  The title of the section is
 >    : misleading as it only mentions the group file.
 
 How about?
 
 	<title>Update the files of <filename>/etc</filename></title>
 
 > There have been occasions when the installation part of ``make world''
 > has expected certain usernames or groups to exist. When performing
 > an upgrade it is likely that these groups did not exist. This caused
 > problems when upgrading.
 >    
 >    : Not only ``make world'', but also ``make installworld''
 
 That's what it says.  The ``installation part of "make world"'' is the
 same as ``installworld''.  I have left this unchanged but if there is
 someone that has an idea of a better wording I won't object to
 changing it.
 
 >    : The first sentence says "usernames or groups".  The second sentence
 >    : only mentions "groups".  Missing usernames cause just as many
 >    : problems as missing groups.
 
 See below.
 
 > The most recent example of this is when the ``ppp'' group (later renamed
 > ``network'') was added. Users had the installation process fail for them
 > when parts of the ppp subsystem were installed using a non-existent (for
 > them) group name.
 > 
 >    : The new most recent example is the ``smmsp'' username
 >    : and group, both of which are needed for mtree to create
 >    : /var/spool/clientmqueue/.
 > 
 > The solution is to examine /usr/src/etc/group and compare its list of
 > groups with your own. If there are any groups in the new file that are
 > not in your file then copy them over. Similarly, you should rename any
 > groups in /etc/group which have the same GID but a different name to
 > those in /usr/src/etc/group.
 > 
 >    : You should also document merging /usr/src/etc/master.passwd using
 >    : vipw (so the database files are regenerated properly after the
 >    : users manually merge the new accounts).
 
 How does this look?
 
 %%%
 Index: chapter.sgml
 ===================================================================
 RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v
 retrieving revision 1.120
 diff -u -r1.120 chapter.sgml
 --- chapter.sgml	4 May 2002 14:22:34 -0000	1.120
 +++ chapter.sgml	11 May 2002 09:16:22 -0000
 @@ -683,7 +683,7 @@
      </sect2>
  
      <sect2>
 -      <title>Update <filename>/etc/group</filename></title>
 +      <title>Update the files of <filename>/etc</filename></title>
  
        <para>The <filename>/etc</filename> directory contains a large part
  	of your system's configuration information, as well as scripts
 @@ -697,13 +697,13 @@
        <para>There have been occasions when the installation part of
          <quote>make world</quote> has expected certain usernames or groups
  	to exist.  When performing an upgrade it is likely that these
 -	groups did not exist. This caused problems when upgrading.</para>
 +	users or groups did not exist. This caused problems when upgrading.</para>
  
 -      <para>The most recent example of this is when the <quote/ppp/ group
 -	(later renamed <quote/network/) was added.  Users had the
 -	installation process fail for them when parts of the
 -	<filename>ppp</filename> subsystem were installed using a
 -	non-existent (for them) group name.</para>
 +      <para>The most recent example of this is when the
 +	<username>smmsp</username> user was added.  Users had the
 +	installation process fail for them when
 +	<command>mtree</command> was trying to create
 +	<filename>/var/spool/clientmqueue</filename>.</para>
  
        <para>The solution is to examine
  	<filename>/usr/src/etc/group</filename> and compare its list of
 @@ -711,7 +711,14 @@
  	are not in your file then copy them over.  Similarly, you should
  	rename any groups in <filename>/etc/group</filename> which have
  	the same GID but a different name to those in
 -	<filename>/usr/src/etc/group</filename>.</para>
 +	<filename>/usr/src/etc/group</filename>.  You should also
 +	merge any changes from
 +	<filename>/usr/src/etc/master.passwd</filename> into your
 +	existing <filename>/etc/master.passwd</filename> with
 +	&man.vipw.8;.  Always use &man.vipw.8; to make the merge to
 +	<filename>/etc/master.passwd</filename>, since &man.vipw.8;
 +	makes sure that the proper database files are rebuilt after
 +	the merge.</para>
  
        <tip>
  	<para>If you are feeling particularly paranoid, you can check your
 %%%
 
 Giorgos Keramidas                       FreeBSD Documentation Project
 keramida@{freebsd.org,ceid.upatras.gr}  http://www.FreeBSD.org/docproj/
State-Changed-From-To: open->closed 
State-Changed-By: keramida 
State-Changed-When: Sat May 11 17:51:38 PDT 2002 
State-Changed-Why:  
Changes from Martin's suggestions merged, and the rest committed as it 
appears in the audit trail.  Greg, thank you for spotting this :) 


Responsible-Changed-From-To: freebsd-doc->keramida 
Responsible-Changed-By: keramida 
Responsible-Changed-When: Sat May 11 17:51:38 PDT 2002 
Responsible-Changed-Why:  

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