








            IInnssttaalllliinngg aanndd OOppeerraattiinngg 44..44BBSSDD UUNNIIXX
                        MMaayy 1144,, 11999944


                   _M_a_r_s_h_a_l_l _K_i_r_k _M_c_K_u_s_i_c_k
                        _K_e_i_t_h _B_o_s_t_i_c
                     _M_i_c_h_a_e_l _J_. _K_a_r_e_l_s
                     _S_a_m_u_e_l _J_. _L_e_f_f_l_e_r
              Computer Systems Research Group
 Department of Electrical Engineering and Computer Science
             University of California, Berkeley
                Berkeley, California  94720
                       (415) 642-7780

                        _M_i_k_e _H_i_b_l_e_r
                Center for Software Science
               Department of Computer Science
                     University of Utah
                Salt Lake City, Utah  84112
                       (801) 581-5017


                          _A_B_S_T_R_A_C_T

          This  document  contains instructions for the
     installation and operation of the  4.4BSD  release
     of  UNIX as distributed by The University of Cali-
     fornia at Berkeley.

          It discusses procedures for  installing  UNIX
     on  a  new  machine, and for upgrading an existing
     4.3BSD UNIX system to the new release.  An  expla-
     nation  of how to lay out filesystems on available
     disks and the space requirements for various parts
     of  the system are given.  A brief overview of the
     major changes to the  system  between  4.3BSD  and
     4.4BSD are outlined.  An explanation of how to set
     up terminal lines and user accounts, and how to do
     system-specific tailoring is provided.  A descrip-
     tion of how to install and  configure  the  4.4BSD
     networking  facilities  is included.  Finally, the
     document  details  system  operation   procedures:
     shutdown  and  startup,  filesystem  backup proce-
     dures, resource control,  performance  monitoring,
     and  procedures  for  recompiling and reinstalling
     system software.














SMM:1-4                 Installing and Operating 4.4BSD UNIX


11..  IInnttrroodduuccttiioonn
     This document explains how to install the 4.4BSD Berke-
ley  version  of UNIX on your system.  The filesystem format
is compatible with 4.3BSD and it will only be necessary  for
you  to  do a full bootstrap procedure if you are installing
the release on a new machine.  The object file  formats  are
completely  different from the System V release, so the most
straightforward procedure for upgrading a System V system is
to do a full bootstrap.
     The  full bootstrap procedure is outlined in section 2;
the process starts with copying a filesystem  image  onto  a
new  disk.   This  filesystem  is  then  booted  and used to
extract the remainder of the  system  binaries  and  sources
from the archives on the tape(s).
     The   technique   for  upgrading  a  4.3BSD  system  is
described in section 3 of this document.  The upgrade proce-
dure  involves  extracting system binaries onto new root and
/usr filesystems and merging local configuration files  into
the  new system.  User filesystems may be upgraded in place.
Most 4.3BSD binaries may be used with 4.4BSD in  the  course
of  the  conversion.   It  is  desirable  to recompile local
sources after the conversion, as the new compiler (GCC) pro-
vides superior code optimization.  Consult section 3.5 for a
description of some of the differences  between  4.3BSD  and
4.4BSD.

11..11..  DDiissttrriibbuuttiioonn ffoorrmmaatt
     The distribution comes in two formats:

     (3)   6250bpi 2400' 9-track magnetic tapes, or
     (1)   8mm Exabyte tape

     If you have the facilities, we ssttrroonnggllyy recommend copy-
ing the magnetic tape(s) in the distribution  kit  to  guard
against  disaster.   The  tapes  contain 10240-byte records.
There are interspersed tape marks; end-of-tape  is  signaled
by  a  double  end-of-file.   The  first file on the tape is
architecture dependent.  Additional  files  on  the  tape(s)
contain  tape  archive  images  of  the  system binaries and
sources (see _t_a_r(1)1).  See the tape label for a description
of the contents and format of each individual tape.

11..22..  UUNNIIXX ddeevviiccee nnaammiinngg
     Device  names  have  a  different  syntax  depending on
whether you are talking to the standalone system or  a  run-
ning UNIX kernel.  The standalone system syntax is currently
architecture dependent  and  is  described  in  the  various
architecture specific sections as applicable.  When not run-
ning standalone, devices are  available  via  files  in  the
/dev/ directory.  The file name typically encodes the device
-----------
  1 References of the form  _X(Y)  mean  the  entry
named  _X  in  section Y of the ``UNIX Programmer's
Manual''.



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                 SMM:1-5


type, its logical unit and a  partition  within  that  unit.
For  example,  /dev/sd2b  refers  to  the  second  partition
(``b'') of SCSI (``sd'') drive number ``2'', while /dev/rmt0
refers to the raw (``r'') interface of 9-track tape (``mt'')
unit ``0''.
     The mapping of physical  addressing  information  (e.g.
controller, target) to a logical unit number is dependent on
the system configuration.  In all simple cases, where only a
single  controller  is  present,  a drive with physical unit
number 0 (e.g., as determined  by  its  unit  specification,
either  unit  plug  or  other  selection  mechanism) will be
called unit 0 in its UNIX file name.  This is not,  however,
strictly necessary, since the system has a level of indirec-
tion in this naming.  If there are multiple controllers, the
disk  unit  numbers  will  normally  be counted sequentially
across controllers.  This can be taken advantage of to  make
the  system less dependent on the interconnect topology, and
to make reconfiguration after hardware failure easier.
     Each UNIX physical disk is divided into at most 8 logi-
cal  disk  partitions, each of which may occupy any consecu-
tive cylinder range on the physical device.   The  cylinders
occupied  by the 8 partitions for each drive type are speci-
fied initially in the  disk  description  file  /etc/disktab
(c.f.   _d_i_s_k_t_a_b(5)).  The partition information and descrip-
tion of the drive geometry are written in one of  the  first
sectors  of  each  disk with the _d_i_s_k_l_a_b_e_l(8) program.  Each
partition may be used for either a raw data area such  as  a
paging  area  or  to store a UNIX filesystem.  It is conven-
tional for the first partition on a disk to be used to store
a root filesystem, from which UNIX may be bootstrapped.  The
second partition is traditionally used as a paging area, and
the  rest  of the disk is divided into spaces for additional
``mounted filesystems'' by use of  one  or  more  additional
partitions.

11..33..  UUNNIIXX ddeevviicceess:: bblloocckk aanndd rraaww
     UNIX  makes a distinction between ``block'' and ``raw''
(character) devices.  Each disk has a block device interface
where  the  system makes the device byte addressable and you
can write a single byte in the middle of the disk.  The sys-
tem  will read out the data from the disk sector, insert the
byte you gave it and put the modified data back.  The  disks
with  the  names  /dev/xx0[a-h],  etc.,  are  block devices.
There are also raw devices available.  These have names like
/dev/rxx0[a-h],  the  ``r''  here standing for ``raw''.  Raw
devices bypass the buffer cache and use DMA directly to/from
the  program's  I/O buffers; they are normally restricted to
full-sector transfers.  In the bootstrap procedures we  will
often  suggest  using the raw devices, because these tend to
work faster.  Raw devices are used when making new  filesys-
tems,  when  checking  unmounted filesystems, or for copying
quiescent filesystems.  The block devices are used to  mount
filesystems.




                        May 14, 1994





SMM:1-6                 Installing and Operating 4.4BSD UNIX


     You  should  be  aware  that  it is sometimes important
whether to use the character device (for efficiency) or  not
(because  it  would not work, e.g. to write a single byte in
the middle of a sector).  Do not change the instructions  by
using the wrong type of device indiscriminately.

22..  BBoooottssttrraapp pprroocceedduurree
     This  section explains the bootstrap procedure that can
be used to get the kernel supplied  with  this  distribution
running  on  your machine.  If you are not currently running
4.3BSD you will have to do  a  full  bootstrap.   Section  3
describes  how to upgrade a 4.3BSD system.  An understanding
of the operations used in a full  bootstrap  is  helpful  in
doing  an  upgrade  as  well.   In either case, it is highly
desirable to read and understand the remainder of this docu-
ment before proceeding.
     The  distribution  supports  a  somewhat  wider  set of
machines than those for which we have built  binaries.   The
architectures   that  are  supported  only  in  source  form
include:
+o    Intel 386/486-based machines (ISA/AT or EISA bus only)
+o    Sony News MIPS-based workstations
+o    Omron Luna 68000-based workstations
If you wish to run one of these architectures, you will have
to  build  a  cross  compilation environment.  Note that the
distribution does nnoott include the machine  support  for  the
Tahoe  and VAX architectures found in previous BSD distribu-
tions.   Our  primary   development   environment   is   the
HP9000/300  series  machines.   The  other architectures are
developed and supported by people  outside  the  university.
Consequently,  we  are not able to directly test or maintain
these  other  architectures,  so  cannot  comment  on  their
robustness, reliability, or completeness.

22..11..  BBoooottssttrraappppiinngg ffrroomm tthhee ttaappee
The set of files on the distribution tape are as follows:
1)   A   _d_d(1)  (HP300),  _t_a_r(1)  (DECstation),  or  _d_u_m_p(8)
     (SPARC) image of the root filesystem
2)   A _t_a_r image of the /var filesystem
3)   A _t_a_r image of the /usr filesystem
4)   A _t_a_r image of /usr/src/sys
5)   A _t_a_r image of /usr/src except sys and contrib
6)   A _t_a_r image of /usr/src/contrib
7)   (8mm Exabyte tape distributions only) A  _t_a_r  image  of
     /usr/src/X11R5
The tape bootstrap procedure used to create a working system
involves the following major steps:
1)   Transfer a bootable root filesystem from the tape to  a
     disk and get it booted and running.
2)   Build  and  restore  the /var and /usr filesystems from
     tape with _t_a_r(1).
3)   Extract the system and utility source files as desired.
     The  following  sections  describe  the  above steps in
detail.   The  details  of  the  first  step  vary   between



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                 SMM:1-7


architectures.  The specific steps for the HP300, SPARC, and
DECstation are given in  the  next  three  sections  respec-
tively.  You should follow the instructions for your partic-
ular  architecture.   In  all  sections,  commands  you  are
expected  to  type are shown in italics, while that informa-
tion printed by the system is shown emboldened.

22..22..  BBoooottiinngg tthhee HHPP330000

22..22..11..  SSuuppppoorrtteedd hhaarrddwwaarree
The hardware supported by 4.4BSD for  the  HP300/400  is  as
follows:

  +------------------------------------------------------+
  |CPU's        68020  based  (318,  319,  320,  330 and |
  |             350), 68030 based (340, 345,  360,  370, |
  |             375,  400)  and  68040  based (380, 425, |
  |             433).                                    |
  +------------------------------------------------------+
  |DISK's       HP-IB/CS80  (7912,  7914,  7933,   7936, |
  |             7945,  7957, 7958, 7959, 2200, 2203) and |
  |             SCSI-I (including magneto-optical).      |
  +------------------------------------------------------+
  |TAPE's       Low-density CS80 cartridge (7914,  7946, |
  |             9144),   high-density   CS80   cartridge |
  |             (9145), HP SCSI DAT and SCSI Exabyte.    |
  +------------------------------------------------------+
  |RS232        98644 built-in single-port, 98642 4-port |
  |             and 98638 8-port interfaces.             |
  +------------------------------------------------------+
  |NETWORK      98643 internal and external LAN cards.   |
  +------------------------------------------------------+
  |GRAPHICS     Terminal  emulation and raw frame buffer |
  |             support for 98544 / 98545 / 98547  (Top- |
  |             cat color & monochrome), 98548 / 98549 / |
  |             98550  (Catseye  color  &   monochrome), |
  |             98700  / 98710 (Gatorbox), 98720 / 98721 |
  |             (Renaissance), 98730 /  98731  (DaVinci) |
  |             and A1096A (Hyperion monochrome).        |
  +------------------------------------------------------+
  |INPUT        General  interface  supporting  all  HIL |
  |             devices.  (e.g. keyboard, 2 and 3 button |
  |             mice, ID module, ...)                    |
  +------------------------------------------------------+
  |MISC         Battery-backed  real time clock, builtin |
  |             and 98625A/B HP-IB  interfaces,  builtin |
  |             and   98658A   SCSI  interfaces,  serial |
  |             printers and plotters on HP-IB, and SCSI |
  |             autochanger device.                      |
  +------------------------------------------------------+
Major  items  that are not supported include the 310 and 332
CPU's, 400 series machines configured  for  Domain/OS,  EISA
and  VME bus adaptors, audio, the centronics port, 1/2" tape
drives  (7980),  CD-ROM,  and  the  PVRX/TVRX  3D   graphics



                        May 14, 1994





SMM:1-8                 Installing and Operating 4.4BSD UNIX


displays.

22..22..22..  SSttaannddaalloonnee ddeevviiccee ffiillee nnaammiinngg
The  standalone system device name syntax on the HP300 is of
the form:

     xx(a,c,u,p)

where _x_x is the device type, _a specifies the adaptor to use,
_c the controller, _u the unit, and _p a partition.  The _d_e_v_i_c_e
_t_y_p_e differentiates the various disks and tapes and  is  one
of:  ``rd'' for HP-IB CS80 disks, ``ct'' for HP-IB CS80 car-
tridge tapes, or ``sd'' for SCSI-I disks (SCSI-I  tapes  are
currently  not  supported).   The _a_d_a_p_t_o_r field is a logical
HP-IB or SCSI bus adaptor card number.  This will  typically
be  0  for  SCSI  disks, 0 for devices on the ``slow'' HP-IB
interface (usually tapes) and 1 for devices on the  ``fast''
HP-IB  interface (usually disks).  To get a complete mapping
of physical (select-code) to logical card numbers just  type
a  ^C at the standalone prompt.  The _c_o_n_t_r_o_l_l_e_r field is the
disk or tape's target number on the HP-IB or SCSI bus.   For
SCSI  the range is 0 to 6 (7 is the adaptor address) and for
HP-IB the range is 0 to 7.  The _u_n_i_t  field  is  unused  and
should be 0.  The _p_a_r_t_i_t_i_o_n field is interpreted differently
for tapes and disks: for disks it is a  disk  partition  (in
the  range 0-7), and for tapes it is a file number offset on
the tape.  Thus, partition 2 of a SCSI disk drive at  target
3  on SCSI bus 1 would be ``sd(1,3,0,2)''.  If you have only
one of any type bus adaptor, you may omit  the  adaptor  and
controller  numbers;  e.g. ``sd(0,2)'' could be used instead
of ``sd(0,0,0,2)''.  The following examples always  use  the
full syntax for clarity.

22..22..33..  TThhee pprroocceedduurree
The  basic  steps  involved  in bringing up the HP300 are as
follows:
1)   Obtain a second disk and format it, if necessary.
2)   Copy a root filesystem from the tape onto the beginning
     of the disk.
3)   Boot the UNIX system on the new disk.
4)   (Optional)  Build  a root filesystem optimized for your
     disk.
5)   Label the disks with the _d_i_s_k_l_a_b_e_l(8) program.

22..22..33..11..  SStteepp 11:: sseelleeccttiinngg aanndd ffoorrmmaattttiinngg aa ddiisskk
     For your first system you will have to obtain a format-
ted  disk of a type given in the ``supported hardware'' list
above.  If you want to load an entire binary  system  (i.e.,
everything  except  /usr/src),  on  the single disk you will
need a minimum of 290MB, ruling out anything smaller than  a
7959B/S  disk.  The disklabel included in the bootstrap root
image is laid out to accommodate this scenario.   Note  that
an  HP  SCSI  magneto-optical  disk  will work fine for this
case.  4.4BSD will boot and run (albeit slowly)  using  one.



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                 SMM:1-9


If you want to load source on a single disk system, you will
need at least 640MB (at least a 2213A SCSI  or  2203A  HP-IB
disk).   A disk as small as the 7945A (54MB) can be used for
the bootstrap procedure but will hold only the root and pri-
mary  swap  partitions.   If you plan to use multiple disks,
refer to section 2.5 for suggestions on partitioning.
     After selecting a disk, you  may  need  to  format  it.
Since most HP disk drives come pre-formatted (except optical
media) you probably will not, but if necessary, you can for-
mat  a  disk  under  HP-UX  using the _m_e_d_i_a_i_n_i_t(1m) program.
Once you have 4.4BSD up and running on one machine  you  can
use  the  _s_c_s_i_f_o_r_m_a_t(8)  program  to  format additional SCSI
disks.  Any additional HP-IB disks will have to be formatted
using HP-UX.

22..22..33..22..   SStteepp  22:: ccooppyyiinngg tthhee rroooott ffiilleessyysstteemm ffrroomm ttaappee ttoo
ddiisskk
     Once  you  have a formatted second disk you can use the
_d_d(1) command under HP-UX to copy the root filesystem  image
from  the  tape  to  the  beginning of the second disk.  For
HP's, the root filesystem image is the  first  file  on  the
tape.   It includes a disklabel and bootblock along with the
root filesystem.  An example command to copy the image  from
tape to the beginning of a disk is:

     dd if=/dev/rmt/0m of=/dev/rdsk/1s0 bs=20b

The  actual  special  file syntax may vary depending on unit
numbers and the version of HP-UX that is  running.   Consult
the HP-UX _m_t(7) and _d_i_s_k(7) man pages for details.
     Note  that if you have a SCSI disk, you don't necessar-
ily have to use HP-UX (or an HP) to create  the  boot  disk.
Any machine and operating system that will allow you to copy
the raw disk image out to block 0 of the disk will do.
     If you have only a single machine with a  single  disk,
you may still be able to install and boot 4.4BSD if you have
an HP-IB cartridge tape drive.  If so, you can  use  a  more
difficult approach of booting a standalone copy program from
the tape, and using that to copy the root  filesystem  image
from  the tape to the disk.  To do this, you need to extract
the first file of the distribution tape  (the  root  image),
copy  it  over  to a machine with a cartridge drive and then
copy the image onto tape.  For example:

     dd if=/dev/rst0 of=bootimage bs=20b
     rcp bootimage foo:/tmp/bootimage
     <login to foo>
     dd if=/tmp/bootimage of=/dev/rct/0m bs=20b

Once this tape is created you can boot and  run  the  stand-
alone tape copy program from it.  The copy program is loaded
just as any other program would be loaded by the bootrom  in
``attended''  mode:  reset  the CPU, hold down the space bar
until  the  word  ``Keyboard''  appears  in  the   installed



                        May 14, 1994





SMM:1-10                Installing and Operating 4.4BSD UNIX


interface  list, and enter the menu selection for SYS_TCOPY.
Once loaded and running:


     FFrroomm:: _^_C                              (control-C to see logical adaptor assignments)
     hhppiibb00 aatt sscc77
     ssccssii00 aatt sscc1144
     FFrroomm:: _c_t_(_0_,_7_,_0_,_0_)                     (HP-IB tape, target 7, first tape file)
     TToo:: _s_d_(_0_,_0_,_0_,_2_)                       (SCSI disk, target 0, third partition)
     CCooppyy ccoommpplleetteedd:: 11772288 rreeccoorrddss ccooppiieedd


This copy will likely take 30 minutes or more.

22..22..33..33..  SStteepp 33:: bboooottiinngg tthhee rroooott ffiilleessyysstteemm
     You now have a bootable root filesystem  on  the  disk.
If  you  were previously running with two disks, it would be
best if you shut down the machine and turn off power on  the
HP-UX  drive.   It will be less confusing and it will elimi-
nate any chance of accidentally destroying the  HP-UX  disk.
If  you  used  a  cartridge tape for booting you should also
unload the tape at this point.  Whether you booted from tape
or copied from disk you should now reboot the machine and do
another attended boot (see previous section), this time with
SYS_TBOOT.   Once  loaded  and running the boot program will
display the CPU type and prompt for a kernel file to boot:

     HHPP443333 CCPPUU
     BBoooott
     :: _/_v_m_u_n_i_x

After providing the  kernel  name,  the  machine  will  boot
4.4BSD with output that looks about like this:

     559977448800++3344112200++113399228888 ssttaarrtt 00xxffee88001199eecc
     CCooppyyrriigghhtt ((cc)) 11998822,, 11998866,, 11998899,, 11999911,, 11999933
          TThhee RReeggeennttss ooff tthhee UUnniivveerrssiittyy ooff CCaalliiffoorrnniiaa..
     CCooppyyrriigghhtt ((cc)) 11999922 HHeewwlleetttt--PPaacckkaarrdd CCoommppaannyy
     CCooppyyrriigghhtt ((cc)) 11999922 MMoottoorroollaa IInncc..
     AAllll rriigghhttss rreesseerrvveedd..

     44..44BBSSDD UUNNIIXX ##11:: TTuuee JJuull 2200 1111::4400::3366 PPDDTT 11999933
         mmcckkuussiicckk@@vvaannggoogghh..CCSS..BBeerrkkeelleeyy..EEDDUU:://uussrr//oobbjj//ssyyss//ccoommppiillee//GGEENNEERRIICC..hhpp330000
     HHPP99000000//443333 ((3333MMHHzz MMCC6688004400 CCPPUU++MMMMUU++FFPPUU,, 44kk oonn--cchhiipp pphhyyssiiccaall II//DD ccaacchheess))
     rreeaall mmeemm == xxxxxx
     aavvaaiill mmeemm == ######
     uussiinngg ###### bbuuffffeerrss ccoonnttaaiinniinngg ###### bbyytteess ooff mmeemmoorryy
     ((...... iinnffoorrmmaattiioonn aabboouutt aavvaaiillaabbllee ddeevviicceess ......))
     rroooott ddeevviiccee??

     The  first  three  numbers are printed out by the boot-
strap program and are the sizes of different  parts  of  the
system (text, initialized and uninitialized data).  The sys-
tem also allocates several system data structures  after  it



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-11


starts  running.  The sizes of these structures are based on
the amount of available memory  and  the  maximum  count  of
active users expected, as declared in a system configuration
description.  This will be discussed later.
     UNIX itself then runs for the first time and begins  by
printing out a banner identifying the release and version of
the system that is in use and the date that it was compiled.
     Next  the  _m_e_m messages give the amount of real (physi-
cal) memory and the memory available  to  user  programs  in
bytes.   For example, if your machine has 16Mb bytes of mem-
ory, then xxxxxx will be 16777216.
     The messages that come out next show what devices  were
found   on   the  current  processor.   These  messages  are
described in _a_u_t_o_c_o_n_f(4).  The distributed  system  may  not
have  found  all  the communications devices you have or all
the mass storage peripherals you  have,  especially  if  you
have  more than two of anything.  You will correct this when
you create a description of your machine from which to  con-
figure  a  site-dependent  version  of  UNIX.   The messages
printed at boot here contain much of  the  information  that
will  be used in creating the configuration.  In a correctly
configured system most of the  information  present  in  the
configuration description is printed out at boot time as the
system verifies that each device is present.
     The ``root device?'' prompt was printed by  the  system
to ask you for the name of the root filesystem to use.  This
happens because the distribution system is a _g_e_n_e_r_i_c system,
i.e.,  it  can be bootstrapped on a CPU with its root device
and paging area on any available disk drive.  You will  most
likely  respond  to the root device question with ``sd0'' if
you are booting from a SCSI disk, or with ``rd0'' if you are
booting  from  an  HP-IB disk.  This response shows that the
disk it is running on is drive 0 of type  ``sd''  or  ``rd''
respectively.   If you have other disks attached to the sys-
tem, it is possible that the drive you are using will not be
configured  as logical drive 0.  Check the autoconfiguration
messages printed out by the kernel to make sure.  These mes-
sages  will  show  the type of every logical drive and their
associated controller and slave addresses.  You  will  later
build  a system tailored to your configuration that will not
prompt you for a root device when it is bootstrapped.

     rroooott ddeevviiccee?? _s_d_0
     WWAARRNNIINNGG:: pprreeppoosstteerroouuss ttiimmee iinn ffiilleessyysstteemm ---- CCHHEECCKK AANNDD RREESSEETT TTHHEE DDAATTEE!!
     eerraassee ^^??,, kkiillll ^^UU,, iinnttrr ^^CC
     ##

     The ``erase ...'' message is part of the /.profile that
was  executed  by the root shell when it started.  This mes-
sage tells you about the settings of  the  character  erase,
line erase, and interrupt characters.
     UNIX  is  now running, and the _U_N_I_X _P_r_o_g_r_a_m_m_e_r_'_s _M_a_n_u_a_l
applies.  The ``#'' is the prompt from the Bourne shell, and
lets  you know that you are the super-user, whose login name



                        May 14, 1994





SMM:1-12                Installing and Operating 4.4BSD UNIX


is ``root''.
     At this point, the root  filesystem  is  mounted  read-
