MirOS Manual: 01.setup(SMM)

April 27, 2013

SMM:1-4 Installing and Operating 4.4BSD UNIX

Installing and Operating 4.4BSD UNIX
July 27, 1993

Marshall Kirk McKusick

Keith Bostic

Michael J. Karels

Samuel J. Leffler

Computer Systems Research Group
Department of Electrical Engineering and Computer Science
University of California, Berkeley
Berkeley, California 94720
(415) 642-7780

Mike Hibler

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

ABSTRACT

This document contains instructions for the
installation and operation of the 4.4BSD release
of UNIX[1] as distributed by The University of
California 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 explana-
tion 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-
_________________________
[1]
[1] UNIX is a registered trademark of USL in the USA
and some other countries.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-5

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 pro-
cedures, resource control, performance monitoring,
and procedures for recompiling and reinstalling
system software.

July 27, 1993

SMM:1-6 Installing and Operating 4.4BSD UNIX

1. Introduction
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 com-
pletely 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 pro-
cedure 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.

1.1. Distribution format
The distribution comes in two formats:

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

If you have the facilities, we strongly 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) con-
tain tape archive images of the system binaries and sources
(see tar(1)[2]). See the tape label for a description of the
contents and format of each individual tape.

1.2. UNIX device naming
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
_________________________
[2] References of the form X(Y) mean the entry named
X in section Y of the ``UNIX Programmer's Manual''.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-7

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. disktab(5)). The partition information and description
of the drive geometry are written in one of the first sec-
tors of each disk with the disklabel(8) program. Each par-
tition may be used for either a raw data area such as a pag-
ing area or to store a UNIX filesystem. It is conventional
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.

1.3. UNIX devices: block and raw
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.
You should be aware that it is sometimes important

July 27, 1993

SMM:1-8 Installing and Operating 4.4BSD UNIX

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.

2. Bootstrap procedure
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:
+ Intel 386/486-based machines (ISA/AT or EISA bus only)
+ Sony News MIPS-based workstations
+ 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 dis-
tribution does not include the machine support for the Tahoe
and VAX architectures found in previous BSD distributions.
Our primary development environment is the HP9000/300 series
machines. The other architectures are developed and sup-
ported by people outside the university. Consequently, we
are not able to directly test or maintain these other archi-
tectures, so cannot comment on their robustness, reliabil-
ity, or completeness.

