1 .\" Copyright (c) 1980, 1986, 1988, 1993 The Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .\" @(#)6.t 8.1 (Berkeley) 7/27/93
34 .ds LH "Installing/Operating \*(4B
36 .Sh 1 "System operation"
38 This section describes procedures used to operate a \*(4B UNIX system.
39 Procedures described here are used periodically, to reboot the system,
40 analyze error messages from devices, do disk backups, monitor
41 system performance, recompile system software and control local changes.
42 .Sh 2 "Bootstrap and shutdown procedures"
44 In a normal reboot, the system checks the disks and comes up multi-user
45 without intervention at the console.
47 can be stopped (after it prints the date) with a ^C (interrupt).
48 This will leave the system in single-user mode, with only the console
50 (If the console has been marked ``insecure'' in
52 you must enter the root password to bring the machine to single-user mode.)
53 It is also possible to allow the filesystem checks to complete
54 and then to return to single-user mode by signaling
56 with a QUIT signal (^\|\e).
58 To bring the system up to a multi-user configuration from the single-user
60 all you have to do is hit ^D on the console. The system
63 a multi-user restart script (and
65 and come up on the terminals listed as
71 .Xr ttys (5) for more details.
72 Note, however, that this does not cause a filesystem check to be done.
73 Unless the system was taken down cleanly, you should run
74 ``fsck \-p'' or force a reboot with
76 to have the disks checked.
78 To take the system down to a single user state you can use
84 command (which is much more polite, if there are other users logged in)
85 when you are running multi-user.
86 Either command will kill all processes and give you a shell on the console,
87 as if you had just booted. Filesystems remain mounted after the
88 system is taken single-user. If you wish to come up multi-user again, you
92 \fB#\fP \fI/sbin/umount -a\fP
96 Each system shutdown, crash, processor halt and reboot
97 is recorded in the system log
99 .Sh 2 "Device errors and diagnostics"
101 When serious errors occur on peripherals or in the system, the system
102 prints a warning diagnostic on the console.
103 These messages are collected
104 by the system error logging process
106 and written into a system error log file
107 .Pn /var/log/messages .
108 Less serious errors are sent directly to
110 which may log them on the console.
111 The error priorities that are logged and the locations to which they are logged
113 .Pn /etc/syslog.conf .
118 Error messages printed by the devices in the system are described with the
119 drivers for the devices in section 4 of the programmer's manual.
120 If errors occur suggesting hardware problems, you should contact
121 your hardware support group or field service. It is a good idea to
122 examine the error log file regularly
123 (e.g. with the command \fItail \-r /var/log/messages\fP).
124 .Sh 2 "Filesystem checks, backups, and disaster recovery"
126 Periodically (say every week or so in the absence of any problems)
127 and always (usually automatically) after a crash,
128 all the filesystems should be checked for consistency
133 should be used to get the system to a state where a filesystem
134 check can be done manually or automatically.
136 Dumping of the filesystems should be done regularly,
137 since once the system is going it is easy to
139 Complete and incremental dumps are easily done with
141 You should arrange to do a towers-of-hanoi dump sequence; we tune
142 ours so that almost all files are dumped on two tapes and kept for at
143 least a week in most every case. We take full dumps every month (and keep
145 Operators can execute ``dump w'' at login that will tell them what needs
150 Be sure to create a group
154 so that dump can notify logged-in operators when it needs help.
156 More precisely, we have three sets of dump tapes: 10 daily tapes,
157 5 weekly sets of 2 tapes, and fresh sets of three tapes monthly.
158 We do daily dumps circularly on the daily tapes with sequence
159 `3 2 5 4 7 6 9 8 9 9 9 ...'.
160 Each weekly is a level 1 and the daily dump sequence level
161 restarts after each weekly dump.
162 Full dumps are level 0 and the daily sequence restarts after each full dump
165 Thus a typical dump sequence would be:
172 tape name level number date opr size
174 FULL 0 Nov 24, 1992 operator 137K
175 D1 3 Nov 28, 1992 operator 29K
176 D2 2 Nov 29, 1992 operator 34K
177 D3 5 Nov 30, 1992 operator 19K
178 D4 4 Dec 1, 1992 operator 22K
179 W1 1 Dec 2, 1992 operator 40K
180 D5 3 Dec 4, 1992 operator 15K
181 D6 2 Dec 5, 1992 operator 25K
182 D7 5 Dec 6, 1992 operator 15K
183 D8 4 Dec 7, 1992 operator 19K
184 W2 1 Dec 9, 1992 operator 118K
185 D9 3 Dec 11, 1992 operator 15K
186 D10 2 Dec 12, 1992 operator 26K
187 D1 5 Dec 15, 1992 operator 14K
188 W3 1 Dec 17, 1992 operator 71K
189 D2 3 Dec 18, 1992 operator 13K
190 FULL 0 Dec 22, 1992 operator 135K
192 We do weekly dumps often enough that daily dumps always fit on one tape.
194 Dumping of files by name is best done by
196 but the amount of data that can be moved in this way is limited
198 Finally if there are enough drives entire
199 disks can be copied with
201 using the raw special files and an appropriate
202 blocking factor; the number of sectors per track is usually
203 a good value to use, consult
206 It is desirable that full dumps of the root filesystem be
208 This is especially true when only one disk is available.
210 root filesystem is damaged by a hardware or software failure, you
211 can rebuild a workable disk doing a restore in the
212 same way that the initial root filesystem was created.
214 Exhaustion of user-file space is certain to occur
215 now and then; disk quotas may be imposed, or if you
216 prefer a less fascist approach, try using the programs
221 combined with threatening
222 messages of the day, and personal letters.
223 .Sh 2 "Moving filesystem data"
225 If you have the resources,
226 the best way to move a filesystem
227 is to dump it to a spare disk partition, or magtape, using
231 to create the new filesystem,
232 and restore the filesystem using
234 Filesystems may also be moved by piping the output of
240 program uses an ``in-place'' algorithm that
241 allows filesystem dumps to be restored without concern for the
242 original size of the filesystem. Further, portions of a
243 filesystem may be selectively restored using a method similar
244 to the tape archive program.
246 If you have to merge a filesystem into another, existing one,
247 the best bet is to use
249 If you must shrink a filesystem, the best bet is to dump
250 the original and restore it onto the new filesystem.
252 are playing with the root filesystem and only have one drive,
253 the procedure is more complicated.
254 If the only drive is a Winchester disk, this procedure may not be used
255 without overwriting the existing root or another partition.
256 What you do is the following:
258 GET A SECOND PACK, OR USE ANOTHER DISK DRIVE!!!!
260 Dump the root filesystem to tape using
263 Bring the system down.
265 Mount the new pack in the correct disk drive, if
266 using removable media.
268 Load the distribution tape and install the new
269 root filesystem as you did when first installing the system.
271 using the newly created disk filesystem.
273 Note that if you change the disk partition tables or add new disk
274 drivers they should also be added to the standalone system in
275 .Pn /sys/<architecture>/stand ,
276 and the default disk partition tables in
279 .Sh 2 "Monitoring system performance"
283 program provided with the system is designed to be an aid to monitoring
284 systemwide activity. The default ``pigs'' mode shows a dynamic ``ps''.
285 By running in the ``vmstat'' mode
286 when the system is active you can judge the system activity in several
287 dimensions: job distribution, virtual memory load, paging and swapping
288 activity, device interrupts, and disk and cpu utilization.
289 Ideally, there should be few blocked (b) jobs,
290 there should be little paging or swapping activity, there should
291 be available bandwidth on the disk devices (most single arms peak
292 out at 20-30 tps in practice), and the user cpu utilization (us) should
295 If the system is busy, then the count of active jobs may be large,
296 and several of these jobs may often be blocked (b). If the virtual
297 memory is active, then the paging demon will be running (sr will
298 be non-zero). It is healthy for the paging demon to free pages when
299 the virtual memory gets active; it is triggered by the amount of free
300 memory dropping below a threshold and increases its pace as free memory
303 If you run in the ``vmstat'' mode
304 when the system is busy, you can find
305 imbalances by noting abnormal job distributions. If many
306 processes are blocked (b), then the disk subsystem
307 is overloaded or imbalanced. If you have several non-dma
308 devices or open teletype lines that are ``ringing'', or user programs
309 that are doing high-speed non-buffered input/output, then the system
310 time may go high (60-70% or higher).
311 It is often possible to pin down the cause of high system time by
312 looking to see if there is excessive context switching (cs), interrupt
313 activity (in) and per-device interrupt counts,
314 or system call activity (sy). Cumulatively on one of
315 our large machines we average about 60-200 context switches and interrupts
316 per second and about 50-500 system calls per second.
318 If the system is heavily loaded, or if you have little memory
319 for your load (2M is little in most any case), then the system
320 may be forced to swap. This is likely to be accompanied by a noticeable
321 reduction in system performance and pregnant pauses when interactive
322 jobs such as editors swap out.
323 If you expect to be in a memory-poor environment
324 for an extended period you might consider administratively
325 limiting system load.
326 .Sh 2 "Recompiling and reinstalling system software"
328 It is easy to regenerate either the entire system or a single utility,
329 and it is a good idea to try rebuilding pieces of the system to build
330 confidence in the procedures.
332 In general, there are six well-known targets supported by
333 all the makefiles on the system:
335 This entry is the default target, the same as if no target is specified.
336 This target builds the kernel, binary or library, as well as its
337 associated manual pages.
338 This target \fBdoes not\fP build the dependency files.
339 Some of the utilities require that a \fImake depend\fP be done before
340 a \fImake all\fP can succeed.
342 Build the include file dependency file, ``.depend'', which is
349 Install the kernel, binary or library, as well as its associated
355 Remove the kernel, binary or library, as well as any object files
356 created when building it.
358 The same as clean, except that the dependency files and formatted
359 manual pages are removed as well.
361 Build a shadow directory structure in the area referenced by
363 and create a symbolic link in the current source directory to
364 referenced it, named ``obj''.
365 Once this shadow structure has been created, all the files created by
367 will live in the shadow structure, and
369 may be mounted read-only by multiple machines.
370 Doing a \fImake obj\fP in
372 will build the shadow directory structure for everything on the
373 system except for the contributed, old, and kernel software.
375 The system consists of three major parts:
376 the kernel itself, found in
378 the libraries , found in
380 and the user programs (the rest of
383 Deprecated software, found in
385 often has old style makefiles;
386 some of it does not compile under \*(4B at all.
388 Contributed software, found in
389 .Pn /usr/src/contrib ,
390 usually does not support the ``cleandir'', ``depend'', or ``obj'' targets.
392 The kernel does not support the ``obj'' shadow structure.
393 All kernels are compiled in subdirectories of
394 .Pn /usr/src/sys/compile
395 which is usually abbreviated as
397 If you want to mount your source tree read-only,
398 .Pn /usr/src/sys/compile
399 will have to be on a separate filesystem from
403 can be done by making
404 .Pn /usr/src/sys/compile
405 a symbolic link that references
406 .Pn /usr/obj/sys/compile .
407 If it is a symbolic link, the \fIS\fP variable in the kernel
408 Makefile must be changed from
410 to the absolute pathname needed to locate the kernel sources, usually
412 The symbolic link created by
416 must also be manually changed to an absolute pathname.
418 .Pn /usr/src/sys/libkern/obj
419 directory must be located in
420 .Pn /usr/obj/sys/libkern .
422 Each of the standard utilities and libraries may be built and
423 installed by changing directories into the correct location and
427 \fB#\fP \fImake install\fP
429 Note, if system include files have changed between compiles,
431 will not do the correct dependency checks if the dependency
432 files have not been built using the ``depend'' target.
434 The entire library and utility suite for the system may be recompiled
435 from scratch by changing directory to
439 \fB#\fP \fImake build\fP
441 This target installs the system include files, cleans the source
442 tree, builds and installs the libraries, and builds and installs
443 the system utilities.
445 To recompile a specific program, first determine where the binary
448 command, then change to the corresponding source directory and build
449 it with the Makefile in the directory.
450 For instance, to recompile ``passwd'',
451 all one has to do is:
453 \fB#\fP \fIwhereis passwd\fP
454 \fB/usr/bin/passwd\fP
455 \fB#\fP \fIcd /usr/src/usr.bin/passwd\fP
457 \fB#\fP \fImake install\fP
459 this will compile and install the
463 If you wish to recompile and install all programs into a particular
464 target area you can override the default path prefix by doing:
467 \fB#\fP \fImake DESTDIR=\fPpathname \fIinstall\fP
469 Similarly, the mode, owner, group, and other characteristics of
470 the installed object can be modified by changing other default
474 .Pn /usr/src/share/mk/bsd.README ,
475 and the ``.mk'' scripts in the
477 directory for more information.
479 If you modify the C library or system include files, to change a
480 system call for example, and want to rebuild and install everything,
481 you have to be a little careful.
482 You must ensure that the include files are installed before anything
483 is compiled, and that the libraries are installed before the remainder
484 of the source, otherwise the loaded images will not contain the new
485 routine from the library.
486 If include files have been modified, the following commands should
489 \fB#\fP \fIcd /usr/src/include\fP
490 \fB#\fP \fImake install\fP
492 Then, if, for example, C library files have been modified, the
493 following commands should be executed:
495 \fB#\fP \fIcd /usr/src/lib/libc\fP
496 \fB#\fP \fImake depend\fP
498 \fB#\fP \fImake install\fP
499 \fB#\fP \fIcd /usr/src\fP
500 \fB#\fP \fImake depend\fP
502 \fB#\fP \fImake install\fP
504 Alternatively, the \fImake build\fP command described above will
505 accomplish the same tasks.
506 This takes several hours on a reasonably configured machine.
507 .Sh 2 "Making local modifications"
509 The source for locally written commands is normally stored in
511 and their binaries are kept in
513 This isolation of local binaries allows
517 to correspond to the distribution tape (and to the manuals that
519 People using local commands should be made aware that they are not
521 Manual pages for local commands should be installed in
522 .Pn /usr/local/man/cat[1-8].
525 command automatically finds manual pages placed in
526 /usr/local/man/cat[1-8] to encourage this practice (see
530 UNIX optionally records two kinds of accounting information:
531 connect time accounting and process resource accounting. The connect
532 time accounting information is stored in the file
534 which is summarized by the program
536 The process time accounting information is stored in the file
537 .Pn /var/account/acct
538 after it is enabled by
540 and is analyzed and summarized by the program
543 If you need to recharge for computing time, you can develop
544 procedures based on the information provided by these commands.
545 A convenient way to do this is to give commands to the clock daemon
547 to be executed every day at a specified time.
548 This is done by adding lines to
549 .Pn /etc/crontab.local ;
553 .Sh 2 "Resource control"
555 Resource control in the current version of UNIX is more
556 elaborate than in most UNIX systems. The disk quota
557 facilities developed at the University of Melbourne have
558 been incorporated in the system and allow control over the
559 number of files and amount of disk space each user and/or group may use
560 on each filesystem. In addition, the resources consumed
561 by any single process can be limited by the mechanisms of
563 As distributed, the latter mechanism
564 is voluntary, though sites may choose to modify the login
565 mechanism to impose limits not covered with disk quotas.
567 To use the disk quota facilities, the system must be
568 configured with ``options QUOTA''. Filesystems may then
569 be placed under the quota mechanism by creating a null file
573 at the root of the filesystem, running
577 to show that the filesystem is to run
578 with disk quotas (options userquota and/or groupquota).
581 program may then be run to enable quotas.
583 Individual quotas are applied by using the quota editor
585 Users may view their quotas (but not those of other users) with the
589 program may be used to summarize the quotas and current
590 space usage on a particular filesystem or filesystems.
592 Quotas are enforced with \fIsoft\fP and \fIhard\fP limits.
593 When a user and/or group first reaches a soft limit on a resource, a
594 message is generated on their terminal. If the user and/or group fails to
595 lower the resource usage below the soft limit
596 for longer than the time limit established for that filesystem
597 (default seven days) the system then treats the soft limit as a
598 \fIhard\fP limit and disallows any allocations until enough space is
599 reclaimed to bring the user and/or group back below the soft limit.
600 Hard limits are enforced strictly resulting in errors when a user
601 and/or group tries to create or write a file. Each time a hard limit is
602 exceeded the system will generate a message on the user's terminal.
604 Consult the auxiliary document, ``Disc Quotas in a UNIX Environment'' (SMM:4)
605 and the appropriate manual entries for more information.
606 .Sh 2 "Network troubleshooting"
608 If you have anything more than a trivial network configuration,
609 from time to time you are bound to run into problems. Before
610 blaming the software, first check your network connections. On
611 networks such as the Ethernet a
612 loose cable tap or misplaced power cable can result in severely
613 deteriorated service. The
615 program may be of aid in tracking down hardware malfunctions.
616 In particular, look at the \fB\-i\fP and \fB\-s\fP options in the manual page.
618 Should you believe a communication protocol problem exists,
619 consult the protocol specifications and attempt to isolate the
620 problem in a packet trace. The SO_DEBUG option may be supplied
621 before establishing a connection on a socket, in which case the
622 system will trace all traffic and internal actions (such as timers
623 expiring) in a circular trace buffer.
624 This buffer may then be printed out with the
627 Most of the servers distributed with the system
628 accept a \fB\-d\fP option forcing
629 all sockets to be created with debugging turned on.
630 Consult the appropriate manual pages for more information.
631 .Sh 2 "Files that need periodic attention"
633 We conclude the discussion of system operations by listing
634 the files that require periodic attention or are system specific:
638 /etc/fstab how disk partitions are used
639 /etc/disktab default disk partition sizes/labels
640 /etc/printcap printer database
641 /etc/gettytab terminal type definitions
642 /etc/remote names and phone numbers of remote machines for \fItip\fP(1)
643 /etc/group group memberships
644 /etc/motd message of the day
645 /etc/master.passwd password file; each account has a line
646 /etc/rc.local local system restart script; runs reboot; starts daemons
647 /etc/inetd.conf local internet servers
648 /etc/hosts local host name database
649 /etc/networks network name database
650 /etc/services network services database
651 /etc/hosts.equiv hosts under same administrative control
652 /etc/syslog.conf error log configuration for \fIsyslogd\fP\|(8)
653 /etc/ttys enables/disables ports
654 /etc/crontab commands that are run periodically
655 /etc/crontab.local local commands that are run periodically
656 /etc/aliases mail forwarding and distribution groups
657 /var/account/acct raw process account data
658 /var/log/messages system error log
659 /var/log/wtmp login session accounting