only.   Before  continuing  the installation, the filesystem
needs to be ``updated'' to allow writing and device  special
files  for  the following steps need to be created.  This is
done as follows:


     ## _m_o_u_n_t___m_f_s _-_s _1_0_0_0 _-_T _t_y_p_e _/_d_e_v_/_n_u_l_l _/_t_m_p                (create a writable filesystem)
     (_t_y_p_e is the disk type as determined from /etc/disktab)
     ## _c_d _/_t_m_p                                                 (connect to that directory)
     ## _._._/_d_e_v_/_M_A_K_E_D_E_V _s_d_#                                      (create special files for root disk)
     (_s_d is the disk type, _# is the unit number)
     (ignore warning from ``sh'')
     ## _m_o_u_n_t _-_u_w _/_t_m_p_/_s_d_#_a _/                                   (read-write mount root filesystem)
     ## _c_d _/_d_e_v                                                 (go to device directory)
     ## _._/_M_A_K_E_D_E_V _s_d_#                                           (create permanent special files for root disk)
     (again, ignore warning from ``sh'')



22..22..33..44..  SStteepp 44:: ((ooppttiioonnaall)) rreessttoorriinngg tthhee rroooott ffiilleessyysstteemm
     The  root  filesystem that you are currently running on
is complete, however it probably is not optimally  laid  out
for  the  disk  on  which  you  are running.  If you will be
cloning copies of the system onto multiple disks  for  other
machines,  you  are advised to connect one of these disks to
this machine, and build and restore a properly laid out root
filesystem  onto  it.   If this is the only machine on which
you will be running 4.4BSD or peak  performance  is  not  an
issue,  you  can skip this step and proceed directly to step
5.
     Connect a second disk to your machine.   If  you  boot-
strapped  using  the two disk method, you can overwrite your
initial HP-UX disk, as it will no longer be needed (assuming
you have no plans to run HP-UX again).
     To  really  create  the  root filesystem on drive 1 you
should first label the disk as described in  step  5  below.
Then run the following commands:

     ## _c_d _/_d_e_v
     ## _._/_M_A_K_E_D_E_V _s_d_1_a
     ##_n_e_w_f_s _/_d_e_v_/_r_s_d_1_a
     ##_m_o_u_n_t _/_d_e_v_/_s_d_1_a _/_m_n_t
     ##_c_d _/_m_n_t
     ##_d_u_m_p _0_f _- _/_d_e_v_/_r_s_d_0_a _| _r_e_s_t_o_r_e _x_f _-
     (Note: restore will ask if you want to ``set owner/mode for '.'''
     to which you should reply ``yes''.)

     When this completes, you should then shut down the sys-
tem, and boot on the disk that you  just  created  following
the procedure in step (3) above.





                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-13


22..22..33..55..  SStteepp 55:: ppllaacciinngg llaabbeellss oonn tthhee ddiisskkss
     For  each  disk on the HP300, 4.4BSD places information
about the geometry of the drive and the partition layout  at
byte  offset 1024.  This information is written with _d_i_s_k_l_a_-
_b_e_l(8).
     The root image just loaded includes a ``generic'' label
intended to allow easy installation of the root and /usr and
may not be suitable for the actual  disk  on  which  it  was
installed.   In  particular,  it  may  make your disk appear
larger or smaller than its real size.  In the  former  case,
you  lose  some capacity.  In the latter, some of the parti-
tions may map non-existent  sectors  leading  to  errors  if
those  partitions  are  used.   It is also possible that the
defined geometry will interact poorly  with  the  filesystem
code  resulting in reduced performance.  However, as long as
you are willing to give up a little space, not  use  certain
partitions  or  suffer  minor  performance  degradation, you
might want to avoid this step; especially if you do not know
how to use _e_d(1).
     If  you choose to edit this label, you can fill in cor-
rect geometry information from /etc/disktab.  You  may  also
want to rework the ``e'' and ``f'' partitions used for load-
ing /usr and /var.  You should not attempt to, and _d_i_s_k_l_a_b_e_l
will  not  let you, modify the ``a'', ``b'' and ``d'' parti-
tions.  To edit a label:

     ## _E_D_I_T_O_R_=_e_d
     ## _e_x_p_o_r_t _E_D_I_T_O_R
     ## _d_i_s_k_l_a_b_e_l  _-_r  _-_e  _/_d_e_v_/_rXXXX##_d

where XXXX is the type and ## is the logical drive number; e.g.
/dev/rsd0d  or  /dev/rrd0d.   Note  the  explicit use of the
``d'' partition.  This partition includes the  bootblock  as
does  ``c''  and  using  it allows you to change the size of
``c''.
     If you wish to label any additional disks, run the fol-
lowing command for each:

     ##_d_i_s_k_l_a_b_e_l  _-_r_w  XXXX##  ttyyppee  _"_o_p_t_i_o_n_a_l___p_a_c_k___n_a_m_e_"

where XXXX## is the same as in the previous command and ttyyppee is
the HP300 disk device name as listed in  /etc/disktab.   The
optional  information  may  contain any descriptive name for
the contents of a disk, and may be up to 16 characters long.
This  procedure  will  place the label on the disk using the
information found in /etc/disktab for the disk  type  named.
If  you  have changed the disk partition sizes, you may wish
to add entries for the modified configuration in  /etc/disk-
tab before labeling the affected disks.
     You  have  now completed the HP300 specific part of the
installation.  Now  proceed  to  the  generic  part  of  the
installation  described starting in section 2.5 below.  Note
that where the disk name ``sd'' is used  throughout  section
2.5,  you  should  substitute  the  name  ``rd''  if you are



                        May 14, 1994





SMM:1-14                Installing and Operating 4.4BSD UNIX


running on an HP-IB disk.  Also, if you  are  loading  on  a
single  disk  with  the  default  disklabel,  /var should be
restored to the ``f'' partition and /usr to the ``e'' parti-
tion.

22..33..  BBoooottiinngg tthhee SSPPAARRCC

22..33..11..  SSuuppppoorrtteedd hhaarrddwwaarree
The  hardware  supported  by 4.4BSD for the SPARC is as fol-
lows:

  +------------------------------------------------------+
  |CPU's        SPARCstation 1 series (1, 1+, SLC,  IPC) |
  |             and SPARCstation 2 series (2, IPX).      |
  +------------------------------------------------------+
  |DISK's       SCSI.                                    |
  +------------------------------------------------------+
  |TAPE's       none.                                    |
  +------------------------------------------------------+
  |NETWORK      SPARCstation Lance (le).                 |
  +------------------------------------------------------+
  |GRAPHICS     bwtwo, cgthree, and the GX (cgsix).      |
  +------------------------------------------------------+
  |INPUT        Keyboard and mouse.                      |
  +------------------------------------------------------+
  |MISC         Battery-backed real time clock, built-in |
  |             serial devices,  Sbus  SCSI  controller, |
  |             and audio device.                        |
  +------------------------------------------------------+
Major  items  that  are  not supported include anything VME-
based, the floppy disk, and SCSI tapes.

22..33..22..  LLiimmiittaattiioonnss
There are several important limitations on the  4.4BSD  dis-
tribution for the SPARC:
1)   You  mmuusstt  have  SunOS  4.1.x  or  Solaris  to bring up
     4.4BSD.  There is no  SPARCstation  bootstrap  code  in
     this  distribution.   The Sun-supplied boot loader will
     be used to boot 4.4BSD; you must copy  this  from  your
     SunOS  distribution.  This imposes several restrictions
     on the system, as detailed below.
2)   The 4.4BSD SPARC kernel does not  remap  SCSI  IDs.   A
     SCSI  disk  at  target  0 will become ``sd0'', where in
     SunOS the same disk will normally  be  called  ``sd3''.
     If  your  existing  SunOS system is diskful, it will be
     least painful to have SunOS running on the disk on tar-
     get  3 lun 0 and put 4.4BSD on the disk on target 0 lun
     0.  Both systems will then think they  are  running  on
     ``sd0'',  and you can boot either system as needed sim-
     ply by changing the EEPROM's boot device.
3)   There is no SCSI tape driver.  You  must  have  another
     system for tape reading and backups.
4)   Although  the  4.4BSD SPARC kernel will handle existing
     SunOS shared libraries, it does not use or create  them



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-15


     itself,  and  therefore  requires  much more disk space
     than SunOS does.
5)   It is currently difficult (though not completely impos-
     sible)  to  run  4.4BSD  diskless.   These instructions
     assume you will have  a  local  boot,  swap,  and  root
     filesystem.
6)   When using a serial port rather than a graphics display
     as the console, only port ttya can be  used.   Attempts
     to  use  port  ttyb  will fail when the kernel tries to
     print the boot up messages to the console.

22..33..33..  TThhee pprroocceedduurree
     You must have a spare disk on which  to  place  4.4BSD.
The  steps  involved  in bootstrapping this tape are as fol-
lows:
1)   Bring up SunOS (preferably SunOS 4.1.x or Solaris  1.x,
     although Solaris 2 may work -- this is untested).
2)   Attach  auxiliary SCSI disk(s).  Format and label using
     the SunOS formatting and labeling programs  as  needed.
     Note  that  the  root  filesystem currently requires at
     least 10 MB; 16 MB or more is recommended.  The b  par-
     tition  will  be used for swap; this should be at least
     32 MB.
3)   Use the SunOS _n_e_w_f_s to build the root filesystem.   You
     may  also  want  to build other filesystems at the same
     time.  (By default, the 4.4BSD _n_e_w_f_s builds a  filesys-
     tem  that  SunOS will not handle; if you plan to switch
     OSes back and forth you may want to sacrifice the  per-
     formance  gain  from the new filesystem format for com-
     patibility.)  You can build an old-format filesystem on
     4.4BSD  by  giving  the -O option to _n_e_w_f_s(8).  _F_s_c_k(8)
     can  convert  old  format  filesystems  to  new  format
     filesystems,  but  not  vice  versa, so you may want to
     initially build old format filesystems so that they can
     be  mounted under SunOS, and then later convert them to
     new format filesystems  when  you  are  satisfied  that
     4.4BSD  is  running  properly.   In  any case, yyoouu mmuusstt
     bbuuiilldd aann oolldd--ssttyyllee rroooott ffiilleessyysstteemm so  that  the  SunOS
     boot program will work.
4)   Mount  the  new  root,  then  copy the SunOS /boot into
     place and use  the  SunOS  ``installboot''  program  to
     enable  disk-based  booting.   Note that the filesystem
     must be mounted when you do the ``installboot'':

          # mount /dev/sd3a /mnt
          # cp /boot /mnt/boot
          # cd /usr/kvm/mdec
          # installboot /mnt/boot bootsd /dev/rsd3a

     The SunOS /boot will load 4.4BSD kernels; there  is  no
     SPARCstation  bootstrap code on the distribution.  Note
     that the SunOS /boot does not  handle  the  new  4.4BSD
     filesystem format.




                        May 14, 1994





SMM:1-16                Installing and Operating 4.4BSD UNIX


5)   Restore the contents of the 4.4BSD root filesystem.

          # cd /mnt
          # rrestore xf tapehost:/dev/nrst0

6)   Boot the supplied kernel:

          # halt
          ok boot sd(0,3)vmunix -s      [for old proms] OR
          ok boot disk3 -s              [for new proms]
          ... [4.4BSD boot messages]

To  install  the  remaining  filesystems,  use the procedure
described starting in section 2.5.  In  these  instructions,
/usr  should  be loaded into the ``e'' partition and /var in
the ``f'' partition.
After completing the filesystem installation you may want to
set up 4.4BSD to reboot automatically:

     # halt
     ok setenv boot-from sd(0,3)vmunix  [for old proms] OR
     ok setenv boot-device disk3        [for new proms]

If  you  build backwards-compatible filesystems, either with
the SunOS newfs or with the 4.4BSD ``-O''  option,  you  can
mount  these  under  SunOS.   The  SunOS fsck will, however,
always think that these filesystems are corrupted, as  there
are  several  new (previously unused) superblock fields that
are updated in 4.4BSD.  Running ``fsck -b32'' and letting it
``fix'' the superblock will take care of this.
If  you  wish  to  run  SunOS binaries that use SunOS shared
libraries, you simply need to copy all  the  dynamic  linker
files from an existing SunOS system:

     # rcp sunos-host:/etc/ld.so.cache /etc/
     # rcp sunos-host:'/usr/lib/*.so*' /usr/lib/

The  SunOS  compiler  and  linker  should be able to produce
SunOS binaries under 4.4BSD, but this has not  been  tested.
If  you  plan  to  try  it you will need the appropriate .sa
files as well.

22..44..  BBoooottiinngg tthhee DDEECCssttaattiioonn

22..44..11..  SSuuppppoorrtteedd hhaarrddwwaarree
The hardware supported by 4.4BSD for the  DECstation  is  as
follows:










                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-17


  +------------------------------------------------------+
  |CPU's        R2000   based  (3100)  and  R3000  based |
  |             (5000/200, 5000/20, 5000/25,  5000/1xx). |
  +------------------------------------------------------+
  |DISK's       SCSI-I  (tested RZ23, RZ55, RZ57, Maxtor |
  |             8760S).                                  |
  +------------------------------------------------------+
  |TAPE's       SCSI-I (tested DEC  TK50,  Archive  DAT, |
  |             Emulex MT02).                            |
  +------------------------------------------------------+
  |RS232        Internal  DEC  dc7085 and AMD 8530 based |
  |             interfaces.                              |
  +------------------------------------------------------+
  |NETWORK      TURBOchannel PMAD-AA and internal  LANCE |
  |             based interfaces.                        |
  +------------------------------------------------------+
  |GRAPHICS     Terminal  emulation and raw frame buffer |
  |             support for 3100 (color  &  monochrome), |
  |             TURBOchannel  PMAG-AA, PMAG-BA, PMAG-DV. |
  +------------------------------------------------------+
  |INPUT        Standard DEC keyboard (LK201) and mouse. |
  +------------------------------------------------------+
  |MISC         Battery-backed real time clock, internal |
  |             and  TURBOchannel  PMAZ-AA  SCSI  inter- |
  |             faces.                                   |
  +------------------------------------------------------+
Major  items  that  are  not  supported include the 5000/240
(there is code but not compiled in or tested),  R4000  based
machines,  FDDI and audio interfaces.  Diskless machines are
not supported but booting kernels and bootstrapping over the
network is supported on the 5000 series.

22..44..22..  TThhee pprroocceedduurree
     The  first  file on the distribution tape is a tar file
that contains four files.  The first step requires a running
UNIX  (or ULTRIX) system that can be used to extract the tar
archive from the first file on the tape.  The command:

     tar xf /dev/rmt0

will extract the following four files:

     A) root.image: _d_d image of the root filesystem
     B) vmunix.tape: _d_d image for creating boot tapes
     C) vmunix.net: file for booting over the network
     D) root.dump: _d_u_m_p image of the root filesystem

There are three basic ways a system can be bootstrapped cor-
responding  to  the first three files.  You may want to read
the section on bootstrapping the HP300  since  many  of  the
steps  are  similar.   A  spare, formatted SCSI disk is also
useful.





                        May 14, 1994





SMM:1-18                Installing and Operating 4.4BSD UNIX


22..44..22..11..  PPrroocceedduurree AA:: ccooppyy rroooott ffiilleessyysstteemm ttoo ddiisskk
     This procedure is similar to the HP300.  If you have an
extra disk, the easiest  approach  is  to  use  _d_d(1)  under
ULTRIX to copy the root filesystem image to the beginning of
the spare  disk.   The  root  filesystem  image  includes  a
disklabel  and bootblock along with the root filesystem.  An
example command to copy the image to the beginning of a disk
is:

     dd if=root.image of=/dev/rz1c bs=20b

The  actual  special file syntax will vary depending on unit
numbers and the version of ULTRIX  that  is  running.   This
system  is  now  ready to boot. You can boot the kernel with
one of the following PROM commands. If you are booting on  a
3100, the disk must be SCSI id zero because of a bug.

     DEC 3100:    boot -f rz(0,0,0)vmunix
     DEC 5000:    boot 5/rz0/vmunix

You  can  then  proceed  to section 2.5 to create reasonable
disk partitions for your machine and then install  the  rest
of the system.

22..44..22..22..  PPrroocceedduurree BB:: bboooottssttrraapp ffrroomm ttaappee
     If  you  have only a single machine with a single disk,
you need to use the more difficult  approach  of  booting  a
kernel  and mini-root from tape or the network, and using it
to restore the root filesystem.
     First, you will need to create a boot tape. This can be
done using _d_d as in the following example.

     dd if=vmunix.tape of=/dev/nrmt0 bs=1b
     dd if=root.dump of=/dev/nrmt0 bs=20b

The  actual special file syntax for the tape drive will vary
depending on unit numbers, tape device and  the  version  of
ULTRIX that is running.
     The first file on the boot tape contains a boot header,
kernel, and mini-root filesystem that the PROM can copy into
memory.  Installing from tape has only been tested on a 3100
and a 5000/200 using a TK50 tape drive. Here are two example
PROM commands to boot from tape.

     DEC 3100:    boot -f tz(0,5,0) m    # 5 is the SCSI id of the TK50
     DEC 5000:    boot 5/tz6 m           # 6 is the SCSI id of the TK50

The  `m'  argument  tells  the  kernel  to  look  for a root
filesystem in memory.  Next you should  proceed  to  section
2.4.3 to build a disk-based root filesystem.

22..44..22..33..  PPrroocceedduurree CC:: bboooottssttrraapp oovveerr tthhee nneettwwoorrkk
     You  will need a host machine that is running the _b_o_o_t_p
server with the vmunix.net file  installed  in  the  default



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-19


directory defined by the configuration file for _b_o_o_t_p.  Here
are two example PROM commands to boot across the net:

     DEC 3100: boot -f tftp()vmunix.net m
     DEC 5000: boot 6/tftp/vmunix.net m

This command should load the kernel and mini-root into  mem-
ory and run the same as the tape install (procedure B).  The
rest of the steps are the same except you will need to start
the  network  (if  you  are unsure how to fill in the <name>
fields below, see sections 4.4 and 5).  Execute the  follow-
ing to start the networking:

     # mount -uw /
     # echo 127.0.0.1 localhost >> /etc/hosts
     # echo <your.host.inet.number> myname.my.domain myname >> /etc/hosts
     # echo <friend.host.inet.number> myfriend.my.domain myfriend >> /etc/hosts
     # ifconfig le0 inet myname

Next  you  should  proceed to section 2.4.3 to build a disk-
based root filesystem.

22..44..33..  LLaabbeell ddiisskk aanndd ccrreeaattee tthhee rroooott ffiilleessyysstteemm
There are five steps to create a disk-based root filesystem.
1)   Label the disk.

          # disklabel -W /dev/rrz?c          # This enables writing the label
          # disklabel -w -r -B /dev/rrz?c $DISKTYPE
          # newfs /dev/rrz?a
          ...
          # fsck /dev/rrz?a
          ...

     Supported disk types are listed in /etc/disktab.
2)   Restore the root filesystem.

          # mount -uw /
          # mount /dev/rz?a /a
          # cd /a

         If you are restoring locally (procedure B), run:

          # mt -f /dev/nrmt0 rew
          # restore -xsf 2 /dev/rmt0

         If  you are restoring across the net (procedure c),
     run:

          # rrestore xf myfriend:/path/to/root.dump

         When the restore finishes, clean up with:






                        May 14, 1994





SMM:1-20                Installing and Operating 4.4BSD UNIX


          # cd /
          # sync
          # umount /a
          # fsck /dev/rz?a

3)   Reset the system and initialize  the  PROM  monitor  to
     boot automatically.

          DEC 3100: setenv bootpath boot -f rz(0,?,0)vmunix
          DEC 5000: setenv bootpath 5/rz?/vmunix -a

4)   After  booting UNIX, you will need to create /dev/mouse
     to run X windows as in the following example.

          rm /dev/mouse
          ln /dev/xx /dev/mouse

     The 'xx' should be one of the following:

          pm0  raw interface to PMAX graphics devices
          cfb0 raw interface to TURBOchannel PMAG-BA color frame buffer
          xcfb0     raw interface to maxine graphics devices
          mfb0 raw interface to mono graphics devices

     You can then proceed to section 2.5 to install the rest
     of the system.  Note that where the disk name ``sd'' is
     used throughout section 2.5, you should substitute  the
     name ``rz''.

22..55..  DDiisskk ccoonnffiigguurraattiioonn
     All  architectures  now  have  a root filesystem up and
running and proceed from this point to layout filesystems to
make use of the available space and to balance disk load for
better system performance.

22..55..11..  DDiisskk nnaammiinngg aanndd ddiivviissiioonnss
     Each physical disk drive can be divided into  up  to  8
partitions; UNIX typically uses only 3 or 4 partitions.  For
instance, the first partition, sd0a,  is  used  for  a  root
filesystem,  a  backup  thereof, or a small filesystem like,
/var/tmp; the second partition, sd0b, is used for paging and
swapping;  and  a  third  partition, typically sd0e, holds a
user filesystem.
     The space available on a disk varies per device.   Each
disk  typically has a paging area of 30 to 100 megabytes and
a root filesystem of about 17  megabytes.   The  distributed
system  binaries occupy about 150 (180 with X11R5) megabytes
while the major sources occupy another 250 (340 with  X11R5)
megabytes.   The /var filesystem as delivered on the tape is
only 2Mb, however it should have at least 50Mb allocated  to
it just for normal system activity.  Usually it is allocated
the last partition on the disk so that  it  can  provide  as
much  space  as  possible to the /var/users filesystem.  See
section 2.5.4 for further details on disk layouts.



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-21


     Be aware that the disks have their  sizes  measured  in
disk  sectors (usually 512 bytes), while the UNIX filesystem
blocks are variable sized.  If BLOCKSIZE=1k is  set  in  the
user's  environment,  all user programs report disk space in
kilobytes, otherwise, disk  sizes  are  always  reported  in
units  of  512-byte sectors2.  The /etc/disktab file used in
labelling disks and making filesystems specifies disk parti-
tion sizes in sectors.

22..55..22..  LLaayyoouutt ccoonnssiiddeerraattiioonnss
     There  are  several  considerations  in deciding how to
adjust the arrangement of things on your  disks.   The  most
important  is  making  sure that there is adequate space for
what is required; secondarily, throughput  should  be  maxi-
mized.  Paging space is an important parameter.  The system,
as distributed, sizes the configured paging areas each  time
the  system  is  booted.   Further, multiple paging areas of
different sizes may be interleaved.
     Many common system programs (C, the editor, the  assem-
bler etc.)  create intermediate files in the /tmp directory,
so the filesystem where this is stored also should  be  made
large  enough  to  accommodate most high-water marks.  Typi-
cally, /tmp is constructed from  a  memory-based  filesystem
(see  _m_o_u_n_t___m_f_s(8)).   Programs  that  want  their temporary
files to persist across system  reboots  (such  as  editors)
should  use  /var/tmp.  If you plan to use a disk-based /tmp
filesystem to avoid loss across  system  reboots,  it  makes
sense  to  mount  this  in a ``root'' (i.e. first partition)
filesystem on another disk.  All the  programs  that  create
files  in  /tmp take care to delete them, but are not immune
to rare events and can leave dregs.  The directory should be
examined every so often and the old files deleted.
     The  efficiency  with which UNIX is able to use the CPU
is often strongly affected by the configuration of disk con-
trollers;  it  is  critical  for good performance to balance
disk load.  There are at least five components of  the  disk
load that you can divide between the available disks:
1)   The root filesystem.
2)   The /var and /var/tmp filesystems.
3)   The /usr filesystem.
4)   The user filesystems.
5)   The paging activity.
The  following  possibilities are ones we have used at times
when we had 2, 3 and 4 disks:






-----------
  2 You can thank System V intransigence and POSIX
duplicity for requiring that  512-byte  blocks  be
the units that programs report.



                        May 14, 1994





SMM:1-22                Installing and Operating 4.4BSD UNIX


               +----------------------------+
               +--------+-------------------+
               |        |     | disk|s       |
               |what    | 2   | 3   | 4     |
               +--------+-----+-----+-------+
               |root    | 0   | 0   | 0     |
               |var     | 1   | 2   | 3     |
               |usr     | 1   | 1   | 1     |
               |paging  | 0+1 | 0+2 | 0+2+3 |
               |users   | 0   | 0+2 | 0+2   |
               |archive | x   | x   | 3     |
               +--------+-----+-----+-------+
     The most i+m-p-o-r-t-a-n-t--t-h-i-n-g-s--t-o--c-o-n-s-i-d-e-r--a+re to  even  out
the  disk load as much as possible, and to do this by decou-
pling filesystems (on separate  arms)  between  which  heavy
copying occurs.  Note that a long term average balanced load
is not important; it is  much  more  important  to  have  an
instantaneously balanced load when the system is busy.
     Intelligent   experimentation  with  a  few  filesystem
arrangements can pay off in much improved  performance.   It
is particularly easy to move the root, the /var and /var/tmp
filesystems and the paging areas.  Place the user files  and
the  /usr  directory  as  space needs dictate and experiment
with the other, more easily moved filesystems.

22..55..33..  FFiilleessyysstteemm ppaarraammeetteerrss
     Each filesystem is parameterized according to its block
size,  fragment  size, and the disk geometry characteristics
of the medium on which it resides.  Inaccurate specification
of  the  disk  characteristics  or  haphazard  choice of the
filesystem parameters can result in  substantial  throughput
degradation or significant waste of disk space.  As distrib-
uted, filesystems are configured according to the  following
table.


             Filesystem   Block size   Fragment size
             ----------------------------------------
             root         8 kbytes     1 kbytes
             usr          8 kbytes     1 kbytes
             users        4 kbytes     512 bytes


     The  root  filesystem block size is made large to opti-
mize bandwidth to the associated disk.  The large block size
is  important  as many of the most heavily used programs are
demand paged out of the /bin directory.  The  fragment  size
of  1 kbyte is a ``nominal'' value to use with a filesystem.
With a 1 kbyte fragment size disk space utilization is about
the same as with the earlier versions of the filesystem.
     The  filesystems  for  users  have a 4 kbyte block size
with 512 byte fragment size.   These  parameters  have  been
selected  based  on  observations  of the performance of our
user filesystems.  The 4 kbyte block size provides  adequate



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-23


bandwidth  while the 512 byte fragment size provides accept-
able space compaction and disk fragmentation.
     Other parameters may be chosen in constructing filesys-
tems,  but the factors involved in choosing a block size and
fragment size are many and interact in complex ways.  Larger
block  sizes  result  in better throughput to large files in
the filesystem as larger I/O requests will then be  done  by
the  system.   However,  consideration  must be given to the
average file sizes found in the filesystem and  the  perfor-
mance of the internal system buffer cache.   The system cur-
rently provides space in  the  inode  for  12  direct  block
pointers, 1 single indirect block pointer, 1 double indirect
block pointer, and 1 triple indirect block  pointer.   If  a
file  uses  only  direct  blocks,  access time to it will be
optimized by maximizing the block size.  If  a  file  spills
over  into  an  indirect block, increasing the block size of
the filesystem may decrease the  amount  of  space  used  by
eliminating  the  need  to allocate an indirect block.  How-
ever, if the block size is increased and an  indirect  block
is  still required, then more disk space will be used by the
file because indirect blocks are allocated according to  the
block size of the filesystem.
     In selecting a fragment size for a filesystem, at least
two considerations should be given.  The  major  performance
tradeoffs  observed  are between an 8 kbyte block filesystem
and a 4 kbyte block filesystem.  Because  of  implementation
constraints,  the  block size versus fragment size ratio can
not be greater than 8.  This means that an 8 kbyte  filesys-
tem  will  always have a fragment size of at least 1 kbytes.
If a filesystem is created with a 4 kbyte block size and a 1
kbyte  fragment size, then upgraded to an 8 kbyte block size
and 1 kbyte fragment size, identical space  compaction  will
be  observed.   However, if a filesystem has a 4 kbyte block
size and 512 byte fragment size, converting it to  an  8K/1K
filesystem  will result in 4-8% more space being used.  This
implies  that  4  kbyte  block  filesystems  that  might  be
upgraded to 8 kbyte blocks for higher performance should use
fragment sizes of at least 1 kbytes to minimize  the  amount
of work required in conversion.
     A  second, more important, consideration when selecting
the fragment size for a filesystem is the level of  fragmen-
tation  on  the  disk.  With an 8:1 fragment to block ratio,
storage fragmentation occurs much sooner, particularly  with
a  busy  filesystem running near full capacity.  By compari-
son, the level of fragmentation in a 4:1 fragment  to  block
ratio filesystem is one tenth as severe.  This means that on
filesystems where many files are created  and  deleted,  the
512  byte fragment size is more likely to result in apparent
space exhaustion because of fragmentation.   That  is,  when
the  filesystem is nearly full, file expansion that requires
locating a contiguous area of disk space is more  likely  to
fail  on a 512 byte filesystem than on a 1 kbyte filesystem.
To minimize fragmentation problems of this sort, a parameter
in the super block specifies a minimum acceptable free space



                        May 14, 1994





SMM:1-24                Installing and Operating 4.4BSD UNIX


threshold.  When normal users (i.e. anyone  but  the  super-
user)  attempt  to  allocate  disk  space and the free space
threshold is exceeded, the user is returned an error  as  if
the  filesystem  were  really full.  This parameter is nomi-
nally set to 5%; it may be changed by supplying a  parameter
to  _n_e_w_f_s(8),  or by updating the super block of an existing
filesystem using _t_u_n_e_f_s(8).
     Finally, a third,  less  common  consideration  is  the
attributes of the disk itself.  The fragment size should not
be smaller than the physical sector size of the disk.  As an
example,  the HP magneto-optical disks have 1024 byte physi-
cal sectors.  Using a 512 byte fragment size on  such  disks
will work but is extremely inefficient.
     Note that the above discussion considers block sizes of
up to only 8k.  As of the 4.4  release,  the  maximum  block
size has been increased to 64k.  This allows an entirely new
set of block/fragment combinations for which there is little
experience  to date.  In general though, unless a filesystem
is to be used for a special purpose application  (for  exam-
ple,  storing image processing data), we recommend using the
values supplied above.  Remember that the current  implemen-
tation  limits  the  block size to at most 64 kbytes and the
ratio of block size versus fragment size must be 1, 2, 4, or
8.
     The  disk  geometry  information used by the filesystem
affects  the  block  layout  policies  employed.   The  file
/etc/disktab,  as  supplied,  contains the data for most all
drives supported  by  the  system.   Before  constructing  a
filesystem  with  _n_e_w_f_s(8)  you should label the disk (if it
has not yet been labeled, and the driver  supports  labels).
If  labels cannot be used, you must instead specify the type
of disk on which the filesystem resides;  _n_e_w_f_s  then  reads
/etc/disktab instead of the pack label.  This file also con-
tains the default filesystem partition  sizes,  and  default
block  and  fragment  sizes.  To override any of the default
values you can modify the file, edit the disk label, or  use
an option to _n_e_w_f_s.

22..55..44..  IImmpplleemmeennttiinngg aa llaayyoouutt
     To put a chosen disk layout into effect, you should use
the _n_e_w_f_s(8) command to create each  new  filesystem.   Each
filesystem must also be added to the file /etc/fstab so that
it will be checked and mounted  when  the  system  is  boot-
strapped.
     First  we  will  consider  a system with a single disk.
There is little real choice on how to  do  the  layout;  the
root  filesystem  goes  in the ``a'' partition, /usr goes in
the ``e'' partition, and /var fills out the remainder of the
disk  in the ``f'' partition.  This is the organization used
if you loaded the  disk-image  root  filesystem.   With  the
addition  of a memory-based /tmp filesystem, its fstab entry
would be as follows:





                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-25


/dev/sd0a   /      ufs    rw                                     1   1
/dev/sd0b   none   swap   sw                                     0   0
/dev/sd0b   /tmp   mfs    rw,-s=14000,-b=8192,-f=1024,-T=sd660   0   0
/dev/sd0e   /usr   ufs    ro                                     1   2
/dev/sd0f   /var   ufs    rw                                     1   2

     If we had a  second  disk,  we  would  split  the  load
between  the  drives.  On the second disk, we place the /usr
and /var filesystems in their usual sd1e and sd1f partitions
respectively.   The sd1b partition would be used as a second
paging area, and the sd1a partition left  as  a  spare  root
filesystem  (alternatively sd1a could be used for /var/tmp).
The first disk still holds the the root filesystem in  sd0a,
and  the  primary  swap area in sd0b.  The sd0e partition is
used to hold home directories in /var/users.  The sd0f  par-
tition can be used for /usr/src or alternately the sd0e par-
tition can be extended to cover the rest of  the  disk  with
_d_i_s_k_l_a_b_e_l(8).   As  before,  the /tmp directory is a memory-
based  filesystem.   Note  that  to  interleave  the  paging
between  the two disks you must build a system configuration
that specifies:

     config    vmunix    root on sd0 swap on sd0 and sd1

The /etc/fstab file would then contain

/dev/sd0a   /            ufs    rw                                     1   1
/dev/sd0b   none         swap   sw                                     0   0
/dev/sd1b   none         swap   sw                                     0   0
/dev/sd0b   /tmp         mfs    rw,-s=14000,-b=8192,-f=1024,-T=sd660   0   0
/dev/sd1e   /usr         ufs    ro                                     1   2
/dev/sd0f   /usr/src     ufs    rw                                     1   2
/dev/sd1f   /var         ufs    rw                                     1   2
/dev/sd0e   /var/users   ufs    rw                                     1   2

     To make the /var filesystem we would do:

     ## _c_d _/_d_e_v
     ## _M_A_K_E_D_E_V _s_d_1
     ## _d_i_s_k_l_a_b_e_l _-_w_r _s_d_1 _"_d_i_s_k _t_y_p_e_" _"_d_i_s_k _n_a_m_e_"
     ## _n_e_w_f_s _s_d_1_f
     (information about filesystem prints out)
     ## _m_k_d_i_r _/_v_a_r
     ## _m_o_u_n_t _/_d_e_v_/_s_d_1_f _/_v_a_r


22..66..  IInnssttaalllliinngg tthhee rreesstt ooff tthhee ssyysstteemm
     At this point you should have your  disks  partitioned.
The  next  step  is to extract the rest of the data from the
tape.  At a minimum you need to set up  the  /var  and  /usr
filesystems.   You  may also want to extract some or all the
program sources.  Since not all architectures  support  tape
drives  or  don't  support the correct ones, you may need to
extract the files indirectly using _r_s_h(1).  For example, for



                        May 14, 1994





SMM:1-26                Installing and Operating 4.4BSD UNIX


a directly connected tape drive you might do:

     ## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f
     ## _t_a_r _x_b_p_f _2_0 _/_d_e_v_/_n_r_m_t_0

The  equivalent  indirect procedure (where the tape drive is
on machine ``foo'') is:

     ## _r_s_h _f_o_o _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f
     ## _r_s_h _f_o_o _d_d _i_f_=_/_d_e_v_/_n_r_m_t_0 _b_s_=_2_0_b _| _t_a_r _x_b_p_f _2_0 _-

Obviously, the target machine must be connected to the local
network for this to work.  To do this:

     ## _e_c_h_o  _1_2_7_._0_._0_._1  _l_o_c_a_l_h_o_s_t _>_> _/_e_t_c_/_h_o_s_t_s
     ## _e_c_h_o  your.host.inet.number  myname.my.domain  myname _>_> _/_e_t_c_/_h_o_s_t_s
     ## _e_c_h_o  friend.host.inet.number  myfriend.my.domain  myfriend _>_> _/_e_t_c_/_h_o_s_t_s
     ## _i_f_c_o_n_f_i_g  _l_e_0  _i_n_e_t  myname

where  the  ``host.inet.number'' fields are the IP addresses
for your host and the host  with  the  tape  drive  and  the
``my.domain''  fields  are the names of your machine and the
tape-hosting machine.  See  sections  4.4  and  5  for  more
information on setting up the network.
     Assuming  a  directly connected tape drive, here is how
to extract and install /var and /usr:

## _m_o_u_n_t _-_u_w _/_d_e_v_/_s_d_#_a _/                                 (read-write mount root filesystem)
## _d_a_t_e _y_y_m_m_d_d_h_h_m_m                                       (set date, see _d_a_t_e(1))
....
## _p_a_s_s_w_d _-_l _r_o_o_t                                        (set password for super-user)
NNeeww ppaasssswwoorrdd::                                           (password will not echo)
RReettyyppee nneeww ppaasssswwoorrdd::
## _p_a_s_s_w_d _-_l _t_o_o_r                                        (set password for super-user)
NNeeww ppaasssswwoorrdd::                                           (password will not echo)
RReettyyppee nneeww ppaasssswwoorrdd::
## _h_o_s_t_n_a_m_e _m_y_s_i_t_e_n_a_m_e                                   (set your hostname)
## _n_e_w_f_s _r_s_d_#_p                                           (create empty user filesystem)
(_s_d is the disk type, _# is the unit number,
_p is the partition; this takes a few minutes)
## _m_o_u_n_t _/_d_e_v_/_s_d_#_p _/_v_a_r                                  (mount the var filesystem)
## _c_d _/_v_a_r                                               (make /var the current directory)
## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f                                  (space to end of previous tape file)
## _t_a_r _x_b_p_f _2_0 _/_d_e_v_/_n_r_m_t_0                                (extract all of var)
(this takes a few minutes)
## _n_e_w_f_s _r_s_d_#_p                                           (create empty user filesystem)
(as before _s_d is the disk type, _# is the unit number,
_p is the partition)
## _m_o_u_n_t _/_d_e_v_/_s_d_#_p _/_m_n_t                                  (mount the new /usr in temporary location)
## _c_d _/_m_n_t                                               (make /mnt the current directory)
## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f                                  (space to end of previous tape file)
## _t_a_r _x_b_p_f _2_0 _/_d_e_v_/_n_r_m_t_0                                (extract all of usr except usr/src)
(this takes about 15-20 minutes)




                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-27


## _c_d _/                                                  (make / the current directory)
## _u_m_o_u_n_t _/_m_n_t                                           (unmount from temporary mount point)
## _r_m _-_r _/_u_s_r_/_*                                          (remove excess bootstrap binaries)
## _m_o_u_n_t _/_d_e_v_/_s_d_#_p _/_u_s_r                                  (remount /usr)

If no disk label has been installed on the disk,  the  _n_e_w_f_s
command  will  require  a third argument to specify the disk
type, using one of the names in /etc/disktab.  If  the  tape
had  been  rewound or positioned incorrectly before the _t_a_r,
to extract /var it may be repositioned by the following com-
mands.

     ## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _r_e_w
     ## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f _1

The  data  on  the  second and third tape files has now been
extracted.  If you are using 6250bpi tapes, the  first  reel
of  the  distribution  is  no  longer needed; you should now
mount the second reel instead.  The  installation  procedure
continues from this point on the 8mm tape.  The next step is
to extract  the  sources.   As  previously  noted,  /usr/src
requires  about  250-340Mb of space.  Ideally sources should
be in a separate filesystem; if you plan to  put  them  into
your  /usr filesystem, it will need at least 500Mb of space.
Assuming that you will be using  a  separate  filesystem  on
sd0f  for  /usr/src, you will start by creating and mounting
it:

     ## _n_e_w_f_s _s_d_0_f
     (information about filesystem prints out)
     ## _m_k_d_i_r _/_u_s_r_/_s_r_c
     ## _m_o_u_n_t _/_d_e_v_/_s_d_0_f _/_u_s_r_/_s_r_c

First you will extract the kernel source:


     ## _c_d _/_u_s_r_/_s_r_c
     ## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f                                (space to end of previous tape file)
     (this should only be done on Exabyte distributions)
     ## _t_a_r _x_p_b_f _2_0 _/_d_e_v_/_n_r_m_t_0                              (extract the kernel sources)
     (this takes about 15-30 minutes)


The next tar file contains the sources  for  the  utilities.
It is extracted as follows:


     ## _c_d _/_u_s_r_/_s_r_c
     ## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f             (space to end of previous tape file)
     ## _t_a_r _x_p_b_f _2_0 _/_d_e_v_/_r_m_t_1_2           (extract the utility source)
     (this takes about 30-60 minutes)






                        May 14, 1994





SMM:1-28                Installing and Operating 4.4BSD UNIX


     If  you are using 6250bpi tapes, the second reel of the
distribution is no longer needed; you should now  mount  the
third  reel  instead.   The installation procedure continues
from this point on the 8mm tape.
     The next tar file contains the sources for the contrib-
uted software.  It is extracted as follows:


     ## _c_d _/_u_s_r_/_s_r_c
     ## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f                                (space to end of previous tape file)
     (this should only be done on Exabyte distributions)
     ## _t_a_r _x_p_b_f _2_0 _/_d_e_v_/_r_m_t_1_2                              (extract the contributed software source)
     (this takes about 30-60 minutes)


     If  you  received  a  distribution on 8mm Exabyte tape,
there is one additional tape file on the  distribution  tape
that  has  not been installed to this point; it contains the
sources for X11R5 in _t_a_r(1) format.  As  distributed,  X11R5
should be placed in /usr/src/X11R5.


     ## _c_d _/_u_s_r_/_s_r_c
     ## _m_t _-_f _/_d_e_v_/_n_r_m_t_0 _f_s_f             (space to end of previous tape file)
     ## _t_a_r _x_p_b_f _2_0 _/_d_e_v_/_n_r_m_t_0           (extract the X11R5 source)
     (this takes about 30-60 minutes)


Many of the X11 utilities search using the path /usr/X11, so
be sure that you have a symbolic link  that  points  at  the
location of your X11 binaries (here, X11R5).
     Having now completed the extraction of the sources, you
may want to verify that your /usr/src filesystem is  consis-
tent.   To  do  so,  you  must  unmount it, and run _f_s_c_k(8);
assuming that you used sd0f you would proceed as follows:


     ## _c_d _/                 (change directory, back to the root)
     ## _u_m_o_u_n_t _/_u_s_r_/_s_r_c      (unmount /usr/src)
     ## _f_s_c_k _/_d_e_v_/_r_s_d_0_f


The output from _f_s_c_k should look something like:

     **** //ddeevv//rrssdd00ff
     **** LLaasstt MMoouunntteedd oonn //uussrr//ssrrcc
     **** PPhhaassee 11 -- CChheecckk BBlloocckkss aanndd SSiizzeess
     **** PPhhaassee 22 -- CChheecckk PPaatthhnnaammeess
     **** PPhhaassee 33 -- CChheecckk CCoonnnneeccttiivviittyy
     **** PPhhaassee 44 -- CChheecckk RReeffeerreennccee CCoouunnttss
     **** PPhhaassee 55 -- CChheecckk CCyyll ggrroouuppss
     2233000000 ffiilleess,, 226611000000 uusseedd,, 3399000000 ffrreeee ((22220000 ffrraaggss,, 44660000 bblloocckkss))





                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-29


     If there are inconsistencies in the filesystem, you may
be  prompted  to apply corrective action; see the _f_s_c_k(8) or
_F_s_c_k _- _T_h_e _U_N_I_X _F_i_l_e _S_y_s_t_e_m _C_h_e_c_k _P_r_o_g_r_a_m (SMM:3)  for  more
details.
     To  use the /usr/src filesystem, you should now remount
it with:

     ## _m_o_u_n_t _/_d_e_v_/_s_d_0_f _/_u_s_r_/_s_r_c

or if you have made an entry for it in  /etc/fstab  you  can
remount it with:

     ## _m_o_u_n_t _/_u_s_r_/_s_r_c


22..77..  AAddddiittiioonnaall ccoonnvveerrssiioonn iinnffoorrmmaattiioonn
     After  setting  up  the new 4.4BSD filesystems, you may
restore the user files that were saved on tape before begin-
ning  the  conversion.  Note that the 4.4BSD _r_e_s_t_o_r_e program
does its work on a mounted filesystem  using  normal  system
operations.    This  means  that  filesystem  dumps  may  be
restored even  if  the  characteristics  of  the  filesystem
changed.  To restore a dump tape for, say, the /a filesystem
something like the following would be used:

     ## _m_k_d_i_r _/_a
     ## _n_e_w_f_s _s_d_#_p
     ## _m_o_u_n_t _/_d_e_v_/_s_d_#_p _/_a
     ## _c_d _/_a
     ## _r_e_s_t_o_r_e _x

     If _t_a_r images were written instead of doing a dump, you
should be sure to use its `-p' option when reading the files
back.  No matter how you restore a filesystem,  be  sure  to
unmount it and and check its integrity with _f_s_c_k(8) when the
job is complete.

33..  UUppggrraaddiinngg aa 44..33BBSSDD ssyysstteemm
     This section describes the procedure  for  upgrading  a
4.3BSD  system to 4.4BSD.  This procedure may vary according
to the version of the system running before conversion.   If
you are converting from a System V system, some of this sec-
tion will still apply (in particular, the filesystem conver-
sion).   However, many of the system configuration files are
different, and the executable file  formats  are  completely
incompatible.
     In  particular  be  wary when using this information to
upgrade a 4.3BSD HP300 system.  There are at least four dif-
ferent versions of ``4.3BSD'' out there:
1)   HPBSD 1.x from Utah.
     This was the original version of 4.3BSD for HP300s from
     which the other variants (and 4.4BSD) are derived.   It
     is  largely a 4.3BSD system with Sun's NFS 3.0 filesys-
     tem  code  and   some   4.3BSD-Tahoe   features   (e.g.



                        May 14, 1994





SMM:1-30                Installing and Operating 4.4BSD UNIX


     networking code).  Since the filesystem code is 4.2/4.3
     vintage and the filesystem hierarchy is largely 4.3BSD,
     most of this section should apply.
2)   MORE/bsd from Mt. Xinu.
     This  is  a  4.3BSD-Tahoe vintage system with Sun's NFS
     4.0 filesystem code upgraded with Tahoe  UFS  features.
     The instructions for 4.3BSD-Tahoe should largely apply.
3)   4.3BSD-Reno from CSRG.
     At least one site bootstrapped HP300 support  from  the
     Reno  distribution.  The Reno filesystem code was some-
     where between 4.3BSD and 4.4BSD:  the  VFS  switch  had
     been   added   but  many  of  the  UFS  features  (e.g.
     ``inline''  symlinks)  were  missing.   The  filesystem
     hierarchy   reorganization   first   appeared  in  this
     release.  Be extremely careful following these instruc-
     tions  if you are upgrading from the Reno distribution.
4)   HPBSD 2.0 from Utah.
     As if things were not bad enough already, this  release
     has  the  4.4BSD filesystem and networking code as well
     as some utilities, but still has  a  4.3BSD  hierarchy.
     No   filesystem  conversions  are  necessary  for  this
     upgrade, but files will still need to be moved  around.

33..11..  IInnssttaallllaattiioonn oovveerrvviieeww
     If  you  are  running  4.3BSD,  upgrading  your  system
involves replacing your kernel  and  system  utilities.   In
general,  there are three possible ways to install a new BSD
distribution: (1) boot directly from the distribution  tape,
use it to load new binaries onto empty disks, and then merge
or restore any existing configuration files and filesystems;
(2)  use  an  existing 4.3BSD or later system to extract the
root and /usr filesystems from the distribution  tape,  boot
from the new system, then merge or restore existing configu-
ration files and filesystems; or  (3)  extract  the  sources
from  the distribution tape onto an existing system, and use
that system to cross-compile and install 4.4BSD.   For  this
release,  the  second  alternative is strongly advised, with
the third alternative reserved as a last  resort.   In  gen-
eral,  older binaries will continue to run under 4.4BSD, but
there are many exceptions that are on the critical path  for
getting  the  system running.  Ideally, the new system bina-
ries (root and /usr  filesystems)  should  be  installed  on
spare  disk  partitions,  then site-specific files should be
merged into them.  Once the  new  system  is  up  and  fully
merged,  the  previous  root  and  /usr  filesystems  can be
reused.  Other existing  filesystems  can  be  retained  and
used,  except  that  (as  usual)  the new _f_s_c_k should be run
before they are mounted.
     It is SSTTRROONNGGLLYY advised that you make full dumps of each
filesystem  before beginning, especially any that you intend
to modify in place during the merge.  It is  also  desirable
to  run filesystem checks of all filesystems to be converted
to 4.4BSD before shutting down.  This is an  excellent  time
to review your disk configuration for possible tuning of the



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-31


layout.  Most systems will need to provide a new  filesystem
for  system  use  mounted on /var (see below).  However, the
/tmp  filesystem  can  be  an  MFS   virtual-memory-resident
filesystem,  potentially freeing an existing disk partition.
(Additional swap space may be desirable as  a  consequence.)
See _m_o_u_n_t___m_f_s(8).
     The  recommended  installation  procedure  includes the
following steps.  The order of  these  steps  will  probably
vary according to local needs.
+o    Extract root and /usr filesystems from the distribution
     tapes.
+o    Extract kernel and/or user-level sources from the  dis-
     tribution tape if space permits.  This can serve as the
     backup documentation as needed.
+o    Configure and boot a kernel for the local system.  This
     can be delayed if the generic kernel from the distribu-
     tion supports enough hardware to proceed.
+o    Build a skeletal /var filesystem (see _m_t_r_e_e(8)).
+o    Merge site-dependent configuration files from /etc  and
     /usr/lib  into  the new /etc directory.  Note that many
     file formats and contents have changed; see section 3.4
     of this document.
+o    Copy   or   merge   files  from  /usr/adm,  /usr/spool,
     /usr/preserve, /usr/lib, and other locations into /var.
+o    Merge local macros, dictionaries, etc. into /usr/share.
+o    Merge and update local software to reflect  the  system
     changes.
+o    Take off the rest of the morning, you've earned it!
     Section  3.2 lists the files to be saved as part of the
conversion process.  Section  3.3  describes  the  bootstrap
process.   Section  3.4  discusses  the  merger of the saved
files back into the new system.  Section 3.5 gives an  over-
view  of  the major bug fixes and changes between 4.3BSD and
4.4BSD.  Section 3.6  provides  general  hints  on  possible
problems  to  be  aware  of  when  converting from 4.3BSD to
4.4BSD.

33..22..  FFiilleess ttoo ssaavvee
     The following list enumerates the standard set of files
you  will  want  to  save  and suggests directories in which
site-specific files  should  be  present.   This  list  will
likely  be  augmented with non-standard files you have added
to your system.  If you do not have enough space  to  create
parallel  filesystems,  you should create a _t_a_r image of the
following files before the new filesystems are created.  The
rest  of  this  subsection describes where theses files have
moved and how they have changed.

/.cshrc                  [+]    root csh startup script (moves to /root/.cshrc)
/.login                  [+]    root csh login script (moves to /root/.login)
/.profile                [+]    root sh startup script (moves to /root/.profile)
/.rhosts                 [+]    for trusted machines and users (moves to /root/.rhosts)
/etc/disktab             [++]   in case you changed disk partition sizes




                        May 14, 1994





SMM:1-32                Installing and Operating 4.4BSD UNIX


/etc/fstab                *     disk configuration data
/etc/ftpusers            [+]    for local additions
/etc/gettytab            [++]   getty database
/etc/group                *     group data base
/etc/hosts               [+]    for local host information
/etc/hosts.equiv         [+]    for local host equivalence information
/etc/hosts.lpd           [+]    printer access file
/etc/inetd.conf           *     Internet services configuration data
/etc/named*              [+]    named configuration files
/etc/netstart            [+]    network initialization
/etc/networks            [+]    for local network information
/etc/passwd               *     user data base
/etc/printcap             *     line printer database
/etc/protocols           [++]   in case you added any local protocols
/etc/rc                   *     for any local additions
/etc/rc.local             *     site specific system startup commands
/etc/remote              [+]    auto-dialer configuration
/etc/services            [++]   for local additions
/etc/shells              [++]   list of valid shells
/etc/syslog.conf          *     system logger configuration
/etc/securettys           *     merged into ttys
/etc/ttys                 *     terminal line configuration data
/etc/ttytype              *     merged into ttys
/etc/termcap             [++]   for any local entries that may have been added
/lib                     [++]   for any locally developed language processors
/usr/dict/*              [++]   for local additions to words and papers
/usr/include/*           [++]   for local additions
/usr/lib/aliases          *     mail forwarding data base (moves to /etc/aliases)
/usr/lib/crontab          *     cron daemon data base (moves to /etc/crontab)
/usr/lib/crontab.local    *     local cron daemon data base (moves to /etc/crontab.local)
/usr/lib/lib*.a          [+]    for local libraries
/usr/lib/mail.rc         [+]    system-wide mail(1) initialization (moves to /etc/mail.rc)
/usr/lib/sendmail.cf      *     sendmail configuration (moves to /etc/sendmail.cf)
/usr/lib/tmac/*          [++]   for locally developed troff/nroff macros (moves to /usr/share/tmac/*)
/usr/lib/uucp/*          [+]    for local uucp configuration files
/usr/man/manl             *     for manual pages for locally developed programs (moves to /usr/local/man)
/usr/spool/*             [+]    for current mail, news, uucp files, etc. (moves to /var/spool)
/usr/src/local           [+]    for source for locally developed programs
/sys/conf/HOST           [+]    configuration file for your machine (moves to /sys/<arch>/conf)
/sys/conf/files.HOST     [+]    list of special files in your kernel (moves to /sys/<arch>/conf)
/*/quotas                 *     filesystem quota files (moves to /*/quotas.user)


     [+]Files that can be used from 4.3BSD without change.
     [++]Files that need local changes merged into 4.4BSD files.
     *Files that require special work to merge and are discussed in section 3.4.


33..33..  IInnssttaalllliinngg 44..44BBSSDD
     The next step is to  build  a  working  4.4BSD  system.
This can be done by following the steps in section 2 of this
document for extracting the root and /usr  filesystems  from
the  distribution tape onto unused disk partitions.  For the
SPARC, the root filesystem dump on the tape  could  also  be



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-33


extracted  directly.   For the HP300 and DECstation, the raw
disk image can be copied into an unused partition  and  this
partition  can then be dumped to create an image that can be
restored.  The exact procedure chosen  will  depend  on  the
disk  configuration  and  the number of suitable disk parti-
tions that may  be  used.   It  is  also  desirable  to  run
filesystem  checks  of  all  filesystems  to be converted to
4.4BSD before shutting down.  In any case, this is an excel-
lent  time  to  review  your disk configuration for possible
tuning  of  the  layout.   Section  2.5  and  _c_o_n_f_i_g(8)  are
required reading.
The  filesystem  in 4.4BSD has been reorganized in an effort
to meet several goals:
1)   The root filesystem should be small.
2)   There should be a per-architecture  centrally-shareable
     read-only /usr filesystem.
3)   Variable per-machine directories should be concentrated
     below a single mount point named /var.
4)   Site-wide  machine  independent  shareable  text  files
     should  be  separated from architecture specific binary
     files and should be concentrated below a  single  mount
     point named /usr/share.
These goals are realized with the following general layouts.
The reorganized root filesystem has the  following  directo-
ries:

/etc     (config files)
/bin     (user binaries needed when single-user)
/sbin    (root binaries needed when single-user)
/local   (locally added binaries used only by this machine)
/tmp     (mount point for memory based filesystem)
/dev     (local devices)
/home    (mount point for AMD)
/var     (mount point for per-machine variable directories)
/usr     (mount point for multiuser binaries and files)

The  reorganized  /usr filesystem has the following directo-
ries:

/usr/bin       (user binaries)
/usr/contrib   (software contributed to 4.4BSD)
/usr/games     (binaries for games, score files in /var)
/usr/include   (standard include files)
/usr/lib       (lib*.a from old /usr/lib)
/usr/libdata   (databases from old /usr/lib)
/usr/libexec   (executables from old /usr/lib)
/usr/local     (locally added binaries used site-wide)
/usr/old       (deprecated binaries)
/usr/sbin      (root binaries)
/usr/share     (mount point for site-wide shared text)
/usr/src       (mount point for sources)

The reorganized  /usr/share  filesystem  has  the  following
directories:



                        May 14, 1994





SMM:1-34                Installing and Operating 4.4BSD UNIX


/usr/share/calendar     (various useful calendar files)
/usr/share/dict         (dictionaries)
/usr/share/doc          (4.4BSD manual sources)
/usr/share/games        (games text files)
/usr/share/groff_font   (groff font information)
/usr/share/man          (typeset manual pages)
/usr/share/misc         (dumping ground for random text files)
/usr/share/mk           (templates for 4.4BSD makefiles)
/usr/share/skel         (template user home directory files)
/usr/share/tmac         (various groff macro packages)
/usr/share/zoneinfo     (information on time zones)

The  reorganized  /var filesystem has the following directo-
ries:

/var/account        (accounting files, formerly /usr/adm)
/var/at             (_a_t(1) spooling area)
/var/backups        (backups of system files)
/var/crash          (crash dumps)
/var/db             (system-wide databases, e.g. tags)
/var/games          (score files)
/var/log            (log files)
/var/mail           (users mail)
/var/obj            (hierarchy to build /usr/src)
/var/preserve       (preserve area for vi)
/var/quotas         (directory to store quota files)
/var/run            (directory to store *.pid files)
/var/rwho           (rwho databases)
/var/spool/ftp      (home directory for anonymous ftp)
/var/spool/mqueue   (sendmail spooling directory)
/var/spool/news     (news spooling area)
/var/spool/output   (printer spooling area)
/var/spool/uucp     (uucp spooling area)
/var/tmp            (disk-based temporary directory)
/var/users          (root of per-machine user home directories)

     The 4.4BSD bootstrap routines pass the identity of  the
boot  device  through  to  the kernel.  The kernel then uses
that device as its root filesystem.  Thus, for  example,  if
you  boot  from  /dev/sd1a,  the kernel will use sd1a as its
root filesystem. If /dev/sd1b is configured as a swap parti-
tion,  it  will  be used as the initial swap area, otherwise
the normal primary swap area (/dev/sd0b) will be used.   The
4.4BSD  bootstrap is backward compatible with 4.3BSD, so you
can replace your old bootstrap if you use it  to  boot  your
first  4.4BSD  kernel.  However, the 4.3BSD bootstrap cannot
access 4.4BSD filesystems, so if you plan  to  convert  your
filesystems  to  4.4BSD,  you  must  install a new bootstrap
_b_e_f_o_r_e doing the conversion.  Note that SPARC  users  cannot
build  a 4.4BSD compatible version of the bootstrap, so must
_n_o_t convert their root filesystem to the new 4.4BSD  format.
     Once  you  have  extracted the 4.4BSD system and booted
from it, you will have to build a kernel customized for your
configuration.   If  you have any local device drivers, they



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-35


will have to be incorporated into the new kernel.  See  sec-
tion  4.1.3 and ``Building 4.3BSD UNIX Systems with Config''
(SMM:2).
     If converting from 4.3BSD, your old filesystems  should
be  converted.   If you've modified the partition sizes from
the original 4.3BSD ones, and  are  not  already  using  the
4.4BSD disk labels, you will have to modify the default disk
partition tables in the kernel.  Make  the  necessary  table
changes  and boot your custom kernel BBEEFFOORREE trying to access
any of your old filesystems!  After doing  this,  if  neces-
sary, the remaining filesystems may be converted in place by
running the 4.4BSD version of _f_s_c_k(8) on each filesystem and
allowing it to make the necessary corrections.  The new ver-
sion of _f_s_c_k is more strict about the  size  of  directories
than  the version supplied with 4.3BSD.  Thus the first time
that it is run on a 4.3BSD filesystem, it will produce  mes-
sages of the form:

     DDIIRREECCTTOORRYY ......:: LLEENNGGTTHH xx NNOOTT MMUULLTTIIPPLLEE OOFF 551122 ((AADDJJUUSSTTEEDD))

Length  ``xx'' will be the size of the directory; it will be
expanded to the next multiple of 512 bytes.   The  new  _f_s_c_k
will also set default _i_n_t_e_r_l_e_a_v_e and _n_p_s_e_c_t (number of phys-
ical sectors per track)  values  on  older  filesystems,  in
which  these fields were unused spares; this correction will
produce messages of the form:

     IIMMPPOOSSSSIIBBLLEE IINNTTEERRLLEEAAVVEE==00 IINN SSUUPPEERRBBLLOOCCKK ((SSEETT TTOO DDEEFFAAUULLTT))3
     IIMMPPOOSSSSIIBBLLEE NNPPSSEECCTT==00 IINN SSUUPPEERRBBLLOOCCKK ((SSEETT TTOO DDEEFFAAUULLTT))

Filesystems that have had their interleave and npsect values
set will be diagnosed by  the  old  _f_s_c_k  as  having  a  bad
superblock; the old _f_s_c_k will run only if given an alternate
superblock (_f_s_c_k _-_b_3_2), in which case it will re-zero  these
fields.   The 4.4BSD kernel will internally set these fields
to their defaults if fsck has not done so; again,  the  _-_b_3_2
option may be necessary for running the old _f_s_c_k.
     In  addition, 4.4BSD removes several limits on filesys-
tem sizes that were present in 4.3BSD.  The limited filesys-
tems  continue to work in 4.4BSD, but should be converted as
soon as it is convenient by  running  _f_s_c_k  with  the  _-_c  _2
option.  The sequence _f_s_c_k _-_p _-_c _2 will update them all, fix
the interleave and npsect fields, fix any  incorrect  direc-
tory  lengths,  expand  maximum  uid's and gid's to 32-bits,
place symbolic links less than 60 bytes  into  their  inode,
and  fill  in  directory  type  fields all at once.  The new
filesystem formats are incompatible with older systems.   If
you  wish to continue using these filesystems with the older
systems you should make only the  compatible  changes  using
-----------
  3 The defaults are to set _i_n_t_e_r_l_e_a_v_e  to  1  and
_n_p_s_e_c_t  to _n_s_e_c_t.  This is correct on most drives;
it affects  only  performance  (usually  virtually
unmeasurably).



                        May 14, 1994





SMM:1-36                Installing and Operating 4.4BSD UNIX


_f_s_c_k _-_c _1.

33..44..  MMeerrggiinngg yyoouurr ffiilleess ffrroomm 44..33BBSSDD iinnttoo 44..44BBSSDD
     When  your  system is booting reliably and you have the
4.4BSD root and /usr filesystems fully installed you will be
ready  to  continue  with  the  next  step in the conversion
process, merging your old files into the new system.
     If you saved the files on a _t_a_r tape, extract them into
a scratch directory, say /usr/convert:

     ## _m_k_d_i_r _/_u_s_r_/_c_o_n_v_e_r_t
     ## _c_d _/_u_s_r_/_c_o_n_v_e_r_t
     ## _t_a_r _x_p

     The data files marked in the previous table with a dag-
ger ([+]) may be used without change from the previous  sys-
tem.   Those  data  files marked with a double dagger ([++])
have syntax changes or substantial enhancements.  You should
start  with  the  4.4BSD version and carefully integrate any
local changes  into  the  new  file.   Usually  these  local
changes  can  be  incorporated without conflict into the new
file; some exceptions are noted  below.   The  files  marked
with  an  asterisk  (*) require particular attention and are
discussed below.
     As described in section 3.3, the most immediately obvi-
ous  change  in  4.4BSD  is the reorganization of the system
filesystems.  Users of certain recent vendor  releases  have
seen  this  general  organization, although 4.4BSD takes the
reorganization a bit further.  The directories most affected
are /etc, that now contains only system configuration files;
/var, a new filesystem containing per-system spool  and  log
files;  and /usr/share, that contains most of the text files
shareable across architectures  such  as  documentation  and
macros.  System administration programs formerly in /etc are
now found in /sbin and /usr/sbin.  Various programs and data
files formerly in /usr/lib are now found in /usr/libexec and
/usr/libdata, respectively.  Administrative  files  formerly
in  /usr/adm  are  in /var/account and, similarly, log files
are now in /var/log.  The directory /usr/ucb has been merged
into  /usr/bin, and the sources for programs in /usr/bin are
in /usr/src/usr.bin.  Other source directories parallel  the
destination   directories;  /usr/src/etc  has  been  greatly
expanded, and /usr/src/share is new.   The  source  for  the
manual  pages,  in general, are with the source code for the
applications they document.  Manual pages not closely corre-
sponding   to   an   application   program   are   found  in
/usr/src/share/man.  The  locations  of  all  man  pages  is
listed in /usr/src/share/man/man0/man[1-8].  The manual page
_h_i_e_r(7) has been updated  and  made  more  detailed;  it  is
included in the printed documentation.  You should review it
to familiarize yourself with the new layout.
     A new utility, _m_t_r_e_e(8), is provided to build and check
filesystem  hierarchies with the proper contents, owners and
permissions.   Scripts  are  provided  in  /etc/mtree   (and



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-37


/usr/src/etc/mtree) for the root, /usr and /var filesystems.
Once a filesystem has been made for /var, _m_t_r_e_e can be  used
to  create a directory hierarchy there or you can simply use
tar to extract the prototype from the  second  file  of  the
distribution tape.

33..44..11..  CChhaannggeess iinn tthhee //eettcc ddiirreeccttoorryy
     The  /etc  directory  now contains nearly all the host-
specific configuration files.  Note that some  file  formats
have changed, and those configuration files containing path-
names are nearly all affected by  the  reorganization.   See
the  examples provided in /etc (installed from /usr/src/etc)
as a guide.  The following table lists  some  of  the  local
configuration  files  whose  locations  and/or contents have
changed.

4.3BSD and Earlier     4.4BSD               Comments
-----------------------------------------------------------------------------
/etc/fstab             /etc/fstab           new format; see below
/etc/inetd.conf        /etc/inetd.conf      pathnames of executables changed
/etc/printcap          /etc/printcap        pathnames changed
/etc/syslog.conf       /etc/syslog.conf     pathnames of log files changed
/etc/ttys              /etc/ttys            pathnames of executables changed
/etc/passwd            /etc/master.passwd   new format; see below
/usr/lib/sendmail.cf   /etc/sendmail.cf     changed pathnames
/usr/lib/aliases       /etc/aliases         may contain changed pathnames
/etc/*.pid             /var/run/*.pid


New in 4.3BSD-Tahoe       4.4BSD                Comments
------------------------------------------------------------------------------------
/usr/games/dm.config      /etc/dm.conf          configuration for games (see _d_m(8))
/etc/zoneinfo/localtime   /etc/localtime        timezone configuration
/etc/zoneinfo             /usr/share/zoneinfo   timezone configuration


    New in 4.4BSD     Comments
--------------------------------------------------------------------
    /etc/aliases.db   database version of the aliases file
    /etc/amd-home     location database of home directories
    /etc/amd-vol      location database of exported filesystems
    /etc/changelist   /etc/security files to back up
    /etc/csh.cshrc    system-wide csh(1) initialization file
    /etc/csh.login    system-wide csh(1) login file
    /etc/csh.logout   system-wide csh(1) logout file
    /etc/disklabels   directory for saving disklabels
    /etc/exports      NFS list of export permissions
    /etc/ftpwelcome   message displayed for ftp users; see ftpd(8)
    /etc/kerberosIV   Kerberos directory; see below
    /etc/man.conf     lists directories searched by _m_a_n(1)
    /etc/mtree        directory for local mtree files; see mtree(8)
    /etc/netgroup     NFS group list used in /etc/exports
    /etc/pwd.db       non-secure hashed user data base file




                        May 14, 1994





SMM:1-38                Installing and Operating 4.4BSD UNIX


    /etc/spwd.db      secure hashed user data base file
    /etc/security     daily system security checker

     System security  changes  require  adding  several  new
``well-known''  groups  to  /etc/group.  The groups that are
needed by the system as distributed are:

name       number   purpose
------------------------------------------------------------------
wheel         0     users allowed superuser privilege
daemon        1     processes that need less than wheel privilege
kmem          2     read access to kernel memory
sys           3     access to kernel sources
tty           4     access to terminals
operator      5     read access to raw disks
bin           7     group for system binaries
news          8     group for news
wsrc          9     write access to sources
games        13     access to games
staff        20     system staff
guest        31     system guests
nobody       39     the least privileged group
utmp         45     access to utmp files
dialer      117     access to remote ports and dialers


Only users in the ``wheel'' group are  permitted  to  _s_u  to
``root''.    Most   programs   that  manage  directories  in
/var/spool now run set-group-id to ``daemon'' so that  users
cannot  directly  access the files in the spool directories.
The special files that access kernel memory,  /dev/kmem  and
/dev/mem,  are  made readable only by group ``kmem''.  Stan-
dard system programs that require this access are made  set-
group-id  to  that  group.  The group ``sys'' is intended to
control access to kernel sources, and other  sources  belong
to group ``wsrc.''  Rather than make user terminals writable
by all users, they are now placed in group ``tty'' and  made
only group writable.  Programs that should legitimately have
access to write on user terminals such as  _t_a_l_k_d  and  _w_r_i_t_e
now  run  set-group-id  to  ``tty''.  The ``operator'' group
controls access to disks.  By default, disks are readable by
group ``operator'',

so  that  programs  such  as  _d_u_m_p can access the filesystem
information without  being  set-user-id  to  ``root''.   The
_s_h_u_t_d_o_w_n(8) program is executable only by group operator and
is setuid to root so that members of group operator may shut
down the system without root access.
     The  ownership  and  modes  of  some  directories  have
changed.  The  _a_t  programs  now  run  set-user-id  ``root''
instead  of  ``daemon.''  Also, the uucp directory no longer
needs to be publicly writable, as _t_i_p reverts to  privileged
status to remove its lock files.  After copying your version
of /var/spool, you should do:



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-39


     ## _c_h_o_w_n _-_R _r_o_o_t _/_v_a_r_/_s_p_o_o_l_/_a_t
     ## _c_h_o_w_n _-_R _u_u_c_p_._d_a_e_m_o_n _/_v_a_r_/_s_p_o_o_l_/_u_u_c_p
     ## _c_h_m_o_d _-_R _o_-_w _/_v_a_r_/_s_p_o_o_l_/_u_u_c_p

     The format of the cron table,  /etc/crontab,  has  been
changed  to specify the user-id that should be used to run a
process.  The userid ``nobody''  is  frequently  useful  for
non-privileged  programs.   Local  changes  are now put in a
separate file, /etc/crontab.local.
     Some of the commands previously in  /etc/rc.local  have
been moved to /etc/rc; several new functions are now handled
by /etc/rc, /etc/netstart  and  /etc/rc.local.   You  should
look  closely  at  the  prototype version of these files and
read the manual pages  for  the  commands  contained  in  it
before  trying to merge your local copy.  Note in particular
that _i_f_c_o_n_f_i_g has had many changes, and that host names  are
now  fully  specified  as  domain-style  names  (e.g.,  van-
gogh.CS.Berkeley.EDU) for the benefit of the name server.
     Some of the commands previously in /etc/daily have been
moved  to /etc/security, and several new functions have been
added to /etc/security to do nightly security checks on  the
system.   The  script  /etc/daily  runs  /etc/security  each
night, and mails the output to the super-user.  Some of  the
checks done by /etc/security are:

     +o Syntax errors in the password and group files.
     +o Duplicate user and group names and id's.
     +o Dangerous search paths and umask values for the superuser.
     +o Dangerous values in various initialization files.
     +o Dangerous .rhosts files.
     +o Dangerous directory and file ownership or permissions.
     +o Globally exported filesystems.
     +o Dangerous owners or permissions for special devices.

In  addition,  it  reports  any changes to setuid and setgid
files, special devices,  or  the  files  in  /etc/changelist
since  the  last run of /etc/security.  Backup copies of the
files are saved in /var/backups.  Finally, the system  bina-
ries are checksummed and their permissions validated against
the _m_t_r_e_e(8) specifications in /etc/mtree.
     The C-library and system binaries on  the  distribution
tape  are  compiled  with  new versions of _g_e_t_h_o_s_t_b_y_n_a_m_e and
_g_e_t_h_o_s_t_b_y_a_d_d_r that use the name server,  _n_a_m_e_d(8).   If  you
have  only  a small network and are not connected to a large
network, you can use the distributed library routines  with-
out  any  problems; they use a linear scan of the host table
/etc/hosts if the name server is not running.  If you are on
the  Internet or have a large local network, it is recommend
that you set up and use the name server.   For  instructions
on how to set up the necessary configuration files, refer to
``Name Server Operations Guide for BIND'' (SMM:10).  Several
programs  rely  on  the host name returned by _g_e_t_h_o_s_t_n_a_m_e to
determine the local domain name.




                        May 14, 1994





SMM:1-40                Installing and Operating 4.4BSD UNIX


     If you are using the name server, your _s_e_n_d_m_a_i_l config-
uration  file will need some updates to accommodate it.  See
the ``Sendmail Installation and  Operation  Guide''  (SMM:8)
and    the    sample   _s_e_n_d_m_a_i_l   configuration   files   in
/usr/src/usr.sbin/sendmail/cf.     The     aliases     file,
/etc/aliases has also been changed to add certain well-known
addresses.

33..44..22..  SShhaaddooww ppaasssswwoorrdd ffiilleess
     The password file format  adds  change  and  expiration
fields and its location has changed to protect the encrypted
passwords stored there.  The actual  password  file  is  now
stored in /etc/master.passwd.  The hashed dbm password files
do not contain encrypted passwords,  but  contain  the  file
offset  to the entry with the password in /etc/master.passwd
(that is readable only by root).  Thus, the  _g_e_t_p_w_n_a_m()  and
_g_e_t_p_w_u_i_d()  functions  will  no  longer  return an encrypted
password string to non-root callers.   An  old-style  passwd
file   is   created   in  /etc/passwd  by  the  _v_i_p_w(8)  and
_p_w_d___m_k_d_b(8) programs.  See also _p_a_s_s_w_d(5).
     Several new users have also been added to the group  of
``well-known'' users in /etc/passwd.  The current list is:


     name       number
     ------------------
     root         0
     daemon       1
     operator     2
     bin          3
     games        7
     uucp         66
     nobody     32767


The ``daemon'' user is used for daemon processes that do not
need root privileges.  The ``operator'' user-id is  used  as
an  account for dumpers so that they can log in without hav-
ing the root password.  By placing them in the  ``operator''
group,  they can get read access to the disks.  The ``uucp''
login has existed long before 4.4BSD, and is noted here just
to  provide a common user-id.  The password entry ``nobody''
has been added to specify the  user  with  least  privilege.
The  ``games'' user is a pseudo-user that controls access to
game programs.
     After installing your updated password file,  you  must
run  _p_w_d___m_k_d_b(8) to create the password database.  Note that
_p_w_d___m_k_d_b(8) is run whenever _v_i_p_w(8) is run.

33..44..33..  TThhee //vvaarr ffiilleessyysstteemm
     The spooling directories saved on tape may be  restored
in  their  eventual resting places without too much concern.
Be sure to use the `-p' option to _t_a_r(1) so that  files  are
recreated  with the same file modes.  The following commands



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-41


provide a guide for copying spool  and  log  files  from  an
existing  system  into  a new /var filesystem.  At least the
following directories should already exist on /var:  output,
log, backups and db.

     SRC=/oldroot/usr

     cd $SRC; tar cf - msgs preserve | (cd /var && tar xpf -)


     # copy $SRC/spool to /var
     cd $SRC/spool
     tar cf - at mail rwho | (cd /var && tar xpf -)
     tar cf - ftp mqueue news uucp uucppublic | \
          (cd /var/spool && tar xpf -)


     # everything else in spool is probably a printer area
     mkdir .save
     mv at ftp mail mqueue rwho uucp uucppublic .save
     tar cf - * | (cd /var/spool/output && tar xpf -)
     mv .save/* .
     rmdir .save


     cd /var/spool/mqueue
     mv syslog.7 /var/log/maillog.7
     mv syslog.6 /var/log/maillog.6
     mv syslog.5 /var/log/maillog.5
     mv syslog.4 /var/log/maillog.4
     mv syslog.3 /var/log/maillog.3
     mv syslog.2 /var/log/maillog.2
     mv syslog.1 /var/log/maillog.1
     mv syslog.0 /var/log/maillog.0
     mv syslog /var/log/maillog


     # move $SRC/adm to /var
     cd $SRC/adm
     tar cf - . | (cd /var/account && tar  xpf -)
     cd /var/account
     rm -f msgbuf
     mv messages messages.[0-9] ../log
     mv wtmp wtmp.[0-9] ../log
     mv lastlog ../log


33..55..  BBuugg ffiixxeess aanndd cchhaannggeess bbeettwweeeenn 44..33BBSSDD aanndd 44..44BBSSDD
     The  major  new  facilities  available  in  the  4.4BSD
release  are  a  new  virtual memory system, the addition of
ISO/OSI networking support, a new virtual filesystem  inter-
face   supporting   filesystem  stacking,  a  freely  redis-
tributable implementation of NFS, a log-structured  filesys-
tem,  enhancement  of the local filesystems to support files



                        May 14, 1994





SMM:1-42                Installing and Operating 4.4BSD UNIX


and filesystems that are up to 2^63 bytes in size,  enhanced
security  and  system management support, and the conversion
to and addition of the IEEE Std1003.1 (``POSIX'') facilities
and  many  of  the  IEEE Std1003.2 facilities.  In addition,
many new utilities  and  additions  to  the  C  library  are
present  as  well.  The kernel sources have been reorganized
to collect all machine-dependent files for each architecture
under  one  directory,  and  most of the machine-independent
code is now free of code conditional on  specific  machines.
The  user  structure and process structure have been reorga-
nized to eliminate the statically-mapped user structure  and
to  make most of the process resources shareable by multiple
processes.  The system and include files have been converted
to  be compatible with ANSI C, including function prototypes
for most of the  exported  functions.   There  are  numerous
other changes throughout the system.

33..55..11..  CChhaannggeess ttoo tthhee kkeerrnneell
     This release includes several important structural ker-
nel changes.  The kernel uses a  new  internal  system  call
convention;  the  use  of  global  (``u-dot'') variables for
parameters and error returns has been eliminated, and inter-
rupted  system  calls no longer abort using non-local goto's
(longjmp's).  A new sleep interface  separates  signal  han-
dling  from  scheduling  priority,  returning characteristic
errors to abort or restart the current  system  call.   This
sleep  call  also  passes  a  string  describing the process
state, that is used by the ps(1)  program.   The  old  sleep
interface  can  be  used  only for non-interruptible sleeps.
The sleep interface (_t_s_l_e_e_p) can be used  at  any  priority,
but  is  only interruptible if the PCATCH flag is set.  When
interrupted, _t_s_l_e_e_p returns EINTR or ERESTART.
     Many data structures that  were  previously  statically
allocated  are  now allocated dynamically.  These structures
include mount entries, file entries, user open file descrip-
tors,  the process entries, the vnode table, the name cache,
and the quota structures.
     To protect against indiscriminate reading or writing of
kernel  memory,  all writing and most reading of kernel data
structures must be done using a  new  ``sysctl''  interface.
The  information  to  be  accessed  is  described through an
extensible ``Management Information Base'' (MIB) style name,
described  as  a  dotted  set of components.  A new utility,
_s_y_s_c_t_l(8), retrieves kernel state and allows processes  with
appropriate privilege to set kernel state.

33..55..22..  SSeeccuurriittyy
     The kernel runs with four different levels of security.
Any superuser process can raise the security level, but only
_i_n_i_t()(8) can lower it.  Security levels are defined as fol-
lows:
-1   Permanently insecure mode - always run system in  level
     0 mode.




                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-43


  0  Insecure  mode - immutable and append-only flags may be
     turned off.  All devices may be read or written subject
     to their permissions.
  1  Secure  mode  - immutable and append-only flags may not
     be cleared; disks for  mounted  filesystems,  /dev/mem,
     and /dev/kmem are read-only.
  2  Highly  secure  mode  - same as secure mode, plus disks
     are always read-only  whether  mounted  or  not.   This
     level  precludes tampering with filesystems by unmount-
     ing them, but also inhibits running _n_e_w_f_s(8) while  the
     system is multi-user.  See _c_h_f_l_a_g_s(1) and the -oo option
     to _l_s(1) for information on setting and displaying  the
     immutable and append-only flags.
     Normally,  the system runs in level 0 mode while single
user and in level 1 mode while multiuser.  If  the  level  2
mode  is  desired  while running multiuser, it can be set in
the startup  script  /etc/rc  using  _s_y_s_c_t_l(1).   If  it  is
desired  to  run the system in level 0 mode while multiuser,
the administrator must build  a  kernel  with  the  variable
securelevel      in      the      kernel     source     file
/sys/kern/kern_sysctl.c initialized to -1.

33..55..22..11..  VViirrttuuaall mmeemmoorryy cchhaannggeess
     The new virtual memory implementation is  derived  from
the  Mach operating system developed at Carnegie-Mellon, and
was ported to the BSD kernel at the University of Utah.   It
is  based  on  the  2.0 release of Mach (with some bug fixes
from the 2.5 and 3.0  releases)  and  retains  many  of  its
essential  features  such  as  the separation of the machine
dependent and independent layers (the  ``pmap''  interface),
efficient  memory  utilization using copy-on-write and other
lazy-evaluation techniques, and support  for  large,  sparse
address  spaces.  It does not include the ``external pager''
interface instead using a primitive  internal  pager  inter-
face.   The  Mach  virtual  memory system call interface has
been replaced with the ``mmap''-based interface described in
the ``Berkeley Software Architecture Manual'' (see UNIX Pro-
grammer's  Manual,  Supplementary  Documents,  PSD:5).   The
interface  is  similar  to the interfaces shipped by several
commercial vendors such as Sun,  USL,  and  Convex  Computer
Corp.   The  integration  of the new virtual memory is func-
tionally complete, but still has serious  performance  prob-
lems  under  heavy  memory load.  The internal kernel inter-
faces have not yet been completed and the  memory  pool  and
buffer cache have not been merged.  Some additional caveats:
+o    Since the code is based on the  2.0  release  of  Mach,
     bugs  and  misfeatures of the BSD version should not be
     considered short-comings of the  current  Mach  virtual
     memory system.
+o    Because  of  the  disjoint virtual memory (page) and IO
     (buffer) caches, it is possible to see  inconsistencies
     if using both the mmap and read/write interfaces on the
     same file simultaneously.




                        May 14, 1994





SMM:1-44                Installing and Operating 4.4BSD UNIX


+o    Swap space is allocated on-demand rather than up  front
     and  no allocation checks are performed so it is possi-
     ble to over-commit memory and eventually deadlock.
+o    The semantics of the _v_f_o_r_k(2) system call are  slightly
     different.   The  synchronization  between  parent  and
     child is preserved, but the memory  sharing  aspect  is
     not.   In  practice  this  has been enough for backward
     compatibility, but newer code should just use  _f_o_r_k(2).

33..55..22..22..  NNeettwwoorrkkiinngg aaddddiittiioonnss aanndd cchhaannggeess
     The ISO/OSI Networking consists of a kernel implementa-
tion of transport class 4 (TP-4), connectionless  networking
protocol  (CLNP),  and 802.3-based link-level support (hard-
ware-compatible  with  Ethernet4).   We also include support
for ISO Connection-Oriented  Network  Service,  X.25,  TP-0.
The session and presentation layers are provided outside the
kernel using the ISO  Development  Environment  by  Marshall
Rose,  that  is  available  via  anonymous  FTP  (but is not
included on the distribution tape).  Included in this devel-
opment  environment are file transfer and management (FTAM),
virtual terminals (VT), a directory services  implementation
(X.500), and miscellaneous other utilities.
     Kernel  support  for  the  ISO OSI protocols is enabled
with the ISO option in the kernel configuration  file.   The
_i_s_o(4)  manual  page describes the protocols and addressing;
see also _c_l_n_p(4), _t_p(4) and _c_l_t_p(4).  The OSI equivalent  to
ARP  is ESIS (End System to Intermediate System Routing Pro-
tocol); running this protocol is mandatory, however one  can
manually  add translations for machines that do not partici-
pate by use of the _r_o_u_t_e(8) command.  Additional information
is provided in the manual page describing _e_s_i_s(4).
     The  command  _r_o_u_t_e(8) has a new syntax and several new
capabilities: it can install routes with a specified  desti-
nation  and  mask, and can change route characteristics such
as hop count, packet size and window size.
     Several important enhancements have been added  to  the
TCP/IP  protocols including TCP header prediction and serial
line IP (SLIP) with header compression.  The routing  imple-
mentation  has been completely rewritten to use a hierarchi-
cal routing tree with a mask per route to support the  arbi-
trary  levels  of  routing  found in the ISO protocols.  The
routing table also stores and caches  route  characteristics
to  speed  the  adaptation  of the throughput and congestion
avoidance algorithms.
     The format of the  _s_o_c_k_a_d_d_r  structure  (the  structure
used  to  describe a generic network address with an address
family and family-specific data) has changed  from  previous
releases,  as  have  the address family-specific versions of
this structure.  The _s_a___f_a_m_i_l_y family field has  been  split
into  a  length,  sa_len,  and  a family, sa_family.  System
calls that pass a _s_o_c_k_a_d_d_r structure into the  kernel  (e.g.
-----------
  4 Ethernet is a trademark of the Xerox  Corpora-
tion.



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-45


_s_e_n_d_t_o() and _c_o_n_n_e_c_t()) have a separate parameter that spec-
ifies the _s_o_c_k_a_d_d_r length, and thus it is not  necessary  to
fill  in  the  _s_a___l_e_n  field for those system calls.  System
calls that pass a _s_o_c_k_a_d_d_r structure back  from  the  kernel
(e.g.  _r_e_c_v_f_r_o_m() and _a_c_c_e_p_t()) receive a completely filled-
in _s_o_c_k_a_d_d_r structure,  thus  the  length  field  is  valid.
Because  this  would  not  work  for  old  binaries, the new
library uses a different system  call  number.   Thus,  most
networking  programs  compiled under 4.4BSD are incompatible
with older systems.
     Although this change is mostly source and  binary  com-
patible with old programs, there are three exceptions.  Pro-
grams with statically initialized _s_o_c_k_a_d_d_r structures  (usu-
ally  the  Internet form, a _s_o_c_k_a_d_d_r___i_n) are not compatible.
Generally, such programs should be changed to  fill  in  the
structure  at  run  time, as C allows no way to initialize a
structure without assuming the order and number  of  fields.
Also,  programs  with  use  structures to describe a network
packet format that contain embedded _s_o_c_k_a_d_d_r structures also
require  change;  a  definition of an _o_s_o_c_k_a_d_d_r structure is
provided for this purpose.  Finally, programs that  use  the
SIOCGIFCONF  ioctl  to  get  a  complete  list  of interface
addresses need to check  the  _s_a___l_e_n  field  when  iterating
through  the  array  of  addresses  returned, as not all the
structures returned have the same length (this  variance  in
length  is  nearly  guaranteed by the presence of link-layer
address structures).


33..55..22..33..  AAddddiittiioonnss aanndd cchhaannggeess ttoo ffiilleessyysstteemmss
     The 4.4BSD distribution contains most of the interfaces
specified  in  the IEEE Std1003.1 system interface standard.
Filesystem additions include  IEEE  Std1003.1  FIFOs,  byte-
range file locking, and saved user and group identifiers.
     A  new  virtual  filesystem interface has been added to
the kernel to support multiple filesystems.   In  comparison
with  other  interfaces,  the  Berkeley  interface  has been
structured for more efficient support  of  filesystems  that
maintain  state  (such as the local filesystem).  The inter-
face has been extended with support for  stackable  filesys-
tems  done  at UCLA.  These extensions allow for filesystems
to be layered on top of each other and allow new vnode oper-
ations  to  be  added  without requiring changes to existing
filesystem implementations.  For example, the umap  filesys-
tem  (see  _m_o_u_n_t___u_m_a_p(8))  is used to mount a sub-tree of an
existing filesystem that uses a different set  of  uids  and
gids  than  the  local  system.   Such a filesystem could be
mounted from a remote site via NFS or it could be a filesys-
tem  on  removable  media brought from some foreign location
that uses a different password file.
     Other new filesystems that may be stacked  include  the
loopback  filesystem  _m_o_u_n_t___l_o_f_s(8),  the  kernel filesystem
_m_o_u_n_t___k_e_r_n_f_s(8), and the portal filesystem  _m_o_u_n_t___p_o_r_t_a_l(8).




                        May 14, 1994





SMM:1-46                Installing and Operating 4.4BSD UNIX


     The  buffer  cache  in the kernel is now organized as a
file block cache rather than a device  block  cache.   As  a
consequence,  cached  blocks from a file and from the corre-
sponding block device would no longer  be  kept  consistent.
The  block  device  thus  has little remaining value.  Three
changes have been made for these reasons:
1)   block devices may not be opened while they are mounted,
     and may not be mounted while open, so that the two ver-
     sions of cached file blocks cannot be created,
2)   filesystem checks of the root now use the raw device to
     access the root filesystem, and
3)   the  root  filesystem is initially mounted read-only so
     that nothing can be written  back  to  disk  during  or
     after change to the raw filesystem by _f_s_c_k.
The  root  filesystem  may be made writable while in single-
user mode with the command:

     mount -uw /

The mount command has an option to update  the  flags  on  a
mounted  filesystem,  including  the  ability  to  upgrade a
filesystem from read-only to read-write or downgrade it from
read-write to read-only.
     In  addition  to the local ``fast filesystem'', we have
added an implementation of the network filesystem (NFS) that
fully  interoperates  with  the  NFS  shipped by Sun and its
licensees.  Because our NFS implementation  was  implemented
by  Rick  Macklem of the University of Guelph using only the
publicly available NFS specification, it does not require  a
license  from  Sun  to  use  in  source  or binary form.  By
default it runs over UDP to be compatible with Sun's  imple-
mentation.   However,  it  can  be configured on a per-mount
basis to run over TCP.  Using  TCP  allows  it  to  be  used
quickly  and efficiently through gateways and over long-haul
networks.  Using an extended protocol, it supports Leases to
allow  a limited callback mechanism that greatly reduces the
network traffic  necessary  to  maintain  cache  consistency
between  the server and its clients.  Its use will be famil-
iar to users of other implementations of NFS.  See the  man-
ual  pages  _m_o_u_n_t(8),  _m_o_u_n_t_d(8), _f_s_t_a_b(5), _e_x_p_o_r_t_s(5), _n_e_t_-
_g_r_o_u_p(5), _n_f_s_d(8), _n_f_s_i_o_d(8), and _n_f_s_s_v_c(8).  and the  docu-
ment  ``The  4.4BSD NFS Implementation'' (SMM:6) for further
information.  The format of /etc/fstab has changed from pre-
vious  BSD  releases  to  a  blank-separated format to allow
colons in pathnames.
     A new local filesystem, the  log-structured  filesystem
(LFS), has been added to the system.  It provides near disk-
speed output and fast crash recovery.  This work  is  based,
in  part, on the LFS filesystem created for the Sprite oper-
ating system at Berkeley.  While the  kernel  implementation
is  almost  complete,  only some of the utilities to support
the filesystem have been written, so we do not recommend  it
for   production   use.   See  _n_e_w_l_f_s(8),  _m_o_u_n_t___l_f_s(8)  and
_l_f_s___c_l_e_a_n_e_r_d(8)  for  more  information.   For  a   in-depth



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-47


description of the implementation and performance character-
istics of log-structured filesystems in  general,  and  this
one  in particular, see Dr. Margo Seltzer's doctoral thesis,
available from the University of California Computer Science
Department.
     We  have also added a memory-based filesystem that runs
in pageable memory,  allowing  large  temporary  filesystems
without requiring dedicated physical memory.
     The  local  ``fast filesystem'' has been enhanced to do
clustering that allows large pieces of files to be allocated
contiguously   resulting  in  near  doubling  of  filesystem
throughput.  The filesystem interface has been  extended  to
allow  files  and filesystems to grow to 2^63 bytes in size.
The quota system has been rewritten to support both user and
group  quotas (simultaneously if desired).  Quota expiration
is based on time rather than the previous metric  of  number
of  logins over quota.  This change makes quotas more useful
on fileservers onto which users seldom login.
     The system security has been greatly  enhanced  by  the
addition  of  additional file flags that permit a file to be
marked as immutable or append only.  Once set,  these  flags
can  only  be  cleared  by the super-user when the system is
running in insecure mode (normally, single-user).  In  addi-
tion  to the immutable and append-only flags, the filesystem
supports a new user-settable flag ``nodump''.   (File  flags
are  set using the _c_h_f_l_a_g_s(1) utility.)  When set on a file,
_d_u_m_p(8) will omit the  file  from  incremental  backups  but
retain them on full backups.  See the ``-h'' flag to _d_u_m_p(8)
for details on how to change this default.   The  ``nodump''
flag  is  usually set on core dumps, system crash dumps, and
object files generated by the compiler.  Note that the  flag
is not preserved when files are copied so that installing an
object file will cause it to be preserved.
     The filesystem format used in 4.4BSD has several  addi-
tions.   Directory entries have an additional field, d_type,
that identifies the type of the entry (normally found in the
st_mode field of the stat structure).  This field is partic-
ularly useful for identifying directories without  the  need
to use _s_t_a_t(2).
     Short  (less  than  sixty  byte) symbolic links are now
stored in the inode itself rather than in  a  separate  data
block.   This  saves disk space and makes access of symbolic
links faster.  Short symbolic links are not given a  special
type,  so  a user-level application is unaware of their spe-
cial treatment.  Unlike pre-4.4BSD systems,  symbolic  links
do  not  have  an  owner,  group,  access  mode, times, etc.
Instead, these attributes are taken from the directory  that
contains  the  link.   The  only attributes returned from an
_l_s_t_a_t(2) that refer to the symbolic link itself are the file
type (S_IFLNK), size, blocks, and link count (always 1).
     An  implementation  of an auto-mounter daemon, _a_m_d, was
contributed by Jan-Simon Pendry of the Imperial  College  of
Science,  Technology  &  Medicine.  See the document ``AMD -
The 4.4BSD Automounter'' (SMM:13) for further information.



                        May 14, 1994





SMM:1-48                Installing and Operating 4.4BSD UNIX


     The directory /dev/fd contains special files 0  through
63  that,  when  opened,  duplicate  the  corresponding file
descriptor.    The   names   /dev/stdin,   /dev/stdout   and
/dev/stderr refer to file descriptors 0, 1 and 2.  See _f_d(4)
and _m_o_u_n_t___f_d_e_s_c(8) for more information.

33..55..22..44..  PPOOSSIIXX tteerrmmiinnaall ddrriivveerr cchhaannggeess
     The 4.4BSD system uses the IEEE P1003.1 (POSIX.1)  ter-
minal interface rather than the previous BSD terminal inter-
face.  The terminal driver is similar to the System V termi-
nal  driver with the addition of the necessary extensions to
get the functionality previously  available  in  the  4.3BSD
terminal  driver.   Both the old _i_o_c_t_l calls and old options
to _s_t_t_y(1) are emulated.  This emulation is expected  to  be
unavailable  in  many vendors releases, so conversion to the
new interface is encouraged.
     4.4BSD also adds the IEEE Std1003.1 job control  inter-
face,  that  is similar to the 4.3BSD job control interface,
but adds a security model that was missing in the 4.3BSD job
control  implementation.   A new system call, _s_e_t_s_i_d(), cre-
ates a job-control session consisting of  a  single  process
group  with  one  member, the caller, that becomes a session
leader.  Only a session leader  may  acquire  a  controlling
terminal.   This  is done explicitly via a TIOCSCTTY _i_o_c_t_l()
call, not implicitly by an _o_p_e_n() call.  The call  fails  if
the  terminal is in use.  Programs that allocate controlling
terminals (or pseudo-terminals) require change  to  work  in
this  environment.   The  versions  of _x_t_e_r_m provided in the
X11R5 release includes the necessary changes.   New  library
routines  are  available  for  allocating  and  initializing
pseudo-terminals and other terminals as  controlling  termi-
nal;  see  /usr/src/lib/libutil/pty.c and /usr/src/lib/libu-
til/login_tty.c.
     The POSIX job control  model  formalizes  the  previous
conventions  used  in  setting up a process group.  Unfortu-
nately, this requires that changes  be  made  in  a  defined
order  and with some synchronization that were not necessary
in the past.  Older job control shells (csh, ksh) will  gen-
erally not operate correctly with the new system.
     Most  of  the other kernel interfaces have been changed
to correspond with the POSIX.1 interface, although that work
is not complete.  See the relevant manual pages and the IEEE
POSIX standard.


33..55..22..55..  NNaattiivvee ooppeerraattiinngg ssyysstteemm ccoommppaattiibbiilliittyy
     Both the HP300 and SPARC ports feature the  ability  to
run binaries built for the native operating system (HP-UX or
SunOS) by emulating their system calls.  Building  an  HP300
kernel  with  the  HPUXCOMPAT  and COMPAT_OHPUX options or a
SPARC kernel with the COMPAT_SUNOS option will  enable  this
feature (on by default in the generic kernel provided in the
root filesystem image).  Though this native operating system
compatibility  was  provided by the developers as needed for



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-49


their purposes and is by no means complete, it  is  complete
enough  to  run  several  non-trivial applications including
those that require HP-UX or  SunOS  shared  libraries.   For
example,  the vendor supplied X11 server and windowing envi-
ronment can be used on both the HP300 and SPARC.
     It is important to remember that merely copying over  a
native  binary  and  executing  it (or executing it directly
across NFS) does not imply that it will run.   All  but  the
most trivial of applications are likely to require access to
auxiliary  files  that  do  not  exist  under  4.4BSD  (e.g.
/etc/ld.so.cache)  or have a slightly different format (e.g.
/etc/passwd).  However, by using  system  call  tracing  and
through  creative  use  of  symlinks,  many  problems can be
tracked down and corrected.
     The DECstation port also has code for ULTRIX  emulation
(kernel  option  ULTRIXCOMPAT, not compiled into the generic
kernel) but it was used primarily for  initially  bootstrap-
ping the port and has not been used since.  Hence, some work
may be required to make it generally useful.

33..55..33..  CChhaannggeess ttoo tthhee uuttiilliittiieess
     We have been tracking  the  IEEE  Std1003.2  shell  and
utility  work  and  have  included prototypes of many of the
proposed utilities based on draft 12 of  the  POSIX.2  Shell
and  Utilities  document.   Because  most of the traditional
utilities have been replaced with implementations conformant
to  the POSIX standards, you should realize that the utility
software may not be as stable, reliable or  well  documented
as  in traditional Berkeley releases.  In particular, almost
the entire manual suite has been rewritten  to  reflect  the
POSIX  defined interfaces, and in some instances it does not
correctly reflect the current state of the software.  It  is
also  worth noting that, in rewriting this software, we have
generally  been  rewarded   with   significant   performance
improvements.   Most  of the libraries and header files have
been converted to be compliant with  ANSI  C.   The  shipped
compiler  (gcc) is a superset of ANSI C, but supports tradi-
tional C as a command-line option.  The system libraries and
utilities all compile with either ANSI or traditional C.

33..55..33..11..  MMaakkee aanndd MMaakkeeffiilleess
     This  release uses a completely new version of the _m_a_k_e
program derived from the  _p_m_a_k_e  program  developed  by  the
Sprite project at Berkeley.  It supports existing makefiles,
although certain incorrect makefiles may  fail.   The  make-
files  for  the 4.4BSD sources make extensive use of the new
facilities, especially conditionals and file inclusion,  and
are thus completely incompatible with older versions of _m_a_k_e
(but nearly all the makefiles are now trivial!).  The  stan-
dard  include files for _m_a_k_e are in /usr/share/mk.  There is
a bsd.README file in /usr/src/share/mk.
     Another global change supported  by  the  new  _m_a_k_e  is
designed  to allow multiple architectures to share a copy of
the sources.  If a subdirectory named obj is present in  the



                        May 14, 1994





SMM:1-50                Installing and Operating 4.4BSD UNIX


current  directory,  _m_a_k_e  descends  into that directory and
creates all object and other files there.  We  use  this  by
building  a  directory  hierarchy in /var/obj that parallels
/usr/src.  We then create the obj subdirectories in /usr/src
as  symbolic  links  to  the  corresponding  directories  in
/var/obj.  (This step  is  automated.   The  command  ``make
obj''  in  /usr/src  builds  both  the local symlink and the
shadow directory, using /usr/obj, that  may  be  a  symbolic
link,  as  the root of the shadow tree.  The use of /usr/obj
is for historic reasons only, and the system make configura-
tion files in /usr/share/mk can trivially be modified to use
/var/obj instead.)  We have one /var/obj  hierarchy  on  the
local  system,  and  another  on each system that shares the
source filesystem.  All the sources in /usr/src  except  for
/usr/src/contrib and portions of /usr/src/old have been con-
verted to use the new  make  and  obj  subdirectories;  this
change  allows  compilation  for multiple architectures from
the same source tree (that may be mounted read-only).

33..55..33..22..  KKeerrbbeerrooss
     The Kerberos authentication server from MIT (version 4)
is included in this release.  See _k_e_r_b_e_r_o_s(1) for a general,
if  MIT-specific,  introduction.   If  it   is   configured,
_l_o_g_i_n(1),  _p_a_s_s_w_d(1), _r_l_o_g_i_n(1) and _r_s_h(1) will all begin to
use  it  automatically.   The  file   /etc/kerberosIV/README
describes  the  configuration.   Each  system needs the file
/etc/kerberosIV/krb.conf to set its realm and local servers,
and  a  private  key  stored  in /etc/kerberosIV/srvtab (see
_e_x_t___s_r_v_t_a_b(8)).  The Kerberos server should be set up  on  a
single,  physically secure, server machine.  Users and hosts
may  be  added  to  the  server   database   manually   with
_k_d_b___e_d_i_t(8), or users on authorized hosts can add themselves
and  a  Kerberos  password  after  verification   of   their
``local''  (passwd-file) password using the _r_e_g_i_s_t_e_r(1) pro-
gram.
     Note that  by  default  the  password-changing  program
_p_a_s_s_w_d(1)  changes  the  Kerberos password, that must exist.
The -l option to _p_a_s_s_w_d(1) changes the ``local'' password if
one exists.
     Note  that Version 5 of Kerberos will be released soon;
Version 4 should probably be replaced at that time.

33..55..33..33..  TTiimmeezzoonnee ssuuppppoorrtt
     The timezone conversion code in the C library uses data
files  installed  in  /usr/share/zoneinfo  to  convert  from
``GMT'' to various timezones.  The data file for the default
timezone  for the system should be copied to /etc/localtime.
Other timezones can be selected by setting the  TZ  environ-
ment variable.
     The  data files initially installed in /usr/share/zone-
info include corrections for leap seconds since  the  begin-
ning of 1970.  Thus, they assume that the kernel will incre-
ment the time at a constant rate during a leap second;  that
is,  time  just  keeps  on ticking.  The conversion routines



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-51


will then name a leap second 23:59:60.   For  purists,  this
effectively  means  that  the kernel maintains TAI (Interna-
tional Atomic Time) rather than UTC  (Coordinated  Universal
Time, aka GMT).
     For  systems  that run current NTP (Network Time Proto-
col) implementations or that wish to conform to  the  letter
of  the  POSIX.1 law, it is possible to rebuild the timezone
data files so that  leap  seconds  are  not  counted.   (NTP
causes the time to jump over a leap second, and POSIX effec-
tively requires the clock to be reset by hand  when  a  leap
second  occurs.   In  this mode, the kernel effectively runs
UTC rather than TAI.)
     The data files without leap second information are con-
structed from the source directory, /usr/src/share/zoneinfo.
Change the variable  REDO  in  Makefile  from  ``right''  to
``posix'', and then do

     make obj  (if necessary)
     make
     make install

     You  will  then  need  to copy the correct default zone
file to /etc/localtime, as the old one would still have used
leap  seconds,  and  because the Makefile installs a default
/etc/localtime each time ``make install'' is done.
     It is possible to install both sets  of  timezone  data
files.   This  results  in  subdirectories  /usr/share/zone-
info/right and /usr/share/zoneinfo/posix.   Each  contain  a
complete   set  of  zone  files.   See  /usr/src/share/zone-
info/Makefile for details.

33..55..33..44..  AAddddiittiioonnss aanndd cchhaannggeess ttoo tthhee lliibbrraarriieess
     Notable additions to the libraries include functions to
traverse  a  filesystem  hierarchy,  database  interfaces to
btree and hashing functions, a new, faster implementation of
stdio and a radix and merge sort functions.
     The _f_t_s(3) functions will do either physical or logical
traversal of a file hierarchy as well as handle  essentially
infinite depth filesystems and filesystems with cycles.  All
the utilities in 4.4BSD which traverse file hierarchies have
been  converted  to  use  _f_t_s(3).  The conversion has always
resulted in a significant performance gain, often of four or
five to one in system time.
     The  _d_b_o_p_e_n(3) functions are intended to be a family of
database  access  methods.   Currently,  they   consist   of
_h_a_s_h(3),  an extensible, dynamic hashing scheme, _b_t_r_e_e(3), a
sorted, balanced tree structure (B+tree's), and _r_e_c_n_o(3),  a
flat-file  interface  for  fixed  or variable length records
referenced by logical record number.   Each  of  the  access
methods  stores  associated key/data pairs and uses the same
record oriented interface for access.
     The _q_s_o_r_t(3) function has been rewritten for additional
performance.   In addition, three new types of sorting func-
tions, _h_e_a_p_s_o_r_t(3), _m_e_r_g_e_s_o_r_t(3) and _r_a_d_i_x_s_o_r_t(3) have  been



                        May 14, 1994





SMM:1-52                Installing and Operating 4.4BSD UNIX


added  to  the  system.  The _m_e_r_g_e_s_o_r_t function is optimized
for data with pre-existing order, in which case  it  usually
significantly outperforms _q_s_o_r_t.  The _r_a_d_i_x_s_o_r_t(3) functions
are variants of most-significant-byte radix  sorting.   They
take  time  linear to the number of bytes to be sorted, usu-
ally significantly outperforming _q_s_o_r_t on data that  can  be
sorted  in  this  fashion.   An  implementation of the POSIX
1003.2 standard _s_o_r_t(1), based on _r_a_d_i_x_s_o_r_t, is included  in
/usr/src/contrib/sort.
     Some additional comments about the 4.4BSD C library:
+o    The  floating  point  support in the C library has been
     replaced and is now accurate.
+o    The C functions specified by both ANSI C, POSIX  1003.1
     and  1003.2  are  now  part  of  the  C  library.  This
     includes support for file name matching, shell globbing
     and both basic and extended regular expressions.
+o    ANSI  C  multibyte  and wide-character support has been
     integrated.  The rune functionality from the Bell Labs'
     Plan 9 system is provided as well.
+o    The  _t_e_r_m_c_a_p(3)  functions  have  been  generalized and
     replaced with a general purpose  interface  named  _g_e_t_-
     _c_a_p(3).
+o    The  _s_t_d_i_o(3) routines have been replaced, and are usu-
     ally much faster.  In addition, the  _f_u_n_o_p_e_n(3)  inter-
     face  permits  applications  to  provide  their own I/O
     stream function support.
     The  _c_u_r_s_e_s(3)  library  has  been  largely  rewritten.
Important  additional features include support for scrolling
and _t_e_r_m_i_o_s(3).
     An  application  front-end   editing   library,   named
libedit, has been added to the system.
     A  superset  implementation  of the SunOS kernel memory
interface library, libkvm, has been integrated into the sys-
tem.

33..55..33..55..  AAddddiittiioonnss aanndd cchhaannggeess ttoo ootthheerr uuttiilliittiieess
     There  are  many new utilities, offering many new capa-
bilities, in 4.4BSD.  Skimming through  the  section  1  and
section  8 manual pages is sure to be useful.  The additions
to the utility suite include greatly  enhanced  versions  of
programs that display system status information, implementa-
tions of various traditional tools  described  in  the  IEEE
Std1003.2  standard,  new  tools  not  previous available on
Berkeley UNIX systems, and many others.  Also, with  only  a
very  few  exceptions,  all  the  utilities from 4.3BSD that
included proprietary source code  have  been  replaced,  and
their  4.4BSD counterparts are freely redistributable.  Nor-
mally, this replacement resulted in significant  performance
improvements  and the increase of the limits imposed on data
by the utility as well.
     A summary of specific additions and changes are as fol-
lows:





                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-53


amd          An auto-mounter implementation.
ar           Replacement of the historic archive format with a new one.
awk          Replaced by gawk; see /usr/src/old/awk for the historic version.
bdes         Utility implementing DES modes of operation described in FIPS PUB 81.
calendar     Addition of an interface for system calendars.
cap_mkdb     Utility for building hashed versions of termcap style databases.
cc           Replacement of pcc with gcc suite.
chflags      A utility for setting the per-file user and system flags.
chfn         An editor based replacement for changing user information.
chpass       An editor based replacement for changing user information.
chsh         An editor based replacement for changing user information.
cksum        The POSIX 1003.2 checksum utility; compatible with sum.
column       A columnar text formatting utility.
cp           POSIX 1003.2 compatible, able to copy special files.
csh          Freely redistributable and 8-bit clean.
date         User specified formats added.
dd           New EBCDIC conversion tables, major performance improvements.
dev_mkdb     Hashed interface to devices.
dm           Dungeon master.
find         Several new options and primaries, major performance improvements.
fstat        Utility displaying information on files open on the system.
ftpd         Connection logging added.
hexdump      A binary dump utility, superseding od.
id           The POSIX 1003.2 user identification utility.
inetd        Tcpmux added.
jot          A text formatting utility.
kdump        A system-call tracing facility.
ktrace       A system-call tracing facility.
kvm_mkdb     Hashed interface to the kernel name list.
lam          A text formatting utility.
lex          A new, freely redistributable, significantly faster version.
locate       A database of the system files, by name, constructed weekly.
logname      The POSIX 1003.2 user identification utility.
mail.local   New local mail delivery agent, replacing mail.
make         Replaced with a new, more powerful make, supporting include files.
man          Added support for man page location configuration.
mkdep        A new utility for generating make dependency lists.
mkfifo       The POSIX 1003.2 FIFO creation utility.
mtree        A new utility for mapping file hierarchies to a file.
nfsstat      An NFS statistics utility.
nvi          A freely redistributable replacement for the ex/vi editors.
pax          The POSIX 1003.2 replacement for cpio and tar.
printf       The POSIX 1003.2 replacement for echo.
roff         Replaced by groff; see /usr/src/old/roff for the historic versions.
rs           New utility for text formatting.
shar         An archive building utility.
sysctl       MIB-style interface to system state.
tcopy        Fast tape-to-tape copying and verification.
touch        Time and file reference specifications.
tput         The POSIX 1003.2 terminal display utility.
tr           Addition of character classes.
uname        The POSIX 1003.2 system identification utility.
vis          A filter for converting and displaying non-printable characters.




                        May 14, 1994





SMM:1-54                Installing and Operating 4.4BSD UNIX


xargs        The POSIX 1003.2 argument list constructor utility.
yacc         A new, freely redistributable, significantly faster version.

     The  new  versions  of  _l_e_x(1)  (``flex'')  and _y_a_c_c(1)
(``zoo'') should be installed  early  on  if  attempting  to
cross-compile  4.4BSD  on another system.  Note that the new
_l_e_x program is not completely backward compatible with  his-
toric versions of _l_e_x, although it is believed that all doc-
umented features are supported.
     The _f_i_n_d utility has two new options that are important
to be aware of if you intend to use NFS.  The ``fstype'' and
``prune'' options can be used together to prevent find  from
crossing NFS mount points.  See /etc/daily for an example of
their use.

33..66..  HHiinnttss oonn ccoonnvveerrttiinngg ffrroomm 44..33BBSSDD ttoo 44..44BBSSDD
     This section  summarizes  changes  between  4.3BSD  and
4.4BSD that are likely to cause difficulty in doing the con-
version.  It does not include changes in  the  network;  see
section 5 for information on setting up the network.
     Since  the stat st_size field is now 64-bits instead of
32, doing something like:

     foo(st.st_size);

and then  (improperly)  defining  foo  with  an  ``int''  or
``long'' parameter:

     foo(size)
          int size;
     {
          ...
     }

will  fail miserably (well, it might work on a little endian
machine).  This problem showed up in  _e_m_a_c_s(1)  as  well  as
several  other  programs.   A  related problem is improperly
casting  (or  failing  to  cast)  the  second  argument   to
_l_s_e_e_k(2), _t_r_u_n_c_a_t_e(2), or _f_t_r_u_n_c_a_t_e(2) ala:

     lseek(fd, (long)off, 0);

or

     lseek(fd, 0, 0);

The  best solution is to include <unistd.h> which has proto-
types that catch these types of errors.
     Determining the ``namelen'' parameter for a  _c_o_n_n_e_c_t(2)
call  on  a  unix  domain  socket should use the ``SUN_LEN''
macro from <sys/un.h>.  One old way that was used:

     addrlen = strlen(unaddr.sun_path) + sizeof(unaddr.sun_family);




                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-55


no longer works as there is an additional sun_len field.
     The kernel's limit on the number of open files has been
increased  from 20 to 64.  It is now possible to change this
limit almost arbitrarily.  The standard I/O library autocon-
figures  to  the  kernel  limit.   Note that file (``_iob'')
entries may be allocated by _m_a_l_l_o_c from _f_o_p_e_n; this  alloca-
tion has been known to cause problems with programs that use
their own memory allocators.   Memory  allocation  does  not
occur  until after 20 files have been opened by the standard
I/O library.
     _S_e_l_e_c_t can be used with more  than  32  descriptors  by
using  arrays  of iinntts for the bit fields rather than single
iinntts.  Programs that used _g_e_t_d_t_a_b_l_e_s_i_z_e as their first argu-
ment  to  _s_e_l_e_c_t will no longer work correctly.  Usually the
program can be modified to correctly specify the  number  of
bits  in  an iinntt.  Alternatively the program can be modified
to use an array of iinntts.  There are a set of  macros  avail-
able in <sys/types.h> to simplify this.  See _s_e_l_e_c_t(2).
     Old  core files will not be intelligible by the current
debuggers because of numerous changes to the user  structure
and  because  the kernel stack has been enlarged.  The _a_._o_u_t
header that was in the user structure is no longer  present.
Locally-written debuggers that try to check the magic number
will need to be changed.
     Files may not be deleted from  directories  having  the
``sticky''  (ISVTX)  bit  set  in  their modes except by the
owner of the file or of the directory, or by the  superuser.
This  is  primarily  to  protect  users'  files in publicly-
writable directories such as /tmp and  /var/tmp.   All  pub-
licly-writable directories should have their ``sticky'' bits
set with ``chmod +t.''
     The following two  sections  contain  additional  notes
about  changes  in  4.4BSD  that  affect the installation of
local files; be sure to read them as well.

44..  SSyysstteemm sseettuupp
     This section describes procedures  used  to  set  up  a
4.4BSD UNIX system.  These procedures are used when a system
is first installed or when the system configuration changes.
Procedures  for normal system operation are described in the
next section.

44..11..  KKeerrnneell ccoonnffiigguurraattiioonn
     This section briefly describes the layout of the kernel
code and how files for devices are made.  For a full discus-
sion of configuring and building system images, consult  the
document   ``Building  4.3BSD  UNIX  Systems  with  Config''
(SMM:2).

44..11..11..  KKeerrnneell oorrggaanniizzaattiioonn
     As distributed, the kernel source is in a separate  tar
image.  The source may be physically located anywhere within
any filesystem so long as a symbolic link to the location is
created  for  the  file /sys (many files in /usr/include are



                        May 14, 1994





SMM:1-56                Installing and Operating 4.4BSD UNIX


normally symbolic links relative to /sys).  In further  dis-
cussions  of  the system source all path names will be given
relative to /sys.
The kernel is made up of several large generic parts:

sys               main kernel header files
kern              kernel functions broken down as follows
         init     system startup, syscall dispatching, entry points
         kern     scheduling, descriptor handling and generic I/O
         sys      process management, signals
         tty      terminal handling and job control
         vfs      filesystem management
         uipc     interprocess communication (sockets)
         subr     miscellaneous support routines
vm                virtual memory management
ufs               local filesystems broken down as follows
         ufs      common local filesystem routines
         ffs      fast filesystem
         lfs      log-based filesystem
         mfs      memory based filesystem
nfs               Sun-compatible network filesystem
miscfs            miscellaneous filesystems broken down as follows
         deadfs   where rejected vnodes go to die
         fdesc    access to per-process file descriptors
         fifofs   IEEE Std1003.1 FIFOs
         kernfs   filesystem access to kernel data structures
         lofs     loopback filesystem
         nullfs   another loopback filesystem
         portal   associate processes with filesystem locations
         specfs   device special files
         umapfs   provide alternate uid/gid mappings
dev               generic device drivers (SCSI, vnode, concatenated disk)

The networking code is organized by protocol

net       routing and generic interface drivers
netinet   Internet protocols (TCP, UDP, IP, etc)
netiso    ISO protocols (TP-4, CLNP, CLTP, etc)
netns     Xerox network systems protocols (IDP, SPP, etc)
netx25    CCITT X.25 protocols (X.25 Packet Level, HDLC/LAPB)

A separate subdirectory is provided for each machine  archi-
tecture

hp300      HP 9000/300 series of Motorola 68000-based machines
hp         code common to both HP 68k and (non-existent) PA-RISC ports
i386       Intel 386/486-based PC machines
luna68k    Omron 68000-based workstations
news3400   Sony News MIPS-based workstations
pmax       Digital 3100/5000 MIPS-based workstations
sparc      Sun Microsystems SPARCstation 1, 1+, and 2
tahoe      (deprecated) CCI Power 6-series machines
vax        (deprecated) Digital VAX machines




                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-57


Each  machine directory is subdivided by function; for exam-
ple the hp300 directory contains

include   exported machine-dependent header files
hp300     machine-dependent support code and private header files
dev       device drivers
conf      configuration files
stand     machine-dependent standalone code

Other kernel related directories

compile   area to compile kernels
conf      machine-independent configuration files
stand     machine-independent standalone code


44..11..22..  DDeevviicceess aanndd ddeevviiccee ddrriivveerrss
     Devices supported by UNIX are implemented in the kernel
by  drivers whose source is kept in /sys/<architecture>/dev.
These drivers are loaded into the system when included in  a
CPU  specific configuration file kept in the conf directory.
Devices are accessed through special files in  the  filesys-
tem,  made  by the _m_k_n_o_d(8) program and normally kept in the
/dev directory.  For all the devices supported by  the  dis-
tribution  system,  the  files  in  /dev  are created by the
/dev/MAKEDEV shell script.
     Determine the set of devices that you have and create a
new  /dev  directory  by  running the MAKEDEV script.  First
create a new directory /newdev, copy MAKEDEV into  it,  edit
the  file MAKEDEV.local to provide an entry for local needs,
and run it to generate a /newdevdirectory.  For instance,

     ## _c_d _/
     ## _m_k_d_i_r _n_e_w_d_e_v
     ## _c_p _d_e_v_/_M_A_K_E_D_E_V _n_e_w_d_e_v_/_M_A_K_E_D_E_V
     ## _c_d _n_e_w_d_e_v
     ## _M_A_K_E_D_E_V _s_d_0 _p_t_0 _s_t_d _L_O_C_A_L

Note the ``std'' argument causes standard  devices  such  as
/dev/console, the machine console, to be created.
     You can then do

     ## _c_d _/
     ## _m_v _d_e_v _o_l_d_d_e_v _; _m_v _n_e_w_d_e_v _d_e_v
     ## _s_y_n_c

to install the new device directory.

44..11..33..  BBuuiillddiinngg nneeww ssyysstteemm iimmaaggeess
     The   kernel  configuration  of  each  UNIX  system  is
described by a single  configuration  file,  stored  in  the
/sys/<architecture>/conf directory.  To learn about the for-
mat of this file and the  procedure  used  to  build  system
images, start by reading ``Building 4.3BSD UNIX Systems with



                        May 14, 1994





SMM:1-58                Installing and Operating 4.4BSD UNIX


Config'' (SMM:2), look at the manual pages in section  4  of
the  UNIX  manual  for the devices you have, and look at the
sample configuration files in  the  /sys/<architecture>/conf
directory.
     The  configured system image vmunix should be copied to
the root, and then booted to try it out.  It is best to name
it  /newvmunix so as not to destroy the working system until
you are sure it does work:

     ## _c_p _v_m_u_n_i_x _/_n_e_w_v_m_u_n_i_x
     ## _s_y_n_c

It is also a good idea to keep the  previous  system  around
under some other name.  In particular, we recommend that you
save the generic distribution version of the  system  perma-
nently  as  /genvmunix  for use in emergencies.  To boot the
new version of the system you should  follow  the  bootstrap
procedures outlined in section 6.1.  After having booted and
tested the new system, it should  be  installed  as  /vmunix
before  going into multiuser operation.  A systematic scheme
for numbering and saving old versions of the system  may  be
useful.

44..22..  CCoonnffiigguurriinngg tteerrmmiinnaallss
     If   UNIX   is  to  support  simultaneous  access  from
directly-connected terminals other  than  the  console,  the
file /etc/ttys (see _t_t_y_s(5)) must be edited.
     To  add  a  new  terminal device, be sure the device is
configured into the system and that the  special  files  for
the device have been made by /dev/MAKEDEV.  Then, enable the
appropriate lines of /etc/ttys  by  setting  the  ``status''
field  to  oonn  (or  add  new  lines).   Note  that  lines in
/etc/ttys are one-for-one with entries in the file  of  cur-
rent  users (see /var/run/utmp), and therefore it is best to
make changes while running in single-user mode  and  to  add
all the entries for a new device at once.
     Each line in the /etc/ttys file is broken into four tab
separated fields (comments are shown by a `#' character  and
extend  to the end of the line).  For each terminal line the
four fields are: the device (without a  leading  /dev),  the
program  /sbin/init  should  startup to service the line (or
nnoonnee if the line is to be left  alone),  the  terminal  type
(found  in  /usr/share/misc/termcap),  and  optional  status
information describing if the terminal is enabled or not and
if  it  is ``secure'' (i.e. the super user should be allowed
to login on the line).  If the console is marked as  ``inse-
cure'',  then  the  root  password  is required to bring the
machine up single-user.  All fields  are  character  strings
with entries requiring embedded white space enclosed in dou-
ble quotes.  Thus a newly added terminal /dev/tty00 could be
added as

     tty00     "/usr/libexec/getty std.9600" vt100     on secure # mike's office




                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-59


The  std.9600  parameter  provided  to /usr/libexec/getty is
used in searching the file  /etc/gettytab;  it  specifies  a
terminal's  characteristics  (such  as  baud rate).  To make
custom terminal types, consult _g_e_t_t_y_t_a_b(5) before  modifying
/etc/gettytab.
     Dialup  terminals  should  be  wired so that carrier is
asserted only when the phone line is dialed  up.   For  non-
dialup terminals, from which modem control is not available,
you must wire back the signals so that the  carrier  appears
to always be present.  For further details, find your termi-
nal driver in section 4 of the manual.
     For network terminals (i.e. pseudo terminals), no  pro-
gram  should  be  started up on the lines.  Thus, the normal
entry in /etc/ttys would look like

     ttyp0     none network

(Note, the fourth field is not needed here.)
     When the system is running  multi-user,  all  terminals
that  are listed in /etc/ttys as oonn have their line enabled.
If, during normal operations, you wish to disable a terminal
line,  you  can edit the file /etc/ttys to change the termi-
nal's status to ooffff and then send a  hangup  signal  to  the
_i_n_i_t process, by doing

     ## _k_i_l_l _-_s _H_U_P _1

Terminals  can  similarly  be enabled by changing the status
field from ooffff to oonn and sending a hangup signal to _i_n_i_t.
     Note that if a special file is inaccessible  when  _i_n_i_t
tries to create a process for it, _i_n_i_t will log a message to
the system error logging process (see _s_y_s_l_o_g_d(8)) and try to
reopen  the  terminal  every  minute, reprinting the warning
message every 10 minutes.  Messages of this  sort  are  nor-
mally printed on the console, though other actions may occur
depending  on  the  configuration   information   found   in
/etc/syslog.conf.
     Finally  note  that  you should change the names of any
dialup terminals to ttyd?  where ?  is  in  [0-9a-zA-Z],  as
some programs use this property of the names to determine if
a terminal is a dialup.  Shell commands to do this should be
put in the /dev/MAKEDEV.local script.
     While it is possible to use truly arbitrary strings for
terminal names, the accounting and noticeably the _p_s(1) com-
mand  make  good  use  of  the convention that tty names (by
default, and also  after  dialups  are  named  as  suggested
above)  are  distinct in the last 2 characters.  Change this
and you may be sorry later,  as  the  heuristic  _p_s(1)  uses
based  on these conventions will then break down and _p_s will
run MUCH slower.

44..33..  AAddddiinngg uusseerrss
     The procedure for adding a new  user  is  described  in
_a_d_d_u_s_e_r(8).   You  should  add accounts for the initial user



                        May 14, 1994





SMM:1-60                Installing and Operating 4.4BSD UNIX


community, giving each  a  directory  and  a  password,  and
putting  users  who  will wish to share software in the same
groups.
     Several guest accounts have been provided on  the  dis-
tribution system; these accounts are for people at Berkeley,
Bell Laboratories, and others who have done  major  work  on
UNIX  in  the past.  You can delete these accounts, or leave
them on the system if you expect  that  these  people  would
have occasion to login as guests on your system.

44..44..  SSiittee ttaaiilloorriinngg
     All programs that require the site's name, or some sim-
ilar characteristic, obtain the information  through  system
calls  or  from  files located in /etc.  Aside from parts of
the system related to the network, to tailor the  system  to
your  site you must simply select a site name, then edit the
file

     /etc/netstart

The first lines in /etc/netstart use a variable to  set  the
hostname,

     hostname=_m_y_s_i_t_e_n_a_m_e
     /bin/hostname $hostname

to  define  the  value returned by the _g_e_t_h_o_s_t_n_a_m_e(2) system
call.  If you are running the name server,  your  site  name
should  be  your fully qualified domain name.  Programs such
as _g_e_t_t_y(8), _m_a_i_l(1), _w_a_l_l(1), and _u_u_c_p(1) use  this  system
call so that the binary images are site independent.
     You will also need to edit /etc/netstart to do the net-
work interface initialization using _i_f_c_o_n_f_i_g(8).  If you are
not sure how to do this, see sections 5.1, 5.2, and 5.3.  If
you are not running a routing daemon and have more than  one
Ethernet  in  your  environment  you  will  need to set up a
default route; see section 5.4 for details.  Before bringing
your  system  up  multiuser, you should ensure that the net-
working is properly configured.  The network is  started  by
running  /etc/netstart.   Once started, you should test con-
nectivity using _p_i_n_g(8).  You should first test connectivity
to yourself, then another host on your Ethernet, and finally
a host on another Ethernet.  The _n_e_t_s_t_a_t(8) program  can  be
used to inspect and debug your routes; see section 5.4.

44..55..  SSeettttiinngg uupp tthhee lliinnee pprriinntteerr ssyysstteemm
     The  line  printer system consists of at least the fol-
lowing files and commands:









                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-61


     /usr/bin/lpq     spooling queue examination program
     /usr/bin/lprm    program to delete jobs from a queue
     /usr/bin/lpr     program to enter a job in a printer queue
     /etc/printcap    printer configuration and capability database
     /usr/sbin/lpd    line printer daemon, scans spooling queues
     /usr/sbin/lpc    line printer control program
     /etc/hosts.lpd   list of host allowed to use the printers


     The file /etc/printcap is a master database  describing
line  printers  directly  attached  to  a machine and, also,
printers accessible  across  a  network.   The  manual  page
_p_r_i_n_t_c_a_p(5)  describes  the format of this database and also
shows the default values for such things as the directory in
which  spooling  is performed.  The line printer system han-
dles multiple printers, multiple spooling queues, local  and
remote printers, and also printers attached via serial lines
that require line initialization  such  as  the  baud  rate.
Raster  output  devices  such  as  a Varian or Versatec, and
laser printers such as an Imagen, are also supported by  the
line printer system.
     Remote  spooling  via  the  network is handled with two
spooling queues, one on the local machine  and  one  on  the
remote  machine.   When a remote printer job is started with
_l_p_r, the job is queued locally and a daemon process  created
to  oversee  the  transfer of the job to the remote machine.
If the destination machine  is  unreachable,  the  job  will
remain  queued until it is possible to transfer the files to
the spooling queue on the remote machine.  The  _l_p_q  program
shows  the  contents  of  spool queues on both the local and
remote machines.
     To configure your line printers, consult  the  printcap
manual  page  and  the  accompanying document, ``4.3BSD Line
Printer Spooler Manual'' (SMM:7).  A call to the _l_p_d program
should be present in /etc/rc.

44..66..  SSeettttiinngg uupp tthhee mmaaiill ssyysstteemm
     The mail system consists of the following commands:


     /usr/bin/mail         UCB mail program, described in _m_a_i_l(1)
     /usr/sbin/sendmail    mail routing program
     /var/spool/mail       mail spooling directory
     /etc/aliases          mail forwarding information
     /usr/bin/newaliases   command to rebuild binary forwarding database
     /usr/bin/biff         mail notification enabler
     /usr/libexec/comsat   mail notification daemon


Mail is normally sent and received using the _m_a_i_l(1) command
(found in /usr/bin/mail), which provides a front-end to edit
the  messages  sent and received, and passes the messages to
_s_e_n_d_m_a_i_l(8) for routing.  The routing algorithm uses  knowl-
edge  of  the  network  name syntax, aliasing and forwarding



                        May 14, 1994





SMM:1-62                Installing and Operating 4.4BSD UNIX


information, and network topology, as defined in the config-
uration  file /usr/lib/sendmail.cf, to process each piece of
mail.  Local mail is delivered by giving it to  the  program
/usr/libexec/mail.local that adds it to the mailboxes in the
directory /var/spool/mail/<username>, using a locking proto-
col  to avoid problems with simultaneous updates.  After the
mail  is  delivered,  the   local   mail   delivery   daemon
/usr/libexec/comsat  is  notified,  which  in  turn notifies
users who have issued a ``_b_i_f_f y''  command  that  mail  has
arrived.
     Mail  queued  in  the directory /var/spool/mail is nor-
mally readable only by the recipient.
     To set  up  the  mail  facility  you  should  read  the
instructions   in   the   file   READ_ME  in  the  directory
/usr/src/usr.sbin/sendmail and  then  adjust  the  necessary
configuration  files.   You  should  also  set  up  the file
/etc/aliases for your installation, creating mail groups  as
appropriate.  For more informations see ``Sendmail Installa-
tion and Operation  Guide''  (SMM:8)  and  ``Sendmail  -  An
Internetwork Mail Router'' (SMM:9).


44..66..11..  SSeettttiinngg uupp aa UUUUCCPP ccoonnnneeccttiioonn
The  version  of  _u_u_c_p  included in 4.4BSD has the following
features:
+o  support for many auto call units and dialers in  addition
   to the DEC DN11,
+o  breakup  of  the  spooling area into multiple subdirecto-
   ries,
+o  addition of an L.cmds file to control the set of commands
   that may be executed by a remote site,
+o  enhanced  ``expect-send'' sequence capabilities when log-
   ging in to a remote site,
+o  new commands to be used in polling  sites  and  obtaining
   snap shots of _u_u_c_p activity,
+o  additional protocols for different communication media.
This  section  gives a brief overview of _u_u_c_p and points out
the most important steps in its installation.
     To connect two UNIX machines with a _u_u_c_p  network  link
using  modems, one site must have an automatic call unit and
the other must have a dialup port.  It  is  better  if  both
sites have both.
     You should first read the paper in the UNIX System Man-
ager's Manual: ``Uucp Implementation Description'' (SMM:14).
It describes in detail the file formats and conventions, and
will give you a little context.  In addition,  the  document
``setup.tblms'',      located      in      the     directory
/usr/src/usr.bin/uucp/UUAIDS, may be of use in tailoring the
software to your needs.
     The _u_u_c_p support is located in three major directories:
/usr/bin, /usr/lib/uucp, and /var/spool/uucp.  User commands
are kept in /usr/bin, operational commands in /usr/lib/uucp,
and /var/spool/uucp is used as a spooling  area.   The  com-
mands in /usr/bin are:



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-63


     /usr/bin/uucp       file-copy command
     /usr/bin/uux        remote execution command
     /usr/bin/uusend     binary file transfer using mail
     /usr/bin/uuencode   binary file encoder (for _u_u_s_e_n_d)
     /usr/bin/uudecode   binary file decoder (for _u_u_s_e_n_d)
     /usr/bin/uulog      scans session log files
     /usr/bin/uusnap     gives a snap-shot of _u_u_c_p activity
     /usr/bin/uupoll     polls remote system until an answer is received
     /usr/bin/uuname     prints a list of known uucp hosts
     /usr/bin/uuq        gives information about the queue


The important files and commands in /usr/lib/uucp are:


     /usr/lib/uucp/L-devices     list of dialers and hard-wired lines
     /usr/lib/uucp/L-dialcodes   dialcode abbreviations
     /usr/lib/uucp/L.aliases     hostname aliases
     /usr/lib/uucp/L.cmds        commands remote sites may execute
     /usr/lib/uucp/L.sys         systems to communicate with, how to connect, and when
     /usr/lib/uucp/SEQF          sequence numbering control file
     /usr/lib/uucp/USERFILE      remote site pathname access specifications
     /usr/lib/uucp/uucico        _u_u_c_p protocol daemon
     /usr/lib/uucp/uuclean       cleans up garbage files in spool area
     /usr/lib/uucp/uuxqt         _u_u_c_p remote execution server


while  the  spooling  area  contains the following important
files and directories:


     /var/spool/uucp/C.           directory for command, ``C.'' files
     /var/spool/uucp/D.           directory for data, ``D.'', files
     /var/spool/uucp/X.           directory for command execution, ``X.'', files
     /var/spool/uucp/D._m_a_c_h_i_n_e    directory for local ``D.'' files
     /var/spool/uucp/D._m_a_c_h_i_n_eX   directory for local ``X.'' files
     /var/spool/uucp/TM.          directory for temporary, ``TM.'', files
     /var/spool/uucp/LOGFILE      log file of _u_u_c_p activity
     /var/spool/uucp/SYSLOG       log file of _u_u_c_p file transfers


     To install _u_u_c_p on your system, start  by  selecting  a
site name (shorter than 14 characters).  A _u_u_c_p account must
be created in the password  file  and  a  password  set  up.
Then,  create the appropriate spooling directories with mode
755 and owned by user _u_u_c_p, group _d_a_e_m_o_n.
     If you have an auto-call unit, the L.sys,  L-dialcodes,
and  L-devices  files  should  be  created.   The L.sys file
should  contain  the  phone  numbers  and  login   sequences
required  to  establish  a  connection with a _u_u_c_p daemon on
another machine.  For example, our L.sys  file  looks  some-
thing like:





                        May 14, 1994





SMM:1-64                Installing and Operating 4.4BSD UNIX


     adiron Any ACU 1200 out0123456789- ogin-EOT-ogin uucp
     cbosg Never Slave 300
     cbosgd Never Slave 300
     chico Never Slave 1200 out2010123456

The first field is the name of a site, the second shows when
the machine may be called, the third field specifies how the
host is connected (through an ACU, a hard-wired line, etc.),
then comes the phone number to use in connecting through  an
auto-call  unit,  and  finally  a login sequence.  The phone
number may contain common abbreviations that are defined  in
the L-dialcodes file.  The device specification should refer
to devices specified in the L-devices  file.   Listing  only
ACU causes the _u_u_c_p daemon, _u_u_c_i_c_o, to search for any avail-
able auto-call unit in L-devices.  Our L-dialcodes  file  is
of the form:

     ucb 2
     out 9%

while our L-devices file is:

     ACU cul0 unused 1200 ventel

Refer  to  the  README file in the _u_u_c_p source directory for
more information about installation.
     As _u_u_c_p operates it creates (and  removes)  many  small
files  in the directories underneath /var/spool/uucp.  Some-
times files are left undeleted; these are most easily purged
with  the  _u_u_c_l_e_a_n  program.  The log files can grow without
bound unless trimmed  back;  _u_u_l_o_g  maintains  these  files.
Many  useful  aids in maintaining your _u_u_c_p installation are
included    in     a     subdirectory     UUAIDS     beneath
/usr/src/usr.bin/uucp.   Peruse  this directory and read the
``setup'' instructions also located there.

55..  NNeettwwoorrkk sseettuupp
     4.4BSD provides support for the standard Internet  pro-
tocols  IP, ICMP, TCP, and UDP.  These protocols may be used
on top of a variety of hardware devices ranging from  serial
lines  to  local  area network controllers for the Ethernet.
Network services are split between the kernel (communication
protocols)  and  user programs (user services such as TELNET
and FTP).  This section describes how to configure your sys-
tem  to  use  the  Internet networking support.  4.4BSD also
supports the Xerox Network Systems (NS) protocols.  IDP  and
SPP  are implemented in the kernel, and other protocols such
as Courier run at the user level.  4.4BSD provides some sup-
port  for  the  ISO  OSI protocols CLNP TP4, and ESIS.  User
level process complete the  application  protocols  such  as
X.400 and X.500.






                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-65


55..11..  SSyysstteemm ccoonnffiigguurraattiioonn
     To  configure the kernel to include the Internet commu-
nication protocols, define the INET option.  Xerox  NS  sup-
port  is  enabled  with  the  NS option.  ISO OSI support is
enabled with the ISO option.  In either  case,  include  the
pseudo-devices  ``pty'', and ``loop'' in your machine's con-
figuration  file.   The  ``pty''  pseudo-device  forces  the
pseudo terminal device driver to be configured into the sys-
tem, see _p_t_y(4), while  the  ``loop''  pseudo-device  forces
inclusion  of  the  software loopback interface driver.  The
loop driver is used in network testing and also by the error
logging system.
     If you are planning to use the Internet network facili-
ties on  a  10Mb/s  Ethernet,  the  pseudo-device  ``ether''
should  also  be  included in the configuration; this forces
inclusion of the Address Resolution Protocol module used  in
mapping   between   48-bit   Ethernet  and  32-bit  Internet
addresses.
     Before configuring the appropriate networking hardware,
you should consult the manual pages in section 4 of the Pro-
grammer's Manual selecting the  appropriate  interfaces  for
your architecture.
     All  network  interface  drivers including the loopback
interface, require that their host address(es) be defined at
boot  time.  This is done with _i_f_c_o_n_f_i_g(8) commands included
in the /etc/netstart file.   Interfaces  that  are  able  to
dynamically  deduce  the  host  part of an address may check
that the host part of the address is  correct.   The  manual
page for each network interface describes the method used to
establish a host's address.  _I_f_c_o_n_f_i_g(8) can also be used to
set options for the interface at boot time.  Options are set
independently for each interface, and apply to  all  packets
sent  using that interface.  Alternatively, translations for
such hosts may be set  in  advance  or  ``published''  by  a
4.4BSD host by use of the _a_r_p(8) command.  Note that the use
of trailer link-level is now negotiated between 4.4BSD hosts
using ARP, and it is thus no longer necessary to disable the
use of trailers with _i_f_c_o_n_f_i_g.
     The OSI equivalent to ARP is ESIS (End System to Inter-
mediate  System  Routing Protocol); running this protocol is
mandatory, however one can  manually  add  translations  for
machines that do not participate by use of the _r_o_u_t_e(8) com-
mand.  Additional information is provided in the manual page
describing _E_S_I_S(4).
     To  use  the  pseudo  terminals just configured, device
entries must be created in the /dev directory.  To create 32
pseudo  terminals  (plenty,  unless you have a heavy network
load) execute the following commands.

     ## _c_d _/_d_e_v
     ## _M_A_K_E_D_E_V _p_t_y_0 _p_t_y_1

More pseudo terminals may be made by specifying pty2,  pty3,
etc.   The  kernel  normally  includes support for 32 pseudo



                        May 14, 1994





SMM:1-66                Installing and Operating 4.4BSD UNIX


terminals unless the configuration file specifies a  differ-
ent  number.   Each  pseudo  terminal really consists of two
files in /dev: a master and a slave.  The master pseudo ter-
minal  file  is  named  /dev/ptyp?,  while the slave side is
/dev/ttyp?.  Pseudo terminals are also used by several  pro-
grams  not  related to the network.  In addition to creating
the pseudo  terminals,  be  sure  to  install  them  in  the
/etc/ttys  file  (with  a  `none' in the second column so no
_g_e_t_t_y is started).

55..22..  LLooccaall ssuubbnneettss
     In 4.4BSD the Internet support includes the  notion  of
``subnets''.   This  is  a mechanism by which multiple local
networks may appears as a single Internet  network  to  off-
site  hosts.   Subnetworks  are  useful because they allow a
site to hide their local topology, requiring only  a  single
route in external gateways; it also means that local network
numbers may be locally administered.  The standard  describ-
ing this change in Internet addressing is RFC-950.
     To  set  up local subnets one must first decide how the
available address space (the Internet ``host part''  of  the
32-bit  address) is to be partitioned.  Sites with a class A
network number have a 24-bit host address space  with  which
to  work,  sites with a class B network number have a 16-bit
host address space, while sites with a class C network  num-
ber have an 8-bit host address space5.  To define local sub-
nets you must steal some bits from the  local  host  address
space for use in extending the network portion of the Inter-
net address.  This reinterpretation of Internet addresses is
done  only  for  local  networks;  i.e. it is not visible to
hosts off-site.  For example, if your site  has  a  class  B
network  number,  hosts  on  this  network  have an Internet
address that contains the network number, 16 bits,  and  the
host  number, another 16 bits.  To define 254 local subnets,
each possessing at most 255 hosts, 8 bits may be taken  from
the  local  part.  (The use of subnets 0 and all-1's, 255 in
this example, is discouraged to avoid confusion about broad-
cast  addresses.)   These  new network numbers are then con-
structed by concatenating the original 16-bit network number
with the extra 8 bits containing the local subnet number.
     The  existence  of local subnets is communicated to the
system at the time a network interface  is  configured  with
the  _n_e_t_m_a_s_k  option  to  the _i_f_c_o_n_f_i_g program.  A ``network
mask'' is specified to define the portion  of  the  Internet
address  that  is to be considered the network part for that
network.  This mask normally contains the bits corresponding
to  the  standard network part as well as the portion of the
local part that has been assigned to subnets.  If no mask is
-----------
  5 If   you  are  unfamiliar  with  the  Internet
addressing  structure,  consult   ``Address   Map-
pings'',  Internet  RFC-796,  J. Postel; available
from the Internet Network  Information  Center  at
SRI.



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-67


specified  when the address is set, it will be set according
to the class of  the  network.   For  example,  at  Berkeley
(class  B network 128.32) 8 bits of the local part have been
reserved for defining subnets;  consequently  the  /etc/net-
start file contains lines of the form

     /sbin/ifconfig le0 netmask 0xffffff00 128.32.1.7

This specifies that for interface ``le0'', the upper 24 bits
of the Internet address should be used in  calculating  net-
work  numbers  (netmask  0xffffff00),  and  the  interface's
Internet  address  is  ``128.32.1.7''  (host  7  on  network
128.32.1).   Hosts  _m on sub-network _n of this network would
then have addresses of the form ``128.32._n._m'';   for  exam-
ple,   host   99  on  network  129  would  have  an  address
``128.32.129.99''.  For hosts with multiple interfaces,  the
network  mask  should be set for each interface, although in
practice only the mask of the first interface on  each  net-
work is really used.

55..33..  IInntteerrnneett bbrrooaaddccaasstt aaddddrreesssseess
     The address defined as the broadcast address for Inter-
net networks according to RFC-919 is the address with a host
part of all 1's.  The address used by 4.2BSD was the address
with a host part of 0.  4.4BSD uses the  standard  broadcast
address  (all  1's)  by  default,  but  allows the broadcast
address to be set (with _i_f_c_o_n_f_i_g) for each interface.   This
allows networks consisting of both 4.2BSD, 4.3BSD and 4.4BSD
hosts to coexist while the upgrade process proceeds.  In the
presence  of  subnets, the broadcast address uses the subnet
field as for normal host addresses, with the remaining  host
part  set to 1's (or 0's, on a network that has not yet been
converted).  4.4BSD hosts recognize and accept packets  sent
to  the  logical-network  broadcast address as well as those
sent to the subnet broadcast  address,  and  when  using  an
all-1's  broadcast,  also recognize and receive packets sent
to host 0 as a broadcast.

55..44..  RRoouuttiinngg
     If your  environment  allows  access  to  networks  not
directly attached to your host you will need to set up rout-
ing information to allow packets to be properly routed.  Two
schemes  are  supported  by  the  system.   The first scheme
employs a routing table management daemon.   Optimally,  you
should  use  the routing daemon _g_a_t_e_d available from Cornell
university.  We use it on our systems  and  it  works  well,
especially  for  multi-homed  hosts  using  Serial  Line  IP
(SLIP).  Unfortunately, we were not able to  obtain  permis-
sion to include it on 4.4BSD.
     If  you do not wish to or cannot obtain _g_a_t_e_d, the dis-
tribution does include  _r_o_u_t_e_d(8)  to  maintain  the  system
routing  tables.   The  routing daemon uses a variant of the
Xerox Routing Information Protocol to maintain  up  to  date
routing  tables  in  a  cluster  of local area networks.  By



                        May 14, 1994





SMM:1-68                Installing and Operating 4.4BSD UNIX


using the /etc/gateways file, the routing daemon can also be
used  to  initialize  static routes to distant networks (see
the next section for further discussion).  When the  routing
daemon  is  started  up  (usually  from  /etc/rc)  it  reads
/etc/gateways if it exists and installs those routes defined
there,  then  broadcasts  on each local network to which the
host is attached to find other instances of the routing dae-
mon.   If  any  responses  are received, the routing daemons
cooperate in maintaining a globally consistent view of rout-
ing  in the local environment.  This view can be extended to
include remote sites also running the routing daemon by set-
ting up suitable entries in /etc/gateways; consult _r_o_u_t_e_d(8)
for a more thorough discussion.
     The second approach is to define a default or  wildcard
route  to  a smart gateway and depend on the gateway to pro-
vide ICMP routing redirect information to dynamically create
a routing data base.  This is done by adding an entry of the
form

     /sbin/route add default _s_m_a_r_t_-_g_a_t_e_w_a_y 1

to /etc/netstart; see _r_o_u_t_e(8) for  more  information.   The
default  route  will  be  used  by  the  system  as a ``last
resort'' in routing packets to their destination.   Assuming
the  gateway to which packets are directed is able to gener-
ate the proper routing redirect messages,  the  system  will
then add routing table entries based on the information sup-
plied.  This approach has certain advantages over the  rout-
ing  daemon, but is unsuitable in an environment where there
are only bridges (i.e.  pseudo gateways that, for  instance,
do not generate routing redirect messages).  Further, if the
smart gateway goes down there is no alternative, save manual
alteration  of  the routing table entry, to maintaining ser-
vice.
     The system always listens, and processes, routing redi-
rect  information,  so it is possible to combine both of the
above facilities.  For example, the routing table management
process  might  be  used  to maintain up to date information
about routes to geographically local networks, while employ-
ing  the  wildcard  routing  techniques for ``distant'' net-
works.  The _n_e_t_s_t_a_t(1) program may be used to display  rout-
ing  table contents as well as various routing oriented sta-
tistics.  For example,

     ## _n_e_t_s_t_a_t _-_r

will display the contents of the routing tables, while

     ## _n_e_t_s_t_a_t _-_r _-_s

will show the number of routing  table  entries  dynamically
created as a result of routing redirect messages, etc.





                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-69


55..55..  UUssee ooff 44..44BBSSDD mmaacchhiinneess aass ggaatteewwaayyss
     Several changes have been made in 4.4BSD in the area of
gateway support (or packet forwarding, if one  prefers).   A
new  configuration option, GATEWAY, is used when configuring
a machine to be used as a gateway.   This  option  increases
the  size  of the routing hash tables in the kernel.  Unless
configured with that option, hosts with only a  single  non-
loopback  interface  never  attempt to forward packets or to
respond with ICMP error  messages  to  misdirected  packets.
This change reduces the problems that may occur when differ-
ent hosts on a network disagree on  the  network  number  or
broadcast  address.   Another change is that 4.4BSD machines
that forward packets back  through  the  same  interface  on
which  they  arrived  will send ICMP redirects to the source
host if it is on the same network.  This improves the inter-
action  of  4.4BSD  gateways with hosts that configure their
routes via default gateways and redirects.   The  generation
of  redirects  may be disabled with the configuration option
IPSENDREDIRECTS=0 or while the system is  running  by  using
the command:

     sysctl -w net.inet.ip.redirect=0

in environments where it may cause difficulties.

55..66..  NNeettwwoorrkk ddaattaabbaasseess
     Several data files are used by the network library rou-
tines and server programs.  Most of  these  files  are  host
independent and updated only rarely.

File               Manual reference   Use
-----------------------------------------------------------------------------------
/etc/hosts         _h_o_s_t_s(5)           local host names
/etc/networks      _n_e_t_w_o_r_k_s(5)        network names
/etc/services      _s_e_r_v_i_c_e_s(5)        list of known services
/etc/protocols     _p_r_o_t_o_c_o_l_s(5)       protocol names
/etc/hosts.equiv   _r_s_h_d(8)            list of ``trusted'' hosts
/etc/netstart      _r_c(8)              command script for initializing network
/etc/rc            _r_c(8)              command script for starting standard servers
/etc/rc.local      _r_c(8)              command script for starting local servers
/etc/ftpusers      _f_t_p_d(8)            list of ``unwelcome'' ftp users
/etc/hosts.lpd     _l_p_d(8)             list of hosts allowed to access printers
/etc/inetd.conf    _i_n_e_t_d(8)           list of servers started by _i_n_e_t_d

The  files distributed are set up for Internet hosts.  Local
networks and hosts should be added  to  describe  the  local
configuration;  the  Berkeley  entries may serve as examples
(see also the section on /etc/hosts).  Network numbers  will
have to be chosen for each Ethernet.  For sites connected to
the Internet, the normal channels should be used for alloca-
tion  of  network numbers (contact hostmaster@SRI-NIC.ARPA).
For other sites, these could be chosen more  or  less  arbi-
trarily, but it is generally better to request official num-
bers to avoid conversion if a connection to the Internet (or



                        May 14, 1994





SMM:1-70                Installing and Operating 4.4BSD UNIX


others on the Internet) is ever established.

55..66..11..  NNeettwwoorrkk sseerrvveerrss
     Most  network  servers  are automatically started up at
boot time by the command file /etc/rc  or  by  the  Internet
daemon (see below).  These include the following:

Program                Server                            Started by
--------------------------------------------------------------------
/usr/sbin/syslogd      error logging server              /etc/rc
/usr/sbin/named        Internet name server              /etc/rc
/sbin/routed           routing table management daemon   /etc/rc
/usr/sbin/rwhod        system status daemon              /etc/rc
/usr/sbin/timed        time synchronization daemon       /etc/rc
/usr/sbin/sendmail     SMTP server                       /etc/rc
/usr/libexec/rshd      shell server                      inetd
/usr/libexec/rexecd    exec server                       inetd
/usr/libexec/rlogind   login server                      inetd
/usr/libexec/telnetd   TELNET server                     inetd
/usr/libexec/ftpd      FTP server                        inetd
/usr/libexec/fingerd   Finger server                     inetd
/usr/libexec/tftpd     TFTP server                       inetd

Consult  the  manual  pages  and  accompanying documentation
(particularly for named  and  sendmail)  for  details  about
their operation.
     The  use  of  _r_o_u_t_e_d  and  _r_w_h_o_d is controlled by shell
variables set in /etc/netstart.  By default, _r_o_u_t_e_d is used,
but  _r_w_h_o_d is not; they are enabled by setting the variables
_r_o_u_t_e_d_f_l_a_g_s and _r_w_h_o_d to strings  other  than  ``NO.''   The
value  of  _r_o_u_t_e_d_f_l_a_g_s  provides  host-specific  options  to
_r_o_u_t_e_d.  For example,

     routedflags=-q
     rwhod=NO

would run _r_o_u_t_e_d _-_q and would not run _r_w_h_o_d.
     To have other network servers started as well, commands
of the following sort should be placed in the site-dependent
file /etc/rc.local.

     if [ -f /usr/sbin/timed ]; then
          /usr/sbin/timed & echo -n ' timed'           >/dev/console
     fi


55..66..22..  IInntteerrnneett ddaaeemmoonn
     In 4.4BSD most of the servers for user-visible services
are  started  up by a ``super server'', the Internet daemon.
The Internet  daemon,  /usr/sbin/inetd,  acts  as  a  master
server  for  programs  specified  in its configuration file,
/etc/inetd.conf, listening for service  requests  for  these
servers,  and starting up the appropriate program whenever a
request is received.  The configuration file contains  lines



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-71


containing  a  service name (as found in /etc/services), the
type of socket the server expects (e.g.  stream  or  dgram),
the  protocol  to  be  used  with  the  socket  (as found in
/etc/protocols), whether to wait for each server to complete
before  starting  up  another,  the  user  name by which the
server should run, the server program's name,  and  at  most
five  arguments to pass to the server program.  Some trivial
services are implemented  internally  in  _i_n_e_t_d,  and  their
servers  are  listed as ``internal.''  For example, an entry
for the file transfer protocol server would appear as

     ftp  stream    tcp  nowait    root /usr/libexec/ftpd   ftpd

Consult _i_n_e_t_d(8) for more detail on the format of  the  con-
figuration file and the operation of the Internet daemon.

55..66..33..  TThhee //eettcc//hhoossttss..eeqquuiivv ffiillee
     The  remote  login and shell servers use an authentica-
tion scheme based on trusted hosts.   The  hosts.equiv  file
contains  a  list  of hosts that are considered trusted and,
under a single administrative control.  When a user contacts
a  remote  login  or  shell  server  requesting service, the
client process passes the user's name and the official  name
of  the  host on which the client is located.  In the simple
case, if the host's name is located in hosts.equiv  and  the
user has an account on the server's machine, then service is
rendered (i.e. the user is allowed to log in, or the command
is  executed).   Users  may  expand  this ``equivalence'' of
machines by installing a .rhosts file in their login  direc-
tory.   The  root  login is handled specially, bypassing the
hosts.equiv file, and using only the /.rhosts file.
     Thus, to create a class  of  equivalent  machines,  the
hosts.equiv file should contain the _o_f_f_i_c_i_a_l names for those
machines.  If you are running the name server, you may  omit
the  domain part of the host name for machines in your local
domain.  For example, four machines on our local network are
considered trusted, so the hosts.equiv file is of the form:

     vangogh.CS.Berkeley.EDU
     picasso.CS.Berkeley.EDU
     okeeffe.CS.Berkeley.EDU


55..66..44..  TThhee //eettcc//ffttppuusseerrss ffiillee
     The  FTP server included in the system provides support
for an anonymous FTP account.  Because of the inherent secu-
rity problems with such a facility you should read this sec-
tion carefully if you consider providing such a service.
     An anonymous account is enabled by creating a user _f_t_p.
When  a client uses the anonymous account a _c_h_r_o_o_t(2) system
call is performed by the server to restrict the client  from
moving  outside  that  part of the filesystem where the user
ftp home directory is located.  Because  a  _c_h_r_o_o_t  call  is
used,  certain programs and files used by the server process



                        May 14, 1994





SMM:1-72                Installing and Operating 4.4BSD UNIX


must be placed in the ftp home directory.  Further, one must
be  sure  that  all  directories  and  executable images are
unwritable.  The following directory setup  is  recommended.
The  use  of  the  _a_w_k  commands to copy the /etc/passwd and
/etc/group files are SSTTRROONNGGLLYY recommended.

     ## _c_d _~_f_t_p
     ## _c_h_m_o_d _5_5_5 _._; _c_h_o_w_n _f_t_p _._; _c_h_g_r_p _f_t_p _.
     ## _m_k_d_i_r _b_i_n _e_t_c _p_u_b
     ## _c_h_o_w_n _r_o_o_t _b_i_n _e_t_c
     ## _c_h_m_o_d _5_5_5 _b_i_n _e_t_c
     ## _c_h_o_w_n _f_t_p _p_u_b
     ## _c_h_m_o_d _7_7_7 _p_u_b
     ## _c_d _b_i_n
     ## _c_p _/_b_i_n_/_s_h _/_b_i_n_/_l_s _.
     ## _c_h_m_o_d _1_1_1 _s_h _l_s
     ## _c_d _._._/_e_t_c
     ## _a_w_k _-_F_: _'_{_$_2_=_"_*_"_;_p_r_i_n_t_$_1_"_:_"_$_2_"_:_"_$_3_"_:_"_$_4_"_:_"_$_5_"_:_"_$_6_"_:_"_}_' _< _/_e_t_c_/_p_a_s_s_w_d _> _p_a_s_s_w_d
     ## _a_w_k _-_F_: _'_{_$_2_=_"_*_"_;_p_r_i_n_t_$_1_"_:_"_$_2_"_:_"_}_' _< _/_e_t_c_/_g_r_o_u_p _> _g_r_o_u_p
     ## _c_h_m_o_d _4_4_4 _p_a_s_s_w_d _g_r_o_u_p

When local users wish to place files in the anonymous  area,
they  must  be placed in a subdirectory.  In the setup here,
the directory ~ftp/pub is used.
     Aside from the problems of directory  modes  and  such,
the  ftp  server  may  provide a loophole for interlopers if
certain user accounts are allowed.  The  file  /etc/ftpusers
is  checked  on each connection.  If the requested user name
is located in the file, the request for service  is  denied.
This file normally has the following names on our systems.

     uucp
     root

Accounts  without  passwords need not be listed in this file
as the ftp  server  will  refuse  service  to  these  users.
Accounts   with   nonstandard  shells  (any  not  listed  in
/etc/shells) will also be denied access via ftp.

66..  SSyysstteemm ooppeerraattiioonn
     This section describes procedures  used  to  operate  a
4.4BSD  UNIX  system.   Procedures  described  here are used
periodically, to reboot the system, analyze  error  messages
from  devices,  do disk backups, monitor system performance,
recompile system software and control local changes.

66..11..  BBoooottssttrraapp aanndd sshhuuttddoowwnn pprroocceedduurreess
     In a normal reboot, the system  checks  the  disks  and
comes  up  multi-user  without  intervention at the console.
Such a reboot can be stopped (after it prints the date) with
a ^C (interrupt).  This will leave the system in single-user
mode, with only the console terminal active.  (If  the  con-
sole  has  been  marked  ``insecure''  in /etc/ttys you must
enter the root password to bring the machine to  single-user



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-73


mode.)   It  is also possible to allow the filesystem checks
to complete and then to return to single-user mode  by  sig-
naling _f_s_c_k(8) with a QUIT signal (^\).
     To  bring  the  system up to a multi-user configuration
from the single-user status, all you have to do is hit ^D on
the console.  The system will then execute /etc/rc, a multi-
user restart script (and /etc/rc.local), and come up on  the
terminals  listed  as  active  in  the  file /etc/ttys.  See
_i_n_i_t(8) and _t_t_y_s(5) Note, however, that this does not  cause
a  filesystem check to be done.  Unless the system was taken
down cleanly, you should run ``fsck -p'' or force  a  reboot
with _r_e_b_o_o_t(8) to have the disks checked.
     To  take the system down to a single user state you can
use

     ## _k_i_l_l _1

or use the _s_h_u_t_d_o_w_n(8) command (which is much  more  polite,
if  there  are  other  users logged in) when you are running
multi-user.  Either command will kill all processes and give
you  a  shell  on  the  console,  as if you had just booted.
Filesystems remain mounted after the system is taken single-
user.   If  you wish to come up multi-user again, you should
do this by:

     ## _c_d _/
     ## _/_s_b_i_n_/_u_m_o_u_n_t _-_a
     ## _^_D

     Each system shutdown, crash, processor halt and  reboot
is recorded in the system log with its cause.

66..22..  DDeevviiccee eerrrroorrss aanndd ddiiaaggnnoossttiiccss
     When serious errors occur on peripherals or in the sys-
tem, the system prints a warning diagnostic on the  console.
These  messages  are  collected  by the system error logging
process _s_y_s_l_o_g_d(8) and written into a system error log  file
/var/log/messages.  Less serious errors are sent directly to
_s_y_s_l_o_g_d, which may log them on the console.  The error  pri-
orities  that are logged and the locations to which they are
logged are controlled by /etc/syslog.conf.   See  _s_y_s_l_o_g_d(8)
for further details.
     Error messages printed by the devices in the system are
described with the drivers for the devices in section  4  of
the  programmer's  manual.  If errors occur suggesting hard-
ware problems, you  should  contact  your  hardware  support
group  or  field  service.  It is a good idea to examine the
error log file regularly (e.g.  with  the  command  _t_a_i_l  _-_r
_/_v_a_r_/_l_o_g_/_m_e_s_s_a_g_e_s).

66..33..  FFiilleessyysstteemm cchheecckkss,, bbaacckkuuppss,, aanndd ddiissaasstteerr rreeccoovveerryy
     Periodically (say every week or so in  the  absence  of
any  problems)  and  always  (usually automatically) after a
crash, all the filesystems should be checked for consistency



                        May 14, 1994





SMM:1-74                Installing and Operating 4.4BSD UNIX


by  _f_s_c_k(1).   The procedures of _r_e_b_o_o_t(8) should be used to
get the system to a state where a filesystem  check  can  be
done manually or automatically.
     Dumping  of  the  filesystems should be done regularly,
since once the system is going it is easy to become  compla-
cent.   Complete  and incremental dumps are easily done with
_d_u_m_p(8).  You should arrange to do  a  towers-of-hanoi  dump
sequence;  we  tune ours so that almost all files are dumped
on two tapes and kept for at least  a  week  in  most  every
case.  We take full dumps every month (and keep these indef-
initely).  Operators can execute ``dump w''  at  login  that
will  tell  them  what  needs  to  be  dumped  (based on the
/etc/fstab information).  Be sure to create a group ooppeerraattoorr
in  the  file  /etc/group  so that dump can notify logged-in
operators when it needs help.
     More precisely, we have three sets of  dump  tapes:  10
daily  tapes,  5  weekly  sets of 2 tapes, and fresh sets of
three tapes monthly.  We do daily dumps  circularly  on  the
daily tapes with sequence `3 2 5 4 7 6 9 8 9 9 9 ...'.  Each
weekly is a level  1  and  the  daily  dump  sequence  level
restarts after each weekly dump.  Full dumps are level 0 and
the daily sequence restarts after each full dump also.
     Thus a typical dump sequence would be:

 tape name   level number       date         opr      size
 ----------------------------------------------------------
   FULL           0         Nov 24, 1992   operator   137K
     D1           3         Nov 28, 1992   operator   29K
     D2           2         Nov 29, 1992   operator   34K
     D3           5         Nov 30, 1992   operator   19K
     D4           4          Dec 1, 1992   operator   22K
     W1           1          Dec 2, 1992   operator   40K
     D5           3          Dec 4, 1992   operator   15K
     D6           2          Dec 5, 1992   operator   25K
     D7           5          Dec 6, 1992   operator   15K
     D8           4          Dec 7, 1992   operator   19K
     W2           1          Dec 9, 1992   operator   118K
     D9           3         Dec 11, 1992   operator   15K
    D10           2         Dec 12, 1992   operator   26K
     D1           5         Dec 15, 1992   operator   14K
     W3           1         Dec 17, 1992   operator   71K
     D2           3         Dec 18, 1992   operator   13K
   FULL           0         Dec 22, 1992   operator   135K

We do weekly dumps often enough that daily dumps always  fit
on one tape.
     Dumping of files by name is best done by _t_a_r(1) but the
amount of data that can be moved in this way is limited to a
single  tape.   Finally  if  there  are enough drives entire
disks can be copied with _d_d(1) using the raw  special  files
and  an  appropriate  blocking factor; the number of sectors
per track is usually a good value to use, consult /etc/disk-
tab.




                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-75


     It  is desirable that full dumps of the root filesystem
be made regularly.  This is especially true  when  only  one
disk  is available.  Then, if the root filesystem is damaged
by a hardware or software failure, you can rebuild  a  work-
able  disk  doing a restore in the same way that the initial
root filesystem was created.
     Exhaustion of user-file space is certain to  occur  now
and  then;  disk  quotas  may be imposed, or if you prefer a
less fascist approach, try using the programs _d_u(1),  _d_f(1),
and  _q_u_o_t(8), combined with threatening messages of the day,
and personal letters.

66..44..  MMoovviinngg ffiilleessyysstteemm ddaattaa
     If you have the resources,  the  best  way  to  move  a
filesystem  is to dump it to a spare disk partition, or mag-
tape, using _d_u_m_p(8), use _n_e_w_f_s(8) to create the new filesys-
tem,  and restore the filesystem using _r_e_s_t_o_r_e(8).  Filesys-
tems may also be moved by  piping  the  output  of  _d_u_m_p  to
_r_e_s_t_o_r_e.  The _r_e_s_t_o_r_e program uses an ``in-place'' algorithm
that allows filesystem dumps to be restored without  concern
for  the original size of the filesystem.  Further, portions
of a filesystem may be selectively restored using  a  method
similar to the tape archive program.
     If  you have to merge a filesystem into another, exist-
ing one, the best bet is to use _t_a_r(1).  If you must  shrink
a  filesystem,  the  best  bet  is  to dump the original and
restore it onto the new filesystem.  If you are playing with
the  root  filesystem and only have one drive, the procedure
is more complicated.  If the  only  drive  is  a  Winchester
disk, this procedure may not be used without overwriting the
existing root or another partition.  What you do is the fol-
lowing:
1.   GET A SECOND PACK, OR USE ANOTHER DISK DRIVE!!!!
2.   Dump the root filesystem to tape using _d_u_m_p(8).
3.   Bring the system down.
4.   Mount  the new pack in the correct disk drive, if using
     removable media.
5.   Load the distribution tape and  install  the  new  root
     filesystem as you did when first installing the system.
     Boot normally using the newly created disk  filesystem.
     Note  that  if  you change the disk partition tables or
add new disk drivers they should also be added to the stand-
alone  system  in /sys/<architecture>/stand, and the default
disk partition tables in /etc/disktab should be modified.

66..55..  MMoonniittoorriinngg ssyysstteemm ppeerrffoorrmmaannccee
     The _s_y_s_t_a_t program provided with the system is designed
to be an aid to monitoring systemwide activity.  The default
``pigs'' mode shows a dynamic ``ps''.   By  running  in  the
``vmstat''  mode when the system is active you can judge the
system activity in  several  dimensions:  job  distribution,
virtual  memory  load,  paging and swapping activity, device
interrupts, and disk and CPU  utilization.   Ideally,  there
should  be  few  blocked  (b)  jobs,  there should be little



                        May 14, 1994





SMM:1-76                Installing and Operating 4.4BSD UNIX


paging or swapping activity, there should be available band-
width  on  the  disk  devices  (most single arms peak out at
20-30 tps in practice), and the user  CPU  utilization  (us)
should be high (above 50%).
     If  the  system  is busy, then the count of active jobs
may be large, and several of these jobs may often be blocked
(b).  If the virtual memory is active, then the paging demon
will be running (sr will be non-zero).  It  is  healthy  for
the  paging demon to free pages when the virtual memory gets
active; it is triggered by the amount of free  memory  drop-
ping below a threshold and increases its pace as free memory
goes to zero.
     If you run in the ``vmstat'' mode when  the  system  is
busy, you can find imbalances by noting abnormal job distri-
butions.  If many processes are blocked (b), then  the  disk
subsystem  is overloaded or imbalanced.  If you have several
non-DMA devices or open teletype lines that are ``ringing'',
or  user  programs  that  are  doing high-speed non-buffered
input/output, then the system time may go  high  (60-70%  or
higher).  It is often possible to pin down the cause of high
system time by looking to see if there is excessive  context
switching  (cs),  interrupt  activity  (in)  and  per-device
interrupt counts, or system  call  activity  (sy).   Cumula-
tively  on one of our large machines we average about 60-200
context switches and interrupts per second and about  50-500
system calls per second.
     If  the system is heavily loaded, or if you have little
memory for your load (2M is little in most any  case),  then
the  system  may  be  forced  to swap.  This is likely to be
accompanied by a noticeable reduction in system  performance
and  pregnant  pauses  when interactive jobs such as editors
swap out.  If you expect to be in a memory-poor  environment
for  an  extended period you might consider administratively
limiting system load.

66..66..  RReeccoommppiilliinngg aanndd rreeiinnssttaalllliinngg ssyysstteemm ssooffttwwaarree
     It  is easy to regenerate either the entire system or a
single utility, and it is a  good  idea  to  try  rebuilding
pieces  of the system to build confidence in the procedures.
In general, there are six well-known  targets  supported  by
all the makefiles on the system:
all      This entry is the default target, the same as if no
         target is specified.  This target builds  the  ker-
         nel,  binary  or library, as well as its associated
         manual pages.   This  target  ddooeess  nnoott  build  the
         dependency  files.   Some  of the utilities require
         that a _m_a_k_e _d_e_p_e_n_d be done before a  _m_a_k_e  _a_l_l  can
         succeed.
depend   Build    the    include   file   dependency   file,
         ``.depend'', which is read by _m_a_k_e.   See  _m_k_d_e_p(1)
         for further details.
install  Install  the  kernel, binary or library, as well as
         its associated manual pages.   See  _i_n_s_t_a_l_l(1)  for
         further details.



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-77


clean    Remove  the  kernel,  binary or library, as well as
         any object files created when building it.
cleandir The same as clean, except that the dependency files
         and formatted manual pages are removed as well.
obj      Build a shadow directory structure in the area ref-
         erenced by /usr/obj and create a symbolic  link  in
         the  current  source  directory  to  referenced it,
         named ``obj''.  Once this shadow structure has been
         created, all the files created by _m_a_k_e will live in
         the shadow structure, and /usr/src may  be  mounted
         read-only  by  multiple machines.  Doing a _m_a_k_e _o_b_j
         in /usr/src will build the shadow directory  struc-
         ture  for  everything  on the system except for the
         contributed, old, and kernel software.
     The system consists of three major  parts:  the  kernel
itself,  found  in  /usr/src/sys,  the  libraries , found in
/usr/src/lib, and the user programs (the rest of  /usr/src).
     Deprecated  software,  found in /usr/src/old, often has
old style makefiles; some  of  it  does  not  compile  under
4.4BSD at all.
     Contributed  software,  found in /usr/src/contrib, usu-
ally does  not  support  the  ``cleandir'',  ``depend'',  or
``obj'' targets.
     The  kernel  does not support the ``obj'' shadow struc-
ture.   All  kernels  are  compiled  in  subdirectories   of
/usr/src/sys/compile   which   is   usually  abbreviated  as
/sys/compile.  If you want to mount your source  tree  read-
only,  /usr/src/sys/compile  will  have  to be on a separate
filesystem from /usr/src.  Separation from /usr/src  can  be
done  by  making  /usr/src/sys/compile  a symbolic link that
references /usr/obj/sys/compile.  If it is a symbolic  link,
the  _S  variable in the kernel Makefile must be changed from
../..  to the absolute pathname needed to locate the  kernel
sources, usually /usr/src/sys.  The symbolic link created by
_c_o_n_f_i_g(8) for machine must also be manually  changed  to  an
absolute  pathname.   Finally,  the /usr/src/sys/libkern/obj
directory must be located in /usr/obj/sys/libkern.
     Each of the standard utilities  and  libraries  may  be
built and installed by changing directories into the correct
location and doing:

     ## _m_a_k_e
     ## _m_a_k_e _i_n_s_t_a_l_l

Note, if system include files have changed between compiles,
_m_a_k_e will not do the correct dependency checks if the depen-
dency files have not been built using the ``depend'' target.
     The entire library and utility suite for the system may
be recompiled from scratch by changing directory to /usr/src
and doing:

     ## _m_a_k_e _b_u_i_l_d

This  target  installs  the system include files, cleans the



                        May 14, 1994





SMM:1-78                Installing and Operating 4.4BSD UNIX


source tree, builds and installs the libraries,  and  builds
and installs the system utilities.
     To  recompile a specific program, first determine where
the binary resides with the _w_h_e_r_e_i_s(1) command, then  change
to  the corresponding source directory and build it with the
Makefile in  the  directory.   For  instance,  to  recompile
``passwd'', all one has to do is:

     ## _w_h_e_r_e_i_s _p_a_s_s_w_d
     //uussrr//bbiinn//ppaasssswwdd
     ## _c_d _/_u_s_r_/_s_r_c_/_u_s_r_._b_i_n_/_p_a_s_s_w_d
     ## _m_a_k_e
     ## _m_a_k_e _i_n_s_t_a_l_l

this will compile and install the _p_a_s_s_w_d utility.
     If  you wish to recompile and install all programs into
a particular target area you can override the  default  path
prefix by doing:

     ## _m_a_k_e
     ## _m_a_k_e _D_E_S_T_D_I_R_=pathname _i_n_s_t_a_l_l

Similarly, the mode, owner, group, and other characteristics
of the installed object can be modified  by  changing  other
default       make       variables.        See      _m_a_k_e(1),
/usr/src/share/mk/bsd.README, and the ``.mk'' scripts in the
/usr/share/mk directory for more information.
     If you modify the C library or system include files, to
change a system call for example, and want  to  rebuild  and
install  everything,  you  have to be a little careful.  You
must ensure that the include files are installed before any-
thing  is  compiled,  and  that  the libraries are installed
before the remainder of the  source,  otherwise  the  loaded
images  will  not  contain the new routine from the library.
If include files have been modified, the following  commands
should be done first:

     ## _c_d _/_u_s_r_/_s_r_c_/_i_n_c_l_u_d_e
     ## _m_a_k_e _i_n_s_t_a_l_l

Then,  if,  for example, C library files have been modified,
the following commands should be executed:

     ## _c_d _/_u_s_r_/_s_r_c_/_l_i_b_/_l_i_b_c
     ## _m_a_k_e _d_e_p_e_n_d
     ## _m_a_k_e
     ## _m_a_k_e _i_n_s_t_a_l_l
       ## _c_d _/_u_s_r_/_s_r_c
       ## _m_a_k_e _d_e_p_e_n_d
       ## _m_a_k_e
       ## _m_a_k_e _i_n_s_t_a_l_l

Alternatively, the _m_a_k_e _b_u_i_l_d command described  above  will
accomplish  the  same  tasks.  This takes several hours on a



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-79


reasonably configured machine.

66..77..  MMaakkiinngg llooccaall mmooddiiffiiccaattiioonnss
     The source for locally  written  commands  is  normally
stored  in  /usr/src/local,  and  their binaries are kept in
/usr/local/bin.  This isolation  of  local  binaries  allows
/usr/bin,  and  /bin  to correspond to the distribution tape
(and to the manuals that  people  can  buy).   People  using
local commands should be made aware that they are not in the
base manual.  Manual pages  for  local  commands  should  be
installed  in  /usr/local/man/cat[1-8].   The _m_a_n(1) command
automatically    finds    manual     pages     placed     in
/usr/local/man/cat[1-8]  to  encourage  this  practice  (see
_m_a_n_._c_o_n_f(5)).

66..88..  AAccccoouunnttiinngg
     UNIX optionally records two kinds of accounting  infor-
mation:   connect   time  accounting  and  process  resource
accounting.  The  connect  time  accounting  information  is
stored in the file /var/log/wtmp, which is summarized by the
program _a_c(8).  The process time accounting  information  is
stored  in the file /var/account/acct after it is enabled by
_a_c_c_t_o_n(8), and is analyzed and  summarized  by  the  program
_s_a(8).
     If  you  need  to  recharge for computing time, you can
develop procedures based  on  the  information  provided  by
these commands.  A convenient way to do this is to give com-
mands to the clock  daemon  /usr/sbin/cron  to  be  executed
every day at a specified time.  This is done by adding lines
to /etc/crontab.local; see _c_r_o_n(8) for details.

66..99..  RReessoouurrccee ccoonnttrrooll
     Resource control in the current version of UNIX is more
elaborate than in most UNIX systems.  The disk quota facili-
ties developed at the  University  of  Melbourne  have  been
incorporated in the system and allow control over the number
of files and amount of disk space each user and/or group may
use on each filesystem.  In addition, the resources consumed
by any single process can be limited by  the  mechanisms  of
_s_e_t_r_l_i_m_i_t(2).   As distributed, the latter mechanism is vol-
untary, though sites may choose to modify the  login  mecha-
nism to impose limits not covered with disk quotas.
     To  use  the  disk quota facilities, the system must be
configured with ``options QUOTA''.  Filesystems may then  be
placed  under  the  quota  mechanism by creating a null file
quota.user and/or quota.group at the root of the filesystem,
running _q_u_o_t_a_c_h_e_c_k(8), and modifying /etc/fstab to show that
the filesystem is to run with disk quotas (options userquota
and/or  groupquota).  The _q_u_o_t_a_o_n(8) program may then be run
to enable quotas.
     Individual quotas are applied by using the quota editor
_e_d_q_u_o_t_a(8).   Users  may view their quotas (but not those of
other users) with the _q_u_o_t_a(1) program. The _r_e_p_q_u_o_t_a(8) pro-
gram  may  be used to summarize the quotas and current space



                        May 14, 1994





SMM:1-80                Installing and Operating 4.4BSD UNIX


usage on a particular filesystem or filesystems.
     Quotas are enforced with _s_o_f_t and _h_a_r_d limits.  When  a
user  and/or group first reaches a soft limit on a resource,
a message is generated  on  their  terminal.   If  the  user
and/or  group  fails  to  lower the resource usage below the
soft limit for longer than the time  limit  established  for
that  filesystem (default seven days) the system then treats
the soft limit as a _h_a_r_d limit and disallows any allocations
until  enough  space  is  reclaimed to bring the user and/or
group back below the soft limit.  Hard limits  are  enforced
strictly  resulting in errors when a user and/or group tries
to create or write a  file.   Each  time  a  hard  limit  is
exceeded  the  system  will generate a message on the user's
terminal.
     Consult the auxiliary document, ``Disc Quotas in a UNIX
Environment'' (SMM:4) and the appropriate manual entries for
more information.

66..1100..  NNeettwwoorrkk ttrroouubblleesshhoooottiinngg
     If you have anything more than a trivial  network  con-
figuration,  from  time  to  time  you are bound to run into
problems.  Before blaming the  software,  first  check  your
network  connections.   On  networks  such as the Ethernet a
loose cable tap or misplaced power cable can result  in  se-
verely  deteriorated service.  The _n_e_t_s_t_a_t(1) program may be
of aid in tracking down hardware malfunctions.  In  particu-
lar, look at the --ii and --ss options in the manual page.
     Should  you  believe  a  communication protocol problem
exists, consult the protocol specifications and  attempt  to
isolate  the problem in a packet trace.  The SO_DEBUG option
may be  supplied  before  establishing  a  connection  on  a
socket,  in which case the system will trace all traffic and
internal actions (such as timers  expiring)  in  a  circular
trace  buffer.  This buffer may then be printed out with the
_t_r_p_t(8) program.  Most of the servers distributed  with  the
system  accept a --dd option forcing all sockets to be created
with debugging turned on.  Consult  the  appropriate  manual
pages for more information.

66..1111..  FFiilleess tthhaatt nneeeedd ppeerriiooddiicc aatttteennttiioonn
     We  conclude  the  discussion  of  system operations by
listing the files that require  periodic  attention  or  are
system specific:

/etc/fstab           how disk partitions are used
/etc/disktab         default disk partition sizes/labels
/etc/printcap        printer database
/etc/gettytab        terminal type definitions
/etc/remote          names and phone numbers of remote machines for _t_i_p(1)
/etc/group           group memberships
/etc/motd            message of the day
/etc/master.passwd   password file; each account has a line
/etc/rc.local        local system restart script; runs reboot; starts daemons




                        May 14, 1994





Installing and Operating 4.4BSD UNIX                SMM:1-81


/etc/inetd.conf      local internet servers
/etc/hosts           local host name database
/etc/networks        network name database
/etc/services        network services database
/etc/hosts.equiv     hosts under same administrative control
/etc/syslog.conf     error log configuration for _s_y_s_l_o_g_d(8)
/etc/ttys            enables/disables ports
/etc/crontab         commands that are run periodically
/etc/crontab.local   local commands that are run periodically
/etc/aliases         mail forwarding and distribution groups
/var/account/acct    raw process account data
/var/log/messages    system error log
/var/log/wtmp        login session accounting












































                        May 14, 1994





SMM:1-2                 Installing and Operating 4.4BSD UNIX



                     TTaabbllee ooff CCoonntteennttss


1.    Introduction . . . . . . . . . . . . . . . . . . .   4
1.1.  Distribution format  . . . . . . . . . . . . . . .   4
1.2.  UNIX device naming . . . . . . . . . . . . . . . .   4
1.3.  UNIX devices: block and raw  . . . . . . . . . . .   5
2.    Bootstrap procedure  . . . . . . . . . . . . . . .   6
2.1.  Bootstrapping from the tape  . . . . . . . . . . .   6
2.2.  Booting the HP300  . . . . . . . . . . . . . . . .   7
2.2.1.Supported hardware . . . . . . . . . . . . . . . .   7
2.2.2.Standalone device file naming  . . . . . . . . . .   8
2.2.3.The procedure  . . . . . . . . . . . . . . . . . .   8
2.2.3.1.Step 1: selecting and formatting a disk  . . . .   8
2.2.3.2.Step 2: copying the root filesystem from
tape to disk . . . . . . . . . . . . . . . . . . . . . .   9
2.2.3.3.Step 3: booting the root filesystem  . . . . . .  10
2.2.3.4.Step 4: (optional) restoring the root
filesystem . . . . . . . . . . . . . . . . . . . . . . .  12
2.2.3.5.Step 5: placing labels on the disks  . . . . . .  13
2.3.  Booting the SPARC  . . . . . . . . . . . . . . . .  14
2.3.1.Supported hardware . . . . . . . . . . . . . . . .  14
2.3.2.Limitations  . . . . . . . . . . . . . . . . . . .  14
2.3.3.The procedure  . . . . . . . . . . . . . . . . . .  15
2.4.  Booting the DECstation . . . . . . . . . . . . . .  16
2.4.1.Supported hardware . . . . . . . . . . . . . . . .  16
2.4.2.The procedure  . . . . . . . . . . . . . . . . . .  17
2.4.2.1.Procedure A: copy root filesystem to disk  . . .  18
2.4.2.2.Procedure B: bootstrap from tape . . . . . . . .  18
2.4.2.3.Procedure C: bootstrap over the network  . . . .  18
2.4.3.Label disk and create the root filesystem  . . . .  19
2.5.  Disk configuration . . . . . . . . . . . . . . . .  20
2.5.1.Disk naming and divisions  . . . . . . . . . . . .  20
2.5.2.Layout considerations  . . . . . . . . . . . . . .  21
2.5.3.Filesystem parameters  . . . . . . . . . . . . . .  22
2.5.4.Implementing a layout  . . . . . . . . . . . . . .  24
2.6.  Installing the rest of the system  . . . . . . . .  25
2.7.  Additional conversion information  . . . . . . . .  29
3.    Upgrading a 4.3BSD system  . . . . . . . . . . . .  29
3.1.  Installation overview  . . . . . . . . . . . . . .  30
3.2.  Files to save  . . . . . . . . . . . . . . . . . .  31
3.3.  Installing 4.4BSD  . . . . . . . . . . . . . . . .  32
3.4.  Merging your files from 4.3BSD into 4.4BSD . . . .  36
3.4.1.Changes in the /etc directory  . . . . . . . . . .  37
3.4.2.Shadow password files  . . . . . . . . . . . . . .  40
3.4.3.The /var filesystem  . . . . . . . . . . . . . . .  40
3.5.  Bug fixes and changes between 4.3BSD and
4.4BSD . . . . . . . . . . . . . . . . . . . . . . . . .  41
3.5.1.Changes to the kernel  . . . . . . . . . . . . . .  42
3.5.2.Security . . . . . . . . . . . . . . . . . . . . .  42
3.5.2.1.Virtual memory changes . . . . . . . . . . . . .  43
3.5.2.2.Networking additions and changes . . . . . . . .  44
3.5.2.3.Additions and changes to filesystems . . . . . .  45



                        May 14, 1994





Installing and Operating 4.4BSD UNIX                 SMM:1-3


3.5.2.4.POSIX terminal driver changes  . . . . . . . . .  48
3.5.2.5.Native operating system compatibility  . . . . .  48
3.5.3.Changes to the utilities . . . . . . . . . . . . .  49
3.5.3.1.Make and Makefiles . . . . . . . . . . . . . . .  49
3.5.3.2.Kerberos . . . . . . . . . . . . . . . . . . . .  50
3.5.3.3.Timezone support . . . . . . . . . . . . . . . .  50
3.5.3.4.Additions and changes to the libraries . . . . .  51
3.5.3.5.Additions and changes to other utilities . . . .  52
3.6.  Hints on converting from 4.3BSD to 4.4BSD  . . . .  54
4.    System setup . . . . . . . . . . . . . . . . . . .  55
4.1.  Kernel configuration . . . . . . . . . . . . . . .  55
4.1.1.Kernel organization  . . . . . . . . . . . . . . .  55
4.1.2.Devices and device drivers . . . . . . . . . . . .  57
4.1.3.Building new system images . . . . . . . . . . . .  57
4.2.  Configuring terminals  . . . . . . . . . . . . . .  58
4.3.  Adding users . . . . . . . . . . . . . . . . . . .  59
4.4.  Site tailoring . . . . . . . . . . . . . . . . . .  60
4.5.  Setting up the line printer system . . . . . . . .  60
4.6.  Setting up the mail system . . . . . . . . . . . .  61
4.6.1.Setting up a UUCP connection . . . . . . . . . . .  62
5.    Network setup  . . . . . . . . . . . . . . . . . .  64
5.1.  System configuration . . . . . . . . . . . . . . .  65
5.2.  Local subnets  . . . . . . . . . . . . . . . . . .  66
5.3.  Internet broadcast addresses . . . . . . . . . . .  67
5.4.  Routing  . . . . . . . . . . . . . . . . . . . . .  67
5.5.  Use of 4.4BSD machines as gateways . . . . . . . .  69
5.6.  Network databases  . . . . . . . . . . . . . . . .  69
5.6.1.Network servers  . . . . . . . . . . . . . . . . .  70
5.6.2.Internet daemon  . . . . . . . . . . . . . . . . .  70
5.6.3.The /etc/hosts.equiv file  . . . . . . . . . . . .  71
5.6.4.The /etc/ftpusers file . . . . . . . . . . . . . .  71
6.    System operation . . . . . . . . . . . . . . . . .  72
6.1.  Bootstrap and shutdown procedures  . . . . . . . .  72
6.2.  Device errors and diagnostics  . . . . . . . . . .  73
6.3.  Filesystem checks, backups, and disaster
recovery . . . . . . . . . . . . . . . . . . . . . . . .  73
6.4.  Moving filesystem data . . . . . . . . . . . . . .  75
6.5.  Monitoring system performance  . . . . . . . . . .  75
6.6.  Recompiling and reinstalling system software
 . . . . . . . . . . . . . . . . . . . . . . . . . . . .  76
6.7.  Making local modifications . . . . . . . . . . . .  79
6.8.  Accounting . . . . . . . . . . . . . . . . . . . .  79
6.9.  Resource control . . . . . . . . . . . . . . . . .  79
6.10. Network troubleshooting  . . . . . . . . . . . . .  80
6.11. Files that need periodic attention . . . . . . . .  80












                        May 14, 1994