2.1. Bootstrapping from the tape
The set of files on the distribution tape are as follows:
1) A dd(1) (HP300), tar(1) (DECstation), or dump(8)
(SPARC) image of the root filesystem
2) A tar image of the /var filesystem
3) A tar image of the /usr filesystem
4) A tar image of /usr/src/sys
5) A tar image of /usr/src except sys and contrib
6) A tar image of /usr/src/contrib
7) (8mm Exabyte tape distributions only) A tar 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 tar(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 architec-
tures. The specific steps for the HP300, SPARC, and

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-9

DECstation are given in the next three sections respec-
tively. You should follow the instructions for your particu-
lar architecture. In all sections, commands you are expected
to type are shown in italics, while that information printed
by the system is shown emboldened.

2.2. Booting the HP300

2.2.1. Supported hardware
The hardware supported by 4.4BSD for the HP300/400 is as
follows:

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

July 27, 1993

SMM:1-10 Installing and Operating 4.4BSD UNIX

displays.

2.2.2. Standalone device file naming
The standalone system device name syntax on the HP300 is of
the form:

xx(a,c,u,p)

where xx is the device type, a specifies the adaptor to use,
c the controller, u the unit, and p a partition. The device
type 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 adaptor 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 controller 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 unit field is unused and
should be 0. The partition 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 con-
troller 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.

2.2.3. The procedure
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 disklabel(8) program.

2.2.3.1. Step 1: selecting and formatting a disk
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. If you

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-11

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 primary
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 mediainit(1m) program. Once
you have 4.4BSD up and running on one machine you can use
the scsiformat(8) program to format additional SCSI disks.
Any additional HP-IB disks will have to be formatted using
HP-UX.

2.2.3.2. Step 2: copying the root filesystem from tape to
disk
Once you have a formatted second disk you can use the
dd(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 mt(7) and disk(7) man pages for details.
Note that if you have a SCSI disk, you don't neces-
sarily 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 stan-
dalone 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

July 27, 1993

SMM:1-12 Installing and Operating 4.4BSD UNIX

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

From: ^C (control-C to see logical adaptor assignments)
hpib0 at sc7
scsi0 at sc14
From: ct(0,7,0,0) (HP-IB tape, target 7, first tape file)
To: sd(0,0,0,2) (SCSI disk, target 0, third partition)
Copy completed: 1728 records copied

This copy will likely take 30 minutes or more.

2.2.3.3. Step 3: booting the root filesystem
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 eliminate 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:

HP433 CPU
Boot
: /vmunix

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

597480+34120+139288 start 0xfe8019ec
Copyright (c) 1982, 1986, 1989, 1991, 1993
The Regents of the University of California.
Copyright (c) 1992 Hewlett-Packard Company
Copyright (c) 1992 Motorola Inc.
All rights reserved.

4.4BSD UNIX #1: Tue Jul 20 11:40:36 PDT 1993
mckusick@vangogh.CS.Berkeley.EDU:/usr/obj/sys/compile/GENERIC.hp300
HP9000/433 (33MHz MC68040 CPU+MMU+FPU, 4k on-chip physical I/D caches)
real mem = xxx
avail mem = ###
using ### buffers containing ### bytes of memory
(... information about available devices ...)
root device?

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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-13

it 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 mem 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
memory, then xxx will be 16777216.
The messages that come out next show what devices were
found on the current processor. These messages are
described in autoconf(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 generic 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.

root device? sd0
WARNING: preposterous time in filesystem -- CHECK AND RESET THE DATE!
erase ^?, kill ^U, intr ^C
#

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 UNIX Programmer's Manual
applies. The ``#'' is the prompt from the Bourne shell, and
lets you know that you are the super-user, whose login name

July 27, 1993

SMM:1-14 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:

# mount_mfs -s 1000 -T type /dev/null /tmp (create a writable filesystem)
(type is the disk type as determined from /etc/disktab)
# cd /tmp (connect to that directory)
# ../dev/MAKEDEV sd# (create special files for root disk)
(sd is the disk type, # is the unit number)
(ignore warning from ``sh'')
# mount -uw /tmp/sd#a / (read-write mount root filesystem)
# cd /dev (go to device directory)
# ./MAKEDEV sd# (create permanent special files for root disk)
(again, ignore warning from ``sh'')

2.2.3.4. Step 4: (optional) restoring the root filesystem
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 clon-
ing 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
bootstrapped 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:

# cd /dev
# ./MAKEDEV sd1a
#newfs /dev/rsd1a
#mount /dev/sd1a /mnt
#cd /mnt
#dump 0f - /dev/rsd0a | restore xf -
(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.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-15

2.2.3.5. Step 5: placing labels on the disks
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 diskla-
bel(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 ed(1).
If you choose to edit this label, you can fill in
correct 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 disklabel
will not let you, modify the ``a'', ``b'' and ``d'' parti-
tions. To edit a label:

# EDITOR=ed
# export EDITOR
# disklabel -r -e /dev/rXX#d

where XX 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:

#disklabel -rw XX# type "optional_pack_name"

where XX# is the same as in the previous command and type 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/disktab before labeling the affected disks.
You have now completed the HP300 specific part of the
installation. Now proceed to the generic part of the instal-
lation 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 running on
an HP-IB disk. Also, if you are loading on a single disk

July 27, 1993

SMM:1-16 Installing and Operating 4.4BSD UNIX

with the default disklabel, /var should be restored to the
``f'' partition and /usr to the ``e'' partition.

2.3. Booting the SPARC

2.3.1. Supported hardware
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 and cgthree. |
|______________________________________________________|
| 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 GX (cgsix) display, the floppy disk, and SCSI
tapes.

2.3.2. Limitations
There are several important limitations on the 4.4BSD dis-
tribution for the SPARC:
1) You must 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 0 lun 0 and put 4.4BSD on the disk on target 3 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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-17

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.

2.3.3. The procedure
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 newfs to build the root filesystem. You
may also want to build other filesystems at the same
time. (By default, the 4.4BSD newfs 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 compa-
tibility.) You can build an old-format filesystem on
4.4BSD by giving the -O option to newfs(8). Fsck(8) can
convert old format filesystems to new format filesys-
tems, 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, you must build an
old-style root filesystem so that the SunOS boot pro-
gram 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.
5) Restore the contents of the 4.4BSD root filesystem.

July 27, 1993

SMM:1-18 Installing and Operating 4.4BSD UNIX

# 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.

2.4. Booting the DECstation

2.4.1. Supported hardware
The hardware supported by 4.4BSD for the DECstation is as
follows:

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-19

_______________________________________________________
| 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.

2.4.2. The procedure
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: dd image of the root filesystem
B) vmunix.tape: dd image for creating boot tapes
C) vmunix.net: file for booting over the network
D) root.dump: dump image of the root filesystem

There are three basic ways a system can be bootstrapped
corresponding 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 use-
ful.

July 27, 1993

SMM:1-20 Installing and Operating 4.4BSD UNIX

2.4.2.1. Procedure A: copy root filesystem to disk
This procedure is similar to the HP300. If you have an
extra disk, the easiest approach is to use dd(1) under
ULTRIX to copy the root filesystem image to the beginning of
the spare disk. The root filesystem image includes a diskla-
bel 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 sys-
tem 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.

2.4.2.2. Procedure B: bootstrap from tape
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 dd 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.

2.4.2.3. Procedure C: bootstrap over the network
You will need a host machine that is running the bootp
server with the vmunix.net file installed in the default
directory defined by the configuration file for bootp. Here

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-21

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
memory 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
following 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.

2.4.3. Label disk and create the root filesystem
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:

July 27, 1993

SMM:1-22 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''.

2.5. Disk configuration
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.

2.5.1. Disk naming and divisions
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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-23

section 2.5.4 for further details on disk layouts.
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 sectors[3]. The /etc/disktab file used in
labelling disks and making filesystems specifies disk parti-
tion sizes in sectors.

2.5.2. Layout considerations
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 maxim-
ized. 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 dif-
ferent 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 mount_mfs(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 filesys-
tem 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:

_________________________
[3] You can thank System V intransigence and POSIX
duplicity for requiring that 512-byte blocks be the un-
its that programs report.

July 27, 1993

SMM:1-24 Installing and Operating 4.4BSD UNIX

_________________________________
| | disks |
| 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 important things to consider are 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.

2.5.3. Filesystem parameters
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 distri-
buted, 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 optim-
ize 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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-25

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
currently 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. However,
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 com-
parison, 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

July 27, 1993

SMM:1-26 Installing and Operating 4.4BSD UNIX

acceptable free space 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 nominally set to 5%; it may be changed by
supplying a parameter to newfs(8), or by updating the super
block of an existing filesystem using tunefs(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 implementa-
tion 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 newfs(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; newfs 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 newfs.

2.5.4. Implementing a layout
To put a chosen disk layout into effect, you should use
the newfs(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
bootstrapped.
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 addi-
tion of a memory-based /tmp filesystem, its fstab entry
would be as follows:

/dev/sd0a / ufs rw 1 1

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-27

/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 parti-
tion can be used for /usr/src or alternately the sd0e parti-
tion can be extended to cover the rest of the disk with
disklabel(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:

# cd /dev
# MAKEDEV sd1
# disklabel -wr sd1 "disk type" "disk name"
# newfs sd1f
(information about filesystem prints out)
# mkdir /var
# mount /dev/sd1f /var

2.6. Installing the rest of the system
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 rsh(1). For example, for
a directly connected tape drive you might do:

July 27, 1993

SMM:1-28 Installing and Operating 4.4BSD UNIX

# mt -f /dev/nrmt0 fsf
# tar xbpf 20 /dev/nrmt0

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

# rsh foo mt -f /dev/nrmt0 fsf
# rsh foo dd if=/dev/nrmt0 bs=20b | tar xbpf 20 -

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

# 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

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 infor-
mation on setting up the network.
Assuming a directly connected tape drive, here is how
to extract and install /var and /usr:

# mount -uw /dev/sd#a / (read-write mount root filesystem)
# date yymmddhhmm (set date, see date(1))
....
# passwd -l root (set password for super-user)
New password: (password will not echo)
Retype new password:
# passwd -l toor (set password for super-user)
New password: (password will not echo)
Retype new password:
# hostname mysitename (set your hostname)
# newfs rsd#p (create empty user filesystem)
(sd is the disk type, # is the unit number,
p is the partition; this takes a few minutes)
# mount /dev/sd#p /var (mount the var filesystem)
# cd /var (make /var the current directory)
# mt -f /dev/nrmt0 fsf (space to end of previous tape file)
# tar xbpf 20 /dev/nrmt0 (extract all of var)
(this takes a few minutes)
# newfs rsd#p (create empty user filesystem)
(as before sd is the disk type, # is the unit number,
p is the partition)
# mount /dev/sd#p /mnt (mount the new /usr in temporary location)
# cd /mnt (make /mnt the current directory)
# mt -f /dev/nrmt0 fsf (space to end of previous tape file)
# tar xbpf 20 /dev/nrmt0 (extract all of usr except usr/src)
(this takes about 15-20 minutes)
# cd / (make / the current directory)
# umount /mnt (unmount from temporary mount point)

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-29

# rm -r /usr/* (remove excess bootstrap binaries)
# mount /dev/sd#p /usr (remount /usr)

If no disk label has been installed on the disk, the newfs
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 tar,
to extract /var it may be repositioned by the following com-
mands.

# mt -f /dev/nrmt0 rew
# mt -f /dev/nrmt0 fsf 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 contin-
ues 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:

# newfs sd0f
(information about filesystem prints out)
# mkdir /usr/src
# mount /dev/sd0f /usr/src

First you will extract the kernel source:

# cd /usr/src
# mt -f /dev/nrmt0 fsf (space to end of previous tape file)
(this should only be done on Exabyte distributions)
# tar xpbf 20 /dev/nrmt0 (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:

# cd /usr/src
# mt -f /dev/nrmt0 fsf (space to end of previous tape file)
# tar xpbf 20 /dev/rmt12 (extract the utility source)
(this takes about 30-60 minutes)

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.

July 27, 1993

SMM:1-30 Installing and Operating 4.4BSD UNIX

The next tar file contains the sources for the contri-
buted software. It is extracted as follows:

# cd /usr/src
# mt -f /dev/nrmt0 fsf (space to end of previous tape file)
(this should only be done on Exabyte distributions)
# tar xpbf 20 /dev/rmt12 (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 tar(1) format. As distributed, X11R5
should be placed in /usr/src/X11R5.

# cd /usr/src
# mt -f /dev/nrmt0 fsf (space to end of previous tape file)
# tar xpbf 20 /dev/nrmt0 (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 con-
sistent. To do so, you must unmount it, and run fsck(8);
assuming that you used sd0f you would proceed as follows:

# cd / (change directory, back to the root)
# umount /usr/src (unmount /usr/src)
# fsck /dev/rsd0f

The output from fsck should look something like:

** /dev/rsd0f
** Last Mounted on /usr/src
** Phase 1 - Check Blocks and Sizes
** Phase 2 - Check Pathnames
** Phase 3 - Check Connectivity
** Phase 4 - Check Reference Counts
** Phase 5 - Check Cyl groups
23000 files, 261000 used, 39000 free (2200 frags, 4600 blocks)

If there are inconsistencies in the filesystem, you may
be prompted to apply corrective action; see the fsck(8) or
Fsck The UNIX File System Check Program (SMM:3) for more
details.
To use the /usr/src filesystem, you should now remount

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-31

it with:

# mount /dev/sd0f /usr/src

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

# mount /usr/src

2.7. Additional conversion information
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 restore 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:

# mkdir /a
# newfs sd#p
# mount /dev/sd#p /a
# cd /a
# restore x

If tar 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 fsck(8) when the
job is complete.

3. Upgrading a 4.3BSD system
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. network-
ing 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

July 27, 1993

SMM:1-32 Installing and Operating 4.4BSD UNIX

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.

3.1. Installation overview
If you are running 4.3BSD, upgrading your system
involves replacing your kernel and system utilities. In gen-
eral, 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 confi-
guration 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 general,
older binaries will continue to run under 4.4BSD, but there
are many exceptions that are on the critical path for get-
ting the system running. Ideally, the new system binaries
(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 fsck should be run before they are
mounted.
It is STRONGLY 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
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.)

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-33

See mount_mfs(8).
The recommended installation procedure includes the
following steps. The order of these steps will probably vary
according to local needs.
+ Extract root and /usr filesystems from the distribution
tapes.
+ Extract kernel and/or user-level sources from the dis-
tribution tape if space permits. This can serve as the
backup documentation as needed.
+ 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.
+ Build a skeletal /var filesystem (see mtree(8)).
+ 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.
+ Copy or merge files from /usr/adm, /usr/spool,
/usr/preserve, /usr/lib, and other locations into /var.
+ Merge local macros, dictionaries, etc. into /usr/share.
+ Merge and update local software to reflect the system
changes.
+ 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 pro-
cess. Section 3.4 discusses the merger of the saved files
back into the new system. Section 3.5 gives an overview 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.

3.2. Files to save
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 tar 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
/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

July 27, 1993

SMM:1-34 Installing and Operating 4.4BSD UNIX

/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.

3.3. Installing 4.4BSD
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
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 partitions
that may be used. It is also desirable to run filesystem
checks of all filesystems to be converted to 4.4BSD before

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-35

shutting down. In any case, this is an excellent time to
review your disk configuration for possible tuning of the
layout. Section 2.5 and config(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 direc-
tories:

/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 direc-
tories:

/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:

/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)

July 27, 1993

SMM:1-36 Installing and Operating 4.4BSD UNIX

/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 direc-
tories:

/var/account (accounting files, formerly /usr/adm)
/var/at (at(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 partition,
it will be used as the initial swap area, otherwise the nor-
mal 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 filesys-
tems to 4.4BSD, you must install a new bootstrap before
doing the conversion. Note that SPARC users cannot build a
4.4BSD compatible version of the bootstrap, so must not con-
vert 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
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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-37

partition tables in the kernel. Make the necessary table
changes and boot your custom kernel BEFORE 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 fsck(8) on each filesystem and
allowing it to make the necessary corrections. The new ver-
sion of fsck 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:

DIRECTORY ...: LENGTH xx NOT MULTIPLE OF 512 (ADJUSTED)

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

IMPOSSIBLE INTERLEAVE=0 IN SUPERBLOCK (SET TO DEFAULT)[4]
IMPOSSIBLE NPSECT=0 IN SUPERBLOCK (SET TO DEFAULT)

Filesystems that have had their interleave and npsect values
set will be diagnosed by the old fsck as having a bad super-
block; the old fsck will run only if given an alternate
superblock (fsck -b32), 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 -b32
option may be necessary for running the old fsck.
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 fsck with the -c 2
option. The sequence fsck -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
fsck -c 1.

3.4. Merging your files from 4.3BSD into 4.4BSD
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
_________________________
[4] The defaults are to set interleave to 1 and
npsect to nsect. This is correct on most drives; it af-
fects only performance (usually virtually unmeasur-
ably).

July 27, 1993

SMM:1-38 Installing and Operating 4.4BSD UNIX

process, merging your old files into the new system.
If you saved the files on a tar tape, extract them into
a scratch directory, say /usr/convert:

# mkdir /usr/convert
# cd /usr/convert
# tar xp

The data files marked in the previous table with a
dagger (-) 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 aster-
isk (*) 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 des-
tination 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
corresponding 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 hier(7)
has been updated and made more detailed; it is included in
the printed documentation. You should review it to familiar-
ize yourself with the new layout.
A new utility, mtree(8), is provided to build and check
filesystem hierarchies with the proper contents, owners and
permissions. Scripts are provided in /etc/mtree (and
/usr/src/etc/mtree) for the root, /usr and /var filesystems.
Once a filesystem has been made for /var, mtree 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.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-39

3.4.1. Changes in the /etc directory
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 confi-
guration 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 dm(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 man(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
/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
_________________________________________________________________

July 27, 1993

SMM:1-40 Installing and Operating 4.4BSD UNIX

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 su 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''. Standard
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 talkd and write
now run set-group-id to ``tty''. The ``operator'' group con-
trols access to disks. By default, disks are readable by
group ``operator'', so that programs such as dump can access
the filesystem information without being set-user-id to
``root''. The shutdown(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 at programs now run set-user-id ``root''
instead of ``daemon.'' Also, the uucp directory no longer
needs to be publicly writable, as tip reverts to privileged
status to remove its lock files. After copying your version
of /var/spool, you should do:

# chown -R root /var/spool/at
# chown -R uucp:daemon /var/spool/uucp
# chmod -R o-w /var/spool/uucp

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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-41

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 ifconfig
has had many changes, and that host names are now fully
specified as domain-style names (e.g.,
vangogh.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:

+ Syntax errors in the password and group files.
+ Duplicate user and group names and id's.
+ Dangerous search paths and umask values for the superuser.
+ Dangerous values in various initialization files.
+ Dangerous .rhosts files.
+ Dangerous directory and file ownership or permissions.
+ Globally exported filesystems.
+ 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
binaries are checksummed and their permissions validated
against the mtree(8) specifications in /etc/mtree.
The C-library and system binaries on the distribution
tape are compiled with new versions of gethostbyname and
gethostbyaddr that use the name server, named(8). If you
have only a small network and are not connected to a large
network, you can use the distributed library routines
without 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
gethostname to determine the local domain name.
If you are using the name server, your sendmail confi-
guration file will need some updates to accommodate it. See
the ``Sendmail Installation and Operation Guide'' (SMM:8)
and the sample sendmail configuration files in
/usr/src/usr.sbin/sendmail/cf. The aliases file,
/etc/aliases has also been changed to add certain well-known
addresses.

3.4.2. Shadow password files
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

July 27, 1993

SMM:1-42 Installing and Operating 4.4BSD UNIX

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 getpwnam() and
getpwuid() 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 vipw(8) and
pwd_mkdb(8) programs. See also passwd(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 having
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 pwd_mkdb(8) to create the password database. Note that
pwd_mkdb(8) is run whenever vipw(8) is run.

3.4.3. The /var filesystem
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 tar(1) so that files are
recreated with the same file modes. The following commands
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 -)

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-43

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

# everything else in spool is probably a printer area
mkdir .save
mv at ftp mail mqueue rwho secretmail 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

3.5. Bug fixes and changes between 4.3BSD and 4.4BSD
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 redistribut-
able implementation of NFS, a log-structured filesystem,
enhancement of the local filesystems to support files 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

July 27, 1993

SMM:1-44 Installing and Operating 4.4BSD UNIX

structure and process structure have been reorganized 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.

3.5.1. Changes to the kernel
This release includes several important structural ker-
nel changes. The kernel uses a new internal system call con-
vention; the use of global (``u-dot'') variables for parame-
ters and error returns has been eliminated, and interrupted
system calls no longer abort using non-local goto's
(longjmp's). A new sleep interface separates signal handling
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
(tsleep) can be used at any priority, but is only interrup-
tible if the PCATCH flag is set. When interrupted, tsleep
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,
sysctl(8), retrieves kernel state and allows processes with
appropriate privilege to set kernel state.

3.5.2. Security
The kernel runs with four different levels of security.
Any superuser process can raise the security level, but only
init()(8) can lower it. Security levels are defined as fol-
lows:
-1 Permanently insecure mode - always run system in level
0 mode.
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 unmounting
them, but also inhibits running newfs(8) while the

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-45

system is multi-user. See chflags(1) and the -o option
to ls(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 sysctl(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.

3.5.2.1. Virtual memory changes
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
Programmer'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 function-
ally complete, but still has serious performance problems
under heavy memory load. The internal kernel interfaces have
not yet been completed and the memory pool and buffer cache
have not been merged. Some additional caveats:
+ 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.
+ 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.
+ 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.
+ The semantics of the vfork(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 compatibil-
ity, but newer code should just use fork(2).

July 27, 1993

SMM:1-46 Installing and Operating 4.4BSD UNIX

3.5.2.2. Networking additions and changes
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
(hardware-compatible with Ethernet[5]). We also include sup-
port 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
development environment are file transfer and management
(FTAM), virtual terminals (VT), a directory services imple-
mentation (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
iso(4) manual page describes the protocols and addressing;
see also clnp(4), tp(4) and cltp(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 route(8) command. Additional information
is provided in the manual page describing esis(4).
The command route(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 sockaddr 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 sa_family family field has been split
into a length, sa_len, and a family, sa_family. System calls
that pass a sockaddr structure into the kernel (e.g.
sendto() and connect()) have a separate parameter that
specifies the sockaddr length, and thus it is not necessary
to fill in the sa_len field for those system calls. System
calls that pass a sockaddr structure back from the kernel
(e.g. recvfrom() and accept()) receive a completely filled-
in sockaddr 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 net-
working programs compiled under 4.4BSD are incompatible with
_________________________
[5] Ethernet is a trademark of the Xerox Corporation.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-47

older systems.
Although this change is mostly source and binary compa-
tible with old programs, there are three exceptions. Pro-
grams with statically initialized sockaddr structures (usu-
ally the Internet form, a sockaddr_in) 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 sockaddr structures also
require change; a definition of an osockaddr 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 sa_len 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).

3.5.2.3. Additions and changes to filesystems
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 interface
has been extended with support for stackable filesystems
done at UCLA. These extensions allow for filesystems to be
layered on top of each other and allow new vnode operations
to be added without requiring changes to existing filesystem
implementations. For example, the umap filesystem (see
mount_umap(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 filesystem on removable
media brought from some foreign location that uses a dif-
ferent password file.
Other new filesystems that may be stacked include the
loopback filesystem mount_lofs(8), the kernel filesystem
mount_kernfs(8), and the portal filesystem mount_portal(8).
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
corresponding block device would no longer be kept con-
sistent. 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

July 27, 1993

SMM:1-48 Installing and Operating 4.4BSD UNIX

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 fsck.
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 pub-
licly 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 implementation.
However, it can be configured on a per-mount basis to run
over TCP. Using TCP allows it to be used quickly and effi-
ciently 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 familiar to users of other
implementations of NFS. See the manual pages mount(8),
mountd(8), fstab(5), exports(5), netgroup(5), nfsd(8),
nfsiod(8), and nfssvc(8). and the document ``The 4.4BSD NFS
Implementation'' (SMM:6) for further information. The format
of /etc/fstab has changed from previous 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 operating
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 newlfs(8), mount_lfs(8) and
lfs_cleanerd(8) for more information. For a in-depth
description of the implementation and performance charac-
teristics 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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-49

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 chflags(1) utility.) When set on a file,
dump(8) will omit the file from incremental backups but
retain them on full backups. See the ``-h'' flag to dump(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 particu-
larly useful for identifying directories without the need to
use stat(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 lstat(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, amd, 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.
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 fd(4)
and mount_fdesc(8) for more information.

3.5.2.4. POSIX terminal driver changes
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

July 27, 1993

SMM:1-50 Installing and Operating 4.4BSD UNIX

terminal driver. Both the old ioctl calls and old options to
stty(1) are emulated. This emulation is expected to be una-
vailable 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, setsid(), creates
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 ioctl() call, not
implicitly by an open() call. The call fails if the terminal
is in use. Programs that allocate controlling terminals (or
pseudo-terminals) require change to work in this environ-
ment. The versions of xterm 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 terminal; see
/usr/src/lib/libutil/pty.c and
/usr/src/lib/libutil/login_tty.c.
The POSIX job control model formalizes the previous
conventions used in setting up a process group. Unfor-
tunately, 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.

3.5.2.5. Native operating system compatibility
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
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
environment 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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-51

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.

3.5.3. Changes to the utilities
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 com-
piler (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.

3.5.3.1. Make and Makefiles
This release uses a completely new version of the make
program derived from the pmake program developed by the
Sprite project at Berkeley. It supports existing makefiles,
although certain incorrect makefiles may fail. The makefiles
for the 4.4BSD sources make extensive use of the new facili-
ties, especially conditionals and file inclusion, and are
thus completely incompatible with older versions of make
(but nearly all the makefiles are now trivial!). The stan-
dard include files for make are in /usr/share/mk. There is a
bsd.README file in /usr/src/share/mk.
Another global change supported by the new make is
designed to allow multiple architectures to share a copy of
the sources. If a subdirectory named obj is present in the
current directory, make 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 his-
toric reasons only, and the system make configuration files
in /usr/share/mk can trivially be modified to use /var/obj
instead.) We have one /var/obj hierarchy on the local sys-
tem, and another on each system that shares the source

July 27, 1993

SMM:1-52 Installing and Operating 4.4BSD UNIX

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).

3.5.3.2. Kerberos
The Kerberos authentication server from MIT (version 4)
is included in this release. See kerberos(1) for a general,
if MIT-specific, introduction. If it is configured,
login(1), passwd(1), rlogin(1) and rsh(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
ext_srvtab(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
kdb_edit(8), or users on authorized hosts can add themselves
and a Kerberos password after verification of their
``local'' (passwd-file) password using the register(1) pro-
gram.
Note that by default the password-changing program
passwd(1) changes the Kerberos password, that must exist.
The -l option to passwd(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.

3.5.3.3. Timezone support
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/zoneinfo include corrections for leap seconds
since the beginning of 1970. Thus, they assume that the ker-
nel will increment the time at a constant rate during a leap
second; that is, time just keeps on ticking. The conversion
routines will then name a leap second 23:59:60. For pur-
ists, this effectively means that the kernel maintains TAI
(International 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 effectively
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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-53

constructed 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/zoneinfo/right and /usr/share/zoneinfo/posix.
Each contain a complete set of zone files. See
/usr/src/share/zoneinfo/Makefile for details.

3.5.3.4. Additions and changes to the libraries
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 fts(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 fts(3). The conversion has always
resulted in a significant performance gain, often of four or
five to one in system time.
The dbopen(3) functions are intended to be a family of
database access methods. Currently, they consist of hash(3),
an extensible, dynamic hashing scheme, btree(3), a sorted,
balanced tree structure (B+tree's), and recno(3), a flat-
file interface for fixed or variable length records refer-
enced by logical record number. Each of the access methods
stores associated key/data pairs and uses the same record
oriented interface for access.
The qsort(3) function has been rewritten for additional
performance. In addition, three new types of sorting func-
tions, heapsort(3), mergesort(3) and radixsort(3) have been
added to the system. The mergesort function is optimized for
data with pre-existing order, in which case it usually sig-
nificantly outperforms qsort. The radixsort(3) functions are
variants of most-significant-byte radix sorting. They take
time linear to the number of bytes to be sorted, usually
significantly outperforming qsort on data that can be sorted
in this fashion. An implementation of the POSIX 1003.2 stan-
dard sort(1), based on radixsort, is included in
/usr/src/contrib/sort.
Some additional comments about the 4.4BSD C library:
+ The floating point support in the C library has been
replaced and is now accurate.
+ The C functions specified by both ANSI C, POSIX 1003.1

July 27, 1993

SMM:1-54 Installing and Operating 4.4BSD UNIX

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.
+ ANSI C multibyte and wide character support has been
integrated. The rune functionality from the Bell Labs'
Plan 9 system is provided as well.
+ The termcap(3) functions have been generalized and
replaced with a general purpose interface named
getcap(3).
+ The stdio(3) routines have been replaced, and are usu-
ally much faster. In addition, the funopen(3) interface
permits applications to provide their own I/O stream
function support.
The curses(3) library has been largely rewritten.
Important additional features include support for scrolling
and termios(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.

3.5.3.5. Additions and changes to other utilities
There are many new utilities, offering many new capa-
bilities, in 4.4BSD. Skimming through the section 1 and sec-
tion 8 manual pages is sure to be useful. The additions to
the utility suite include greatly enhanced versions of pro-
grams 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:

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.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-55

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.
xargs The POSIX 1003.2 argument list constructor utility.
yacc A new, freely redistributable, significantly faster version.

The new versions of lex(1) (``flex'') and yacc(1)
(``zoo'') should be installed early on if attempting to
cross-compile 4.4BSD on another system. Note that the new
lex program is not completely backward compatible with his-
toric versions of lex, although it is believed that all
documented features are supported.
The find 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.

July 27, 1993

SMM:1-56 Installing and Operating 4.4BSD UNIX

3.6. Hints on converting from 4.3BSD to 4.4BSD
This section summarizes changes between 4.3BSD and
4.4BSD that are likely to cause difficulty in doing the
conversion. 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 emacs(1) as well as
several other programs. A related problem is improperly
casting (or failing to cast) the second argument to
lseek(2), truncate(2), or ftruncate(2) ala:

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

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 connect(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);

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 malloc from fopen; 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.
Select can be used with more than 32 descriptors by
using arrays of ints for the bit fields rather than single
ints. Programs that used getdtablesize as their first argu-
ment to select will no longer work correctly. Usually the
program can be modified to correctly specify the number of

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-57

bits in an int. Alternatively the program can be modified to
use an array of ints. There are a set of macros available in
<sys/types.h> to simplify this. See select(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.out
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
publicly-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.

4. System setup
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.

4.1. Kernel configuration
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).

4.1.1. Kernel organization
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
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

July 27, 1993

SMM:1-58 Installing and Operating 4.4BSD UNIX

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

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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-59

4.1.2. Devices and device drivers
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 mknod(8) program and normally kept in the
/dev directory. For all the devices supported by the distri-
bution 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,

# cd /
# mkdir newdev
# cp dev/MAKEDEV newdev/MAKEDEV
# cd newdev
# MAKEDEV sd0 pt0 std LOCAL

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

# cd /
# mv dev olddev ; mv newdev dev
# sync

to install the new device directory.

4.1.3. Building new system images
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
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:

# cp vmunix /newvmunix
# sync

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 per-
manently as /genvmunix for use in emergencies. To boot the

July 27, 1993

SMM:1-60 Installing and Operating 4.4BSD UNIX

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.

4.2. Configuring terminals
If UNIX is to support simultaneous access from
directly-connected terminals other than the console, the
file /etc/ttys (see ttys(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 on (or add new lines). Note that lines in /etc/ttys
are one-for-one with entries in the file of current 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
none 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
``insecure'', 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

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 cus-
tom terminal types, consult gettytab(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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-61

(Note, the fourth field is not needed here.)
When the system is running multi-user, all terminals
that are listed in /etc/ttys as on 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
terminal's status to off and then send a hangup signal to
the init process, by doing

# kill -s HUP 1

Terminals can similarly be enabled by changing the status
field from off to on and sending a hangup signal to init.
Note that if a special file is inaccessible when init
tries to create a process for it, init will log a message to
the system error logging process (see syslogd(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 ps(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 ps(1) uses
based on these conventions will then break down and ps will
run MUCH slower.

4.3. Adding users
The procedure for adding a new user is described in
adduser(8). You should add accounts for the initial user
community, giving each a directory and a password, and put-
ting 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.

4.4. Site tailoring
All programs that require the site's name, or some
similar characteristic, obtain the information through sys-
tem 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

July 27, 1993

SMM:1-62 Installing and Operating 4.4BSD UNIX

/etc/netstart

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

hostname=mysitename
/bin/hostname $hostname

to define the value returned by the gethostname(2) system
call. If you are running the name server, your site name
should be your fully qualified domain name. Programs such
as getty(8), mail(1), wall(1), and uucp(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 ifconfig(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 connec-
tivity using ping(8). You should first test connectivity to
yourself, then another host on your Ethernet, and finally a
host on another Ethernet. The netstat(8) program can be used
to inspect and debug your routes; see section 5.4.

4.5. Setting up the line printer system
The line printer system consists of at least the fol-
lowing files and commands:

/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
printcap(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.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-63

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
lpr, 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 lpq 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 lpd program
should be present in /etc/rc.

4.6. Setting up the mail system
The mail system consists of the following commands:

/usr/bin/mail UCB mail program, described in mail(1)
/usr/sbin/sendmail mail routing program
/var/spool/mail mail spooling directory
/var/spool/secretmail secure mail directory
/usr/bin/xsend secure mail sender
/usr/bin/xget secure mail receiver
/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 mail(1) command
(found in /usr/bin/mail), which provides a front-end to edit
the messages sent and received, and passes the messages to
sendmail(8) for routing. The routing algorithm uses
knowledge of the network name syntax, aliasing and forward-
ing information, and network topology, as defined in the
configuration 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 mail-
boxes in the directory /var/spool/mail/<username>, using a
locking protocol 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 ``biff y'' command
that mail has arrived.
Mail queued in the directory /var/spool/mail is nor-
mally readable only by the recipient. To send mail that is
secure against perusal (except by a code-breaker) you should
use the secret mail facility, which encrypts the mail.
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

July 27, 1993

SMM:1-64 Installing and Operating 4.4BSD UNIX

/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).

4.6.1. Setting up a UUCP connection
The version of uucp included in 4.4BSD has the following
features:
+ support for many auto call units and dialers in addition
to the DEC DN11,
+ breakup of the spooling area into multiple subdirec-
tories,
+ addition of an L.cmds file to control the set of commands
that may be executed by a remote site,
+ enhanced ``expect-send'' sequence capabilities when log-
ging in to a remote site,
+ new commands to be used in polling sites and obtaining
snap shots of uucp activity,
+ additional protocols for different communication media.
This section gives a brief overview of uucp and points out
the most important steps in its installation.
To connect two UNIX machines with a uucp 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
Manager's Manual: ``Uucp Implementation Description''
(SMM:14). It describes in detail the file formats and con-
ventions, 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 uucp 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 commands
in /usr/bin are:

/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 uusend)
/usr/bin/uudecode binary file decoder (for uusend)
/usr/bin/uulog scans session log files
/usr/bin/uusnap gives a snap-shot of uucp 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:

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-65

/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 uucp protocol daemon
/usr/lib/uucp/uuclean cleans up garbage files in spool area
/usr/lib/uucp/uuxqt uucp 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.machine directory for local ``D.'' files
/var/spool/uucp/D.machineX directory for local ``X.'' files
/var/spool/uucp/TM. directory for temporary, ``TM.'', files
/var/spool/uucp/LOGFILE log file of uucp activity
/var/spool/uucp/SYSLOG log file of uucp file transfers

To install uucp on your system, start by selecting a
site name (shorter than 14 characters). A uucp 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 uucp, group daemon.
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 uucp daemon on another
machine. For example, our L.sys file looks something like:

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 uucp daemon, uucico, to search for any available
auto-call unit in L-devices. Our L-dialcodes file is of the

July 27, 1993

SMM:1-66 Installing and Operating 4.4BSD UNIX

form:

ucb 2
out 9%

while our L-devices file is:

ACU cul0 unused 1200 ventel

Refer to the README file in the uucp source directory for
more information about installation.
As uucp 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 uuclean program. The log files can grow without
bound unless trimmed back; uulog maintains these files. Many
useful aids in maintaining your uucp installation are
included in a subdirectory UUAIDS beneath
/usr/src/usr.bin/uucp. Peruse this directory and read the
``setup'' instructions also located there.

5. Network setup
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 sup-
ports 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 support
for the ISO OSI protocols CLNP TP4, and ESIS. User level
process complete the application protocols such as X.400 and
X.500.

5.1. System configuration
To configure the kernel to include the Internet commun-
ication protocols, define the INET option. Xerox NS support
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 configura-
tion file. The ``pty'' pseudo-device forces the pseudo ter-
minal device driver to be configured into the system, see
pty(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 sys-
tem.
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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-67

addresses.
Before configuring the appropriate networking hardware,
you should consult the manual pages in section 4 of the
Programmer'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 ifconfig(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. Ifconfig(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 arp(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 ifconfig.
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 route(8) com-
mand. Additional information is provided in the manual page
describing ESIS(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.

# cd /dev
# MAKEDEV pty0 pty1

More pseudo terminals may be made by specifying pty2, pty3,
etc. The kernel normally includes support for 32 pseudo
terminals unless the configuration file specifies a dif-
ferent 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
getty is started).

5.2. Local subnets
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

July 27, 1993

SMM:1-68 Installing and Operating 4.4BSD UNIX

numbers may be locally administered. The standard describing
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
number have an 8-bit host address space[6]. To define local
subnets 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 netmask option to the ifconfig 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
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/netstart 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
_________________________
[6] If you are unfamiliar with the Internet address-
ing structure, consult ``Address Mappings'', Internet
RFC-796, J. Postel; available from the Internet Network
Information Center at SRI.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-69

practice only the mask of the first interface on each net-
work is really used.

5.3. Internet broadcast addresses
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 ifconfig) 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.

5.4. Routing
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 gated 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 permission
to include it on 4.4BSD.
If you do not wish to or cannot obtain gated, the dis-
tribution does include routed(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
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 routed(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

July 27, 1993

SMM:1-70 Installing and Operating 4.4BSD UNIX

form

/sbin/route add default smart-gateway 1

to /etc/netstart; see route(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 gen-
erate 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
redirect 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 employing the wildcard routing techniques for ``dis-
tant'' networks. The netstat(1) program may be used to
display routing table contents as well as various routing
oriented statistics. For example,

# netstat -r

will display the contents of the routing tables, while

# netstat -r -s

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

5.5. Use of 4.4BSD machines as gateways
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 con-
figured 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 dif-
ferent 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
interaction of 4.4BSD gateways with hosts that configure
their routes via default gateways and redirects. The genera-
tion of redirects may be disabled with the configuration

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-71

option IPSENDREDIRECTS=0 or while the system is running by
using the command:

sysctl net.inet.ip.redirect=0

in environments where it may cause difficulties.

5.6. Network databases
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 hosts(5) local host names
/etc/networks networks(5) network names
/etc/services services(5) list of known services
/etc/protocols protocols(5) protocol names
/etc/hosts.equiv rshd(8) list of ``trusted'' hosts
/etc/netstart rc(8) command script for initializing network
/etc/rc rc(8) command script for starting standard servers
/etc/rc.local rc(8) command script for starting local servers
/etc/ftpusers ftpd(8) list of ``unwelcome'' ftp users
/etc/hosts.lpd lpd(8) list of hosts allowed to access printers
/etc/inetd.conf inetd(8) list of servers started by inetd

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
numbers to avoid conversion if a connection to the Internet
(or others on the Internet) is ever established.

5.6.1. Network servers
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

July 27, 1993

SMM:1-72 Installing and Operating 4.4BSD UNIX

/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 routed and rwhod is controlled by shell
variables set in /etc/netstart. By default, routed is used,
but rwhod is not; they are enabled by setting the variables
routedflags and rwhod to strings other than ``NO.'' The
value of routedflags provides host-specific options to
routed. For example,

routedflags=-q
rwhod=NO

would run routed -q and would not run rwhod.
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

5.6.2. Internet daemon
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
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 inetd, 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 inetd(8) for more detail on the format of the confi-
guration file and the operation of the Internet daemon.

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-73

5.6.3. The /etc/hosts.equiv file
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 official 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

5.6.4. The /etc/ftpusers file
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 ftp.
When a client uses the anonymous account a chroot(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 chroot call is
used, certain programs and files used by the server process
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 awk commands to copy the /etc/passwd and
/etc/group files are STRONGLY recommended.

July 27, 1993

SMM:1-74 Installing and Operating 4.4BSD UNIX

# cd ~ftp
# chmod 555 .; chown ftp .; chgrp ftp .
# mkdir bin etc pub
# chown root bin etc
# chmod 555 bin etc
# chown ftp pub
# chmod 777 pub
# cd bin
# cp /bin/sh /bin/ls .
# chmod 111 sh ls
# cd ../etc
# awk -F: '{$2="*";print$1":"$2":"$3":"$4":"$5":"$6":"}' < /etc/passwd > passwd
# awk -F: '{$2="*";print$1":"$2":"}' < /etc/group > group
# chmod 444 passwd group

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.

6. System operation
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.

6.1. Bootstrap and shutdown procedures
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 console
has been marked ``insecure'' in /etc/ttys you must enter the
root password to bring the machine to single-user mode.) It
is also possible to allow the filesystem checks to complete
and then to return to single-user mode by signaling fsck(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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-75

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
init(8) and ttys(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 reboot(8) to have the disks checked.
To take the system down to a single user state you can
use

# kill 1

or use the shutdown(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:

# cd /
# /sbin/umount -a
# ^D

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

6.2. Device errors and diagnostics
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 syslogd(8) and written into a system error log file
/var/log/messages. Less serious errors are sent directly to
syslogd, which may log them on the console. The error prior-
ities that are logged and the locations to which they are
logged are controlled by /etc/syslog.conf. See syslogd(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 hardware
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 tail -r
/var/log/messages).

6.3. Filesystem checks, backups, and disaster recovery
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
by fsck(1). The procedures of reboot(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

July 27, 1993

SMM:1-76 Installing and Operating 4.4BSD UNIX

complacent. Complete and incremental dumps are easily done
with dump(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
indefinitely). 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 operator
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 res-
tarts 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 tar(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 dd(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/disktab.
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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-77

and then; disk quotas may be imposed, or if you prefer a
less fascist approach, try using the programs du(1), df(1),
and quot(8), combined with threatening messages of the day,
and personal letters.

6.4. Moving filesystem data
If you have the resources, the best way to move a
filesystem is to dump it to a spare disk partition, or
magtape, using dump(8), use newfs(8) to create the new
filesystem, and restore the filesystem using restore(8).
Filesystems may also be moved by piping the output of dump
to restore. The restore program uses an ``in-place'' algo-
rithm 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 tar(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 following:
1. GET A SECOND PACK, OR USE ANOTHER DISK DRIVE!!!!
2. Dump the root filesystem to tape using dump(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 stan-
dalone system in /sys/<architecture>/stand, and the default
disk partition tables in /etc/disktab should be modified.

6.5. Monitoring system performance
The systat 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 pag-
ing or swapping activity, there should be available
bandwidth 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

July 27, 1993

SMM:1-78 Installing and Operating 4.4BSD UNIX

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.

6.6. Recompiling and reinstalling system software
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 kernel,
binary or library, as well as its associated manual
pages. This target does not build the dependency
files. Some of the utilities require that a make
depend be done before a make all can succeed.
depend Build the include file dependency file,
``.depend'', which is read by make. See mkdep(1)
for further details.
install Install the kernel, binary or library, as well as
its associated manual pages. See install(1) for
further details.
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
referenced 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 make will live in

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-79

the shadow structure, and /usr/src may be mounted
read-only by multiple machines. Doing a make obj in
/usr/src will build the shadow directory structure
for everything on the system except for the contri-
buted, 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
config(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:

# make
# make install

Note, if system include files have changed between compiles,
make 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:

# make build

This target installs the system include files, cleans the
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 whereis(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:

July 27, 1993

SMM:1-80 Installing and Operating 4.4BSD UNIX

# whereis passwd
/usr/bin/passwd
# cd /usr/src/usr.bin/passwd
# make
# make install

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

# make
# make DESTDIR=pathname install

Similarly, the mode, owner, group, and other characteristics
of the installed object can be modified by changing other
default make variables. See make(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:

# cd /usr/src/include
# make install

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

# cd /usr/src/lib/libc
# make depend
# make
# make install
# cd /usr/src
# make depend
# make
# make install

Alternatively, the make build command described above will
accomplish the same tasks. This takes several hours on a
reasonably configured machine.

6.7. Making local modifications
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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-81

(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 man(1) command automatically
finds manual pages placed in /usr/local/man/cat[1-8] to
encourage this practice (see man.conf(5)).

6.8. Accounting
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 ac(8). The process time accounting information is
stored in the file /var/account/acct after it is enabled by
accton(8), and is analyzed and summarized by the program
sa(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 cron(8) for details.

6.9. Resource control
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
setrlimit(2). As distributed, the latter mechanism is volun-
tary, though sites may choose to modify the login mechanism
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 quotacheck(8), and modifying /etc/fstab to show that
the filesystem is to run with disk quotas (options userquota
and/or groupquota). The quotaon(8) program may then be run
to enable quotas.
Individual quotas are applied by using the quota editor
edquota(8). Users may view their quotas (but not those of
other users) with the quota(1) program. The repquota(8) pro-
gram may be used to summarize the quotas and current space
usage on a particular filesystem or filesystems.
Quotas are enforced with soft and hard 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 hard limit and disallows any allocations

July 27, 1993

SMM:1-82 Installing and Operating 4.4BSD UNIX

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.

6.10. Network troubleshooting
If you have anything more than a trivial network confi-
guration, from time to time you are bound to run into prob-
lems. 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 severely
deteriorated service. The netstat(1) program may be of aid
in tracking down hardware malfunctions. In particular, look
at the -i and -s 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
trpt(8) program. Most of the servers distributed with the
system accept a -d option forcing all sockets to be created
with debugging turned on. Consult the appropriate manual
pages for more information.

6.11. Files that need periodic attention
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 tip(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
/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 syslogd(8)
/etc/ttys enables/disables ports
/etc/crontab commands that are run periodically
/etc/crontab.local local commands that are run periodically

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-83

/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

July 27, 1993

SMM:1-2 Installing and Operating 4.4BSD UNIX

Table of Contents

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

July 27, 1993

Installing and Operating 4.4BSD UNIX SMM:1-3

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

July 27, 1993

Generated on 2013-04-27 00:20:00 by $MirOS: src/scripts/roff2htm,v 1.77 2013/01/01 20:49:09 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2013 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report – diffs preferred.