From kensmith@cse.Buffalo.EDU  Sun Jul 13 20:58:55 2003
Return-Path: <kensmith@cse.Buffalo.EDU>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id 356F737B401
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 13 Jul 2003 20:58:55 -0700 (PDT)
Received: from zeus.cse.buffalo.edu (zeus.cse.Buffalo.EDU [128.205.32.30])
	by mx1.FreeBSD.org (Postfix) with ESMTP id 7DB0143F85
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 13 Jul 2003 20:58:54 -0700 (PDT)
	(envelope-from kensmith@cse.Buffalo.EDU)
Received: from zeus.cse.buffalo.edu (localhost.cse.buffalo.edu [127.0.0.1])
	by zeus.cse.buffalo.edu (8.12.8p1/8.12.4) with ESMTP id h6E3vUew046181;
	Sun, 13 Jul 2003 23:57:30 -0400 (EDT)
Received: (from kensmith@localhost)
	by zeus.cse.buffalo.edu (8.12.8p1/8.12.8/Submit) id h6E3vTWR046180;
	Sun, 13 Jul 2003 23:57:29 -0400 (EDT)
Message-Id: <200307140357.h6E3vTWR046180@zeus.cse.buffalo.edu>
Date: Sun, 13 Jul 2003 23:57:29 -0400 (EDT)
From: Ken Smith <kensmith@cse.Buffalo.EDU>
Reply-To: Ken Smith <kensmith@cse.Buffalo.EDU>
To: FreeBSD-gnats-submit@freebsd.org
Cc: kensmith@cse.Buffalo.EDU
Subject: Possible addition to Handbook
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         54461
>Category:       docs
>Synopsis:       [patch] Possible additions to Handbook (Basics and Users)
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       handbook
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jul 13 21:00:27 PDT 2003
>Closed-Date:    Sun May 19 00:03:19 UTC 2013
>Last-Modified:  Sun May 19 00:03:19 UTC 2013
>Originator:     Ken Smith
>Release:        FreeBSD 4.8-RELEASE i386
>Organization:
U. Buffalo CSE Department/FreeBSD
>Environment:
System: FreeBSD zeus.cse.buffalo.edu 4.8-RELEASE FreeBSD 4.8-RELEASE #0: Thu Apr 3 10:53:38 GMT 2003 root@freebsd-stable.sentex.ca:/usr/obj/usr/src/sys/GENERIC i386
>Description:
	Just some suggested additions to the Handbook, "Basics" and "Users"
	chapters.
>How-To-Repeat:
	N/A
>Fix:

	Apply following diff, relative to handbook directory.

--- basics/chapter.sgml.orig	Fri Jul 11 09:24:44 2003
+++ basics/chapter.sgml	Sun Jul 13 23:54:45 2003
@@ -69,6 +69,15 @@
       sharing and managing requests for hardware devices, peripherals,
       memory, and CPU time evenly to each user.</para>
 
+    <para>Much more information about User Accounts is in the chapter
+      about <link linkend="users">accounts</link>.  For now you just
+      need to know that each person (user) who uses the computer should be
+      given their own username and password.  The system keeps track
+      of the people using the computer based on this username.  Since
+      it is often the case that several people are working on the same
+      project Unix also provides groups.  Several users can be placed
+      in the same group.</para>
+
     <para>Because the system is capable of supporting multiple users,
       everything the system manages has a set of permissions governing who
       can read, write, and execute the resource.  These permissions are
@@ -1687,6 +1696,20 @@
 
   <sect1 id="binary-formats">
     <title>Binary Formats</title>
+    <para>Typically when you type in a command to a shell the shell
+      will arrange for an executable file to be loaded into memory and
+      a new process results.  Executable files can either be a binary
+      file (usually created by the linker as part of compiling a program)
+      or a shell script (text file to be interpreted by a binary file,
+      like &man.sh.1; or &man.perl.1;).  The &man.file.1; command can
+      usually tell you what is inside of a file.</para>
+
+    <para>Binary files need to have a well defined format for the system
+      to be able to use them properly.  Part of the file will be the
+      executable machine code (the instructions that tell the CPU what
+      to do), part of it will be data space with pre-defined values,
+      part will be data space with no pre-defined values, etc.  Through
+      time different binary file formats have evolved.</para>
 
     <para>To understand why FreeBSD uses the <filename>ELF</filename>
       format, you must first know a little about the 3 currently
@@ -1824,6 +1847,14 @@
       <filename>a.out</filename> will be moved out of the GENERIC
       kernel, and eventually removed from the kernel once the need to
       run legacy <filename>a.out</filename> programs is past.</para>
+
+    <para>In addition to &man.file.1; another command that can prove
+      useful when working with executables is &man.ldd.1;.  If
+      &man.file.1; says that a file is a dynamically linked executable
+      &man.ldd.1; can tell you what dynamically linked libraries that
+      executable file requires.  Sometimes programs can be linked against
+      compatibility libraries instead of the main system libraries, or
+      otherwise rely on dynamic libraries you were not aware of.</para>
   </sect1>
 
   <sect1 id="basics-more-information">
--- users/chapter.sgml.orig	Thu Oct 10 17:14:28 2002
+++ users/chapter.sgml	Sun Jul 13 23:45:12 2003
@@ -248,8 +248,8 @@
       for general usage if you have not already.  This applies equally
       whether you are running a multi-user or single-user machine.
       Later in this chapter, we discuss how to create additional
-      accounts, and how to change between the normal user and
-      superuser.</para>
+      accounts, and how to <link linkend="users-becomesuper">
+        change between the normal user and superuser</link>.</para>
   </sect1>
     
   <sect1 id="users-system">
@@ -1053,6 +1053,50 @@
       <filename>/etc/group</filename>, consult the &man.group.5; manual
       page.</para>
   </sect1>
+
+  <sect1 id="users-becomesuper">
+    <title>Becoming Superuser</title>
+
+    <para>There are several ways to do things as the superuser.  The worst
+      way is to log in as <username>root</username>.  Usually very little
+      needs to be done as <username>root</username> so logging off as your
+      normal username, logging in as <username>root</username>, doing what
+      you needed to do, then logging off and back on as your normal username
+      is quite a waste of time.</para>
+
+    <para>A better way is to use &man.su.1; without providing a username,
+      which implies the <username>root</username> user.  For this to work
+      the username that you normally log in as must be in the <groupname>
+      wheel</groupname> group.  An example of a fairly typical software
+      installation would involve the sys-admin unpacking the software as
+      their normal user account.  Then in the unpacked directory, starting
+      as their normal user account, doing something like.</para>
+
+    <example>
+      <title>Compile and Install a Program</title>
+
+      <screen>&prompt.user; <userinput>configure</userinput>
+&prompt.user; <userinput>make</userinput>
+&prompt.user; <userinput>su</userinput>
+Password:
+&prompt.root; <userinput>make install</userinput>
+&prompt.root; <userinput>exit</userinput>
+&prompt.user;</screen>
+    </example>
+
+    <para>Note in this example the transition to <username>root</username>
+      was much less painful than logging off and back on twice, and only
+      what was absolutely necessary got run as <username>root</username>.</para>
+
+    <para>Using &man.su.1; works well for single systems or small networks
+      with just one systems administrator.  For more complex environments
+      (or even for these simple environments) you should take a look at
+      &man.sudo.8;.  It is provided as the port <filename role="package">
+      security/sudo</filename>.  It allows for things like logging what
+      gets done, granting users the ability to only run certain things
+      as the superuser, etc.</para>
+  </sect1>
+
 </chapter>
 
 <!-- 
>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->ceri 
Responsible-Changed-By: ceri 
Responsible-Changed-When: Mon Jul 14 02:34:07 PDT 2003 
Responsible-Changed-Why:  
I like the look of this patch. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=54461 

