docs/54461: Possible addition to Handbook

[Ken Smith]

>Number:         54461
>Category:       docs
>Synopsis:       Possible addition to Handbook
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Sun Jul 13 21:00:27 PDT 2003
>Closed-Date:
>Last-Modified:
>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 at 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:
>Unformatted: