1.\" Copyright (c) 1980, 1986, 1988, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" $FreeBSD: head/share/doc/smm/01.setup/3.t 108533 2003-01-01 18:49:04Z schweikh $
33.\" @(#)3.t 8.1 (Berkeley) 7/27/93
34.\"
35.ds lq ``
36.ds rq ''
37.ds RH "Upgrading a \*(Ps System
38.ds CF \*(Dy
39.Sh 1 "Upgrading a \*(Ps system"
40.PP
41This section describes the procedure for upgrading a \*(Ps
42system to \*(4B. This procedure may vary according to the version of
43the system running before conversion.
44If you are converting from a
45System V system, some of this section will still apply (in particular,
46the filesystem conversion). However, many of the system configuration
47files are different, and the executable file formats are completely
48incompatible.
49.PP
50In particular be wary when using this information to upgrade
51a \*(Ps HP300 system.
52There are at least four different versions of ``\*(Ps'' out there:
53.IP 1)
54HPBSD 1.x from Utah.
55.br
56This was the original version of \*(Ps for HP300s from which the
57other variants (and \*(4B) are derived.
58It is largely a \*(Ps system with Sun's NFS 3.0 filesystem code and
59some \*(Ps-Tahoe features (e.g. networking code).
60Since the filesystem code is 4.2/4.3 vintage and the filesystem
61hierarchy is largely \*(Ps, most of this section should apply.
62.IP 2)
63MORE/bsd from Mt. Xinu.
64.br
65This is a \*(Ps-Tahoe vintage system with Sun's NFS 4.0 filesystem code
66upgraded with Tahoe UFS features.
67The instructions for \*(Ps-Tahoe should largely apply.
68.IP 3)
69\*(Ps-Reno from CSRG.
70.br
71At least one site bootstrapped HP300 support from the Reno distribution.
72The Reno filesystem code was somewhere between \*(Ps and \*(4B: the VFS switch
73had been added but many of the UFS features (e.g. ``inline'' symlinks)
74were missing.
75The filesystem hierarchy reorganization first appeared in this release.
76Be extremely careful following these instructions if you are
77upgrading from the Reno distribution.
78.IP 4)
79HPBSD 2.0 from Utah.
80.br
81As if things were not bad enough already,
82this release has the \*(4B filesystem and networking code
83as well as some utilities, but still has a \*(Ps hierarchy.
84No filesystem conversions are necessary for this upgrade,
85but files will still need to be moved around.
86.Sh 2 "Installation overview"
87.PP
88If you are running \*(Ps, upgrading your system
89involves replacing your kernel and system utilities.
90In general, there are three possible ways to install a new \*(Bs distribution:
91(1) boot directly from the distribution tape, use it to load new binaries
92onto empty disks, and then merge or restore any existing configuration files
93and filesystems;
94(2) use an existing \*(Ps or later system to extract the root and
95.Pn /usr
96filesystems from the distribution tape,
97boot from the new system, then merge or restore existing
98configuration files and filesystems; or
99(3) extract the sources from the distribution tape onto an existing system,
100and use that system to cross-compile and install \*(4B.
101For this release, the second alternative is strongly advised,
102with the third alternative reserved as a last resort.
103In general, older binaries will continue to run under \*(4B,
104but there are many exceptions that are on the critical path
105for getting the system running.
106Ideally, the new system binaries (root and
107.Pn /usr
108filesystems) should be installed on spare disk partitions,
109then site-specific files should be merged into them.
110Once the new system is up and fully merged, the previous root and
111.Pn /usr
112filesystems can be reused.
113Other existing filesystems can be retained and used,
114except that (as usual) the new
115.Xr fsck
116should be run before they are mounted.
117.PP
118It is \fBSTRONGLY\fP advised that you make full dumps of each filesystem
119before beginning, especially any that you intend to modify in place
120during the merge.
121It is also desirable to run filesystem checks
122of all filesystems to be converted to \*(4B before shutting down.
123This is an excellent time to review your disk configuration
124for possible tuning of the layout.
125Most systems will need to provide a new filesystem for system use
126mounted on
127.Pn /var
128(see below).
129However, the
130.Pn /tmp
131filesystem can be an MFS virtual-memory-resident filesystem,
132potentially freeing an existing disk partition.
133(Additional swap space may be desirable as a consequence.)
134See
135.Xr mount_mfs (8).
136.PP
137The recommended installation procedure includes the following steps.
138The order of these steps will probably vary according to local needs.
139.IP \(bu
140Extract root and
141.Pn /usr
142filesystems from the distribution tapes.
143.IP \(bu
144Extract kernel and/or user-level sources from the distribution tape
145if space permits.
146This can serve as the backup documentation as needed.
147.IP \(bu
148Configure and boot a kernel for the local system.
149This can be delayed if the generic kernel from the distribution
150supports enough hardware to proceed.
151.IP \(bu
152Build a skeletal
153.Pn /var
154filesystem (see
155.Xr mtree (8)).
156.IP \(bu
157Merge site-dependent configuration files from
158.Pn /etc
159and
160.Pn /usr/lib
161into the new
162.Pn /etc
163directory.
164Note that many file formats and contents have changed; see section 3.4
165of this document.
166.IP \(bu
167Copy or merge files from
168.Pn /usr/adm ,
169.Pn /usr/spool ,
170.Pn /usr/preserve ,
171.Pn /usr/lib ,
172and other locations into
173.Pn /var .
174.IP \(bu
175Merge local macros, dictionaries, etc. into
176.Pn /usr/share .
177.IP \(bu
178Merge and update local software to reflect the system changes.
179.IP \(bu
180Take off the rest of the morning, you've earned it!
181.PP
182Section 3.2 lists the files to be saved as part of the conversion process.
183Section 3.3 describes the bootstrap process.
184Section 3.4 discusses the merger of the saved files back into the new system.
185Section 3.5 gives an overview of the major
186bug fixes and changes between \*(Ps and \*(4B.
187Section 3.6 provides general hints on possible problems to be
188aware of when converting from \*(Ps to \*(4B.
189.Sh 2 "Files to save"
190.PP
191The following list enumerates the standard set of files you will want to
192save and suggests directories in which site-specific files should be present.
193This list will likely be augmented with non-standard files you
194have added to your system.
195If you do not have enough space to create parallel
196filesystems, you should create a
197.Xr tar
198image of the following files before the new filesystems are created.
199The rest of this subsection describes where theses files
200have moved and how they have changed.
201.TS
202lfC c l.
203/.cshrc \(dg root csh startup script (moves to \f(CW/root/.cshrc\fP)
204/.login \(dg root csh login script (moves to \f(CW/root/.login\fP)
205/.profile \(dg root sh startup script (moves to \f(CW/root/.profile\fP)
206/.rhosts \(dg for trusted machines and users (moves to \f(CW/root/.rhosts\fP)
207/etc/disktab \(dd in case you changed disk partition sizes
208/etc/fstab * disk configuration data
209/etc/ftpusers \(dg for local additions
210/etc/gettytab \(dd getty database
211/etc/group * group data base
212/etc/hosts \(dg for local host information
213/etc/hosts.equiv \(dg for local host equivalence information
214/etc/hosts.lpd \(dg printer access file
215/etc/inetd.conf * Internet services configuration data
216/etc/named* \(dg named configuration files
217/etc/netstart \(dg network initialization
218/etc/networks \(dg for local network information
219/etc/passwd * user data base
220/etc/printcap * line printer database
221/etc/protocols \(dd in case you added any local protocols
222/etc/rc * for any local additions
223/etc/rc.local * site specific system startup commands
224/etc/remote \(dg auto-dialer configuration
225/etc/services \(dd for local additions
226/etc/shells \(dd list of valid shells
227/etc/syslog.conf * system logger configuration
228/etc/securettys * merged into ttys
229/etc/ttys * terminal line configuration data
230/etc/ttytype * merged into ttys
231/etc/termcap \(dd for any local entries that may have been added
232/lib \(dd for any locally developed language processors
233/usr/dict/* \(dd for local additions to words and papers
234/usr/include/* \(dd for local additions
235/usr/lib/aliases * mail forwarding data base (moves to \f(CW/etc/aliases\fP)
236/usr/lib/crontab * cron daemon data base (moves to \f(CW/etc/crontab\fP)
237/usr/lib/crontab.local * local cron daemon data base (moves to \f(CW/etc/crontab.local\fP)
238/usr/lib/lib*.a \(dg for local libraries
239/usr/lib/mail.rc \(dg system-wide mail(1) initialization (moves to \f(CW/etc/mail.rc\fP)
240/usr/lib/sendmail.cf * sendmail configuration (moves to \f(CW/etc/sendmail.cf\fP)
241/usr/lib/tmac/* \(dd for locally developed troff/nroff macros (moves to \f(CW/usr/share/tmac/*\fP)
242/usr/lib/uucp/* \(dg for local uucp configuration files
243/usr/man/manl * for manual pages for locally developed programs (moves to \f(CW/usr/local/man\fP)
244/usr/spool/* \(dg for current mail, news, uucp files, etc. (moves to \f(CW/var/spool\fP)
245/usr/src/local \(dg for source for locally developed programs
246/sys/conf/HOST \(dg configuration file for your machine (moves to \f(CW/sys/<arch>/conf\fP)
247/sys/conf/files.HOST \(dg list of special files in your kernel (moves to \f(CW/sys/<arch>/conf\fP)
248/*/quotas * filesystem quota files (moves to \f(CW/*/quotas.user\fP)
249.TE
250.DS
251\(dg\|Files that can be used from \*(Ps without change.
252\(dd\|Files that need local changes merged into \*(4B files.
253*\|Files that require special work to merge and are discussed in section 3.4.
254.DE
255.Sh 2 "Installing \*(4B"
256.PP
257The next step is to build a working \*(4B system.
258This can be done by following the steps in section 2 of
259this document for extracting the root and
260.Pn /usr
261filesystems from the distribution tape onto unused disk partitions.
262For the SPARC, the root filesystem dump on the tape could also be
263extracted directly.
264For the HP300 and DECstation, the raw disk image can be copied
265into an unused partition and this partition can then be dumped
266to create an image that can be restored.
267The exact procedure chosen will depend on the disk configuration
268and the number of suitable disk partitions that may be used.
269It is also desirable to run filesystem checks
270of all filesystems to be converted to \*(4B before shutting down.
271In any case, this is an excellent time to review your disk configuration
272for possible tuning of the layout.
273Section 2.5 and
274.Xr config (8)
275are required reading.
276.LP
277The filesystem in \*(4B has been reorganized in an effort to
278meet several goals:
279.IP 1)
280The root filesystem should be small.
281.IP 2)
282There should be a per-architecture centrally-shareable read-only
283.Pn /usr
284filesystem.
285.IP 3)
286Variable per-machine directories should be concentrated below
287a single mount point named
288.Pn /var .
289.IP 4)
290Site-wide machine independent shareable text files should be separated
291from architecture specific binary files and should be concentrated below
292a single mount point named
293.Pn /usr/share .
294.LP
295These goals are realized with the following general layouts.
296The reorganized root filesystem has the following directories:
297.TS
298lfC l.
299/etc (config files)
300/bin (user binaries needed when single-user)
301/sbin (root binaries needed when single-user)
302/local (locally added binaries used only by this machine)
303/tmp (mount point for memory based filesystem)
304/dev (local devices)
305/home (mount point for AMD)
306/var (mount point for per-machine variable directories)
307/usr (mount point for multiuser binaries and files)
308.TE
309.LP
310The reorganized
311.Pn /usr
312filesystem has the following directories:
313.TS
314lfC l.
315/usr/bin (user binaries)
316/usr/contrib (software contributed to \*(4B)
317/usr/games (binaries for games, score files in \f(CW/var\fP)
318/usr/include (standard include files)
319/usr/lib (lib*.a from old \f(CW/usr/lib\fP)
320/usr/libdata (databases from old \f(CW/usr/lib\fP)
321/usr/libexec (executables from old \f(CW/usr/lib\fP)
322/usr/local (locally added binaries used site-wide)
323/usr/old (deprecated binaries)
324/usr/sbin (root binaries)
325/usr/share (mount point for site-wide shared text)
326/usr/src (mount point for sources)
327.TE
328.LP
329The reorganized
330.Pn /usr/share
331filesystem has the following directories:
332.TS
333lfC l.
334/usr/share/calendar (various useful calendar files)
335/usr/share/dict (dictionaries)
336/usr/share/doc (\*(4B manual sources)
337/usr/share/games (games text files)
338/usr/share/groff_font (groff font information)
339/usr/share/man (typeset manual pages)
340/usr/share/misc (dumping ground for random text files)
341/usr/share/mk (templates for \*(4B makefiles)
342/usr/share/skel (template user home directory files)
343/usr/share/tmac (various groff macro packages)
344/usr/share/zoneinfo (information on time zones)
345.TE
346.LP
347The reorganized
348.Pn /var
349filesystem has the following directories:
350.TS
351lfC l.
352/var/account (accounting files, formerly \f(CW/usr/adm\fP)
353/var/at (\fIat\fP\|(1) spooling area)
354/var/backups (backups of system files)
355/var/crash (crash dumps)
356/var/db (system-wide databases, e.g. tags)
357/var/games (score files)
358/var/log (log files)
359/var/mail (users mail)
360/var/obj (hierarchy to build \f(CW/usr/src\fP)
361/var/preserve (preserve area for vi)
362/var/quotas (directory to store quota files)
363/var/run (directory to store *.pid files)
364/var/rwho (rwho databases)
365/var/spool/ftp (home directory for anonymous ftp)
366/var/spool/mqueue (sendmail spooling directory)
367/var/spool/news (news spooling area)
368/var/spool/output (printer spooling area)
369/var/spool/uucp (uucp spooling area)
370/var/tmp (disk-based temporary directory)
371/var/users (root of per-machine user home directories)
372.TE
373.PP
374The \*(4B bootstrap routines pass the identity of the boot device
375through to the kernel.
376The kernel then uses that device as its root filesystem.
377Thus, for example, if you boot from
378.Pn /dev/\*(Dk1a ,
379the kernel will use
380.Pn \*(Dk1a
381as its root filesystem. If
382.Pn /dev/\*(Dk1b
383is configured as a swap partition,
384it will be used as the initial swap area,
385otherwise the normal primary swap area (\c
386.Pn /dev/\*(Dk0b )
387will be used.
388The \*(4B bootstrap is backward compatible with \*(Ps,
389so you can replace your old bootstrap if you use it
390to boot your first \*(4B kernel.
391However, the \*(Ps bootstrap cannot access \*(4B filesystems,
392so if you plan to convert your filesystems to \*(4B,
393you must install a new bootstrap \fIbefore\fP doing the conversion.
394Note that SPARC users cannot build a \*(4B compatible version
395of the bootstrap, so must \fInot\fP convert their root filesystem
396to the new \*(4B format.
397.PP
398Once you have extracted the \*(4B system and booted from it,
399you will have to build a kernel customized for your configuration.
400If you have any local device drivers,
401they will have to be incorporated into the new kernel.
402See section 4.1.3 and ``Building 4.3BSD UNIX Systems with Config'' (SMM:2).
403.PP
404If converting from \*(Ps, your old filesystems should be converted.
405If you've modified the partition
406sizes from the original \*(Ps ones, and are not already using the
407\*(4B disk labels, you will have to modify the default disk partition
408tables in the kernel. Make the necessary table changes and boot
409your custom kernel \fBBEFORE\fP trying to access any of your old
410filesystems! After doing this, if necessary, the remaining filesystems
411may be converted in place by running the \*(4B version of
412.Xr fsck (8)
413on each filesystem and allowing it to make the necessary corrections.
414The new version of
415.Xr fsck
416is more strict about the size of directories than
417the version supplied with \*(Ps.
418Thus the first time that it is run on a \*(Ps filesystem,
419it will produce messages of the form:
420.DS
421\fBDIRECTORY ...: LENGTH\fP xx \fBNOT MULTIPLE OF 512 (ADJUSTED)\fP
422.DE
423Length ``xx'' will be the size of the directory;
424it will be expanded to the next multiple of 512 bytes.
425The new
426.Xr fsck
427will also set default \fIinterleave\fP and
428\fInpsect\fP (number of physical sectors per track) values on older
429filesystems, in which these fields were unused spares; this correction
430will produce messages of the form:
431.DS
432\fBIMPOSSIBLE INTERLEAVE=0 IN SUPERBLOCK (SET TO DEFAULT)\fP\**
433\fBIMPOSSIBLE NPSECT=0 IN SUPERBLOCK (SET TO DEFAULT)\fP
434.DE
435.FS
436The defaults are to set \fIinterleave\fP to 1 and
437\fInpsect\fP to \fInsect\fP.
438This is correct on most drives;
439it affects only performance (usually virtually unmeasurably).
440.FE
441Filesystems that have had their interleave and npsect values
442set will be diagnosed by the old
443.Xr fsck
444as having a bad superblock; the old
445.Xr fsck
446will run only if given an alternate superblock
447(\fIfsck \-b32\fP),
448in which case it will re-zero these fields.
449The \*(4B kernel will internally set these fields to their defaults
450if fsck has not done so; again, the \fI\-b32\fP option may be
451necessary for running the old
452.Xr fsck .
453.PP
454In addition, \*(4B removes several limits on filesystem sizes
455that were present in \*(Ps.
456The limited filesystems
457continue to work in \*(4B, but should be converted
458as soon as it is convenient
459by running
460.Xr fsck
461with the \fI\-c 2\fP option.
462The sequence \fIfsck \-p \-c 2\fP will update them all,
463fix the interleave and npsect fields,
464fix any incorrect directory lengths,
465expand maximum uid's and gid's to 32-bits,
466place symbolic links less than 60 bytes into their inode,
467and fill in directory type fields all at once.
468The new filesystem formats are incompatible with older systems.
469If you wish to continue using these filesystems with the older
470systems you should make only the compatible changes using
471\fIfsck \-c 1\fP.
472.Sh 2 "Merging your files from \*(Ps into \*(4B"
473.PP
474When your system is booting reliably and you have the \*(4B root and
475.Pn /usr
476filesystems fully installed you will be ready
477to continue with the next step in the conversion process,
478merging your old files into the new system.
479.PP
480If you saved the files on a
481.Xr tar
482tape, extract them into a scratch directory, say
483.Pn /usr/convert :
484.DS
485\fB#\fP \fImkdir /usr/convert\fP
486\fB#\fP \fIcd /usr/convert\fP
487\fB#\fP \fItar xp\fP
488.DE
489.PP
490The data files marked in the previous table with a dagger (\(dg)
491may be used without change from the previous system.
492Those data files marked with a double dagger (\(dd) have syntax
493changes or substantial enhancements.
494You should start with the \*(4B version and carefully
495integrate any local changes into the new file.
496Usually these local changes can be incorporated
497without conflict into the new file;
498some exceptions are noted below.
499The files marked with an asterisk (*) require
500particular attention and are discussed below.
501.PP
502As described in section 3.3,
503the most immediately obvious change in \*(4B is the reorganization
504of the system filesystems.
505Users of certain recent vendor releases have seen this general organization,
506although \*(4B takes the reorganization a bit further.
507The directories most affected are
508.Pn /etc ,
509that now contains only system configuration files;
510.Pn /var ,
511a new filesystem containing per-system spool and log files; and
512.Pn /usr/share,
513that contains most of the text files shareable across architectures
514such as documentation and macros.
515System administration programs formerly in
516.Pn /etc
517are now found in
518.Pn /sbin
519and
520.Pn /usr/sbin .
521Various programs and data files formerly in
522.Pn /usr/lib
523are now found in
524.Pn /usr/libexec
525and
526.Pn /usr/libdata ,
527respectively.
528Administrative files formerly in
529.Pn /usr/adm
530are in
531.Pn /var/account
532and, similarly, log files are now in
533.Pn /var/log .
534The directory
535.Pn /usr/ucb
536has been merged into
537.Pn /usr/bin ,
538and the sources for programs in
539.Pn /usr/bin
540are in
541.Pn /usr/src/usr.bin .
542Other source directories parallel the destination directories;
543.Pn /usr/src/etc
544has been greatly expanded, and
545.Pn /usr/src/share
546is new.
547The source for the manual pages, in general, are with the source
548code for the applications they document.
549Manual pages not closely corresponding to an application program
550are found in
551.Pn /usr/src/share/man .
552The locations of all man pages is listed in
553.Pn /usr/src/share/man/man0/man[1-8] .
554The manual page
555.Xr hier (7)
556has been updated and made more detailed;
557it is included in the printed documentation.
558You should review it to familiarize yourself with the new layout.
559.PP
560A new utility,
561.Xr mtree (8),
562is provided to build and check filesystem hierarchies
563with the proper contents, owners and permissions.
564Scripts are provided in
565.Pn /etc/mtree
566(and
567.Pn /usr/src/etc/mtree )
568for the root,
569.Pn /usr
570and
571.Pn /var
572filesystems.
573Once a filesystem has been made for
574.Pn /var ,
575.Xr mtree
576can be used to create a directory hierarchy there
577or you can simply use tar to extract the prototype from
578the second file of the distribution tape.
579.Sh 3 "Changes in the \f(CW/etc\fP directory"
580.PP
581The
582.Pn /etc
583directory now contains nearly all the host-specific configuration
584files.
585Note that some file formats have changed,
586and those configuration files containing pathnames are nearly all affected
587by the reorganization.
588See the examples provided in
589.Pn /etc
590(installed from
591.Pn /usr/src/etc )
592as a guide.
593The following table lists some of the local configuration files
594whose locations and/or contents have changed.
595.TS
596l l l
597lfC lfC l.
598\*(Ps and Earlier \*(4B Comments
599_ _ _
600/etc/fstab /etc/fstab new format; see below
601/etc/inetd.conf /etc/inetd.conf pathnames of executables changed
602/etc/printcap /etc/printcap pathnames changed
603/etc/syslog.conf /etc/syslog.conf pathnames of log files changed
604/etc/ttys /etc/ttys pathnames of executables changed
605/etc/passwd /etc/master.passwd new format; see below
606/usr/lib/sendmail.cf /etc/sendmail.cf changed pathnames
607/usr/lib/aliases /etc/aliases may contain changed pathnames
608/etc/*.pid /var/run/*.pid
609
610.T&
611l l l
612lfC lfC l.
613New in \*(Ps-Tahoe \*(4B Comments
614_ _ _
615/usr/games/dm.config /etc/dm.conf configuration for games (see \fIdm\fP\|(8))
616/etc/zoneinfo/localtime /etc/localtime timezone configuration
617/etc/zoneinfo /usr/share/zoneinfo timezone configuration
618.TE
619.ne 1.5i
620.TS
621l l l
622lfC lfC l.
623 New in \*(4B Comments
624_ _ _
625 /etc/aliases.db database version of the aliases file
626 /etc/amd-home location database of home directories
627 /etc/amd-vol location database of exported filesystems
628 /etc/changelist \f(CW/etc/security\fP files to back up
629 /etc/csh.cshrc system-wide csh(1) initialization file
630 /etc/csh.login system-wide csh(1) login file
631 /etc/csh.logout system-wide csh(1) logout file
632 /etc/disklabels directory for saving disklabels
633 /etc/exports NFS list of export permissions
634 /etc/ftpwelcome message displayed for ftp users; see ftpd(8)
635 /etc/kerberosIV Kerberos directory; see below
636 /etc/man.conf lists directories searched by \fIman\fP\|(1)
637 /etc/mtree directory for local mtree files; see mtree(8)
638 /etc/netgroup NFS group list used in \f(CW/etc/exports\fP
639 /etc/pwd.db non-secure hashed user data base file
640 /etc/spwd.db secure hashed user data base file
641 /etc/security daily system security checker
642.TE
643.PP
644System security changes require adding several new ``well-known'' groups to
645.Pn /etc/group .
646The groups that are needed by the system as distributed are:
647.TS
648l n l.
649name number purpose
650_
651wheel 0 users allowed superuser privilege
652daemon 1 processes that need less than wheel privilege
653kmem 2 read access to kernel memory
654sys 3 access to kernel sources
655tty 4 access to terminals
656operator 5 read access to raw disks
657bin 7 group for system binaries
658news 8 group for news
659wsrc 9 write access to sources
660games 13 access to games
661staff 20 system staff
662guest 31 system guests
663nobody 39 the least privileged group
664utmp 45 access to utmp files
665dialer 117 access to remote ports and dialers
666.TE
667Only users in the ``wheel'' group are permitted to
668.Xr su
669to ``root''.
670Most programs that manage directories in
671.Pn /var/spool
672now run set-group-id to ``daemon'' so that users cannot
673directly access the files in the spool directories.
674The special files that access kernel memory,
675.Pn /dev/kmem
676and
677.Pn /dev/mem ,
678are made readable only by group ``kmem''.
679Standard system programs that require this access are
680made set-group-id to that group.
681The group ``sys'' is intended to control access to kernel sources,
682and other sources belong to group ``wsrc.''
683Rather than make user terminals writable by all users,
684they are now placed in group ``tty'' and made only group writable.
685Programs that should legitimately have access to write on user terminals
686such as
687.Xr talkd
688and
689.Xr write
690now run set-group-id to ``tty''.
691The ``operator'' group controls access to disks.
692By default, disks are readable by group ``operator'',
693so that programs such as
694.Xr dump
695can access the filesystem information without being set-user-id to ``root''.
696The
697.Xr shutdown (8)
698program is executable only by group operator
699and is setuid to root so that members of group operator may shut down
700the system without root access.
701.PP
702The ownership and modes of some directories have changed.
703The
704.Xr at
705programs now run set-user-id ``root'' instead of ``daemon.''
706Also, the uucp directory no longer needs to be publicly writable,
707as
708.Xr tip
709reverts to privileged status to remove its lock files.
710After copying your version of
711.Pn /var/spool ,
712you should do:
713.DS
714\fB#\fP \fIchown \-R root /var/spool/at\fP
715\fB#\fP \fIchown \-R uucp:daemon /var/spool/uucp\fP
716\fB#\fP \fIchmod \-R o\-w /var/spool/uucp\fP
717.DE
718.PP
719The format of the cron table,
720.Pn /etc/crontab ,
721has been changed to specify the user-id that should be used to run a process.
722The userid ``nobody'' is frequently useful for non-privileged programs.
723Local changes are now put in a separate file,
724.Pn /etc/crontab.local .
725.PP
726Some of the commands previously in
727.Pn /etc/rc.local
728have been moved to
729.Pn /etc/rc ;
730several new functions are now handled by
731.Pn /etc/rc ,
732.Pn /etc/netstart
733and
734.Pn /etc/rc.local .
735You should look closely at the prototype version of these files
736and read the manual pages for the commands contained in it
737before trying to merge your local copy.
738Note in particular that
739.Xr ifconfig
740has had many changes,
741and that host names are now fully specified as domain-style names
742(e.g., vangogh.CS.Berkeley.EDU) for the benefit of the name server.
743.PP
744Some of the commands previously in
745.Pn /etc/daily
746have been moved to
747.Pn /etc/security ,
748and several new functions have been added to
749.Pn /etc/security
750to do nightly security checks on the system.
751The script
752.Pn /etc/daily
753runs
754.Pn /etc/security
755each night, and mails the output to the super-user.
756Some of the checks done by
757.Pn /etc/security
758are:
759.DS
760\(bu Syntax errors in the password and group files.
761\(bu Duplicate user and group names and id's.
762\(bu Dangerous search paths and umask values for the superuser.
763\(bu Dangerous values in various initialization files.
764\(bu Dangerous .rhosts files.
765\(bu Dangerous directory and file ownership or permissions.
766\(bu Globally exported filesystems.
767\(bu Dangerous owners or permissions for special devices.
768.DE
769In addition, it reports any changes to setuid and setgid files, special
770devices, or the files in
771.Pn /etc/changelist
772since the last run of
773.Pn /etc/security .
774Backup copies of the files are saved in
775.Pn /var/backups .
776Finally, the system binaries are checksummed and their permissions
777validated against the
778.Xr mtree (8)
779specifications in
780.Pn /etc/mtree .
781.PP
782The C-library and system binaries on the distribution tape
783are compiled with new versions of
784.Xr gethostbyname
785and
786.Xr gethostbyaddr
787that use the name server,
788.Xr named (8).
789If you have only a small network and are not connected
790to a large network, you can use the distributed library routines without
791any problems; they use a linear scan of the host table
792.Pn /etc/hosts
793if the name server is not running.
794If you are on the Internet or have a large local network,
795it is recommend that you set up
796and use the name server.
797For instructions on how to set up the necessary configuration files,
798refer to ``Name Server Operations Guide for BIND'' (SMM:10).
799Several programs rely on the host name returned by
800.Xr gethostname
801to determine the local domain name.
802.PP
803If you are using the name server, your
804.Xr sendmail
805configuration file will need some updates to accommodate it.
806See the ``Sendmail Installation and Operation Guide'' (SMM:8) and
807the sample
808.Xr sendmail
809configuration files in
810.Pn /usr/src/usr.sbin/sendmail/cf .
811The aliases file,
812.Pn /etc/aliases
813has also been changed to add certain well-known addresses.
814.Sh 3 "Shadow password files"
815.PP
816The password file format adds change and expiration fields
817and its location has changed to protect
818the encrypted passwords stored there.
819The actual password file is now stored in
820.Pn /etc/master.passwd .
821The hashed dbm password files do not contain encrypted passwords,
822but contain the file offset to the entry with the password in
823.Pn /etc/master.passwd
824(that is readable only by root).
825Thus, the
826.Fn getpwnam
827and
828.Fn getpwuid
829functions will no longer return an encrypted password string to non-root
830callers.
831An old-style passwd file is created in
832.Pn /etc/passwd
833by the
834.Xr vipw (8)
835and
836.Xr pwd_mkdb (8)
837programs.
838See also
839.Xr passwd (5).
840.PP
841Several new users have also been added to the group of ``well-known'' users in
842.Pn /etc/passwd .
843The current list is:
844.DS
845.TS
846l c.
847name number
848_
849root 0
850daemon 1
851operator 2
852bin 3
853games 7
854uucp 66
855nobody 32767
856.TE
857.DE
858The ``daemon'' user is used for daemon processes that
859do not need root privileges.
860The ``operator'' user-id is used as an account for dumpers
861so that they can log in without having the root password.
862By placing them in the ``operator'' group,
863they can get read access to the disks.
864The ``uucp'' login has existed long before \*(4B,
865and is noted here just to provide a common user-id.
866The password entry ``nobody'' has been added to specify
867the user with least privilege. The ``games'' user is a pseudo-user
868that controls access to game programs.
869.PP
870After installing your updated password file, you must run
871.Xr pwd_mkdb (8)
872to create the password database.
873Note that
874.Xr pwd_mkdb (8)
875is run whenever
876.Xr vipw (8)
877is run.
878.Sh 3 "The \f(CW/var\fP filesystem"
879.PP
880The spooling directories saved on tape may be restored in their
881eventual resting places without too much concern. Be sure to
882use the `\-p' option to
883.Xr tar (1)
884so that files are recreated with the same file modes.
885The following commands provide a guide for copying spool and log files from
886an existing system into a new
887.Pn /var
888filesystem.
889At least the following directories should already exist on
890.Pn /var :
891.Pn output ,
892.Pn log ,
893.Pn backups
894and
895.Pn db .
896.LP
897.DS
898.ft CW
899SRC=/oldroot/usr
900
901cd $SRC; tar cf - msgs preserve | (cd /var && tar xpf -)
902.DE
903.DS
904.ft CW
905# copy $SRC/spool to /var
906cd $SRC/spool
907tar cf - at mail rwho | (cd /var && tar xpf -)
908tar cf - ftp mqueue news secretmail uucp uucppublic | \e
909 (cd /var/spool && tar xpf -)
910.DE
911.DS
912.ft CW
913# everything else in spool is probably a printer area
914mkdir .save
915mv at ftp mail mqueue rwho secretmail uucp uucppublic .save
916tar cf - * | (cd /var/spool/output && tar xpf -)
917mv .save/* .
918rmdir .save
919.DE
920.DS
921.ft CW
922cd /var/spool/mqueue
923mv syslog.7 /var/log/maillog.7
924mv syslog.6 /var/log/maillog.6
925mv syslog.5 /var/log/maillog.5
926mv syslog.4 /var/log/maillog.4
927mv syslog.3 /var/log/maillog.3
928mv syslog.2 /var/log/maillog.2
929mv syslog.1 /var/log/maillog.1
930mv syslog.0 /var/log/maillog.0
931mv syslog /var/log/maillog
932.DE
933.DS
934.ft CW
935# move $SRC/adm to /var
936cd $SRC/adm
937tar cf - . | (cd /var/account && tar xpf -)
938cd /var/account
939rm -f msgbuf
940mv messages messages.[0-9] ../log
941mv wtmp wtmp.[0-9] ../log
942mv lastlog ../log
943.DE
944.Sh 2 "Bug fixes and changes between \*(Ps and \*(4B"
945.PP
946The major new facilities available in the \*(4B release are
947a new virtual memory system,
948the addition of ISO/OSI networking support,
949a new virtual filesystem interface supporting filesystem stacking,
950a freely redistributable implementation of NFS,
951a log-structured filesystem,
952enhancement of the local filesystems to support
953files and filesystems that are up to 2^63 bytes in size,
954enhanced security and system management support,
955and the conversion to and addition of the IEEE Std1003.1 (``POSIX'')
956facilities and many of the IEEE Std1003.2 facilities.
957In addition, many new utilities and additions to the C
958library are present as well.
959The kernel sources have been reorganized to collect all machine-dependent
960files for each architecture under one directory,
961and most of the machine-independent code is now free of code
962conditional on specific machines.
963The user structure and process structure have been reorganized
964to eliminate the statically-mapped user structure and to make most
965of the process resources shareable by multiple processes.
966The system and include files have been converted to be compatible
967with ANSI C, including function prototypes for most of the exported
968functions.
969There are numerous other changes throughout the system.
970.Sh 3 "Changes to the kernel"
971.PP
972This release includes several important structural kernel changes.
973The kernel uses a new internal system call convention;
974the use of global (``u-dot'') variables for parameters and error returns
975has been eliminated,
976and interrupted system calls no longer abort using non-local goto's (longjmp's).
977A new sleep interface separates signal handling from scheduling priority,
978returning characteristic errors to abort or restart the current system call.
979This sleep call also passes a string describing the process state,
980that is used by the ps(1) program.
981The old sleep interface can be used only for non-interruptible sleeps.
982The sleep interface (\fItsleep\fP) can be used at any priority,
983but is only interruptible if the PCATCH flag is set.
984When interrupted, \fItsleep\fP returns EINTR or ERESTART.
985.PP
986Many data structures that were previously statically allocated
987are now allocated dynamically.
988These structures include mount entries, file entries,
989user open file descriptors, the process entries, the vnode table,
990the name cache, and the quota structures.
991.PP
992To protect against indiscriminate reading or writing of kernel
993memory, all writing and most reading of kernel data structures
994must be done using a new ``sysctl'' interface.
995The information to be accessed is described through an extensible
996``Management Information Base'' (MIB) style name,
997described as a dotted set of components.
998A new utility,
999.Xr sysctl (8),
1000retrieves kernel state and allows processes with appropriate
1001privilege to set kernel state.
1002.Sh 3 "Security"
1003.PP
1004The kernel runs with four different levels of security.
1005Any superuser process can raise the security level, but only
1006.Fn init (8)
1007can lower it.
1008Security levels are defined as follows:
1009.IP \-1
1010Permanently insecure mode \- always run system in level 0 mode.
1011.IP " 0"
1012Insecure mode \- immutable and append-only flags may be turned off.
1013All devices may be read or written subject to their permissions.
1014.IP " 1"
1015Secure mode \- immutable and append-only flags may not be cleared;
1016disks for mounted filesystems,
1017.Pn /dev/mem ,
1018and
1019.Pn /dev/kmem
1020are read-only.
1021.IP " 2"
1022Highly secure mode \- same as secure mode, plus disks are always
1023read-only whether mounted or not.
1024This level precludes tampering with filesystems by unmounting them,
1025but also inhibits running
1026.Xr newfs (8)
1027while the system is multi-user.
1028See
1029.Xr chflags (1)
1030and the \-\fBo\fP option to
1031.Xr ls (1)
1032for information on setting and displaying the immutable and append-only
1033flags.
1034.PP
1035Normally, the system runs in level 0 mode while single user
1036and in level 1 mode while multiuser.
1037If the level 2 mode is desired while running multiuser,
1038it can be set in the startup script
1039.Pn /etc/rc
1040using
1041.Xr sysctl (1).
1042If it is desired to run the system in level 0 mode while multiuser,
1043the administrator must build a kernel with the variable
1044.Li securelevel
1045in the kernel source file
1046.Pn /sys/kern/kern_sysctl.c
1047initialized to \-1.
1048.Sh 4 "Virtual memory changes"
1049.PP
1050The new virtual memory implementation is derived from the Mach
1051operating system developed at Carnegie-Mellon,
1052and was ported to the BSD kernel at the University of Utah.
1053It is based on the 2.0 release of Mach
1054(with some bug fixes from the 2.5 and 3.0 releases)
1055and retains many of its essential features such as
1056the separation of the machine dependent and independent layers
1057(the ``pmap'' interface),
1058efficient memory utilization using copy-on-write
1059and other lazy-evaluation techniques,
1060and support for large, sparse address spaces.
1061It does not include the ``external pager'' interface instead using
1062a primitive internal pager interface.
1063The Mach virtual memory system call interface has been replaced with the
1064``mmap''-based interface described in the ``Berkeley Software
1065Architecture Manual'' (see UNIX Programmer's Manual,
1066Supplementary Documents, PSD:5).
1067The interface is similar to the interfaces shipped
1068by several commercial vendors such as Sun, USL, and Convex Computer Corp.
1069The integration of the new virtual memory is functionally complete,
1070but still has serious performance problems under heavy memory load.
1071The internal kernel interfaces have not yet been completed
1072and the memory pool and buffer cache have not been merged.
1073Some additional caveats:
1074.IP \(bu
1075Since the code is based on the 2.0 release of Mach,
1076bugs and misfeatures of the BSD version should not be considered
1077short-comings of the current Mach virtual memory system.
1078.IP \(bu
1079Because of the disjoint virtual memory (page) and IO (buffer) caches,
1080it is possible to see inconsistencies if using both the mmap and
1081read/write interfaces on the same file simultaneously.
1082.IP \(bu
1083Swap space is allocated on-demand rather than up front and no
1084allocation checks are performed so it is possible to over-commit
1085memory and eventually deadlock.
1086.IP \(bu
1087The semantics of the
1088.Xr vfork (2)
1089system call are slightly different.
1090The synchronization between parent and child is preserved,
1091but the memory sharing aspect is not.
1092In practice this has been enough for backward compatibility,
1093but newer code should just use
1094.Xr fork (2).
1095.Sh 4 "Networking additions and changes"
1096.PP
1097The ISO/OSI Networking consists of a kernel implementation of
1098transport class 4 (TP-4),
1099connectionless networking protocol (CLNP),
1100and 802.3-based link-level support (hardware-compatible with Ethernet\**).
1101.FS
1102Ethernet is a trademark of the Xerox Corporation.
1103.FE
1104We also include support for ISO Connection-Oriented Network Service,
1105X.25, TP-0.
1106The session and presentation layers are provided outside
1107the kernel using the ISO Development Environment by Marshall Rose,
1108that is available via anonymous FTP
1109(but is not included on the distribution tape).
1110Included in this development environment are file
1111transfer and management (FTAM), virtual terminals (VT),
1112a directory services implementation (X.500),
1113and miscellaneous other utilities.
1114.PP
1115Kernel support for the ISO OSI protocols is enabled with the ISO option
1116in the kernel configuration file.
1117The
1118.Xr iso (4)
1119manual page describes the protocols and addressing;
1120see also
1121.Xr clnp (4),
1122.Xr tp (4)
1123and
1124.Xr cltp (4).
1125The OSI equivalent to ARP is ESIS (End System to Intermediate System Routing
1126Protocol); running this protocol is mandatory, however one can manually add
1127translations for machines that do not participate by use of the
1128.Xr route (8)
1129command.
1130Additional information is provided in the manual page describing
1131.Xr esis (4).
1132.PP
1133The command
1134.Xr route (8)
1135has a new syntax and several new capabilities:
1136it can install routes with a specified destination and mask,
1137and can change route characteristics such as hop count, packet size
1138and window size.
1139.PP
1140Several important enhancements have been added to the TCP/IP
1141protocols including TCP header prediction and
1142serial line IP (SLIP) with header compression.
1143The routing implementation has been completely rewritten
1144to use a hierarchical routing tree with a mask per route
1145to support the arbitrary levels of routing found in the ISO protocols.
1146The routing table also stores and caches route characteristics
1147to speed the adaptation of the throughput and congestion avoidance
1148algorithms.
1149.PP
1150The format of the
1151.I sockaddr
1152structure (the structure used to describe a generic network address with an
1153address family and family-specific data)
1154has changed from previous releases,
1155as have the address family-specific versions of this structure.
1156The
1157.I sa_family
1158family field has been split into a length,
1159.Pn sa_len ,
1160and a family,
1161.Pn sa_family .
1162System calls that pass a
1163.I sockaddr
1164structure into the kernel (e.g.
1165.Fn sendto
1166and
1167.Fn connect )
1168have a separate parameter that specifies the
1169.I sockaddr
1170length, and thus it is not necessary to fill in the
1171.I sa_len
1172field for those system calls.
1173System calls that pass a
1174.I sockaddr
1175structure back from the kernel (e.g.
1176.Fn recvfrom
1177and
1178.Fn accept )
1179receive a completely filled-in
1180.I sockaddr
1181structure, thus the length field is valid.
1182Because this would not work for old binaries,
1183the new library uses a different system call number.
1184Thus, most networking programs compiled under \*(4B are incompatible
1185with older systems.
1186.PP
1187Although this change is mostly source and binary compatible
1188with old programs, there are three exceptions.
1189Programs with statically initialized
1190.I sockaddr
1191structures
1192(usually the Internet form, a
1193.I sockaddr_in )
1194are not compatible.
1195Generally, such programs should be changed to fill in the structure
1196at run time, as C allows no way to initialize a structure without
1197assuming the order and number of fields.
1198Also, programs with use structures to describe a network packet format
1199that contain embedded
1200.I sockaddr
1201structures also require change; a definition of an
1202.I osockaddr
1203structure is provided for this purpose.
1204Finally, programs that use the
1205.Sm SIOCGIFCONF
1206ioctl to get a complete list of interface addresses
1207need to check the
1208.I sa_len
1209field when iterating through the array of addresses returned,
1210as not all the structures returned have the same length
1211(this variance in length is nearly guaranteed by the presence of link-layer
1212address structures).
1213.Sh 4 "Additions and changes to filesystems"
1214.PP
1215The \*(4B distribution contains most of the interfaces
1216specified in the IEEE Std1003.1 system interface standard.
1217Filesystem additions include IEEE Std1003.1 FIFOs,
1218byte-range file locking, and saved user and group identifiers.
1219.PP
1220A new virtual filesystem interface has been added to the
1221kernel to support multiple filesystems.
1222In comparison with other interfaces,
1223the Berkeley interface has been structured for more efficient support
1224of filesystems that maintain state (such as the local filesystem).
1225The interface has been extended with support for stackable
1226filesystems done at UCLA.
1227These extensions allow for filesystems to be layered on top of each
1228other and allow new vnode operations to be added without requiring
1229changes to existing filesystem implementations.
1230For example,
1231the umap filesystem (see
1232.Xr mount_umap (8))
1233is used to mount a sub-tree of an existing filesystem
1234that uses a different set of uids and gids than the local system.
1235Such a filesystem could be mounted from a remote site via NFS or it
1236could be a filesystem on removable media brought from some foreign
1237location that uses a different password file.
1238.PP
1239Other new filesystems that may be stacked include the loopback filesystem
1240.Xr mount_lofs (8),
1241the kernel filesystem
1242.Xr mount_kernfs (8),
1243and the portal filesystem
1244.Xr mount_portal (8).
1245.PP
1246The buffer cache in the kernel is now organized as a file block cache
1247rather than a device block cache.
1248As a consequence, cached blocks from a file
1249and from the corresponding block device would no longer be kept consistent.
1250The block device thus has little remaining value.
1251Three changes have been made for these reasons:
1252.IP 1)
1253block devices may not be opened while they are mounted,
1254and may not be mounted while open, so that the two versions of cached
1255file blocks cannot be created,
1256.IP 2)
1257filesystem checks of the root now use the raw device
1258to access the root filesystem, and
1259.IP 3)
1260the root filesystem is initially mounted read-only
1261so that nothing can be written back to disk during or after change to
1262the raw filesystem by
1263.Xr fsck .
1264.LP
1265The root filesystem may be made writable while in single-user mode
1266with the command:
1267.DS
1268.ft CW
1269mount \-uw /
1270.DE
1271The mount command has an option to update the flags on a mounted filesystem,
1272including the ability to upgrade a filesystem from read-only to read-write
1273or downgrade it from read-write to read-only.
1274.PP
1275In addition to the local ``fast filesystem'',
1276we have added an implementation of the network filesystem (NFS)
1277that fully interoperates with the NFS shipped by Sun and its licensees.
1278Because our NFS implementation was implemented
1279by Rick Macklem of the University of Guelph
1280using only the publicly available NFS specification,
1281it does not require a license from Sun to use in source or binary form.
1282By default it runs over UDP to be compatible with Sun's implementation.
1283However, it can be configured on a per-mount basis to run over TCP.
1284Using TCP allows it to be used quickly and efficiently through
1285gateways and over long-haul networks.
1286Using an extended protocol, it supports Leases to allow a limited
1287callback mechanism that greatly reduces the network traffic necessary
1288to maintain cache consistency between the server and its clients.
1289Its use will be familiar to users of other implementations of NFS.
1290See the manual pages
1291.Xr mount (8),
1292.Xr mountd (8),
1293.Xr fstab (5),
1294.Xr exports (5),
1295.Xr netgroup (5),
1296.Xr nfsd (8),
1297.Xr nfsiod (8),
1298and
1299.Xr nfssvc (8).
1300and the document ``The 4.4BSD NFS Implementation'' (SMM:6)
1301for further information.
1302The format of
1303.Pn /etc/fstab
1304has changed from previous \*(Bs releases
1305to a blank-separated format to allow colons in pathnames.
1306.PP
1307A new local filesystem, the log-structured filesystem (LFS),
1308has been added to the system.
1309It provides near disk-speed output and fast crash recovery.
1310This work is based, in part, on the LFS filesystem created
1311for the Sprite operating system at Berkeley.
1312While the kernel implementation is almost complete,
1313only some of the utilities to support the
1314filesystem have been written,
1315so we do not recommend it for production use.
1316See
1317.Xr newlfs (8),
1318.Xr mount_lfs (8)
1319and
1320.Xr lfs_cleanerd (8)
1321for more information.
1322For an in-depth description of the implementation and performance
1323characteristics of log-structured filesystems in general,
1324and this one in particular, see Dr. Margo Seltzer's doctoral thesis,
1325available from the University of California Computer Science Department.
1326.PP
1327We have also added a memory-based filesystem that runs in
1328pageable memory, allowing large temporary filesystems without
1329requiring dedicated physical memory.
1330.PP
1331The local ``fast filesystem'' has been enhanced to do
1332clustering that allows large pieces of files to be
1333allocated contiguously resulting in near doubling
1334of filesystem throughput.
1335The filesystem interface has been extended to allow
1336files and filesystems to grow to 2^63 bytes in size.
1337The quota system has been rewritten to support both
1338user and group quotas (simultaneously if desired).
1339Quota expiration is based on time rather than
1340the previous metric of number of logins over quota.
1341This change makes quotas more useful on fileservers
1342onto which users seldom login.
1343.PP
1344The system security has been greatly enhanced by the
1345addition of additional file flags that permit a file to be
1346marked as immutable or append only.
1347Once set, these flags can only be cleared by the super-user
1348when the system is running in insecure mode (normally, single-user).
1349In addition to the immutable and append-only flags,
1350the filesystem supports a new user-settable flag ``nodump''.
1351(File flags are set using the
1352.Xr chflags (1)
1353utility.)
1354When set on a file,
1355.Xr dump (8)
1356will omit the file from incremental backups
1357but retain them on full backups.
1358See the ``-h'' flag to
1359.Xr dump (8)
1360for details on how to change this default.
1361The ``nodump'' flag is usually set on core dumps,
1362system crash dumps, and object files generated by the compiler.
1363Note that the flag is not preserved when files are copied
1364so that installing an object file will cause it to be preserved.
1365.PP
1366The filesystem format used in \*(4B has several additions.
1367Directory entries have an additional field,
1368.Pn d_type ,
1369that identifies the type of the entry
1370(normally found in the
1371.Pn st_mode
1372field of the
1373.Pn stat
1374structure).
1375This field is particularly useful for identifying
1376directories without the need to use
1377.Xr stat (2).
1378.PP
1379Short (less than sixty byte) symbolic links are now stored
1380in the inode itself rather than in a separate data block.
1381This saves disk space and makes access of symbolic links faster.
1382Short symbolic links are not given a special type,
1383so a user-level application is unaware of their special treatment.
1384Unlike pre-\*(4B systems, symbolic links do
1385not have an owner, group, access mode, times, etc.
1386Instead, these attributes are taken from the directory that contains the link.
1387The only attributes returned from an
1388.Xr lstat (2)
1389that refer to the symbolic link itself are the file type (S_IFLNK),
1390size, blocks, and link count (always 1).
1391.PP
1392An implementation of an auto-mounter daemon,
1393.Xr amd ,
1394was contributed by Jan-Simon Pendry of the
1395Imperial College of Science, Technology & Medicine.
1396See the document ``AMD \- The 4.4BSD Automounter'' (SMM:13)
1397for further information.
1398.PP
1399The directory
1400.Pn /dev/fd
1401contains special files
1402.Pn 0
1403through
1404.Pn 63
1405that, when opened, duplicate the corresponding file descriptor.
1406The names
1407.Pn /dev/stdin ,
1408.Pn /dev/stdout
1409and
1410.Pn /dev/stderr
1411refer to file descriptors 0, 1 and 2.
1412See
1413.Xr fd (4)
1414and
1415.Xr mount_fdesc (8)
1416for more information.
1417.Sh 4 "POSIX terminal driver changes"
1418.PP
1419The \*(4B system uses the IEEE P1003.1 (POSIX.1) terminal interface
1420rather than the previous \*(Bs terminal interface.
1421The terminal driver is similar to the System V terminal driver
1422with the addition of the necessary extensions to get the
1423functionality previously available in the \*(Ps terminal driver.
1424Both the old
1425.Xr ioctl
1426calls and old options to
1427.Xr stty (1)
1428are emulated.
1429This emulation is expected to be unavailable in many vendors releases,
1430so conversion to the new interface is encouraged.
1431.PP
1432\*(4B also adds the IEEE Std1003.1 job control interface,
1433that is similar to the \*(Ps job control interface,
1434but adds a security model that was missing in the
1435\*(Ps job control implementation.
1436A new system call,
1437.Fn setsid ,
1438creates a job-control session consisting of a single process
1439group with one member, the caller, that becomes a session leader.
1440Only a session leader may acquire a controlling terminal.
1441This is done explicitly via a
1442.Sm TIOCSCTTY
1443.Fn ioctl
1444call, not implicitly by an
1445.Fn open
1446call.
1447The call fails if the terminal is in use.
1448Programs that allocate controlling terminals (or pseudo-terminals)
1449require change to work in this environment.
1450The versions of
1451.Xr xterm
1452provided in the X11R5 release includes the necessary changes.
1453New library routines are available for allocating and initializing
1454pseudo-terminals and other terminals as controlling terminal; see
1455.Pn /usr/src/lib/libutil/pty.c
1456and
1457.Pn /usr/src/lib/libutil/login_tty.c .
1458.PP
1459The POSIX job control model formalizes the previous conventions
1460used in setting up a process group.
1461Unfortunately, this requires that changes be made in a defined order
1462and with some synchronization that were not necessary in the past.
1463Older job control shells (csh, ksh) will generally not operate correctly
1464with the new system.
1465.PP
1466Most of the other kernel interfaces have been changed to correspond
1467with the POSIX.1 interface, although that work is not complete.
1468See the relevant manual pages and the IEEE POSIX standard.
1469.Sh 4 "Native operating system compatibility"
1470.PP
1471Both the HP300 and SPARC ports feature the ability to run binaries
1472built for the native operating system (HP-UX or SunOS) by emulating
1473their system calls.
1474Building an HP300 kernel with the HPUXCOMPAT and COMPAT_OHPUX options
1475or a SPARC kernel with the COMPAT_SUNOS option will enable this feature
1476(on by default in the generic kernel provided in the root filesystem image).
1477Though this native operating system compatibility was provided by the
1478developers as needed for their purposes and is by no means complete,
1479it is complete enough to run several non-trivial applications including
1480those that require HP-UX or SunOS shared libraries.
1481For example, the vendor supplied X11 server and windowing environment
1482can be used on both the HP300 and SPARC.
1483.PP
1484It is important to remember that merely copying over a native binary
1485and executing it (or executing it directly across NFS) does not imply
1486that it will run.
1487All but the most trivial of applications are likely to require access
1488to auxiliary files that do not exist under \*(4B (e.g.
1489.Pn /etc/ld.so.cache )
1490or have a slightly different format (e.g.
1491.Pn /etc/passwd ).
1492However, by using system call tracing and
1493through creative use of symlinks,
1494many problems can be tracked down and corrected.
1495.PP
1496The DECstation port also has code for ULTRIX emulation
1497(kernel option ULTRIXCOMPAT, not compiled into the generic kernel)
1498but it was used primarily for initially bootstrapping the port and
1499has not been used since.
1500Hence, some work may be required to make it generally useful.
1501.Sh 3 "Changes to the utilities"
1502.PP
1503We have been tracking the IEEE Std1003.2 shell and utility work
1504and have included prototypes of many of the proposed utilities
1505based on draft 12 of the POSIX.2 Shell and Utilities document.
1506Because most of the traditional utilities have been replaced
1507with implementations conformant to the POSIX standards,
1508you should realize that the utility software may not be as stable,
1509reliable or well documented as in traditional Berkeley releases.
1510In particular, almost the entire manual suite has been rewritten to
1511reflect the POSIX defined interfaces, and in some instances
1512it does not correctly reflect the current state of the software.
1513It is also worth noting that, in rewriting this software, we have generally
1514been rewarded with significant performance improvements.
1515Most of the libraries and header files have been converted
1516to be compliant with ANSI C.
1517The shipped compiler (gcc) is a superset of ANSI C,
1518but supports traditional C as a command-line option.
1519The system libraries and utilities all compile
1520with either ANSI or traditional C.
1521.Sh 4 "Make and Makefiles"
1522.PP
1523This release uses a completely new version of the
1524.Xr make
1525program derived from the
1526.Xr pmake
1527program developed by the Sprite project at Berkeley.
1528It supports existing makefiles, although certain incorrect makefiles
1529may fail.
1530The makefiles for the \*(4B sources make extensive use of the new
1531facilities, especially conditionals and file inclusion, and are thus
1532completely incompatible with older versions of
1533.Xr make
1534(but nearly all the makefiles are now trivial!).
1535The standard include files for
1536.Xr make
1537are in
1538.Pn /usr/share/mk .
1539There is a
1540.Pn bsd.README
1541file in
1542.Pn /usr/src/share/mk .
1543.PP
1544Another global change supported by the new
1545.Xr make
1546is designed to allow multiple architectures to share a copy of the sources.
1547If a subdirectory named
1548.Pn obj
1549is present in the current directory,
1550.Xr make
1551descends into that directory and creates all object and other files there.
1552We use this by building a directory hierarchy in
1553.Pn /var/obj
1554that parallels
1555.Pn /usr/src .
1556We then create the
1557.Pn obj
1558subdirectories in
1559.Pn /usr/src
1560as symbolic links to the corresponding directories in
1561.Pn /var/obj .
1562(This step is automated.
1563The command ``make obj'' in
1564.Pn /usr/src
1565builds both the local symlink and the shadow directory,
1566using
1567.Pn /usr/obj ,
1568that may be a symbolic link, as the root of the shadow tree.
1569The use of
1570.Pn /usr/obj
1571is for historic reasons only, and the system make configuration files in
1572.Pn /usr/share/mk
1573can trivially be modified to use
1574.Pn /var/obj
1575instead.)
1576We have one
1577.Pn /var/obj
1578hierarchy on the local system, and another on each
1579system that shares the source filesystem.
1580All the sources in
1581.Pn /usr/src
1582except for
1583.Pn /usr/src/contrib
1584and portions of
1585.Pn /usr/src/old
1586have been converted to use the new make and
1587.Pn obj
1588subdirectories;
1589this change allows compilation for multiple
1590architectures from the same source tree
1591(that may be mounted read-only).
1592.Sh 4 "Kerberos"
1593.PP
1594The Kerberos authentication server from MIT (version 4)
1595is included in this release.
1596See
1597.Xr kerberos (1)
1598for a general, if MIT-specific, introduction.
1599If it is configured,
1600.Xr login (1),
1601.Xr passwd (1),
1602.Xr rlogin (1)
1603and
1604.Xr rsh (1)
1605will all begin to use it automatically.
1606The file
1607.Pn /etc/kerberosIV/README
1608describes the configuration.
1609Each system needs the file
1610.Pn /etc/kerberosIV/krb.conf
1611to set its realm and local servers,
1612and a private key stored in
1613.Pn /etc/kerberosIV/srvtab
1614(see
1615.Xr ext_srvtab (8)).
1616The Kerberos server should be set up on a single, physically secure,
1617server machine.
1618Users and hosts may be added to the server database manually with
1619.Xr kdb_edit (8),
1620or users on authorized hosts can add themselves and a Kerberos
1621password after verification of their ``local'' (passwd-file) password
1622using the
1623.Xr register (1)
1624program.
1625.PP
1626Note that by default the password-changing program
1627.Xr passwd (1)
1628changes the Kerberos password, that must exist.
1629The
1630.Li \-l
1631option to
1632.Xr passwd (1)
1633changes the ``local'' password if one exists.
1634.PP
1635Note that Version 5 of Kerberos will be released soon;
1636Version 4 should probably be replaced at that time.
1637.Sh 4 "Timezone support"
1638.PP
1639The timezone conversion code in the C library uses data files installed in
1640.Pn /usr/share/zoneinfo
1641to convert from ``GMT'' to various timezones. The data file for the default
1642timezone for the system should be copied to
1643.Pn /etc/localtime .
1644Other timezones can be selected by setting the TZ environment variable.
1645.PP
1646The data files initially installed in
1647.Pn /usr/share/zoneinfo
1648include corrections for leap seconds since the beginning of 1970.
1649Thus, they assume that the
1650kernel will increment the time at a constant rate during a leap second;
1651that is, time just keeps on ticking. The conversion routines will then
1652name a leap second 23:59:60. For purists, this effectively means that
1653the kernel maintains TAI (International Atomic Time) rather than UTC
1654(Coordinated Universal Time, aka GMT).
1655.PP
1656For systems that run current NTP (Network Time Protocol) implementations
1657or that wish to conform to the letter of the POSIX.1 law, it is possible
1658to rebuild the timezone data files so that leap seconds are not counted.
1659(NTP causes the time to jump over a leap second, and POSIX effectively
1660requires the clock to be reset by hand when a leap second occurs.
1661In this mode, the kernel effectively runs UTC rather than TAI.)
1662.PP
1663The data files without leap second information
1664are constructed from the source directory,
1665.Pn /usr/src/share/zoneinfo .
1666Change the variable REDO in Makefile
1667from ``right'' to ``posix'', and then do
1668.DS
1669make obj (if necessary)
1670make
1671make install
1672.DE
1673.PP
1674You will then need to copy the correct default zone file to
1675.Pn /etc/localtime ,
1676as the old one would still have used leap seconds, and because the Makefile
1677installs a default
1678.Pn /etc/localtime
1679each time ``make install'' is done.
1680.PP
1681It is possible to install both sets of timezone data files. This results
1682in subdirectories
1683.Pn /usr/share/zoneinfo/right
1684and
1685.Pn /usr/share/zoneinfo/posix .
1686Each contain a complete set of zone files.
1687See
1688.Pn /usr/src/share/zoneinfo/Makefile
1689for details.
1690.Sh 4 "Additions and changes to the libraries"
1691.PP
1692Notable additions to the libraries include functions to traverse a
1693filesystem hierarchy, database interfaces to btree and hashing functions,
1694a new, faster implementation of stdio and a radix and merge sort
1695functions.
1696.PP
1697The
1698.Xr fts (3)
1699functions will do either physical or logical traversal of
1700a file hierarchy as well as handle essentially infinite depth
1701filesystems and filesystems with cycles.
1702All the utilities in \*(4B which traverse file hierarchies
1703have been converted to use
1704.Xr fts (3).
1705The conversion has always resulted in a significant performance
1706gain, often of four or five to one in system time.
1707.PP
1708The
1709.Xr dbopen (3)
1710functions are intended to be a family of database access methods.
1711Currently, they consist of
1712.Xr hash (3),
1713an extensible, dynamic hashing scheme,
1714.Xr btree (3),
1715a sorted, balanced tree structure (B+tree's), and
1716.Xr recno (3),
1717a flat-file interface for fixed or variable length records
1718referenced by logical record number.
1719Each of the access methods stores associated key/data pairs and
1720uses the same record oriented interface for access.
1721.PP
1722The
1723.Xr qsort (3)
1724function has been rewritten for additional performance.
1725In addition, three new types of sorting functions,
1726.Xr heapsort (3),
1727.Xr mergesort (3)
1728and
1729.Xr radixsort (3)
1730have been added to the system.
1731The
1732.Xr mergesort
1733function is optimized for data with pre-existing order,
1734in which case it usually significantly outperforms
1735.Xr qsort .
1736The
1737.Xr radixsort (3)
1738functions are variants of most-significant-byte radix sorting.
1739They take time linear to the number of bytes to be
1740sorted, usually significantly outperforming
1741.Xr qsort
1742on data that can be sorted in this fashion.
1743An implementation of the POSIX 1003.2 standard
1744.Xr sort (1),
1745based on
1746.Xr radixsort ,
1747is included in
1748.Pn /usr/src/contrib/sort .
1749.PP
1750Some additional comments about the \*(4B C library:
1751.IP \(bu
1752The floating point support in the C library has been replaced
1753and is now accurate.
1754.IP \(bu
1755The C functions specified by both ANSI C, POSIX 1003.1 and
17561003.2 are now part of the C library.
1757This includes support for file name matching, shell globbing
1758and both basic and extended regular expressions.
1759.IP \(bu
1760ANSI C multibyte and wide character support has been integrated.
1761The rune functionality from the Bell Labs' Plan 9 system is provided
1762as well.
1763.IP \(bu
1764The
1765.Xr termcap (3)
1766functions have been generalized and replaced with a general
1767purpose interface named
1768.Xr getcap (3).
1769.IP \(bu
1770The
1771.Xr stdio (3)
1772routines have been replaced, and are usually much faster.
1773In addition, the
1774.Xr funopen (3)
1775interface permits applications to provide their own I/O stream
1776function support.
1777.PP
1778The
1779.Xr curses (3)
1780library has been largely rewritten.
1781Important additional features include support for scrolling and
1782.Xr termios (3).
1783.PP
1784An application front-end editing library, named libedit, has been
1785added to the system.
1786.PP
1787A superset implementation of the SunOS kernel memory interface library,
1788libkvm, has been integrated into the system.
1789.PP
1790.Sh 4 "Additions and changes to other utilities"
1791.PP
1792There are many new utilities, offering many new capabilities,
1793in \*(4B.
1794Skimming through the section 1 and section 8 manual pages is sure
1795to be useful.
1796The additions to the utility suite include greatly enhanced versions of
1797programs that display system status information, implementations of
1798various traditional tools described in the IEEE Std1003.2 standard,
1799new tools not previous available on Berkeley UNIX systems,
1800and many others.
1801Also, with only a very few exceptions, all the utilities from
1802\*(Ps that included proprietary source code have been replaced,
1803and their \*(4B counterparts are freely redistributable.
1804Normally, this replacement resulted in significant performance
1805improvements and the increase of the limits imposed on data by
1806the utility as well.
1807.PP
1808A summary of specific additions and changes are as follows:
1809.TS
1810lfC l.
1811amd An auto-mounter implementation.
1812ar Replacement of the historic archive format with a new one.
1813awk Replaced by gawk; see /usr/src/old/awk for the historic version.
1814bdes Utility implementing DES modes of operation described in FIPS PUB 81.
1815calendar Addition of an interface for system calendars.
1816cap_mkdb Utility for building hashed versions of termcap style databases.
1817cc Replacement of pcc with gcc suite.
1818chflags A utility for setting the per-file user and system flags.
1819chfn An editor based replacement for changing user information.
1820chpass An editor based replacement for changing user information.
1821chsh An editor based replacement for changing user information.
1822cksum The POSIX 1003.2 checksum utility; compatible with sum.
1823column A columnar text formatting utility.
1824cp POSIX 1003.2 compatible, able to copy special files.
1825csh Freely redistributable and 8-bit clean.
1826date User specified formats added.
1827dd New EBCDIC conversion tables, major performance improvements.
1828dev_mkdb Hashed interface to devices.
1829dm Dungeon master.
1830find Several new options and primaries, major performance improvements.
1831fstat Utility displaying information on files open on the system.
1832ftpd Connection logging added.
1833hexdump A binary dump utility, superseding od.
1834id The POSIX 1003.2 user identification utility.
1835inetd Tcpmux added.
1836jot A text formatting utility.
1837kdump A system-call tracing facility.
1838ktrace A system-call tracing facility.
1839kvm_mkdb Hashed interface to the kernel name list.
1840lam A text formatting utility.
1841lex A new, freely redistributable, significantly faster version.
1842locate A database of the system files, by name, constructed weekly.
1843logname The POSIX 1003.2 user identification utility.
1844mail.local New local mail delivery agent, replacing mail.
1845make Replaced with a new, more powerful make, supporting include files.
1846man Added support for man page location configuration.
1847mkdep A new utility for generating make dependency lists.
1848mkfifo The POSIX 1003.2 FIFO creation utility.
1849mtree A new utility for mapping file hierarchies to a file.
1850nfsstat An NFS statistics utility.
1851nvi A freely redistributable replacement for the ex/vi editors.
1852pax The POSIX 1003.2 replacement for cpio and tar.
1853printf The POSIX 1003.2 replacement for echo.
1854roff Replaced by groff; see /usr/src/old/roff for the historic versions.
1855rs New utility for text formatting.
1856shar An archive building utility.
1857sysctl MIB-style interface to system state.
1858tcopy Fast tape-to-tape copying and verification.
1859touch Time and file reference specifications.
1860tput The POSIX 1003.2 terminal display utility.
1861tr Addition of character classes.
1862uname The POSIX 1003.2 system identification utility.
1863vis A filter for converting and displaying non-printable characters.
1864xargs The POSIX 1003.2 argument list constructor utility.
1865yacc A new, freely redistributable, significantly faster version.
1866.TE
1867.PP
1868The new versions of
1869.Xr lex (1)
1870(``flex'') and
1871.Xr yacc (1)
1872(``zoo'') should be installed early on if attempting to
1873cross-compile \*(4B on another system.
1874Note that the new
1875.Xr lex
1876program is not completely backward compatible with historic versions of
1877.Xr lex ,
1878although it is believed that all documented features are supported.
1879.PP
1880The
1881.Xr find
1882utility has two new options that are important to be aware of if you
1883intend to use NFS.
1884The ``fstype'' and ``prune'' options can be used together to prevent
1885find from crossing NFS mount points.
1886See
1887.Pn /etc/daily
1888for an example of their use.
1889.Sh 2 "Hints on converting from \*(Ps to \*(4B"
1890.PP
1891This section summarizes changes between
1892\*(Ps and \*(4B that are likely to
1893cause difficulty in doing the conversion.
1894It does not include changes in the network;
1895see section 5 for information on setting up the network.
1896.PP
1897Since the stat st_size field is now 64-bits instead of 32,
1898doing something like:
1899.DS
1900.ft CW
1901foo(st.st_size);
1902.DE
1903and then (improperly) defining foo with an ``int'' or ``long'' parameter:
1904.DS
1905.ft CW
1906foo(size)
1907 int size;
1908{
1909 ...
1910}
1911.DE
1912will fail miserably (well, it might work on a little endian machine).
1913This problem showed up in
1914.Xr emacs (1)
1915as well as several other programs.
1916A related problem is improperly casting (or failing to cast)
1917the second argument to
1918.Xr lseek (2),
1919.Xr truncate (2),
1920or
1921.Xr ftruncate (2)
1922ala:
1923.DS
1924.ft CW
1925lseek(fd, (long)off, 0);
1926.DE
1927or
1928.DS
1929.ft CW
1930lseek(fd, 0, 0);
1931.DE
1932The best solution is to include
1933.Pn <unistd.h>
1934which has prototypes that catch these types of errors.
1935.PP
1936Determining the ``namelen'' parameter for a
1937.Xr connect (2)
1938call on a unix domain socket should use the ``SUN_LEN'' macro from
1939.Pn <sys/un.h> .
1940One old way that was used:
1941.DS
1942.ft CW
1943addrlen = strlen(unaddr.sun_path) + sizeof(unaddr.sun_family);
1944.DE
1945no longer works as there is an additional
1946.Pn sun_len
1947field.
1948.PP
1949The kernel's limit on the number of open files has been
1950increased from 20 to 64.
1951It is now possible to change this limit almost arbitrarily.
1952The standard I/O library
1953autoconfigures to the kernel limit.
1954Note that file (``_iob'') entries may be allocated by
1955.Xr malloc
1956from
1957.Xr fopen ;
1958this allocation has been known to cause problems with programs
1959that use their own memory allocators.
1960Memory allocation does not occur until after 20 files have been opened
1961by the standard I/O library.
1962.PP
1963.Xr Select
1964can be used with more than 32 descriptors
1965by using arrays of \fBint\fPs for the bit fields rather than single \fBint\fPs.
1966Programs that used
1967.Xr getdtablesize
1968as their first argument to
1969.Xr select
1970will no longer work correctly.
1971Usually the program can be modified to correctly specify the number
1972of bits in an \fBint\fP.
1973Alternatively the program can be modified to use an array of \fBint\fPs.
1974There are a set of macros available in
1975.Pn <sys/types.h>
1976to simplify this.
1977See
1978.Xr select (2).
1979.PP
1980Old core files will not be intelligible by the current debuggers
1981because of numerous changes to the user structure
1982and because the kernel stack has been enlarged.
1983The
1984.Xr a.out
1985header that was in the user structure is no longer present.
1986Locally-written debuggers that try to check the magic number
1987will need to be changed.
1988.PP
1989Files may not be deleted from directories having the ``sticky'' (ISVTX) bit
1990set in their modes
1991except by the owner of the file or of the directory, or by the superuser.
1992This is primarily to protect users' files in publicly-writable directories
1993such as
1994.Pn /tmp
1995and
1996.Pn /var/tmp .
1997All publicly-writable directories should have their ``sticky'' bits set
1998with ``chmod +t.''
1999.PP
2000The following two sections contain additional notes about
2001changes in \*(4B that affect the installation of local files;
2002be sure to read them as well.