From: underway@comcast.net (Gary W. Swearingen)
To: Ken Smith <kensmith@cse.Buffalo.EDU>
Cc: FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/54461: Possible addition to Handbook
Date: Mon, 14 Jul 2003 07:27:12 -0700

 Ken Smith <kensmith@cse.Buffalo.EDU> writes:
 
 > +    <para>Much more information about User Accounts is in the chapter
 
 "User Accounts" shouldn't be capitalized.
 
 > +      about <link linkend="users">accounts</link>.  For now you just
 > +      need to know that each person (user) who uses the computer should be
 
 "For now, it's enough to know...".  "You need to..." irks some folks.
 
 > +      it is often the case that several people are working on the same
 > +      project Unix also provides groups.  Several users can be placed
 
 Comma after "project".  Some kind of emphasis on "groups", as readers
 don't yet know that you mean something special by that word.
 
 > +      will arrange for an executable file to be loaded into memory and
 > +      a new process results.  Executable files can either be a binary
 
 "Results" is a poor verb.  Easily fix with "a new process is the
 result", but "into memory as part of a new process" reads better.
 But do they know that "process" has special meaning yet?
 
 > +      like &man.sh.1; or &man.perl.1;).  The &man.file.1; command can
 > +      usually tell you what is inside of a file.</para>
 
 Lose the "of"?
 
 > +      part will be data space with no pre-defined values, etc.  Through
 > +      time different binary file formats have evolved.</para>
 
 I'd put a comma after time, but maybe that's just me.
 
 > +      useful when working with executables is &man.ldd.1;.  If
 > +      &man.file.1; says that a file is a dynamically linked executable
 > +      &man.ldd.1; can tell you what dynamically linked libraries that
 
 Comma after "executable" (or ", then").
 
 > +      executable file requires.  Sometimes programs can be linked against
 > +      compatibility libraries instead of the main system libraries, or
 > +      otherwise rely on dynamic libraries you were not aware of.</para>
 
 otherwise rely on dynamic libraries that you were not aware of.</para>
 otherwise rely on dynamic libraries of which you were not aware.</para>
 otherwise rely on unexpected dynamic libraries.</para>
 
 > +      the username that you normally log in as must be in the <groupname>
 
 Is "username" the proper form?  A few months ago someone made a sweep
 of docs (and maybe some code?) changing good old "filesystem" to "file
 system" and "manpage" has been complained about.  (I guess it's too late
 for "soft ware". :)
 
 > +      wheel</groupname> group.  An example of a fairly typical software
 > +      installation would involve the sys-admin unpacking the software as
 > +      their normal user account.  Then in the unpacked directory, starting
 > +      as their normal user account, doing something like.</para>
 
 Change "their normal user account" to "a non-root user".  Change
 "like" to "like the following", or change "." to ":".
 
 I suppose the de-facto standard is "system administrator", not "sys-amdin".
 
 > +    <para>Note in this example the transition to <username>root</username>
 > +      was much less painful than logging off and back on twice, and only
 > +      what was absolutely necessary got run as <username>root</username>.</para>
 
 Even less painful would be:  su root -c 'make install'
 
 > +
 > +    <para>Using &man.su.1; works well for single systems or small networks
 > +      with just one systems administrator.  For more complex environments
 
 I suppose the de-facto standard is "system administrator", not plural.
 
 > +      (or even for these simple environments) you should take a look at
 
 Replace " you should" with a comma (or nothing, if you prefer).

From: Ken Smith <kensmith@cse.Buffalo.EDU>
To: "Gary W. Swearingen" <underway@comcast.net>
Cc: Ken Smith <kensmith@cse.Buffalo.EDU>,
	FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/54461: Possible addition to Handbook
Date: Mon, 14 Jul 2003 10:41:33 -0400

 On Mon, Jul 14, 2003 at 07:27:12AM -0700, Gary W. Swearingen wrote:
 > > +    <para>Note in this example the transition to <username>root</username>
 > > +      was much less painful than logging off and back on twice, and only
 > > +      what was absolutely necessary got run as <username>root</username>.</para>
 > 
 > Even less painful would be:  su root -c 'make install'
 
 For one command.  It was a simple example, it is often the case you need
 to type more than one command. :-)
 
 -- 
 						Ken Smith
 - From there to here, from here to      |       kensmith@cse.buffalo.edu
   there, funny things are everywhere.   |
                       - Theodore Geisel |

From: Ken Smith <kensmith@cse.Buffalo.EDU>
To: "Gary W. Swearingen" <underway@comcast.net>
Cc: Ken Smith <kensmith@cse.Buffalo.EDU>,
	FreeBSD-gnats-submit@FreeBSD.org
Subject: Re: docs/54461: Possible addition to Handbook
Date: Mon, 14 Jul 2003 11:35:28 -0400

 On Mon, Jul 14, 2003 at 07:27:12AM -0700, Gary W. Swearingen wrote:
 > Ken Smith <kensmith@cse.Buffalo.EDU> writes:
 > > +      the username that you normally log in as must be in the <groupname>
 > 
 > Is "username" the proper form?  A few months ago someone made a sweep
 > of docs (and maybe some code?) changing good old "filesystem" to "file
 > system" and "manpage" has been complained about.  (I guess it's too late
 > for "soft ware". :)
 
 If I get a vote I'd leave it "username" because "user name" can be
 interpreted too many ways.  "User" alone is often analogous to the
 person, so "user name" for me could mean "kensmith" or could mean
 "Ken Smith".
 
 In case it makes things any easier for you folks adapted diffs are:
 
 ----------------------------
 --- basics/chapter.sgml.orig	Fri Jul 11 09:24:44 2003
 +++ basics/chapter.sgml	Mon Jul 14 11:26:01 2003
 @@ -69,6 +69,15 @@
        sharing and managing requests for hardware devices, peripherals,
        memory, and CPU time evenly to each user.</para>
  
 +    <para>Much more information about user accounts is in the chapter
 +      about <link linkend="users">accounts</link>.  For now, it is
 +      enough to know that each person (user) who uses the computer should be
 +      given their own username and password.  The system keeps track
 +      of the people using the computer based on this username.  Since
 +      it is often the case that several people are working on the same
 +      project, Unix also provides <emphasis>groups</emphasis>.
 +      Several users can be placed in the same group.</para>
 +
      <para>Because the system is capable of supporting multiple users,
        everything the system manages has a set of permissions governing who
        can read, write, and execute the resource.  These permissions are
 @@ -1687,6 +1696,20 @@
  
    <sect1 id="binary-formats">
      <title>Binary Formats</title>
 +    <para>Typically when you type in a command to a shell the shell
 +      will arrange for an executable file to be loaded into memory as
 +      part of a new process.  Executable files can either be a binary
 +      file (usually created by the linker as part of compiling a program)
 +      or a shell script (text file to be interpreted by a binary file,
 +      like &man.sh.1; or &man.perl.1;).  The &man.file.1; command can
 +      usually tell you what is inside a file.</para>
 +
 +    <para>Binary files need to have a well defined format for the system
 +      to be able to use them properly.  Part of the file will be the
 +      executable machine code (the instructions that tell the CPU what
 +      to do), part of it will be data space with pre-defined values,
 +      part will be data space with no pre-defined values, etc.  Through
 +      time, different binary file formats have evolved.</para>
  
      <para>To understand why FreeBSD uses the <filename>ELF</filename>
        format, you must first know a little about the 3 currently
 @@ -1824,6 +1847,14 @@
        <filename>a.out</filename> will be moved out of the GENERIC
        kernel, and eventually removed from the kernel once the need to
        run legacy <filename>a.out</filename> programs is past.</para>
 +
 +    <para>In addition to &man.file.1; another command that can prove
 +      useful when working with executables is &man.ldd.1;.  If
 +      &man.file.1; says that a file is a dynamically linked executable, then
 +      &man.ldd.1; can tell you what dynamically linked libraries that
 +      executable file requires.  Sometimes programs can be linked against
 +      compatibility libraries instead of the main system libraries, or
 +      otherwise rely on unexpected dynamic libraries.</para>
    </sect1>
  
    <sect1 id="basics-more-information">
 --- users/chapter.sgml.orig	Thu Oct 10 17:14:28 2002
 +++ users/chapter.sgml	Mon Jul 14 11:28:11 2003
 @@ -248,8 +248,8 @@
        for general usage if you have not already.  This applies equally
        whether you are running a multi-user or single-user machine.
        Later in this chapter, we discuss how to create additional
 -      accounts, and how to change between the normal user and
 -      superuser.</para>
 +      accounts, and how to <link linkend="users-becomesuper">
 +        change between the normal user and superuser</link>.</para>
    </sect1>
      
    <sect1 id="users-system">
 @@ -1053,6 +1053,50 @@
        <filename>/etc/group</filename>, consult the &man.group.5; manual
        page.</para>
    </sect1>
 +
 +  <sect1 id="users-becomesuper">
 +    <title>Becoming Superuser</title>
 +
 +    <para>There are several ways to do things as the superuser.  The worst
 +      way is to log in as <username>root</username>.  Usually very little
 +      needs to be done as <username>root</username> so logging off as your
 +      normal username, logging in as <username>root</username>, doing what
 +      you needed to do, then logging off and back on as your normal username
 +      is quite a waste of time.</para>
 +
 +    <para>A better way is to use &man.su.1; without providing a username,
 +      which implies the <username>root</username> user.  For this to work
 +      the username that you normally log in as must be in the <groupname>
 +      wheel</groupname> group.  An example of a fairly typical software
 +      installation would involve the system administrator unpacking the
 +      software as a non-root user.  Then in the unpacked directory, starting
 +      as their normal user account, doing something like:</para>
 +
 +    <example>
 +      <title>Compile and Install a Program</title>
 +
 +      <screen>&prompt.user; <userinput>configure</userinput>
 +&prompt.user; <userinput>make</userinput>
 +&prompt.user; <userinput>su</userinput>
 +Password:
 +&prompt.root; <userinput>make install</userinput>
 +&prompt.root; <userinput>exit</userinput>
 +&prompt.user;</screen>
 +    </example>
 +
 +    <para>Note in this example the transition to <username>root</username>
 +      was much less painful than logging off and back on twice, and only
 +      what was absolutely necessary got run as <username>root</username>.</para>
 +
 +    <para>Using &man.su.1; works well for single systems or small networks
 +      with just one system administrator.  For more complex environments
 +      (or even for these simple environments) take a look at
 +      &man.sudo.8;.  It is provided as the port <filename role="package">
 +      security/sudo</filename>.  It allows for things like logging what
 +      gets done, granting users the ability to only run certain things
 +      as the superuser, etc.</para>
 +  </sect1>
 +
  </chapter>
  
  <!-- 
 
 ----------------------------
 -- 
 						Ken Smith
 - From there to here, from here to      |       kensmith@cse.buffalo.edu
   there, funny things are everywhere.   |
                       - Theodore Geisel |
Responsible-Changed-From-To: ceri->kensmith 
Responsible-Changed-By: ceri 
Responsible-Changed-When: Thu Nov 6 13:31:56 PST 2003 
Responsible-Changed-Why:  
Give this back to Ken; I don't have time at the moment to do it, 
and he can now commit this himself. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=54461 
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Sun May 19 00:02:23 UTC 2013 
State-Changed-Why:  
Sorry Ceri, Ken, I rewrote a bunch of this patch and committed it.  Thanks! 
Take and close. 


Responsible-Changed-From-To: kensmith->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Sun May 19 00:02:23 UTC 2013 
Responsible-Changed-Why:  
Sorry Ceri, Ken, I rewrote a bunch of this patch and committed it.  Thanks! 
Take and close. 

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