Aquire serializer before calling ioctl
[dragonfly.git] / share / doc / smm / 01.setup / 6.t
1 .\" Copyright (c) 1980, 1986, 1988, 1993 The Regents of the University of California.
2 .\" 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 .\"
31 .\"
32 .\"     @(#)6.t 8.1 (Berkeley) 7/27/93
33 .\"
34 .ds LH "Installing/Operating \*(4B
35 .ds CF \*(Dy
36 .Sh 1 "System operation"
37 .PP
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"
43 .PP
44 In a normal reboot, the system checks the disks and comes up multi-user
45 without intervention at the console.
46 Such a reboot
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
49 terminal active.
50 (If the console has been marked ``insecure'' in
51 .Pn /etc/ttys
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
55 .Xr fsck (8)
56 with a QUIT signal (^\|\e).
57 .PP
58 To bring the system up to a multi-user configuration from the single-user
59 status,
60 all you have to do is hit ^D on the console.  The system
61 will then execute
62 .Pn /etc/rc ,
63 a multi-user restart script (and
64 .Pn /etc/rc.local ),
65 and come up on the terminals listed as
66 active in the file
67 .Pn /etc/ttys .
68 See
69 .Xr init (8)
70 and
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
75 .Xr reboot (8)
76 to have the disks checked.
77 .PP
78 To take the system down to a single user state you can use
79 .DS
80 \fB#\fP \fIkill 1\fP
81 .DE
82 or use the
83 .Xr shutdown (8)
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
89 should do this by:
90 .DS
91 \fB#\fP \fIcd /\fP
92 \fB#\fP \fI/sbin/umount -a\fP
93 \fB#\fP \fI^D\fP
94 .DE
95 .PP
96 Each system shutdown, crash, processor halt and reboot
97 is recorded in the system log
98 with its cause.
99 .Sh 2 "Device errors and diagnostics"
100 .PP
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
105 .Xr syslogd (8)
106 and written into a system error log file
107 .Pn /var/log/messages .
108 Less serious errors are sent directly to
109 .Xr syslogd ,
110 which may log them on the console.
111 The error priorities that are logged and the locations to which they are logged
112 are controlled by
113 .Pn /etc/syslog.conf .
114 See
115 .Xr syslogd (8)
116 for further details.
117 .PP
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"
125 .PP
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
129 by
130 .Xr fsck (1).
131 The procedures of
132 .Xr reboot (8)
133 should be used to get the system to a state where a filesystem
134 check can be done manually or automatically.
135 .PP
136 Dumping of the filesystems should be done regularly,
137 since once the system is going it is easy to
138 become complacent.
139 Complete and incremental dumps are easily done with
140 .Xr dump (8).
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
144 these indefinitely).
145 Operators can execute ``dump w'' at login that will tell them what needs
146 to be dumped
147 (based on the
148 .Pn /etc/fstab
149 information).
150 Be sure to create a group
151 .B operator
152 in the file
153 .Pn /etc/group
154 so that dump can notify logged-in operators when it needs help.
155 .PP
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
163 also.
164 .PP
165 Thus a typical dump sequence would be:
166 .br
167 .ne 6
168 .TS
169 center;
170 c c c c c
171 n n n l l.
172 tape name       level number    date    opr     size
173 _
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
191 .TE
192 We do weekly dumps often enough that daily dumps always fit on one tape.
193 .PP
194 Dumping of files by name is best done by
195 .Xr tar (1)
196 but the amount of data that can be moved in this way is limited
197 to a single tape.
198 Finally if there are enough drives entire
199 disks can be copied with
200 .Xr dd (1)
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
204 .Pn /etc/disktab .
205 .PP
206 It is desirable that full dumps of the root filesystem be
207 made regularly.
208 This is especially true when only one disk is available.
209 Then, if the
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.
213 .PP
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
217 .Xr du (1),
218 .Xr df (1),
219 and
220 .Xr quot (8),
221 combined with threatening
222 messages of the day, and personal letters.
223 .Sh 2 "Moving filesystem data"
224 .PP
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
228 .Xr dump (8),
229 use
230 .Xr newfs (8)
231 to create the new filesystem,
232 and restore the filesystem using
233 .Xr restore (8).
234 Filesystems may also be moved by piping the output of
235 .Xr dump
236 to
237 .Xr restore .
238 The
239 .Xr restore
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.
245 .PP
246 If you have to merge a filesystem into another, existing one,
247 the best bet is to use
248 .Xr tar (1).
249 If you must shrink a filesystem, the best bet is to dump
250 the original and restore it onto the new filesystem.
251 If you
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:
257 .IP 1.
259 .IP 2.
260 Dump the root filesystem to tape using
261 .Xr dump (8).
262 .IP 3.
263 Bring the system down.
264 .IP 4.
265 Mount the new pack in the correct disk drive, if
266 using removable media.
267 .IP 5.
268 Load the distribution tape and install the new
269 root filesystem as you did when first installing the system.
270 Boot normally
271 using the newly created disk filesystem.
272 .PP
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
277 .Pn /etc/disktab
278 should be modified.
279 .Sh 2 "Monitoring system performance"
280 .PP
281 The
282 .Xr systat
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
293 be high (above 50%).
294 .PP
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
301 goes to zero.
302 .PP
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.
317 .PP
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"
327 .PP
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.
331 .LP
332 In general, there are six well-known targets supported by
333 all the makefiles on the system:
334 .IP all 9
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.
341 .IP depend
342 Build the include file dependency file, ``.depend'', which is
343 read by
344 .Xr make .
345 See
346 .Xr mkdep (1)
347 for further details.
348 .IP install
349 Install the kernel, binary or library, as well as its associated
350 manual pages.
351 See
352 .Xr install (1)
353 for further details.
354 .IP clean
355 Remove the kernel, binary or library, as well as any object files
356 created when building it.
357 .IP cleandir
358 The same as clean, except that the dependency files and formatted
359 manual pages are removed as well.
360 .IP obj
361 Build a shadow directory structure in the area referenced by
362 .Pn /usr/obj
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
366 .Xr make
367 will live in the shadow structure, and
368 .Pn /usr/src
369 may be mounted read-only by multiple machines.
370 Doing a \fImake obj\fP in
371 .Pn /usr/src
372 will build the shadow directory structure for everything on the
373 system except for the contributed, old, and kernel software.
374 .PP
375 The system consists of three major parts:
376 the kernel itself, found in
377 .Pn /usr/src/sys ,
378 the libraries , found in
379 .Pn /usr/src/lib ,
380 and the user programs (the rest of
381 .Pn /usr/src ).
382 .PP
383 Deprecated software, found in
384 .Pn /usr/src/old ,
385 often has old style makefiles;
386 some of it does not compile under \*(4B at all.
387 .PP
388 Contributed software, found in
389 .Pn /usr/src/contrib ,
390 usually does not support the ``cleandir'', ``depend'', or ``obj'' targets.
391 .PP
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
396 .Pn /sys/compile .
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
400 .Pn /usr/src .
401 Separation from
402 .Pn /usr/src
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
409 .Pn \&../..
410 to the absolute pathname needed to locate the kernel sources, usually
411 .Pn /usr/src/sys .
412 The symbolic link created by
413 .Xr config (8)
414 for
415 .Pn machine
416 must also be manually changed to an absolute pathname.
417 Finally, the
418 .Pn /usr/src/sys/libkern/obj
419 directory must be located in
420 .Pn /usr/obj/sys/libkern .
421 .PP
422 Each of the standard utilities and libraries may be built and
423 installed by changing directories into the correct location and
424 doing:
425 .DS
426 \fB#\fP \fImake\fP
427 \fB#\fP \fImake install\fP
428 .DE
429 Note, if system include files have changed between compiles,
430 .Xr make
431 will not do the correct dependency checks if the dependency
432 files have not been built using the ``depend'' target.
433 .PP
434 The entire library and utility suite for the system may be recompiled
435 from scratch by changing directory to
436 .Pn /usr/src
437 and doing:
438 .DS
439 \fB#\fP \fImake build\fP
440 .DE
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.
444 .PP
445 To recompile a specific program, first determine where the binary
446 resides with the
447 .Xr whereis (1)
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:
452 .DS
453 \fB#\fP \fIwhereis passwd\fP
454 \fB/usr/bin/passwd\fP
455 \fB#\fP \fIcd /usr/src/usr.bin/passwd\fP
456 \fB#\fP \fImake\fP
457 \fB#\fP \fImake install\fP
458 .DE
459 this will compile and install the
460 .Xr passwd
461 utility.
462 .PP
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:
465 .DS
466 \fB#\fP \fImake\fP
467 \fB#\fP \fImake DESTDIR=\fPpathname \fIinstall\fP
468 .DE
469 Similarly, the mode, owner, group, and other characteristics of
470 the installed object can be modified by changing other default
471 make variables.
472 See
473 .Xr make (1),
474 .Pn /usr/src/share/mk/bsd.README ,
475 and the ``.mk'' scripts in the
476 .Pn /usr/share/mk
477 directory for more information.
478 .PP
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
487 be done first:
488 .DS
489 \fB#\fP \fIcd /usr/src/include\fP
490 \fB#\fP \fImake install\fP
491 .DE
492 Then, if, for example, C library files have been modified, the
493 following commands should be executed:
494 .DS
495 \fB#\fP \fIcd /usr/src/lib/libc\fP
496 \fB#\fP \fImake depend\fP
497 \fB#\fP \fImake\fP
498 \fB#\fP \fImake install\fP
499 \fB#\fP \fIcd /usr/src\fP
500 \fB#\fP \fImake depend\fP
501 \fB#\fP \fImake\fP
502 \fB#\fP \fImake install\fP
503 .DE
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"
508 .PP
509 The source for locally written commands is normally stored in
510 .Pn /usr/src/local ,
511 and their binaries are kept in
512 .Pn /usr/local/bin .
513 This isolation of local binaries allows
514 .Pn /usr/bin ,
515 and
516 .Pn /bin
517 to correspond to the distribution tape (and to the manuals that
518 people can buy).
519 People using local commands should be made aware that they are not
520 in the base manual.
521 Manual pages for local commands should be installed in
522 .Pn /usr/local/man/cat[1-8].
523 The
524 .Xr man (1)
525 command automatically finds manual pages placed in
526 /usr/local/man/cat[1-8] to encourage this practice (see
527 .Xr man.conf (5)).
528 .Sh 2 "Accounting"
529 .PP
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
533 .Pn /var/log/wtmp ,
534 which is summarized by the program
535 .Xr ac (8).
536 The process time accounting information is stored in the file
537 .Pn /var/account/acct
538 after it is enabled by
539 .Xr accton (8),
540 and is analyzed and summarized by the program
541 .Xr sa (8).
542 .PP
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
546 .Pn /usr/sbin/cron
547 to be executed every day at a specified time.
548 This is done by adding lines to
549 .Pn /etc/crontab.local ;
550 see
551 .Xr cron (8)
552 for details.
553 .Sh 2 "Resource control"
554 .PP
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
562 .Xr setrlimit (2).
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.
566 .PP
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
570 .Pn quota.user
571 and/or
572 .Pn
573 at the root of the filesystem, running
574 .Xr quotacheck (8),
575 and modifying
576 .Pn /etc/fstab
577 to show that the filesystem is to run
578 with disk quotas (options userquota and/or groupquota).
579 The
580 .Xr quotaon (8)
581 program may then be run to enable quotas.
582 .PP
583 Individual quotas are applied by using the quota editor
584 .Xr edquota (8).
585 Users may view their quotas (but not those of other users) with the
586 .Xr quota (1)
587 program. The
588 .Xr repquota (8)
589 program may be used to summarize the quotas and current
590 space usage on a particular filesystem or filesystems.
591 .PP
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.
603 .PP
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"
607 .PP
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
614 .Xr netstat (1)
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.
617 .PP
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
625 .Xr trpt (8)
626 program.
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"
632 .PP
633 We conclude the discussion of system operations by listing
634 the files that require periodic attention or are system specific:
635 .TS
636 center;
637 lfC l.
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
660 .TE
661 .pn 2
662 .bp
663 .PX