diff options
Diffstat (limited to 'share/doc/smm')
39 files changed, 7108 insertions, 4 deletions
diff --git a/share/doc/smm/02.config/0.t b/share/doc/smm/02.config/0.t new file mode 100644 index 0000000..ae5bf77 --- /dev/null +++ b/share/doc/smm/02.config/0.t @@ -0,0 +1,88 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)0.t 8.1 (Berkeley) 7/5/93 +.\" +.bd S B 3 +.de UX +.ie \\n(GA>0 \\$2UNIX\\$1 +.el \{\ +.if n \\$2UNIX\\$1* +.if t \\$2UNIX\\$1\\f1\(dg\\fP +.FS +.if n *UNIX +.if t \(dgUNIX +.ie \\$3=1 is a Footnote of Bell Laboratories. +.el is a Trademark of Bell Laboratories. +.FE +.nr GA 1\} +.. +.de BR +\fB\\$1\fP\\$2 +.. +.TL +Building 4.4BSD Kernels with Config +.AU +Samuel J. Leffler and Michael J. Karels +.AI +Computer Systems Research Group +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, California 94720 +.de IR +\fI\\$1\fP\\$2 +.. +.de DT +.TA 8 16 24 32 40 48 56 64 72 80 +.. +.AB +.PP +This document describes the use of +\fIconfig\fP\|(8) to configure and create bootable +4.4BSD system images. +It discusses the structure of system +configuration files and how to configure +systems with non-standard hardware configurations. +Sections describing the preferred way to +add new code to the system and how the system's autoconfiguration +process operates are included. An appendix +contains a summary of the rules used by the system +in calculating the size of system data structures, +and also indicates some of the standard system size +limitations (and how to change them). +Other configuration options are also listed. +.sp +.LP +Revised July 5, 1993 +.AE +.LP +.OH 'Building 4.4BSD Kernels with Config''SMM:2-%' +.EH 'SMM:2-%''Building 4.4BSD Kernels with Config' diff --git a/share/doc/smm/02.config/1.t b/share/doc/smm/02.config/1.t new file mode 100644 index 0000000..453041b --- /dev/null +++ b/share/doc/smm/02.config/1.t @@ -0,0 +1,61 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)1.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH Introduction +.ne 2i +.sp 3 +.NH +INTRODUCTION +.PP +.I Config +is a tool used in building 4.4BSD system images (the UNIX kernel). +It takes a file describing a system's tunable parameters and +hardware support, and generates a collection +of files which are then used to build a copy of UNIX appropriate +to that configuration. +.I Config +simplifies system maintenance by isolating system dependencies +in a single, easy to understand, file. +.PP +This document describes the content and +format of system configuration +files and the rules which must be followed when creating +these files. Example configuration files are constructed +and discussed. +.PP +Later sections suggest guidelines to be used in modifying +system source and explain some of the inner workings of the +autoconfiguration process. Appendix D summarizes the rules +used in calculating the most important system data structures +and indicates some inherent system data structure size +limitations (and how to go about modifying them). diff --git a/share/doc/smm/02.config/2.t b/share/doc/smm/02.config/2.t new file mode 100644 index 0000000..34e6b63 --- /dev/null +++ b/share/doc/smm/02.config/2.t @@ -0,0 +1,188 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)2.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Configuration File Contents +.ne 2i +.NH +CONFIGURATION FILE CONTENTS +.PP +A system configuration must include at least the following +pieces of information: +.IP \(bu 3 +machine type +.IP \(bu 3 +cpu type +.IP \(bu 3 +system identification +.IP \(bu 3 +timezone +.IP \(bu 3 +maximum number of users +.IP \(bu 3 +location of the root file system +.IP \(bu 3 +available hardware +.PP +.I Config +allows multiple system images to be generated from a single +configuration description. Each system image is configured +for identical hardware, but may have different locations for the root +file system and, possibly, other system devices. +.NH 2 +Machine type +.PP +The +.I "machine type" +indicates if the system is going to operate on a DEC VAX-11\(dg computer, +.FS +\(dg DEC, VAX, UNIBUS, MASSBUS and MicroVAX are trademarks of Digital +Equipment Corporation. +.FE +or some other machine on which 4.4BSD operates. The machine type +is used to locate certain data files which are machine specific, and +also to select rules used in constructing the resultant +configuration files. +.NH 2 +Cpu type +.PP +The +.I "cpu type" +indicates which, of possibly many, cpu's the system is to operate on. +For example, if the system is being configured for a VAX-11, it could +be running on a VAX 8600, VAX-11/780, VAX-11/750, VAX-11/730 or MicroVAX II. +(Other VAX cpu types, including the 8650, 785 and 725, are configured using +the cpu designation for compatible machines introduced earlier.) +Specifying +more than one cpu type implies that the system should be configured to run +on any of the cpu's specified. For some types of machines this is not +possible and +.I config +will print a diagnostic indicating such. +.NH 2 +System identification +.PP +The +.I "system identification" +is a moniker attached to the system, and often the machine on which the +system is to run. For example, at Berkeley we have machines named Ernie +(Co-VAX), Kim (No-VAX), and so on. The system identifier selected is used to +create a global C ``#define'' which may be used to isolate system dependent +pieces of code in the kernel. For example, Ernie's Varian driver used +to be special cased because its interrupt vectors were wired together. The +code in the driver which understood how to handle this non-standard hardware +configuration was conditionally compiled in only if the system +was for Ernie. +.PP +The system identifier ``GENERIC'' is given to a system which +will run on any cpu of a particular machine type; it should not +otherwise be used for a system identifier. +.NH 2 +Timezone +.PP +The timezone in which the system is to run is used to define the +information returned by the \fIgettimeofday\fP\|(2) +system call. This value is specified as the number of hours east +or west of GMT. Negative numbers indicate a value east of GMT. +The timezone specification may also indicate the +type of daylight savings time rules to be applied. +.NH 2 +Maximum number of users +.PP +The system allocates many system data structures at boot time +based on the maximum number of users the system will support. +This number is normally between 8 and 40, depending +on the hardware and expected job mix. The rules +used to calculate system data structures are discussed in +Appendix D. +.NH 2 +Root file system location +.PP +When the system boots it must know the location of +the root of the file system +tree. This location and the part(s) of the disk(s) to be used +for paging and swapping must be specified in order to create +a complete configuration description. +.I Config +uses many rules to calculate default locations for these items; +these are described in Appendix B. +.PP +When a generic system is configured, the root file system is left +undefined until the system is booted. In this case, the root file +system need not be specified, only that the system is a generic system. +.NH 2 +Hardware devices +.PP +When the system boots it goes through an +.I autoconfiguration +phase. During this period, the system searches for all +those hardware devices +which the system builder has indicated might be present. This probing +sequence requires certain pieces of information such as register +addresses, bus interconnects, etc. A system's hardware may be configured +in a very flexible manner or be specified without any flexibility +whatsoever. Most people do not configure hardware devices into the +system unless they are currently present on the machine, expect +them to be present in the near future, or are simply guarding +against a hardware +failure somewhere else at the site (it is often wise to configure in +extra disks in case an emergency requires moving one off a machine which +has hardware problems). +.PP +The specification of hardware devices usually occupies the majority of +the configuration file. As such, a large portion of this document will +be spent understanding it. Section 6.3 contains a description of +the autoconfiguration process, as it applies to those planning to +write, or modify existing, device drivers. +.NH 2 +Pseudo devices +.PP +Several system facilities are configured in a manner like that used +for hardware devices although they are not associated with specific hardware. +These system options are configured as +.IR pseudo-devices . +Some pseudo devices allow an optional parameter that sets the limit +on the number of instances of the device that are active simultaneously. +.NH 2 +System options +.PP +Other than the mandatory pieces of information described above, it +is also possible to include various optional system facilities +or to modify system behavior and/or limits. +For example, 4.4BSD can be configured to support binary compatibility for +programs built under 4.3BSD. Also, optional support is provided +for disk quotas and tracing the performance of the virtual memory +subsystem. Any optional facilities to be configured into +the system are specified in the configuration file. The resultant +files generated by +.I config +will automatically include the necessary pieces of the system. diff --git a/share/doc/smm/02.config/3.t b/share/doc/smm/02.config/3.t new file mode 100644 index 0000000..e0b6234 --- /dev/null +++ b/share/doc/smm/02.config/3.t @@ -0,0 +1,299 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)3.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "System Building Process +.ne 2i +.NH +SYSTEM BUILDING PROCESS +.PP +In this section we consider the steps necessary to build a bootable system +image. We assume the system source is located in the ``/sys'' directory +and that, initially, the system is being configured from source code. +.PP +Under normal circumstances there are 5 steps in building a system. +.IP 1) 3 +Create a configuration file for the system. +.IP 2) 3 +Make a directory for the system to be constructed in. +.IP 3) 3 +Run +.I config +on the configuration file to generate the files required +to compile and load the system image. +.IP 4) +Construct the source code interdependency rules for the +configured system with +.I make depend +using +.IR make (1). +.IP 5) +Compile and load the system with +.IR make . +.PP +Steps 1 and 2 are usually done only once. When a system configuration +changes it usually suffices to just run +.I config +on the modified configuration file, rebuild the source code dependencies, +and remake the system. Sometimes, +however, configuration dependencies may not be noticed in which case +it is necessary to clean out the relocatable object files saved +in the system's directory; this will be discussed later. +.NH 2 +Creating a configuration file +.PP +Configuration files normally reside in the directory ``/sys/conf''. +A configuration file is most easily constructed by copying an +existing configuration file and modifying it. The 4.4BSD distribution +contains a number of configuration files for machines at Berkeley; +one may be suitable or, in worst case, a copy +of the generic configuration file may be edited. +.PP +The configuration file must have the same name as the directory in +which the configured system is to be built. +Further, +.I config +assumes this directory is located in the parent directory of +the directory in which it +is run. For example, the generic +system has a configuration file ``/sys/conf/GENERIC'' and an accompanying +directory named ``/sys/GENERIC''. +Although it is not required that the system sources and configuration +files reside in ``/sys,'' the configuration and compilation procedure +depends on the relative locations of directories within that hierarchy, +as most of the system code and the files created by +.I config +use pathnames of the form ``../''. +If the system files are not located in ``/sys,'' +it is desirable to make a symbolic link there for use in installation +of other parts of the system that share files with the kernel. +.PP +When building the configuration file, be sure to include the items +described in section 2. In particular, the machine type, +cpu type, timezone, system identifier, maximum users, and root device +must be specified. The specification of the hardware present may take +a bit of work; particularly if your hardware is configured at non-standard +places (e.g. device registers located at funny places or devices not +supported by the system). Section 4 of this document +gives a detailed description of the configuration file syntax, +section 5 explains some sample configuration files, and +section 6 discusses how to add new devices to +the system. If the devices to be configured are not already +described in one of the existing configuration files you should check +the manual pages in section 4 of the UNIX Programmers Manual. For each +supported device, the manual page synopsis entry gives a +sample configuration line. +.PP +Once the configuration file is complete, run it through +.I config +and look for any errors. Never try and use a system which +.I config +has complained about; the results are unpredictable. +For the most part, +.IR config 's +error diagnostics are self explanatory. It may be the case that +the line numbers given with the error messages are off by one. +.PP +A successful run of +.I config +on your configuration file will generate a number of files in +the configuration directory. These files are: +.IP \(bu 3 +A file to be used by \fImake\fP\|(1) +in compiling and loading the system, +.IR Makefile . +.IP \(bu 3 +One file for each possible system image for this machine, +.IR swapxxx.c , +where +.I xxx +is the name of the system image, +which describes where swapping, the root file system, and other +miscellaneous system devices are located. +.IP \(bu 3 +A collection of header files, one per possible device the +system supports, which define the hardware configured. +.IP \(bu 3 +A file containing the I/O configuration tables used by the system +during its +.I autoconfiguration +phase, +.IR ioconf.c . +.IP \(bu 3 +An assembly language file of interrupt vectors which +connect interrupts from the machine's external buses to the main +system path for handling interrupts, +and a file that contains counters and names for the interrupt vectors. +.PP +Unless you have reason to doubt +.IR config , +or are curious how the system's autoconfiguration scheme +works, you should never have to look at any of these files. +.NH 2 +Constructing source code dependencies +.PP +When +.I config +is done generating the files needed to compile and link your system it +will terminate with a message of the form ``Don't forget to run make depend''. +This is a reminder that you should change over to the configuration +directory for the system just configured and type ``make depend'' +to build the rules used by +.I make +to recognize interdependencies in the system source code. +This will insure that any changes to a piece of the system +source code will result in the proper modules being recompiled +the next time +.I make +is run. +.PP +This step is particularly important if your site makes changes +to the system include files. The rules generated specify which source code +files are dependent on which include files. Without these rules, +.I make +will not recognize when it must rebuild modules +due to the modification of a system header file. +The dependency rules are generated by a pass of the C preprocessor +and reflect the global system options. +This step must be repeated when the configuration file is changed +and +.I config +is used to regenerate the system makefile. +.NH 2 +Building the system +.PP +The makefile constructed by +.I config +should allow a new system to be rebuilt by simply typing ``make image-name''. +For example, if you have named your bootable system image ``kernel'', +then ``make kernel'' +will generate a bootable image named ``kernel''. Alternate system image names +are used when the root file system location and/or swapping configuration +is done in more than one way. The makefile which +.I config +creates has entry points for each system image defined in +the configuration file. +Thus, if you have configured ``kernel'' to be a system with the root file +system on an ``hp'' device and ``hkkernel'' to be a system with the root +file system on an ``hk'' device, then ``make kernel hkkernel'' will generate +binary images for each. +As the system will generally use the disk from which it is loaded +as the root filesystem, separate system images are only required +to support different swap configurations. +.PP +Note that the name of a bootable image is different from the system +identifier. All bootable images are configured for the same system; +only the information about the root file system and paging devices differ. +(This is described in more detail in section 4.) +.PP +The last step in the system building process is to rearrange certain commonly +used symbols in the symbol table of the system image; the makefile +generated by +.I config +does this automatically for you. +This is advantageous for programs such as +\fInetstat\fP\|(1) and \fIvmstat\fP\|(1), +which run much faster when the symbols they need are located at +the front of the symbol table. +Remember also that many programs expect +the currently executing system to be named ``/kernel''. If you install +a new system and name it something other than ``/kernel'', many programs +are likely to give strange results. +.NH 2 +Sharing object modules +.PP +If you have many systems which are all built on a single machine +there are at least two approaches to saving time in building system +images. The best way is to have a single system image which is run on +all machines. This is attractive since it minimizes disk space used +and time required to rebuild systems after making changes. However, +it is often the case that one or more systems will require a separately +configured system image. This may be due to limited memory (building +a system with many unused device drivers can be expensive), or to +configuration requirements (one machine may be a development machine +where disk quotas are not needed, while another is a production machine +where they are), etc. In these cases it is possible +for common systems to share relocatable object modules which are not +configuration dependent; most of the modules in the directory ``/sys/sys'' +are of this sort. +.PP +To share object modules, a generic system should be built. Then, for +each system configure the system as before, but before recompiling and +linking the system, type ``make links'' in the system compilation directory. +This will cause the system +to be searched for source modules which are safe to share between systems +and generate symbolic links in the current directory to the appropriate +object modules in the directory ``../GENERIC''. A shell script, +``makelinks'' is generated with this request and may be checked for +correctness. The file ``/sys/conf/defines'' contains a list of symbols +which we believe are safe to ignore when checking the source code +for modules which may be shared. Note that this list includes the definitions +used to conditionally compile in the virtual memory tracing facilities, and +the trace point support used only rarely (even at Berkeley). +It may be necessary +to modify this file to reflect local needs. Note further that +interdependencies which are not directly visible +in the source code are not caught. This means that if you place +per-system dependencies in an include file, they will not be recognized +and the shared code may be selected in an unexpected fashion. +.NH 2 +Building profiled systems +.PP +It is simple to configure a system which will automatically +collect profiling information as it operates. The profiling data +may be collected with \fIkgmon\fP\|(8) and processed with +\fIgprof\fP\|(1) +to obtain information regarding the system's operation. Profiled +systems maintain histograms of the program counter as well as the +number of invocations of each routine. The \fIgprof\fP +command will also generate a dynamic call graph of the executing +system and propagate time spent in each routine along the arcs +of the call graph (consult the \fIgprof\fP documentation for elaboration). +The program counter sampling can be driven by the system clock, or +if you have an alternate real time clock, this can be used. The +latter is highly recommended, as use of the system clock will result +in statistical anomalies, and time spent in the clock routine will +not be accurately attributed. +.PP +To configure a profiled system, the +.B \-p +option should be supplied to \fIconfig\fP. +A profiled system is about 5-10% larger in its text space due to +the calls to count the subroutine invocations. When the system +executes, the profiling data is stored in a buffer which is 1.2 +times the size of the text space. The overhead for running a +profiled system varies; under normal load we see anywhere from 5-25% +of the system time spent in the profiling code. +.PP +Note that systems configured for profiling should not be shared as +described above unless all the other shared systems are also to be +profiled. diff --git a/share/doc/smm/02.config/4.t b/share/doc/smm/02.config/4.t new file mode 100644 index 0000000..7498185 --- /dev/null +++ b/share/doc/smm/02.config/4.t @@ -0,0 +1,442 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)4.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Configuration File Syntax +.ne 2i +.NH +CONFIGURATION FILE SYNTAX +.PP +In this section we consider the specific rules used in writing +a configuration file. A complete grammar for the input language +can be found in Appendix A and may be of use if you should have +problems with syntax errors. +.PP +A configuration file is broken up into three logical pieces: +.IP \(bu 3 +configuration parameters global to all system images +specified in the configuration file, +.IP \(bu 3 +parameters specific to each +system image to be generated, and +.IP \(bu 3 +device specifications. +.NH 2 +Global configuration parameters +.PP +The global configuration parameters are the type of machine, +cpu types, options, timezone, system identifier, and maximum users. +Each is specified with a separate line in the configuration file. +.IP "\fBmachine\fP \fItype\fP" +.br +The system is to run on the machine type specified. No more than +one machine type can appear in the configuration file. Legal values +are +.B vax +and +\fBsun\fP. +.IP "\fBcpu\fP ``\fItype\fP''" +.br +This system is to run on the cpu type specified. +More than one cpu type specification +can appear in a configuration file. +Legal types for a +.B vax +machine are +\fBVAX8600\fP, \fBVAX780\fP, \fBVAX750\fP, +\fBVAX730\fP +and +\fBVAX630\fP (MicroVAX II). +The 8650 is listed as an 8600, the 785 as a 780, and a 725 as a 730. +.IP "\fBoptions\fP \fIoptionlist\fP" +.br +Compile the listed optional code into the system. +Options in this list are separated by commas. +Possible options are listed at the top of the generic makefile. +A line of the form ``options FUNNY,HAHA'' generates global ``#define''s +\-DFUNNY \-DHAHA in the resultant makefile. +An option may be given a value by following its name with ``\fB=\fP'', +then the value enclosed in (double) quotes. +The following are major options are currently in use: +COMPAT (include code for compatibility with 4.1BSD binaries), +INET (Internet communication protocols), +NS (Xerox NS communication protocols), +and +QUOTA (enable disk quotas). +Other kernel options controlling system sizes and limits +are listed in Appendix D; +options for the network are found in Appendix E. +There are additional options which are associated with certain +peripheral devices; those are listed in the Synopsis section +of the manual page for the device. +.IP "\fBmakeoptions\fP \fIoptionlist\fP" +.br +Options that are used within the system makefile +and evaluated by +.I make +are listed as +.IR makeoptions . +Options are listed with their values with the form +``makeoptions name=value,name2=value2.'' +The values must be enclosed in double quotes if they include numerals +or begin with a dash. +.IP "\fBtimezone\fP \fInumber\fP [ \fBdst\fP [ \fInumber\fP ] ]" +.br +Specifies the timezone used by the system. This is measured in the +number of hours your timezone is west of GMT. +EST is 5 hours west of GMT, PST is 8. Negative numbers +indicate hours east of GMT. If you specify +\fBdst\fP, the system will operate under daylight savings time. +An optional integer or floating point number may be included +to specify a particular daylight saving time correction algorithm; +the default value is 1, indicating the United States. +Other values are: 2 (Australian style), 3 (Western European), +4 (Middle European), and 5 (Eastern European). See +\fIgettimeofday\fP\|(2) and \fIctime\fP\|(3) for more information. +.IP "\fBident\fP \fIname\fP" +.br +This system is to be known as +.IR name . +This is usually a cute name like ERNIE (short for Ernie Co-Vax) or +VAXWELL (for Vaxwell Smart). +This value is defined for use in conditional compilation, +and is also used to locate an optional list of source files specific +to this system. +.IP "\fBmaxusers\fP \fInumber\fP" +.br +The maximum expected number of simultaneously active user on this system is +.IR number . +This number is used to size several system data structures. +.NH 2 +System image parameters +.PP +Multiple bootable images may be specified in a single configuration +file. The systems will have the same global configuration parameters +and devices, but the location of the root file system and other +system specific devices may be different. A system image is specified +with a ``config'' line: +.IP +\fBconfig\fP\ \fIsysname\fP\ \fIconfig-clauses\fP +.LP +The +.I sysname +field is the name given to the loaded system image; almost everyone +names their standard system image ``kernel''. The configuration clauses +are one or more specifications indicating where the root file system +is located and the number and location of paging devices. +The device used by the system to process argument lists during +.IR execve (2) +calls may also be specified, though in practice this is almost +always selected by +.I config +using one of its rules for selecting default locations for +system devices. +.PP +A configuration clause is one of the following +.IP +.nf +\fBroot\fP [ \fBon\fP ] \fIroot-device\fP +\fBswap\fP [ \fBon\fP ] \fIswap-device\fP [ \fBand\fP \fIswap-device\fP ] ... +\fBdumps\fP [ \fBon\fP ] \fIdump-device\fP +\fBargs\fP [ \fBon\fP ] \fIarg-device\fP +.LP +(the ``on'' is optional.) Multiple configuration clauses +are separated by white space; +.I config +allows specifications to be continued across multiple lines +by beginning the continuation line with a tab character. +The ``root'' clause specifies where the root file system +is located, the ``swap'' clause indicates swapping and paging +area(s), the ``dumps'' clause can be used to force system dumps +to be taken on a particular device, and the ``args'' clause +can be used to specify that argument list processing for +.I execve +should be done on a particular device. +.PP +The device names supplied in the clauses may be fully specified +as a device, unit, and file system partition; or underspecified +in which case +.I config +will use builtin rules to select default unit numbers and file +system partitions. The defaulting rules are a bit complicated +as they are dependent on the overall system configuration. +For example, the swap area need not be specified at all if +the root device is specified; in this case the swap area is +placed in the ``b'' partition of the same disk where the root +file system is located. Appendix B contains a complete list +of the defaulting rules used in selecting system configuration +devices. +.PP +The device names are translated to the +appropriate major and minor device +numbers on a per-machine basis. A file, +``/sys/conf/devices.machine'' (where ``machine'' +is the machine type specified in the configuration file), +is used to map a device name to its major block device number. +The minor device number is calculated using the standard +disk partitioning rules: on unit 0, partition ``a'' is minor device +0, partition ``b'' is minor device 1, and so on; for units +other than 0, add 8 times the unit number to get the minor +device. +.PP +If the default mapping of device name to major/minor device +number is incorrect for your configuration, it can be replaced +by an explicit specification of the major/minor device. +This is done by substituting +.IP +\fBmajor\fP \fIx\fP \fBminor\fP \fIy\fP +.LP +where the device name would normally be found. For example, +.IP +.nf +\fBconfig\fP kernel \fBroot\fP \fBon\fP \fBmajor\fP 99 \fBminor\fP 1 +.fi +.PP +Normally, the areas configured for swap space are sized by the system +at boot time. If a non-standard size is to be used for one +or more swap areas (less than the full partition), +this can also be specified. To do this, the +device name specified for a swap area should have a ``size'' +specification appended. For example, +.IP +.nf +\fBconfig\fP kernel \fBroot\fP \fBon\fP hp0 \fBswap\fP \fBon\fP hp0b \fBsize\fP 1200 +.fi +.LP +would force swapping to be done in partition ``b'' of ``hp0'' and +the swap partition size would be set to 1200 sectors. A swap area +sized larger than the associated disk partition is trimmed to the +partition size. +.PP +To create a generic configuration, only the clause ``swap generic'' +should be specified; any extra clauses will cause an error. +.NH 2 +Device specifications +.PP +Each device attached to a machine must be specified +to +.I config +so that the system generated will know to probe for it during +the autoconfiguration process carried out at boot time. Hardware +specified in the configuration need not actually be present on +the machine where the generated system is to be run. Only the +hardware actually found at boot time will be used by the system. +.PP +The specification of hardware devices in the configuration file +parallels the interconnection hierarchy of the machine to be +configured. On the VAX, this means that a configuration file must +indicate what MASSBUS and UNIBUS adapters are present, and to +which \fInexi\fP they might be connected.* +.FS +* While VAX-11/750's and VAX-11/730 do not actually have +nexi, the system treats them as having +.I "simulated nexi" +to simplify device configuration. +.FE +Similarly, devices +and controllers must be indicated as possibly being connected +to one or more adapters. A device description may provide a +complete definition of the possible configuration parameters +or it may leave certain parameters undefined and make the system +probe for all the possible values. The latter allows a single +device configuration list to match many possible physical +configurations. For example, a disk may be indicated as present +at UNIBUS adapter 0, or at any UNIBUS adapter which the system +locates at boot time. The latter scheme, termed +.IR wildcarding , +allows more flexibility in the physical configuration of a system; +if a disk must be moved around for some reason, the system will +still locate it at the alternate location. +.PP +A device specification takes one of the following forms: +.IP +.nf +\fBmaster\fP \fIdevice-name\fP \fIdevice-info\fP +\fBcontroller\fP \fIdevice-name\fP \fIdevice-info\fP [ \fIinterrupt-spec\fP ] +\fBdevice\fP \fIdevice-name\fP \fIdevice-info\fP \fIinterrupt-spec\fP +\fBdisk\fP \fIdevice-name\fP \fIdevice-info\fP +\fBtape\fP \fIdevice-name\fP \fIdevice-info\fP +.fi +.LP +A ``master'' is a MASSBUS tape controller; a ``controller'' is a +disk controller, a UNIBUS tape controller, a MASSBUS adapter, or +a UNIBUS adapter. A ``device'' is an autonomous device which +connects directly to a UNIBUS adapter (as opposed to something +like a disk which connects through a disk controller). ``Disk'' +and ``tape'' identify disk drives and tape drives connected to +a ``controller'' or ``master.'' +.PP +The +.I device-name +is one of the standard device names, as +indicated in section 4 of the UNIX Programmers Manual, +concatenated with the +.I logical +unit number to be assigned the device (the +.I logical +unit number may be different than the +.I physical +unit number indicated on the front of something +like a disk; the +.I logical +unit number is used to refer to the UNIX device, not +the physical unit number). For example, ``hp0'' is logical +unit 0 of a MASSBUS storage device, even though it might +be physical unit 3 on MASSBUS adapter 1. +.PP +The +.I device-info +clause specifies how the hardware is +connected in the interconnection hierarchy. On the VAX, +UNIBUS and MASSBUS adapters are connected to the internal +system bus through +a \fInexus\fP. +Thus, one of the following +specifications would be used: +.IP +.ta 1.5i 2.5i 4.0i +.nf +\fBcontroller\fP mba0 \fBat\fP \fBnexus\fP \fIx\fP +\fBcontroller\fP uba0 \fBat\fP \fBnexus\fP \fIx\fP +.fi +.LP +To tie a controller to a specific nexus, ``x'' would be supplied +as the number of that nexus; otherwise ``x'' may be specified as +``?'', in which +case the system will probe all nexi present looking +for the specified controller. +.PP +The remaining interconnections on the VAX are: +.IP \(bu 3 +a controller +may be connected to another controller (e.g. a disk controller attached +to a UNIBUS adapter), +.IP \(bu 3 +a master is always attached to a controller (a MASSBUS adapter), +.IP \(bu 3 +a tape is always attached to a master (for MASSBUS +tape drives), +.IP \(bu 3 +a disk is always attached to a controller, and +.IP \(bu 3 +devices +are always attached to controllers (e.g. UNIBUS controllers attached +to UNIBUS adapters). +.LP +The following lines give an example of each of these interconnections: +.IP +.ta 1.5i 2.5i 4.0i +.nf +\fBcontroller\fP hk0 \fBat\fP uba0 ... +\fBmaster\fP ht0 \fBat\fP mba0 ... +\fBdisk\fP hp0 \fBat\fP mba0 ... +\fBtape\fP tu0 \fBat\fP ht0 ... +\fBdisk\fP rk1 \fBat\fP hk0 ... +\fBdevice\fP dz0 \fBat\fP uba0 ... +.fi +.LP +Any piece of hardware which may be connected to a specific +controller may also be wildcarded across multiple controllers. +.PP +The final piece of information needed by the system to configure +devices is some indication of where or how a device will interrupt. +For tapes and disks, simply specifying the \fIslave\fP or \fIdrive\fP +number is sufficient to locate the control status register for the +device. +\fIDrive\fP numbers may be wildcarded +on MASSBUS devices, but not on disks on a UNIBUS controller. +For controllers, the control status register must be +given explicitly, as well the number of interrupt vectors used and +the names of the routines to which they should be bound. +Thus the example lines given above might be completed as: +.IP +.ta 1.5i 2.5i 4.0i +.nf +\fBcontroller\fP hk0 \fBat\fP uba0 \fBcsr\fP 0177440 \fBvector\fP rkintr +\fBmaster\fP ht0 \fBat\fP mba0 \fBdrive\fP 0 +\fBdisk\fP hp0 \fBat\fP mba0 \fBdrive\fP ? +\fBtape\fP tu0 \fBat\fP ht0 \fBslave\fP 0 +\fBdisk\fP rk1 \fBat\fP hk0 \fBdrive\fP 1 +\fBdevice\fP dz0 \fBat\fP uba0 \fBcsr\fP 0160100 \fBvector\fP dzrint dzxint +.fi +.PP +Certain device drivers require extra information passed to them +at boot time to tailor their operation to the actual hardware present. +The line printer driver, for example, needs to know how many columns +are present on each non-standard line printer (i.e. a line printer +with other than 80 columns). The drivers for the terminal multiplexors +need to know which lines are attached to modem lines so that no one will +be allowed to use them unless a connection is present. For this reason, +one last parameter may be specified to a +.IR device , +a +.I flags +field. It has the syntax +.IP +\fBflags\fP \fInumber\fP +.LP +and is usually placed after the +.I csr +specification. The +.I number +is passed directly to the associated driver. The manual pages +in section 4 should be consulted to determine how each driver +uses this value (if at all). +Communications interface drivers commonly use the flags +to indicate whether modem control signals are in use. +.PP +The exact syntax for each specific device is given in the Synopsis +section of its manual page in section 4 of the manual. +.NH 2 +Pseudo-devices +.PP +A number of drivers and software subsystems +are treated like device drivers without any associated hardware. +To include any of these pieces, a ``pseudo-device'' specification +must be used. A specification for a pseudo device takes the form +.IP +.DT +.nf +\fBpseudo-device\fP \fIdevice-name\fP [ \fIhowmany\fP ] +.fi +.PP +Examples of pseudo devices are +\fBpty\fP, the pseudo terminal driver (where the optional +.I howmany +value indicates the number of pseudo terminals to configure, 32 default), +and \fBloop\fP, the software loopback network pseudo-interface. +Other pseudo devices for the network include +\fBimp\fP (required when a CSS or ACC imp is configured) +and \fBether\fP (used by the Address Resolution Protocol +on 10 Mb/sec Ethernets). +More information on configuring each of these can also be found +in section 4 of the manual. diff --git a/share/doc/smm/02.config/5.t b/share/doc/smm/02.config/5.t new file mode 100644 index 0000000..81f2a52 --- /dev/null +++ b/share/doc/smm/02.config/5.t @@ -0,0 +1,271 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)5.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Sample Configuration Files +.ne 2i +.NH +SAMPLE CONFIGURATION FILES +.PP +In this section we will consider how to configure a +sample VAX-11/780 system on which the hardware can be +reconfigured to guard against various hardware mishaps. +We then study the rules needed to configure a VAX-11/750 +to run in a networking environment. +.NH 2 +VAX-11/780 System +.PP +Our VAX-11/780 is configured with hardware +recommended in the document ``Hints on Configuring a VAX for 4.2BSD'' +(this is one of the high-end configurations). +Table 1 lists the pertinent hardware to be configured. +.DS B +.TS +box; +l | l | l | l | l +l | l | l | l | l. +Item Vendor Connection Name Reference +_ +cpu DEC VAX780 +MASSBUS controller Emulex nexus ? mba0 hp(4) +disk Fujitsu mba0 hp0 +disk Fujitsu mba0 hp1 +MASSBUS controller Emulex nexus ? mba1 +disk Fujitsu mba1 hp2 +disk Fujitsu mba1 hp3 +UNIBUS adapter DEC nexus ? +tape controller Emulex uba0 tm0 tm(4) +tape drive Kennedy tm0 te0 +tape drive Kennedy tm0 te1 +terminal multiplexor Emulex uba0 dh0 dh(4) +terminal multiplexor Emulex uba0 dh1 +terminal multiplexor Emulex uba0 dh2 +.TE +.DE +.ce +Table 1. VAX-11/780 Hardware support. +.LP +We will call this machine ANSEL and construct a configuration +file one step at a time. +.PP +The first step is to fill in the global configuration parameters. +The machine is a VAX, so the +.I "machine type" +is ``vax''. We will assume this system will +run only on this one processor, so the +.I "cpu type" +is ``VAX780''. The options are empty since this is going to +be a ``vanilla'' VAX. The system identifier, as mentioned before, +is ``ANSEL,'' and the maximum number of users we plan to support is +about 40. Thus the beginning of the configuration file looks like +this: +.DS +.ta 1.5i 2.5i 4.0i +# +# ANSEL VAX (a picture perfect machine) +# +machine vax +cpu VAX780 +timezone 8 dst +ident ANSEL +maxusers 40 +.DE +.PP +To this we must then add the specifications for three +system images. The first will be our standard system with the +root on ``hp0'' and swapping on the same drive as the root. +The second will have the root file system in the same location, +but swap space interleaved among drives on each controller. +Finally, the third will be a generic system, +to allow us to boot off any of the four disk drives. +.DS +.ta 1.5i 2.5i +config kernel root on hp0 +config hpkernel root on hp0 swap on hp0 and hp2 +config genkernel swap generic +.DE +.PP +Finally, the hardware must be specified. Let us first just try +transcribing the information from Table 1. +.DS +.ta 1.5i 2.5i 4.0i +controller mba0 at nexus ? +disk hp0 at mba0 disk 0 +disk hp1 at mba0 disk 1 +controller mba1 at nexus ? +disk hp2 at mba1 disk 2 +disk hp3 at mba1 disk 3 +controller uba0 at nexus ? +controller tm0 at uba0 csr 0172520 vector tmintr +tape te0 at tm0 drive 0 +tape te1 at tm0 drive 1 +device dh0 at uba0 csr 0160020 vector dhrint dhxint +device dm0 at uba0 csr 0170500 vector dmintr +device dh1 at uba0 csr 0160040 vector dhrint dhxint +device dh2 at uba0 csr 0160060 vector dhrint dhxint +.DE +.LP +(Oh, I forgot to mention one panel of the terminal multiplexor +has modem control, thus the ``dm0'' device.) +.PP +This will suffice, but leaves us with little flexibility. Suppose +our first disk controller were to break. We would like to recable the +drives normally on the second controller so that all our disks could +still be used without reconfiguring the system. To do this we wildcard +the MASSBUS adapter connections and also the slave numbers. Further, +we wildcard the UNIBUS adapter connections in case we decide some time +in the future to purchase another adapter to offload the single UNIBUS +we currently have. The revised device specifications would then be: +.DS +.ta 1.5i 2.5i 4.0i +controller mba0 at nexus ? +disk hp0 at mba? disk ? +disk hp1 at mba? disk ? +controller mba1 at nexus ? +disk hp2 at mba? disk ? +disk hp3 at mba? disk ? +controller uba0 at nexus ? +controller tm0 at uba? csr 0172520 vector tmintr +tape te0 at tm0 drive 0 +tape te1 at tm0 drive 1 +device dh0 at uba? csr 0160020 vector dhrint dhxint +device dm0 at uba? csr 0170500 vector dmintr +device dh1 at uba? csr 0160040 vector dhrint dhxint +device dh2 at uba? csr 0160060 vector dhrint dhxint +.DE +.LP +The completed configuration file for ANSEL is shown in Appendix C. +.NH 2 +VAX-11/750 with network support +.PP +Our VAX-11/750 system will be located on two 10Mb/s Ethernet +local area networks and also the DARPA Internet. The system +will have a MASSBUS drive for the root file system and two +UNIBUS drives. Paging is interleaved among all three drives. +We have sold our standard DEC terminal multiplexors since this +machine will be accessed solely through the network. This +machine is not intended to have a large user community, it +does not have a great deal of memory. First the global parameters: +.DS +.ta 1.5i 2.5i 4.0i +# +# UCBVAX (Gateway to the world) +# +machine vax +cpu "VAX780" +cpu "VAX750" +ident UCBVAX +timezone 8 dst +maxusers 32 +options INET +options NS +.DE +.PP +The multiple cpu types allow us to replace UCBVAX with a +more powerful cpu without reconfiguring the system. The +value of 32 given for the maximum number of users is done to +force the system data structures to be over-allocated. That +is desirable on this machine because, while it is not expected +to support many users, it is expected to perform a great deal +of work. +The ``INET'' indicates that we plan to use the +DARPA standard Internet protocols on this machine, +and ``NS'' also includes support for Xerox NS protocols. +Note that unlike 4.2BSD configuration files, +the network protocol options do not require corresponding pseudo devices. +.PP +The system images and disks are configured next. +.DS +.ta 1.5i 2.5i 4.0i +config kernel root on hp swap on hp and rk0 and rk1 +config upkernel root on up +config hkkernel root on hk swap on rk0 and rk1 + +controller mba0 at nexus ? +controller uba0 at nexus ? +disk hp0 at mba? drive 0 +disk hp1 at mba? drive 1 +controller sc0 at uba? csr 0176700 vector upintr +disk up0 at sc0 drive 0 +disk up1 at sc0 drive 1 +controller hk0 at uba? csr 0177440 vector rkintr +disk rk0 at hk0 drive 0 +disk rk1 at hk0 drive 1 +.DE +.PP +UCBVAX requires heavy interleaving of its paging area to keep up +with all the mail traffic it handles. The limiting factor on this +system's performance is usually the number of disk arms, as opposed +to memory or cpu cycles. The extra UNIBUS controller, ``sc0'', +is in case the MASSBUS controller breaks and a spare controller +must be installed (most of our old UNIBUS controllers have been +replaced with the newer MASSBUS controllers, so we have a number +of these around as spares). +.PP +Finally, we add in the network devices. +Pseudo terminals are needed to allow users to +log in across the network (remember the only hardwired terminal +is the console). +The software loopback device is used for on-machine communications. +The connection to the Internet is through +an IMP, this requires yet another +.I pseudo-device +(in addition to the actual hardware device used by the +IMP software). And, finally, there are the two Ethernet devices. +These use a special protocol, the Address Resolution Protocol (ARP), +to map between Internet and Ethernet addresses. Thus, yet another +.I pseudo-device +is needed. The additional device specifications are show below. +.DS +.ta 1.5i 2.5i 4.0i +pseudo-device pty +pseudo-device loop +pseudo-device imp +device acc0 at uba? csr 0167600 vector accrint accxint +pseudo-device ether +device ec0 at uba? csr 0164330 vector ecrint eccollide ecxint +device il0 at uba? csr 0164000 vector ilrint ilcint +.DE +.LP +The completed configuration file for UCBVAX is shown in Appendix C. +.NH 2 +Miscellaneous comments +.PP +It should be noted in these examples that neither system was +configured to use disk quotas or the 4.1BSD compatibility mode. +To use these optional facilities, and others, we would probably +clean out our current configuration, reconfigure the system, then +recompile and relink the system image(s). This could, of course, +be avoided by figuring out which relocatable object files are +affected by the reconfiguration, then reconfiguring and recompiling +only those files affected by the configuration change. This technique +should be used carefully. diff --git a/share/doc/smm/02.config/6.t b/share/doc/smm/02.config/6.t new file mode 100644 index 0000000..49f6e91 --- /dev/null +++ b/share/doc/smm/02.config/6.t @@ -0,0 +1,233 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)6.t 8.1 (Berkeley) 6/8/93 +.\" $FreeBSD$ +.\" +.\".ds RH "Adding New Devices +.ne 2i +.NH +ADDING NEW SYSTEM SOFTWARE +.PP +This section is not for the novice, it describes +some of the inner workings of the configuration process as +well as the pertinent parts of the system autoconfiguration process. +It is intended to give +those people who intend to install new device drivers and/or +other system facilities sufficient information to do so in the +manner which will allow others to easily share the changes. +.PP +This section is broken into four parts: +.IP \(bu 3 +general guidelines to be followed in modifying system code, +.IP \(bu 3 +how to add non-standard system facilities to 4.4BSD, +.IP \(bu 3 +how to add a device driver to 4.4BSD, and +.NH 2 +Modifying system code +.PP +If you wish to make site-specific modifications to the system +it is best to bracket them with +.DS +#ifdef SITENAME +\&... +#endif +.DE +to allow your source to be easily distributed to others, and +also to simplify \fIdiff\fP\|(1) listings. If you choose not +to use a source code control system (e.g. SCCS, RCS), and +perhaps even if you do, it is +recommended that you save the old code with something +of the form: +.DS +#ifndef SITENAME +\&... +#endif +.DE +We try to isolate our site-dependent code in individual files +which may be configured with pseudo-device specifications. +.PP +Indicate machine-specific code with ``#ifdef vax'' (or other machine, +as appropriate). +4.4BSD underwent extensive work to make it extremely portable to +machines with similar architectures\- you may someday find +yourself trying to use a single copy of the source code on +multiple machines. +.NH 2 +Adding non-standard system facilities +.PP +This section considers the work needed to augment +.IR config 's +data base files for non-standard system facilities. +.I Config +uses a set of files that list the source modules that may be required +when building a system. +The data bases are taken from the directory in which +.I config +is run, normally /sys/conf. +Three such files may be used: +.IR files , +.IR files .machine, +and +.IR files .ident. +The first is common to all systems, +the second contains files unique to a single machine type, +and the third is an optional list of modules for use on a specific machine. +This last file may override specifications in the first two. +The format of the +.I files +file has grown somewhat complex over time. Entries are normally of +the form +.IP +.nf +.DT +\fIdir/source.c\fP \fItype\fP \fIoption-list\fP \fImodifiers\fP +.LP +for example, +.IP +.nf +.DT +\fIvaxuba/foo.c\fP \fBoptional\fP foo \fBdevice-driver\fP +.LP +The +.I type +is one of +.B standard +or +.BR optional . +Files marked as standard are included in all system configurations. +Optional file specifications include a list of one or more system +options that together require the inclusion of this module. +The options in the list may be either names of devices that may +be in the configuration file, +or the names of system options that may be defined. +An optional file may be listed multiple times with different options; +if all of the options for any of the entries are satisfied, +the module is included. +.PP +If a file is specified as a +.IR device-driver , +any special compilation options for device drivers will be invoked. +On the VAX this results in the use of the +.B \-i +option for the C optimizer. This is required when pointer references +are made to memory locations in the VAX I/O address space. +.PP +Two other optional keywords modify the usage of the file. +.I Config +understands that certain files are used especially for +kernel profiling. These files are indicated in the +.I files +files with a +.I profiling-routine +keyword. For example, the current profiling subroutines +are sequestered off in a separate file with the following +entry: +.IP +.nf +.DT +\fIsys/subr_mcount.c\fP \fBoptional\fP \fBprofiling-routine\fP +.fi +.LP +The +.I profiling-routine +keyword forces +.I config +not to compile the source file with the +.B \-pg +option. +.PP +The second keyword which can be of use is the +.I config-dependent +keyword. This causes +.I config +to compile the indicated module with the global configuration +parameters. This allows certain modules, such as +.I machdep.c +to size system data structures based on the maximum number +of users configured for the system. +.NH 2 +Adding device drivers to 4.4BSD +.PP +The I/O system and +.I config +have been designed to easily allow new device support to be added. +The system source directories are organized as follows: +.DS +.TS +lw(1.0i) l. +/sys/h machine independent include files +/sys/sys machine-independent system source files +/sys/conf site configuration files and basic templates +/sys/net network-protocol-independent, but network-related code +/sys/netinet DARPA Internet code +/sys/netimp IMP support code +/sys/netns Xerox NS code +/sys/vax VAX-specific mainline code +/sys/vaxif VAX network interface code +/sys/vaxmba VAX MASSBUS device drivers and related code +/sys/vaxuba VAX UNIBUS device drivers and related code +.TE +.DE +.PP +Existing block and character device drivers for the VAX +reside in ``/sys/vax'', ``/sys/vaxmba'', and ``/sys/vaxuba''. Network +interface drivers reside in ``/sys/vaxif''. Any new device +drivers should be placed in the appropriate source code directory +and named so as not to conflict with existing devices. +Normally, definitions for things like device registers are placed in +a separate file in the same directory. For example, the ``dh'' +device driver is named ``dh.c'' and its associated include file is +named ``dhreg.h''. +.PP +Once the source for the device driver has been placed in a directory, +the file ``/sys/conf/files.machine'', and possibly +``/sys/conf/devices.machine'' should be modified. The +.I files +files in the conf directory contain a line for each C source or binary-only +file in the system. Those files which are machine independent are +located in ``/sys/conf/files,'' while machine specific files +are in ``/sys/conf/files.machine.'' The ``devices.machine'' file +is used to map device names to major block device numbers. If the device +driver being added provides support for a new disk +you will want to modify this file (the format is obvious). +.PP +In addition to including the driver in the +.I files +file, it must also be added to the device configuration tables. These +are located in ``/sys/vax/conf.c'', or similar for machines other than +the VAX. If you don't understand what to add to this file, you should +study an entry for an existing driver. +Remember that the position in the +device table specifies the major device number. +The block major number is needed in the ``devices.machine'' file +if the device is a disk. diff --git a/share/doc/smm/02.config/Makefile b/share/doc/smm/02.config/Makefile index 26ed70a..716eeda 100644 --- a/share/doc/smm/02.config/Makefile +++ b/share/doc/smm/02.config/Makefile @@ -5,6 +5,5 @@ VOLUME= smm/02.config SRCS= 0.t 1.t 2.t 3.t 4.t 5.t 6.t a.t b.t c.t d.t e.t MACROS= -ms USE_TBL= -SRCDIR= ${.CURDIR}/../../../../usr.sbin/config/SMM.doc .include <bsd.doc.mk> diff --git a/share/doc/smm/02.config/a.t b/share/doc/smm/02.config/a.t new file mode 100644 index 0000000..dfcb954 --- /dev/null +++ b/share/doc/smm/02.config/a.t @@ -0,0 +1,162 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)a.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Configuration File Grammar +.bp +.LG +.B +.ce +APPENDIX A. CONFIGURATION FILE GRAMMAR +.sp +.R +.NL +.PP +The following grammar is a compressed form of the actual +\fIyacc\fP\|(1) grammar used by +.I config +to parse configuration files. +Terminal symbols are shown all in upper case, literals +are emboldened; optional clauses are enclosed in brackets, ``['' +and ``]''; zero or more instantiations are denoted with ``*''. +.sp +.nf +.DT +Configuration ::= [ Spec \fB;\fP ]* + +Spec ::= Config_spec + | Device_spec + | \fBtrace\fP + | /* lambda */ + +/* configuration specifications */ + +Config_spec ::= \fBmachine\fP ID + | \fBcpu\fP ID + | \fBoptions\fP Opt_list + | \fBident\fP ID + | System_spec + | \fBtimezone\fP [ \fB\-\fP ] NUMBER [ \fBdst\fP [ NUMBER ] ] + | \fBtimezone\fP [ \fB\-\fP ] FPNUMBER [ \fBdst\fP [ NUMBER ] ] + | \fBmaxusers\fP NUMBER + +/* system configuration specifications */ + +System_spec ::= \fBconfig\fP ID System_parameter [ System_parameter ]* + +System_parameter ::= swap_spec | root_spec | dump_spec | arg_spec + +swap_spec ::= \fBswap\fP [ \fBon\fP ] swap_dev [ \fBand\fP swap_dev ]* + +swap_dev ::= dev_spec [ \fBsize\fP NUMBER ] + +root_spec ::= \fBroot\fP [ \fBon\fP ] dev_spec + +dump_spec ::= \fBdumps\fP [ \fBon\fP ] dev_spec + +arg_spec ::= \fBargs\fP [ \fBon\fP ] dev_spec + +dev_spec ::= dev_name | major_minor + +major_minor ::= \fBmajor\fP NUMBER \fBminor\fP NUMBER + +dev_name ::= ID [ NUMBER [ ID ] ] + +/* option specifications */ + +Opt_list ::= Option [ \fB,\fP Option ]* + +Option ::= ID [ \fB=\fP Opt_value ] + +Opt_value ::= ID | NUMBER + +Mkopt_list ::= Mkoption [ \fB,\fP Mkoption ]* + +Mkoption ::= ID \fB=\fP Opt_value + +/* device specifications */ + +Device_spec ::= \fBdevice\fP Dev_name Dev_info Int_spec + | \fBmaster\fP Dev_name Dev_info + | \fBdisk\fP Dev_name Dev_info + | \fBtape\fP Dev_name Dev_info + | \fBcontroller\fP Dev_name Dev_info [ Int_spec ] + | \fBpseudo-device\fP Dev [ NUMBER ] + +Dev_name ::= Dev NUMBER + +Dev ::= \fBuba\fP | \fBmba\fP | ID + +Dev_info ::= Con_info [ Info ]* + +Con_info ::= \fBat\fP Dev NUMBER + | \fBat\fP \fBnexus\fP NUMBER + +Info ::= \fBcsr\fP NUMBER + | \fBdrive\fP NUMBER + | \fBslave\fP NUMBER + | \fBflags\fP NUMBER + +Int_spec ::= \fBvector\fP ID [ ID ]* + | \fBpriority\fP NUMBER +.fi +.sp +.SH +Lexical Conventions +.LP +The terminal symbols are loosely defined as: +.IP ID +.br +One or more alphabetics, either upper or lower case, and underscore, +``_''. +.IP NUMBER +.br +Approximately the C language specification for an integer number. +That is, a leading ``0x'' indicates a hexadecimal value, +a leading ``0'' indicates an octal value, otherwise the number is +expected to be a decimal value. Hexadecimal numbers may use either +upper or lower case alphabetics. +.IP FPNUMBER +.br +A floating point number without exponent. That is a number of the +form ``nnn.ddd'', where the fractional component is optional. +.LP +In special instances a question mark, ``?'', can be substituted for +a ``NUMBER'' token. This is used to effect wildcarding in device +interconnection specifications. +.LP +Comments in configuration files are indicated by a ``#'' character +at the beginning of the line; the remainder of the line is discarded. +.LP +A specification +is interpreted as a continuation of the previous line +if the first character of the line is tab. diff --git a/share/doc/smm/02.config/b.t b/share/doc/smm/02.config/b.t new file mode 100644 index 0000000..901a009 --- /dev/null +++ b/share/doc/smm/02.config/b.t @@ -0,0 +1,137 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)b.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Device Defaulting Rules +.bp +.LG +.B +.ce +APPENDIX B. RULES FOR DEFAULTING SYSTEM DEVICES +.sp +.R +.NL +.PP +When \fIconfig\fP processes a ``config'' rule which does +not fully specify the location of the root file system, +paging area(s), device for system dumps, and device for +argument list processing it applies a set of rules to +define those values left unspecified. The following list +of rules are used in defaulting system devices. +.IP 1) 3 +If a root device is not specified, the swap +specification must indicate a ``generic'' system is to be built. +.IP 2) 3 +If the root device does not specify a unit number, it +defaults to unit 0. +.IP 3) 3 +If the root device does not include a partition specification, +it defaults to the ``a'' partition. +.IP 4) 3 +If no swap area is specified, it defaults to the ``b'' +partition of the root device. +.IP 5) 3 +If no device is specified for processing argument lists, the +first swap partition is selected. +.IP 6) 3 +If no device is chosen for system dumps, the first swap +partition is selected (see below to find out where dumps are +placed within the partition). +.PP +The following table summarizes the default partitions selected +when a device specification is incomplete, e.g. ``hp0''. +.DS +.TS +l l. +Type Partition +_ +root ``a'' +swap ``b'' +args ``b'' +dumps ``b'' +.TE +.DE +.SH +Multiple swap/paging areas +.PP +When multiple swap partitions are specified, the system treats the +first specified as a ``primary'' swap area which is always used. +The remaining partitions are then interleaved into the paging +system at the time a +.IR swapon (2) +system call is made. This is normally done at boot time with +a call to +.IR swapon (8) +from the /etc/rc file. +.SH +System dumps +.PP +System dumps are automatically taken after a system crash, +provided the device driver for the ``dumps'' device supports +this. The dump contains the contents of memory, but not +the swap areas. Normally the dump device is a disk in +which case the information is copied to a location at the +back of the partition. The dump is placed in the back of the +partition because the primary swap and dump device are commonly +the same device and this allows the system to be rebooted without +immediately overwriting the saved information. When a dump has +occurred, the system variable \fIdumpsize\fP +is set to a non-zero value indicating the size (in bytes) of +the dump. The \fIsavecore\fP\|(8) +program then copies the information from the dump partition to +a file in a ``crash'' directory and also makes a copy of the +system which was running at the time of the crash (usually +``/kernel''). The offset to the system dump is defined in the +system variable \fIdumplo\fP (a sector offset from +the front of the dump partition). The +.I savecore +program operates by reading the contents of \fIdumplo\fP, \fIdumpdev\fP, +and \fIdumpmagic\fP from /dev/kmem, then comparing the value +of \fIdumpmagic\fP read from /dev/kmem to that located in +corresponding location in the dump area of the dump partition. +If a match is found, +.I savecore +assumes a crash occurred and reads \fIdumpsize\fP from the dump area +of the dump partition. This value is then used in copying the +system dump. Refer to +\fIsavecore\fP\|(8) +for more information about its operation. +.PP +The value \fIdumplo\fP is calculated to be +.DS +\fIdumpdev-size\fP \- \fImemsize\fP +.DE +where \fIdumpdev-size\fP is the size of the disk partition +where system dumps are to be placed, and +\fImemsize\fP is the size of physical memory. +If the disk partition is not large enough to hold a full +dump, \fIdumplo\fP is set to 0 (the start of the partition). diff --git a/share/doc/smm/02.config/c.t b/share/doc/smm/02.config/c.t new file mode 100644 index 0000000..67b63ec --- /dev/null +++ b/share/doc/smm/02.config/c.t @@ -0,0 +1,109 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)c.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Sample Config Files +.bp +.LG +.B +.ce +APPENDIX C. SAMPLE CONFIGURATION FILES +.sp +.R +.NL +.PP +The following configuration files are developed in section 5; +they are included here for completeness. +.sp 2 +.nf +.ta 1.5i 2.5i 4.0i +# +# ANSEL VAX (a picture perfect machine) +# +machine vax +cpu VAX780 +timezone 8 dst +ident ANSEL +maxusers 40 + +config kernel root on hp0 +config hpkernel root on hp0 swap on hp0 and hp2 +config genkernel swap generic + +controller mba0 at nexus ? +disk hp0 at mba? disk ? +disk hp1 at mba? disk ? +controller mba1 at nexus ? +disk hp2 at mba? disk ? +disk hp3 at mba? disk ? +controller uba0 at nexus ? +controller tm0 at uba? csr 0172520 vector tmintr +tape te0 at tm0 drive 0 +tape te1 at tm0 drive 1 +device dh0 at uba? csr 0160020 vector dhrint dhxint +device dm0 at uba? csr 0170500 vector dmintr +device dh1 at uba? csr 0160040 vector dhrint dhxint +device dh2 at uba? csr 0160060 vector dhrint dhxint +.bp +# +# UCBVAX - Gateway to the world +# +machine vax +cpu "VAX780" +cpu "VAX750" +ident UCBVAX +timezone 8 dst +maxusers 32 +options INET +options NS + +config kernel root on hp swap on hp and rk0 and rk1 +config upkernel root on up +config hkkernel root on hk swap on rk0 and rk1 + +controller mba0 at nexus ? +controller uba0 at nexus ? +disk hp0 at mba? drive 0 +disk hp1 at mba? drive 1 +controller sc0 at uba? csr 0176700 vector upintr +disk up0 at sc0 drive 0 +disk up1 at sc0 drive 1 +controller hk0 at uba? csr 0177440 vector rkintr +disk rk0 at hk0 drive 0 +disk rk1 at hk0 drive 1 +pseudo-device pty +pseudo-device loop +pseudo-device imp +device acc0 at uba? csr 0167600 vector accrint accxint +pseudo-device ether +device ec0 at uba? csr 0164330 vector ecrint eccollide ecxint +device il0 at uba? csr 0164000 vector ilrint ilcint diff --git a/share/doc/smm/02.config/d.t b/share/doc/smm/02.config/d.t new file mode 100644 index 0000000..db9ab80 --- /dev/null +++ b/share/doc/smm/02.config/d.t @@ -0,0 +1,272 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)d.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Data Structure Sizing Rules +.bp +.LG +.B +.ce +APPENDIX D. VAX KERNEL DATA STRUCTURE SIZING RULES +.sp +.R +.NL +.PP +Certain system data structures are sized at compile time +according to the maximum number of simultaneous users expected, +while others are calculated at boot time based on the +physical resources present, e.g. memory. This appendix lists +both sets of rules and also includes some hints on changing +built-in limitations on certain data structures. +.SH +Compile time rules +.PP +The file \fI/sys/conf\|/param.c\fP contains the definitions of +almost all data structures sized at compile time. This file +is copied into the directory of each configured system to allow +configuration-dependent rules and values to be maintained. +(Each copy normally depends on the copy in /sys/conf, +and global modifications cause the file to be recopied unless +the makefile is modified.) +The rules implied by its contents are summarized below (here +MAXUSERS refers to the value defined in the configuration file +in the ``maxusers'' rule). +Most limits are computed at compile time and stored in global variables +for use by other modules; they may generally be patched in the system +binary image before rebooting to test new values. +.IP \fBnproc\fP +.br +The maximum number of processes which may be running at any time. +It is referred to in other calculations as NPROC and is defined to be +.DS +20 + 8 * MAXUSERS +.DE +.IP \fBntext\fP +.br +The maximum number of active shared text segments. +The constant is intended to allow for network servers and common commands +that remain in the table. +It is defined as +.DS +36 + MAXUSERS. +.DE +.IP \fBninode\fP +.br +The maximum number of files in the file system which may be +active at any time. This includes files in use by users, as +well as directory files being read or written by the system +and files associated with bound sockets in the UNIX IPC domain. +It is defined as +.DS +(NPROC + 16 + MAXUSERS) + 32 +.DE +.IP \fBnfile\fP +.br +The number of ``file table'' structures. One file +table structure is used for each open, unshared, file descriptor. +Multiple file descriptors may reference a single file table +entry when they are created through a \fIdup\fP call, or as the +result of a \fIfork\fP. This is defined to be +.DS +16 * (NPROC + 16 + MAXUSERS) / 10 + 32 +.DE +.IP \fBncallout\fP +.br +The number of ``callout'' structures. One callout +structure is used per internal system event handled with +a timeout. Timeouts are used for terminal delays, +watchdog routines in device drivers, protocol timeout processing, etc. +This is defined as +.DS +16 + NPROC +.DE +.IP \fBnclist\fP +.br +The number of ``c-list'' structures. C-list structures are +used in terminal I/O, and currently each holds 60 characters. +Their number is defined as +.DS +60 + 12 * MAXUSERS +.DE +.IP \fBnmbclusters\fP +.br +The maximum number of pages which may be allocated by the network. +This is defined as 256 (a quarter megabyte of memory) in /sys/h/mbuf.h. +In practice, the network rarely uses this much memory. It starts off +by allocating 8 kilobytes of memory, then requesting more as +required. This value represents an upper bound. +.IP \fBnquota\fP +.br +The number of ``quota'' structures allocated. Quota structures +are present only when disc quotas are configured in the system. One +quota structure is kept per user. This is defined to be +.DS +(MAXUSERS * 9) / 7 + 3 +.DE +.IP \fBndquot\fP +.br +The number of ``dquot'' structures allocated. Dquot structures +are present only when disc quotas are configured in the system. +One dquot structure is required per user, per active file system quota. +That is, when a user manipulates a file on a file system on which +quotas are enabled, the information regarding the user's quotas on +that file system must be in-core. This information is cached, so +that not all information must be present in-core all the time. +This is defined as +.DS +NINODE + (MAXUSERS * NMOUNT) / 4 +.DE +where NMOUNT is the maximum number of mountable file systems. +.LP +In addition to the above values, the system page tables (used to +map virtual memory in the kernel's address space) are sized at +compile time by the SYSPTSIZE definition in the file /sys/vax/vmparam.h. +This is defined to be +.DS +20 + MAXUSERS +.DE +pages of page tables. +Its definition affects +the size of many data structures allocated at boot time because +it constrains the amount of virtual memory which may be addressed +by the running system. This is often the limiting factor +in the size of the buffer cache, in which case a message is printed +when the system configures at boot time. +.SH +Run-time calculations +.PP +The most important data structures sized at run-time are those used in +the buffer cache. Allocation is done by allocating physical memory +(and system virtual memory) immediately after the system +has been started up; look in the file /sys/vax/machdep.c. +The amount of physical memory which may be allocated to the buffer +cache is constrained by the size of the system page tables, among +other things. While the system may calculate +a large amount of memory to be allocated to the buffer cache, +if the system page +table is too small to map this physical +memory into the virtual address space +of the system, only as much as can be mapped will be used. +.PP +The buffer cache is comprised of a number of ``buffer headers'' +and a pool of pages attached to these headers. Buffer headers +are divided into two categories: those used for swapping and +paging, and those used for normal file I/O. The system tries +to allocate 10% of the first two megabytes and 5% of the remaining +available physical memory for the buffer +cache (where \fIavailable\fP does not count that space occupied by +the system's text and data segments). If this results in fewer +than 16 pages of memory allocated, then 16 pages are allocated. +This value is kept in the initialized variable \fIbufpages\fP +so that it may be patched in the binary image (to allow tuning +without recompiling the system), +or the default may be overridden with a configuration-file option. +For example, the option \fBoptions BUFPAGES="3200"\fP +causes 3200 pages (3.2M bytes) to be used by the buffer cache. +A sufficient number of file I/O buffer headers are then allocated +to allow each to hold 2 pages each. +Each buffer maps 8K bytes. +If the number of buffer pages is larger than can be mapped +by the buffer headers, the number of pages is reduced. +The number of buffer headers allocated +is stored in the global variable \fInbuf\fP, +which may be patched before the system is booted. +The system option \fBoptions NBUF="1000"\fP forces the allocation +of 1000 buffer headers. +Half as many swap I/O buffer headers as file I/O buffers +are allocated, +but no more than 256. +.SH +System size limitations +.PP +As distributed, the sum of the virtual sizes of the core-resident +processes is limited to 256M bytes. The size of the text +segment of a single process is currently limited to 6M bytes. +It may be increased to no greater than the data segment size limit +(see below) by redefining MAXTSIZ. +This may be done with a configuration file option, +e.g. \fBoptions MAXTSIZ="(10*1024*1024)"\fP +to set the limit to 10 million bytes. +Other per-process limits discussed here may be changed with similar options +with names given in parentheses. +Soft, user-changeable limits are set to 512K bytes for stack (DFLSSIZ) +and 6M bytes for the data segment (DFLDSIZ) by default; +these may be increased up to the hard limit +with the \fIsetrlimit\fP\|(2) system call. +The data and stack segment size hard limits are set by a system configuration +option to one of 17M, 33M or 64M bytes. +One of these sizes is chosen based on the definition of MAXDSIZ; +with no option, the limit is 17M bytes; with an option +\fBoptions MAXDSIZ="(32*1024*1024)"\fP (or any value between 17M and 33M), +the limit is increased to 33M bytes, and values larger than 33M +result in a limit of 64M bytes. +You must be careful in doing this that you have adequate paging space. +As normally configured , the system has 16M or 32M bytes per paging area, +depending on disk size. +The best way to get more space is to provide multiple, thereby +interleaved, paging areas. +Increasing the virtual memory limits results in interleaving of +swap space in larger sections (from 500K bytes to 1M or 2M bytes). +.PP +By default, the virtual memory system allocates enough memory +for system page tables mapping user page tables +to allow 256 megabytes of simultaneous active virtual memory. +That is, the sum of the virtual memory sizes of all (completely- or partially-) +resident processes can not exceed this limit. +If the limit is exceeded, some process(es) must be swapped out. +To increase the amount of resident virtual space possible, +you can alter the constant USRPTSIZE (in +/sys/vax/vmparam.h). +Each page of system page tables allows 8 megabytes of user virtual memory. +.PP +Because the file system block numbers are stored in +page table \fIpg_blkno\fP +entries, the maximum size of a file system is limited to +2^24 1024 byte blocks. Thus no file system can be larger than 8 gigabytes. +.PP +The number of mountable file systems is set at 20 by the definition +of NMOUNT in /sys/h/param.h. +This should be sufficient; if not, the value can be increased up to 255. +If you have many disks, it makes sense to make some of +them single file systems, and the paging areas don't count in this total. +.PP +The limit to the number of files that a process may have open simultaneously +is set to 64. +This limit is set by the NOFILE definition in /sys/h/param.h. +It may be increased arbitrarily, with the caveat that the user structure +expands by 5 bytes for each file, and thus UPAGES (/sys/vax/machparam.h) +must be increased accordingly. +.PP +The amount of physical memory is currently limited to 64 Mb +by the size of the index fields in the core-map (/sys/h/cmap.h). +The limit may be increased by following instructions in that file +to enlarge those fields. diff --git a/share/doc/smm/02.config/e.t b/share/doc/smm/02.config/e.t new file mode 100644 index 0000000..0a9505b --- /dev/null +++ b/share/doc/smm/02.config/e.t @@ -0,0 +1,114 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)e.t 8.1 (Berkeley) 6/8/93 +.\" +.\".ds RH "Network configuration options +.bp +.LG +.B +.ce +APPENDIX E. NETWORK CONFIGURATION OPTIONS +.sp +.R +.NL +.PP +The network support in the kernel is self-configuring +according to the protocol support options (INET and NS) and the network +hardware discovered during autoconfiguration. +There are several changes that may be made to customize network behavior +due to local restrictions. +Within the Internet protocol routines, the following options +set in the system configuration file are supported: +.IP \fBGATEWAY\fP +.br +The machine is to be used as a gateway. +This option currently makes only minor changes. +First, the size of the network routing hash table is increased. +Secondly, machines that have only a single hardware network interface +will not forward IP packets; without this option, they will also refrain +from sending any error indication to the source of unforwardable packets. +Gateways with only a single interface are assumed to have missing +or broken interfaces, and will return ICMP unreachable errors to hosts +sending them packets to be forwarded. +.IP \fBTCP_COMPAT_42\fP +.br +This option forces the system to limit its initial TCP sequence numbers +to positive numbers. +Without this option, 4.4BSD systems may have problems with TCP connections +to 4.2BSD systems that connect but never transfer data. +The problem is a bug in the 4.2BSD TCP. +.IP \fBIPFORWARDING\fP +.br +Normally, 4.4BSD machines with multiple network interfaces +will forward IP packets received that should be resent to another host. +If the line ``options IPFORWARDING="0"'' is in the system configuration +file, IP packet forwarding will be disabled. +.IP \fBIPSENDREDIRECTS\fP +.br +When forwarding IP packets, 4.4BSD IP will note when a packet is forwarded +using the same interface on which it arrived. +When this is noted, if the source machine is on the directly-attached +network, an ICMP redirect is sent to the source host. +If the packet was forwarded using a route to a host or to a subnet, +a host redirect is sent, otherwise a network redirect is sent. +The generation of redirects may be inhibited with the configuration +option ``options IPSENDREDIRECTS="0".'' +.br +.IP \fBSUBNETSARELOCAL\fP +TCP calculates a maximum segment size to use for each connection, +and sends no datagrams larger than that size. +This size will be no larger than that supported on the outgoing +interface. +Furthermore, if the destination is not on the local network, +the size will be no larger than 576 bytes. +For this test, other subnets of a directly-connected subnetted +network are considered to be local unless the line +``options SUBNETSARELOCAL="0"'' is used in the system configuration file. +.LP +The following options are supported by the Xerox NS protocols: +.IP \fBNSIP\fP +.br +This option allows NS IDP datagrams to be encapsulated in Internet IP +packets for transmission to a collaborating NSIP host. +This may be used to pass IDP packets through IP-only link layer networks. +See +.IR nsip (4P) +for details. +.IP \fBTHREEWAYSHAKE\fP +.br +The NS Sequenced Packet Protocol does not require a three-way handshake +before considering a connection to be in the established state. +(A three-way handshake consists of a connection request, an acknowledgement +of the request along with a symmetrical opening indication, +and then an acknowledgement of the reciprocal opening packet.) +This option forces a three-way handshake before data may be transmitted +on Sequenced Packet sockets. diff --git a/share/doc/smm/02.config/spell.ok b/share/doc/smm/02.config/spell.ok new file mode 100644 index 0000000..dfc5df1 --- /dev/null +++ b/share/doc/smm/02.config/spell.ok @@ -0,0 +1,305 @@ +# $FreeBSD$ +ACC +ANSEL +ARP +Autoconfiguration +BUFPAGES +CANTWAIT +CH +COMPAT +CSS +Co +Config +Config''SMM:2 +DCLR +DFLDSIZ +DFLSSIZ +DFUNNY +DHAHA +DMA +Dev +Dquot +ECC +EMULEX +Emulex +Ethernet +FPNUMBER +FUNNY,HAHA +HAVEBDP +ICMP +IDP +IE +INET +IP +IPC +IPFORWARDING +IPL +IPSENDREDIRECTS +Info +Karels +LH +Leffler +MASSBUS +MAXDSIZ +MAXTSIZ +Makefile +Mb +MicroVAX +Mkopt +Mkoption +NBUF +NEED16 +NEEDBDP +NINODE +NMOUNT +NOFILE +NPROC +NS +NSC +NSIP +NUP +PST +RCS +RDY +RH +RK07 +RK611 +SCCS +SITENAME +SMM:2 +SUBNETSARELOCAL +SYSPTSIZE +TCP +THREEWAYSHAKE +Timezone +UCBVAX +UDP +UNIBUS +UPAGES +UPCS2 +USRPTSIZE +VAX +VAX630 +VAX730 +VAX750 +VAX780 +VAX8600 +VAXWELL +VAXen +Vax +Vaxwell +acc0 +accrint +accxint +addr +arg +args +assym.s +autoconfiguration +autoconfigure +autoconfigured +backpointer +badaddr +blkno +br +br5 +buf +bufpages +buses +caddr +callout +catchall +cmap.h +cmd +conf +conf.c +config +csr +ct.c +ctlr +cvec +datagrams +define''s +dev +devices.machine +dgo +dh.c +dh0 +dh1 +dh2 +dhreg.h +dhrint +dhxint +dinfo +dk +dk.h +dm0 +dmintr +dname +dquot +dst +dumpdev +dumplo +dumpmagic +dumpsize +dz.c +dz0 +dzrint +dzxint +ec0 +eccollide +ecrint +ecxint +endif +es +files.machine +filesystem +foo +foo.c +genkernel +gettimeofday +gigabytes +gprof +hardwired +hd +hk +hk0 +hkkernel +howmany +hp0 +hp0b +hp1 +hp2 +hp3 +hpkernel +ht0 +hz +ident +ifdef +ifndef +il0 +ilcint +ilrint +info +intr +ioconf.c +kgmon +linterrs +loopback +machdep.c +machparam.h +makefile +makelinks +makeoptions +maxusers +mba +mba0 +mba1 +mbuf.h +mcount.c +memsize +minfo +mname +moniker +mspw +nbuf +ncallout +nclist +ndquot +ndrive +netimp +netinet +netns +netstat +nexi +nexus +nfile +ninode +nmbclusters +nnn.ddd +nproc +nquota +nsip +ntext +optionlist +param.c +param.h +pathnames +pg +physaddr +pty +rc +reg +rk.c +rk0 +rk1 +rkintr +savecore +sc +sc0 +sc1 +scdriver +setrlimit +sizeof +softc +source.c +subr +swapxxx.c +sysname +te0 +te1 +timezone +tm0 +tmintr +tu0 +uba +uba.c +uba0 +ubago +uballoc +ubamem +ubanum +ubareg.h +ubarelse +ubavar.h +ubglue.s +ubinfo +ud +ui +um +up.c +up0 +up1 +up2 +upaddr +upattach +upba +upcs1 +upcs2 +updevice +updgo +updinfo +updtab +upintr +upip +upmaptype +upminfo +upprobe +upslave +upstd +upkernel +upwatch +upwstart +value,name2 +value2 +vax +vaxif +vaxmba +vaxuba +vmparam.h +kernel +wildcard +wildcarded +wildcarding +xclu +xxx diff --git a/share/doc/smm/03.fsck/0.t b/share/doc/smm/03.fsck/0.t new file mode 100644 index 0000000..5fe189d --- /dev/null +++ b/share/doc/smm/03.fsck/0.t @@ -0,0 +1,147 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" @(#)0.t 8.1 (Berkeley) 6/8/93 +.\" +.if n .ND +.TL +Fsck_ffs \- The UNIX\(dg File System Check Program +.EH 'SMM:3-%''The \s-2UNIX\s+2 File System Check Program' +.OH 'The \s-2UNIX\s+2 File System Check Program''SMM:3-%' +.AU +Marshall Kirk McKusick +.AI +Computer Systems Research Group +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, CA 94720 +.AU +T. J. Kowalski +.AI +Bell Laboratories +Murray Hill, New Jersey 07974 +.AB +.FS +\(dgUNIX is a trademark of Bell Laboratories. +.FE +.FS +This work was done under grants from +the National Science Foundation under grant MCS80-05144, +and the Defense Advance Research Projects Agency (DoD) under +Arpa Order No. 4031 monitored by Naval Electronic System Command under +Contract No. N00039-82-C-0235. +.FE +This document reflects the use of +.I fsck_ffs +with the 4.2BSD and 4.3BSD file system organization. This +is a revision of the +original paper written by +T. J. Kowalski. +.PP +File System Check Program (\fIfsck_ffs\fR) +is an interactive file system check and repair program. +.I Fsck_ffs +uses the redundant structural information in the +UNIX file system to perform several consistency checks. +If an inconsistency is detected, it is reported +to the operator, who may elect to fix or ignore +each inconsistency. +These inconsistencies result from the permanent interruption +of the file system updates, which are performed every +time a file is modified. +Unless there has been a hardware failure, +.I fsck_ffs +is able to repair corrupted file systems +using procedures based upon the order in which UNIX honors +these file system update requests. +.PP +The purpose of this document is to describe the normal updating +of the file system, +to discuss the possible causes of file system corruption, +and to present the corrective actions implemented +by +.I fsck_ffs. +Both the program and the interaction between the +program and the operator are described. +.sp 2 +.LP +Revised October 7, 1996 +.AE +.LP +.bp +.ce +.B "TABLE OF CONTENTS" +.LP +.sp 1 +.nf +.B "1. Introduction" +.LP +.sp .5v +.nf +.B "2. Overview of the file system +2.1. Superblock +2.2. Summary Information +2.3. Cylinder groups +2.4. Fragments +2.5. Updates to the file system +.LP +.sp .5v +.nf +.B "3. Fixing corrupted file systems +3.1. Detecting and correcting corruption +3.2. Super block checking +3.3. Free block checking +3.4. Checking the inode state +3.5. Inode links +3.6. Inode data size +3.7. Checking the data associated with an inode +3.8. File system connectivity +.LP +.sp .5v +.nf +.B Acknowledgements +.LP +.sp .5v +.nf +.B References +.LP +.sp .5v +.nf +.B "4. Appendix A +4.1. Conventions +4.2. Initialization +4.3. Phase 1 - Check Blocks and Sizes +4.4. Phase 1b - Rescan for more Dups +4.5. Phase 2 - Check Pathnames +4.6. Phase 3 - Check Connectivity +4.7. Phase 4 - Check Reference Counts +4.8. Phase 5 - Check Cyl groups +4.9. Cleanup +.ds RH Introduction +.bp diff --git a/share/doc/smm/03.fsck/1.t b/share/doc/smm/03.fsck/1.t new file mode 100644 index 0000000..3098b49 --- /dev/null +++ b/share/doc/smm/03.fsck/1.t @@ -0,0 +1,80 @@ +.\" Copyright (c) 1982, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" @(#)1.t 8.1 (Berkeley) 6/5/93 +.\" +.ds RH Introduction +.NH +Introduction +.PP +This document reflects the use of +.I fsck_ffs +with the 4.2BSD and 4.3BSD file system organization. This +is a revision of the +original paper written by +T. J. Kowalski. +.PP +When a UNIX +operating system is brought up, a consistency +check of the file systems should always be performed. +This precautionary measure helps to insure +a reliable environment for file storage on disk. +If an inconsistency is discovered, +corrective action must be taken. +.I Fsck_ffs +runs in two modes. +Normally it is run non-interactively by the system after +a normal boot. +When running in this mode, +it will only make changes to the file system that are known +to always be correct. +If an unexpected inconsistency is found +.I fsck_ffs +will exit with a non-zero exit status, +leaving the system running single-user. +Typically the operator then runs +.I fsck_ffs +interactively. +When running in this mode, +each problem is listed followed by a suggested corrective action. +The operator must decide whether or not the suggested correction +should be made. +.PP +The purpose of this memo is to dispel the +mystique surrounding +file system inconsistencies. +It first describes the updating of the file system +(the calm before the storm) and +then describes file system corruption (the storm). +Finally, +the set of deterministic corrective actions +used by +.I fsck_ffs +(the Coast Guard +to the rescue) is presented. +.ds RH Overview of the File System diff --git a/share/doc/smm/03.fsck/2.t b/share/doc/smm/03.fsck/2.t new file mode 100644 index 0000000..b294a6a --- /dev/null +++ b/share/doc/smm/03.fsck/2.t @@ -0,0 +1,262 @@ +.\" Copyright (c) 1982, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" @(#)2.t 8.1 (Berkeley) 6/5/93 +.\" +.ds RH Overview of the file system +.NH +Overview of the file system +.PP +The file system is discussed in detail in [Mckusick84]; +this section gives a brief overview. +.NH 2 +Superblock +.PP +A file system is described by its +.I "super-block" . +The super-block is built when the file system is created (\c +.I newfs (8)) +and never changes. +The super-block +contains the basic parameters of the file system, +such as the number of data blocks it contains +and a count of the maximum number of files. +Because the super-block contains critical data, +.I newfs +replicates it to protect against catastrophic loss. +The +.I "default super block" +always resides at a fixed offset from the beginning +of the file system's disk partition. +The +.I "redundant super blocks" +are not referenced unless a head crash +or other hard disk error causes the default super-block +to be unusable. +The redundant blocks are sprinkled throughout the disk partition. +.PP +Within the file system are files. +Certain files are distinguished as directories and contain collections +of pointers to files that may themselves be directories. +Every file has a descriptor associated with it called an +.I "inode". +The inode contains information describing ownership of the file, +time stamps indicating modification and access times for the file, +and an array of indices pointing to the data blocks for the file. +In this section, +we assume that the first 12 blocks +of the file are directly referenced by values stored +in the inode structure itself\(dg. +.FS +\(dgThe actual number may vary from system to system, but is usually in +the range 5-13. +.FE +The inode structure may also contain references to indirect blocks +containing further data block indices. +In a file system with a 4096 byte block size, a singly indirect +block contains 1024 further block addresses, +a doubly indirect block contains 1024 addresses of further single indirect +blocks, +and a triply indirect block contains 1024 addresses of further doubly indirect +blocks (the triple indirect block is never needed in practice). +.PP +In order to create files with up to +2\(ua32 bytes, +using only two levels of indirection, +the minimum size of a file system block is 4096 bytes. +The size of file system blocks can be any power of two +greater than or equal to 4096. +The block size of the file system is maintained in the super-block, +so it is possible for file systems of different block sizes +to be accessible simultaneously on the same system. +The block size must be decided when +.I newfs +creates the file system; +the block size cannot be subsequently +changed without rebuilding the file system. +.NH 2 +Summary information +.PP +Associated with the super block is non replicated +.I "summary information" . +The summary information changes +as the file system is modified. +The summary information contains +the number of blocks, fragments, inodes and directories in the file system. +.NH 2 +Cylinder groups +.PP +The file system partitions the disk into one or more areas called +.I "cylinder groups". +A cylinder group is comprised of one or more consecutive +cylinders on a disk. +Each cylinder group includes inode slots for files, a +.I "block map" +describing available blocks in the cylinder group, +and summary information describing the usage of data blocks +within the cylinder group. +A fixed number of inodes is allocated for each cylinder group +when the file system is created. +The current policy is to allocate one inode for each 2048 +bytes of disk space; +this is expected to be far more inodes than will ever be needed. +.PP +All the cylinder group bookkeeping information could be +placed at the beginning of each cylinder group. +However if this approach were used, +all the redundant information would be on the top platter. +A single hardware failure that destroyed the top platter +could cause the loss of all copies of the redundant super-blocks. +Thus the cylinder group bookkeeping information +begins at a floating offset from the beginning of the cylinder group. +The offset for +the +.I "i+1" st +cylinder group is about one track further +from the beginning of the cylinder group +than it was for the +.I "i" th +cylinder group. +In this way, +the redundant +information spirals down into the pack; +any single track, cylinder, +or platter can be lost without losing all copies of the super-blocks. +Except for the first cylinder group, +the space between the beginning of the cylinder group +and the beginning of the cylinder group information stores data. +.NH 2 +Fragments +.PP +To avoid waste in storing small files, +the file system space allocator divides a single +file system block into one or more +.I "fragments". +The fragmentation of the file system is specified +when the file system is created; +each file system block can be optionally broken into +2, 4, or 8 addressable fragments. +The lower bound on the size of these fragments is constrained +by the disk sector size; +typically 512 bytes is the lower bound on fragment size. +The block map associated with each cylinder group +records the space availability at the fragment level. +Aligned fragments are examined +to determine block availability. +.PP +On a file system with a block size of 4096 bytes +and a fragment size of 1024 bytes, +a file is represented by zero or more 4096 byte blocks of data, +and possibly a single fragmented block. +If a file system block must be fragmented to obtain +space for a small amount of data, +the remainder of the block is made available for allocation +to other files. +For example, +consider an 11000 byte file stored on +a 4096/1024 byte file system. +This file uses two full size blocks and a 3072 byte fragment. +If no fragments with at least 3072 bytes +are available when the file is created, +a full size block is split yielding the necessary 3072 byte +fragment and an unused 1024 byte fragment. +This remaining fragment can be allocated to another file, as needed. +.NH 2 +Updates to the file system +.PP +Every working day hundreds of files +are created, modified, and removed. +Every time a file is modified, +the operating system performs a +series of file system updates. +These updates, when written on disk, yield a consistent file system. +The file system stages +all modifications of critical information; +modification can +either be completed or cleanly backed out after a crash. +Knowing the information that is first written to the file system, +deterministic procedures can be developed to +repair a corrupted file system. +To understand this process, +the order that the update +requests were being honored must first be understood. +.PP +When a user program does an operation to change the file system, +such as a +.I write , +the data to be written is copied into an internal +.I "in-core" +buffer in the kernel. +Normally, the disk update is handled asynchronously; +the user process is allowed to proceed even though +the data has not yet been written to the disk. +The data, +along with the inode information reflecting the change, +is eventually written out to disk. +The real disk write may not happen until long after the +.I write +system call has returned. +Thus at any given time, the file system, +as it resides on the disk, +lags the state of the file system represented by the in-core information. +.PP +The disk information is updated to reflect the in-core information +when the buffer is required for another use, +when a +.I sync (2) +is done (at 30 second intervals) by +.I "/etc/update" "(8)," +or by manual operator intervention with the +.I sync (8) +command. +If the system is halted without writing out the in-core information, +the file system on the disk will be in an inconsistent state. +.PP +If all updates are done asynchronously, several serious +inconsistencies can arise. +One inconsistency is that a block may be claimed by two inodes. +Such an inconsistency can occur when the system is halted before +the pointer to the block in the old inode has been cleared +in the copy of the old inode on the disk, +and after the pointer to the block in the new inode has been written out +to the copy of the new inode on the disk. +Here, +there is no deterministic method for deciding +which inode should really claim the block. +A similar problem can arise with a multiply claimed inode. +.PP +The problem with asynchronous inode updates +can be avoided by doing all inode deallocations synchronously. +Consequently, +inodes and indirect blocks are written to the disk synchronously +(\fIi.e.\fP the process blocks until the information is +really written to disk) +when they are being deallocated. +Similarly inodes are kept consistent by synchronously +deleting, adding, or changing directory entries. +.ds RH Fixing corrupted file systems diff --git a/share/doc/smm/03.fsck/3.t b/share/doc/smm/03.fsck/3.t new file mode 100644 index 0000000..522a222 --- /dev/null +++ b/share/doc/smm/03.fsck/3.t @@ -0,0 +1,449 @@ +.\" Copyright (c) 1982, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" @(#)3.t 8.1 (Berkeley) 6/5/93 +.\" +.ds RH Fixing corrupted file systems +.NH +Fixing corrupted file systems +.PP +A file system +can become corrupted in several ways. +The most common of these ways are +improper shutdown procedures +and hardware failures. +.PP +File systems may become corrupted during an +.I "unclean halt" . +This happens when proper shutdown +procedures are not observed, +physically write-protecting a mounted file system, +or a mounted file system is taken off-line. +The most common operator procedural failure is forgetting to +.I sync +the system before halting the CPU. +.PP +File systems may become further corrupted if proper startup +procedures are not observed, e.g., +not checking a file system for inconsistencies, +and not repairing inconsistencies. +Allowing a corrupted file system to be used (and, thus, to be modified +further) can be disastrous. +.PP +Any piece of hardware can fail at any time. +Failures +can be as subtle as a bad block +on a disk pack, or as blatant as a non-functional disk-controller. +.NH 2 +Detecting and correcting corruption +.PP +Normally +.I fsck_ffs +is run non-interactively. +In this mode it will only fix +corruptions that are expected to occur from an unclean halt. +These actions are a proper subset of the actions that +.I fsck_ffs +will take when it is running interactively. +Throughout this paper we assume that +.I fsck_ffs +is being run interactively, +and all possible errors can be encountered. +When an inconsistency is discovered in this mode, +.I fsck_ffs +reports the inconsistency for the operator to +chose a corrective action. +.PP +A quiescent\(dd +.FS +\(dd I.e., unmounted and not being written on. +.FE +file system may be checked for structural integrity +by performing consistency checks on the +redundant data intrinsic to a file system. +The redundant data is either read from +the file system, +or computed from other known values. +The file system +.B must +be in a quiescent state when +.I fsck_ffs +is run, +since +.I fsck_ffs +is a multi-pass program. +.PP +In the following sections, +we discuss methods to discover inconsistencies +and possible corrective actions +for the cylinder group blocks, the inodes, the indirect blocks, and +the data blocks containing directory entries. +.NH 2 +Super-block checking +.PP +The most commonly corrupted item in a file system +is the summary information +associated with the super-block. +The summary information is prone to corruption +because it is modified with every change to the file +system's blocks or inodes, +and is usually corrupted +after an unclean halt. +.PP +The super-block is checked for inconsistencies +involving file-system size, number of inodes, +free-block count, and the free-inode count. +The file-system size must be larger than the +number of blocks used by the super-block +and the number of blocks used by the list of inodes. +The file-system size and layout information +are the most critical pieces of information for +.I fsck_ffs . +While there is no way to actually check these sizes, +since they are statically determined by +.I newfs , +.I fsck_ffs +can check that these sizes are within reasonable bounds. +All other file system checks require that these sizes be correct. +If +.I fsck_ffs +detects corruption in the static parameters of the default super-block, +.I fsck_ffs +requests the operator to specify the location of an alternate super-block. +.NH 2 +Free block checking +.PP +.I Fsck_ffs +checks that all the blocks +marked as free in the cylinder group block maps +are not claimed by any files. +When all the blocks have been initially accounted for, +.I fsck_ffs +checks that +the number of free blocks +plus the number of blocks claimed by the inodes +equals the total number of blocks in the file system. +.PP +If anything is wrong with the block allocation maps, +.I fsck_ffs +will rebuild them, +based on the list it has computed of allocated blocks. +.PP +The summary information associated with the super-block +counts the total number of free blocks within the file system. +.I Fsck_ffs +compares this count to the +number of free blocks it found within the file system. +If the two counts do not agree, then +.I fsck_ffs +replaces the incorrect count in the summary information +by the actual free-block count. +.PP +The summary information +counts the total number of free inodes within the file system. +.I Fsck_ffs +compares this count to the number +of free inodes it found within the file system. +If the two counts do not agree, then +.I fsck_ffs +replaces the incorrect count in the +summary information by the actual free-inode count. +.NH 2 +Checking the inode state +.PP +An individual inode is not as likely to be corrupted as +the allocation information. +However, because of the great number of active inodes, +a few of the inodes are usually corrupted. +.PP +The list of inodes in the file system +is checked sequentially starting with inode 2 +(inode 0 marks unused inodes; +inode 1 is saved for future generations) +and progressing through the last inode in the file system. +The state of each inode is checked for +inconsistencies involving format and type, +link count, +duplicate blocks, +bad blocks, +and inode size. +.PP +Each inode contains a mode word. +This mode word describes the type and state of the inode. +Inodes must be one of six types: +regular inode, directory inode, symbolic link inode, +special block inode, special character inode, or socket inode. +Inodes may be found in one of three allocation states: +unallocated, allocated, and neither unallocated nor allocated. +This last state suggests an incorrectly formated inode. +An inode can get in this state if +bad data is written into the inode list. +The only possible corrective action is for +.I fsck_ffs +is to clear the inode. +.NH 2 +Inode links +.PP +Each inode counts the +total number of directory entries +linked to the inode. +.I Fsck_ffs +verifies the link count of each inode +by starting at the root of the file system, +and descending through the directory structure. +The actual link count for each inode +is calculated during the descent. +.PP +If the stored link count is non-zero and the actual +link count is zero, +then no directory entry appears for the inode. +If this happens, +.I fsck_ffs +will place the disconnected file in the +.I lost+found +directory. +If the stored and actual link counts are non-zero and unequal, +a directory entry may have been added or removed without the inode being +updated. +If this happens, +.I fsck_ffs +replaces the incorrect stored link count by the actual link count. +.PP +Each inode contains a list, +or pointers to +lists (indirect blocks), +of all the blocks claimed by the inode. +Since indirect blocks are owned by an inode, +inconsistencies in indirect blocks directly +affect the inode that owns it. +.PP +.I Fsck_ffs +compares each block number claimed by an inode +against a list of already allocated blocks. +If another inode already claims a block number, +then the block number is added to a list of +.I "duplicate blocks" . +Otherwise, the list of allocated blocks +is updated to include the block number. +.PP +If there are any duplicate blocks, +.I fsck_ffs +will perform a partial second +pass over the inode list +to find the inode of the duplicated block. +The second pass is needed, +since without examining the files associated with +these inodes for correct content, +not enough information is available +to determine which inode is corrupted and should be cleared. +If this condition does arise +(only hardware failure will cause it), +then the inode with the earliest +modify time is usually incorrect, +and should be cleared. +If this happens, +.I fsck_ffs +prompts the operator to clear both inodes. +The operator must decide which one should be kept +and which one should be cleared. +.PP +.I Fsck_ffs +checks the range of each block number claimed by an inode. +If the block number is +lower than the first data block in the file system, +or greater than the last data block, +then the block number is a +.I "bad block number" . +Many bad blocks in an inode are usually caused by +an indirect block that was not written to the file system, +a condition which can only occur if there has been a hardware failure. +If an inode contains bad block numbers, +.I fsck_ffs +prompts the operator to clear it. +.NH 2 +Inode data size +.PP +Each inode contains a count of the number of data blocks +that it contains. +The number of actual data blocks +is the sum of the allocated data blocks +and the indirect blocks. +.I Fsck_ffs +computes the actual number of data blocks +and compares that block count against +the actual number of blocks the inode claims. +If an inode contains an incorrect count +.I fsck_ffs +prompts the operator to fix it. +.PP +Each inode contains a thirty-two bit size field. +The size is the number of data bytes +in the file associated with the inode. +The consistency of the byte size field is roughly checked +by computing from the size field the maximum number of blocks +that should be associated with the inode, +and comparing that expected block count against +the actual number of blocks the inode claims. +.NH 2 +Checking the data associated with an inode +.PP +An inode can directly or indirectly +reference three kinds of data blocks. +All referenced blocks must be the same kind. +The three types of data blocks are: +plain data blocks, symbolic link data blocks, and directory data blocks. +Plain data blocks +contain the information stored in a file; +symbolic link data blocks +contain the path name stored in a link. +Directory data blocks contain directory entries. +.I Fsck_ffs +can only check the validity of directory data blocks. +.PP +Each directory data block is checked for +several types of inconsistencies. +These inconsistencies include +directory inode numbers pointing to unallocated inodes, +directory inode numbers that are greater than +the number of inodes in the file system, +incorrect directory inode numbers for ``\fB.\fP'' and ``\fB..\fP'', +and directories that are not attached to the file system. +If the inode number in a directory data block +references an unallocated inode, +then +.I fsck_ffs +will remove that directory entry. +Again, +this condition can only arise when there has been a hardware failure. +.PP +.I Fsck_ffs +also checks for directories with unallocated blocks (holes). +Such directories should never be created. +When found, +.I fsck_ffs +will prompt the user to adjust the length of the offending directory +which is done by shortening the size of the directory to the end of the +last allocated block preceding the hole. +Unfortunately, this means that another Phase 1 run has to be done. +.I Fsck_ffs +will remind the user to rerun fsck_ffs after repairing a +directory containing an unallocated block. +.PP +If a directory entry inode number references +outside the inode list, then +.I fsck_ffs +will remove that directory entry. +This condition occurs if bad data is written into a directory data block. +.PP +The directory inode number entry for ``\fB.\fP'' +must be the first entry in the directory data block. +The inode number for ``\fB.\fP'' +must reference itself; +e.g., it must equal the inode number +for the directory data block. +The directory inode number entry +for ``\fB..\fP'' must be +the second entry in the directory data block. +Its value must equal the inode number for the +parent of the directory entry +(or the inode number of the directory +data block if the directory is the +root directory). +If the directory inode numbers are +incorrect, +.I fsck_ffs +will replace them with the correct values. +If there are multiple hard links to a directory, +the first one encountered is considered the real parent +to which ``\fB..\fP'' should point; +\fIfsck_ffs\fP recommends deletion for the subsequently discovered names. +.NH 2 +File system connectivity +.PP +.I Fsck_ffs +checks the general connectivity of the file system. +If directories are not linked into the file system, then +.I fsck_ffs +links the directory back into the file system in the +.I lost+found +directory. +This condition only occurs when there has been a hardware failure. +.ds RH "References" +.SH +\s+2Acknowledgements\s0 +.PP +I thank Bill Joy, Sam Leffler, Robert Elz and Dennis Ritchie +for their suggestions and help in implementing the new file system. +Thanks also to Robert Henry for his editorial input to +get this document together. +Finally we thank our sponsors, +the National Science Foundation under grant MCS80-05144, +and the Defense Advance Research Projects Agency (DoD) under +Arpa Order No. 4031 monitored by Naval Electronic System Command under +Contract No. N00039-82-C-0235. (Kirk McKusick, July 1983) +.PP +I would like to thank Larry A. Wehr for advice that lead +to the first version of +.I fsck_ffs +and Rick B. Brandt for adapting +.I fsck_ffs +to +UNIX/TS. (T. Kowalski, July 1979) +.sp 2 +.SH +\s+2References\s0 +.LP +.IP [Dolotta78] 20 +Dolotta, T. A., and Olsson, S. B. eds., +.I "UNIX User's Manual, Edition 1.1\^" , +January 1978. +.IP [Joy83] 20 +Joy, W., Cooper, E., Fabry, R., Leffler, S., McKusick, M., and Mosher, D. +4.2BSD System Manual, +.I "University of California at Berkeley" , +.I "Computer Systems Research Group Technical Report" +#4, 1982. +.IP [McKusick84] 20 +McKusick, M., Joy, W., Leffler, S., and Fabry, R. +A Fast File System for UNIX, +\fIACM Transactions on Computer Systems 2\fP, 3. +pp. 181-197, August 1984. +.IP [Ritchie78] 20 +Ritchie, D. M., and Thompson, K., +The UNIX Time-Sharing System, +.I "The Bell System Technical Journal" +.B 57 , +6 (July-August 1978, Part 2), pp. 1905-29. +.IP [Thompson78] 20 +Thompson, K., +UNIX Implementation, +.I "The Bell System Technical Journal\^" +.B 57 , +6 (July-August 1978, Part 2), pp. 1931-46. +.ds RH Appendix A \- Fsck_ffs Error Conditions +.bp diff --git a/share/doc/smm/03.fsck/4.t b/share/doc/smm/03.fsck/4.t new file mode 100644 index 0000000..353fab3 --- /dev/null +++ b/share/doc/smm/03.fsck/4.t @@ -0,0 +1,1421 @@ +.\" Copyright (c) 1982, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" @(#)4.t 8.1 (Berkeley) 6/5/93 +.\" +.ds RH Appendix A \- Fsck_ffs Error Conditions +.NH +Appendix A \- Fsck_ffs Error Conditions +.NH 2 +Conventions +.PP +.I Fsck_ffs +is +a multi-pass file system check program. +Each file system pass invokes a different Phase of the +.I fsck_ffs +program. +After the initial setup, +.I fsck_ffs +performs successive Phases over each file system, +checking blocks and sizes, +path-names, +connectivity, +reference counts, +and the map of free blocks, +(possibly rebuilding it), +and performs some cleanup. +.LP +Normally +.I fsck_ffs +is run non-interactively to +.I preen +the file systems after an unclean halt. +While preen'ing a file system, +it will only fix corruptions that are expected +to occur from an unclean halt. +These actions are a proper subset of the actions that +.I fsck_ffs +will take when it is running interactively. +Throughout this appendix many errors have several options +that the operator can take. +When an inconsistency is detected, +.I fsck_ffs +reports the error condition to the operator. +If a response is required, +.I fsck_ffs +prints a prompt message and +waits for a response. +When preen'ing most errors are fatal. +For those that are expected, +the response taken is noted. +This appendix explains the meaning of each error condition, +the possible responses, and the related error conditions. +.LP +The error conditions are organized by the +.I Phase +of the +.I fsck_ffs +program in which they can occur. +The error conditions that may occur +in more than one Phase +will be discussed in initialization. +.NH 2 +Initialization +.PP +Before a file system check can be performed, certain +tables have to be set up and certain files opened. +This section concerns itself with the opening of files and +the initialization of tables. +This section lists error conditions resulting from +command line options, +memory requests, +opening of files, +status of files, +file system size checks, +and creation of the scratch file. +All the initialization errors are fatal +when the file system is being preen'ed. +.sp +.LP +.B "\fIC\fP option?" +.br +\fIC\fP is not a legal option to +.I fsck_ffs ; +legal options are \-b, \-c, \-y, \-n, and \-p. +.I Fsck_ffs +terminates on this error condition. +See the +.I fsck_ffs (8) +manual entry for further detail. +.sp +.LP +.B "cannot alloc NNN bytes for blockmap" +.br +.B "cannot alloc NNN bytes for freemap" +.br +.B "cannot alloc NNN bytes for statemap" +.br +.B "cannot alloc NNN bytes for lncntp" +.br +.I Fsck_ffs 's +request for memory for its virtual +memory tables failed. +This should never happen. +.I Fsck_ffs +terminates on this error condition. +See a guru. +.sp +.LP +.B "Can't open checklist file: \fIF\fP" +.br +The file system checklist file +\fIF\fP (usually +.I /etc/fstab ) +can not be opened for reading. +.I Fsck_ffs +terminates on this error condition. +Check access modes of \fIF\fP. +.sp +.LP +.B "Can't stat root" +.br +.I Fsck_ffs 's +request for statistics about the root directory ``/'' failed. +This should never happen. +.I Fsck_ffs +terminates on this error condition. +See a guru. +.sp +.LP +.B "Can't stat \fIF\fP" +.br +.B "Can't make sense out of name \fIF\fP" +.br +.I Fsck_ffs 's +request for statistics about the file system \fIF\fP failed. +When running manually, +it ignores this file system +and continues checking the next file system given. +Check access modes of \fIF\fP. +.sp +.LP +.B "Can't open \fIF\fP" +.br +.I Fsck_ffs 's +request attempt to open the file system \fIF\fP failed. +When running manually, it ignores this file system +and continues checking the next file system given. +Check access modes of \fIF\fP. +.sp +.LP +.B "\fIF\fP: (NO WRITE)" +.br +Either the \-n flag was specified or +.I fsck_ffs 's +attempt to open the file system \fIF\fP for writing failed. +When running manually, +all the diagnostics are printed out, +but no modifications are attempted to fix them. +.sp +.LP +.B "file is not a block or character device; OK" +.br +You have given +.I fsck_ffs +a regular file name by mistake. +Check the type of the file specified. +.LP +Possible responses to the OK prompt are: +.IP YES +ignore this error condition. +.IP NO +ignore this file system and continues checking +the next file system given. +.sp +.LP +.B "UNDEFINED OPTIMIZATION IN SUPERBLOCK (SET TO DEFAULT)" +.br +The superblock optimization parameter is neither OPT_TIME +nor OPT_SPACE. +.LP +Possible responses to the SET TO DEFAULT prompt are: +.IP YES +The superblock is set to request optimization to minimize +running time of the system. +(If optimization to minimize disk space utilization is +desired, it can be set using \fItunefs\fP(8).) +.IP NO +ignore this error condition. +.sp +.LP +.B "IMPOSSIBLE MINFREE=\fID\fP IN SUPERBLOCK (SET TO DEFAULT)" +.br +The superblock minimum space percentage is greater than 99% +or less then 0%. +.LP +Possible responses to the SET TO DEFAULT prompt are: +.IP YES +The minfree parameter is set to 10%. +(If some other percentage is desired, +it can be set using \fItunefs\fP(8).) +.IP NO +ignore this error condition. +.sp +.LP +.B "IMPOSSIBLE INTERLEAVE=\fID\fP IN SUPERBLOCK (SET TO DEFAULT)" +.br +The file system interleave is less than or equal to zero. +.LP +Possible responses to the SET TO DEFAULT prompt are: +.IP YES +The interleave parameter is set to 1. +.IP NO +ignore this error condition. +.sp +.LP +.B "IMPOSSIBLE NPSECT=\fID\fP IN SUPERBLOCK (SET TO DEFAULT)" +.br +The number of physical sectors per track is less than the number +of usable sectors per track. +.LP +Possible responses to the SET TO DEFAULT prompt are: +.IP YES +The npsect parameter is set to the number of usable sectors per track. +.IP NO +ignore this error condition. +.sp +.LP +One of the following messages will appear: +.br +.B "MAGIC NUMBER WRONG" +.br +.B "NCG OUT OF RANGE" +.br +.B "CPG OUT OF RANGE" +.br +.B "NCYL DOES NOT JIVE WITH NCG*CPG" +.br +.B "SIZE PREPOSTEROUSLY LARGE" +.br +.B "TRASHED VALUES IN SUPER BLOCK" +.br +and will be followed by the message: +.br +.B "\fIF\fP: BAD SUPER BLOCK: \fIB\fP" +.br +.B "USE -b OPTION TO FSCK_FFS TO SPECIFY LOCATION OF AN ALTERNATE" +.br +.B "SUPER-BLOCK TO SUPPLY NEEDED INFORMATION; SEE fsck_ffs(8)." +.br +The super block has been corrupted. +An alternative super block must be selected from among those +listed by +.I newfs +(8) when the file system was created. +For file systems with a blocksize less than 32K, +specifying \-b 32 is a good first choice. +.sp +.LP +.B "INTERNAL INCONSISTENCY: \fIM\fP" +.br +.I Fsck_ffs 's +has had an internal panic, whose message is specified as \fIM\fP. +This should never happen. +See a guru. +.sp +.LP +.B "CAN NOT SEEK: BLK \fIB\fP (CONTINUE)" +.br +.I Fsck_ffs 's +request for moving to a specified block number \fIB\fP in +the file system failed. +This should never happen. +See a guru. +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +attempt to continue to run the file system check. +Often, +however the problem will persist. +This error condition will not allow a complete check of the file system. +A second run of +.I fsck_ffs +should be made to re-check this file system. +If the block was part of the virtual memory buffer +cache, +.I fsck_ffs +will terminate with the message ``Fatal I/O error''. +.IP NO +terminate the program. +.sp +.LP +.B "CAN NOT READ: BLK \fIB\fP (CONTINUE)" +.br +.I Fsck_ffs 's +request for reading a specified block number \fIB\fP in +the file system failed. +This should never happen. +See a guru. +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +attempt to continue to run the file system check. +It will retry the read and print out the message: +.br +.B "THE FOLLOWING SECTORS COULD NOT BE READ: \fIN\fP" +.br +where \fIN\fP indicates the sectors that could not be read. +If +.I fsck_ffs +ever tries to write back one of the blocks on which the read failed +it will print the message: +.br +.B "WRITING ZERO'ED BLOCK \fIN\fP TO DISK" +.br +where \fIN\fP indicates the sector that was written with zero's. +If the disk is experiencing hardware problems, the problem will persist. +This error condition will not allow a complete check of the file system. +A second run of +.I fsck_ffs +should be made to re-check this file system. +If the block was part of the virtual memory buffer +cache, +.I fsck_ffs +will terminate with the message ``Fatal I/O error''. +.IP NO +terminate the program. +.sp +.LP +.B "CAN NOT WRITE: BLK \fIB\fP (CONTINUE)" +.br +.I Fsck_ffs 's +request for writing a specified block number \fIB\fP +in the file system failed. +The disk is write-protected; +check the write protect lock on the drive. +If that is not the problem, see a guru. +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +attempt to continue to run the file system check. +The write operation will be retried with the failed blocks +indicated by the message: +.br +.B "THE FOLLOWING SECTORS COULD NOT BE WRITTEN: \fIN\fP" +.br +where \fIN\fP indicates the sectors that could not be written. +If the disk is experiencing hardware problems, the problem will persist. +This error condition will not allow a complete check of the file system. +A second run of +.I fsck_ffs +should be made to re-check this file system. +If the block was part of the virtual memory buffer +cache, +.I fsck_ffs +will terminate with the message ``Fatal I/O error''. +.IP NO +terminate the program. +.sp +.LP +.B "bad inode number DDD to ginode" +.br +An internal error has attempted to read non-existent inode \fIDDD\fP. +This error causes +.I fsck_ffs +to exit. +See a guru. +.NH 2 +Phase 1 \- Check Blocks and Sizes +.PP +This phase concerns itself with +the inode list. +This section lists error conditions resulting from +checking inode types, +setting up the zero-link-count table, +examining inode block numbers for bad or duplicate blocks, +checking inode size, +and checking inode format. +All errors in this phase except +.B "INCORRECT BLOCK COUNT" +and +.B "PARTIALLY TRUNCATED INODE" +are fatal if the file system is being preen'ed. +.sp +.LP +.B "UNKNOWN FILE TYPE I=\fII\fP (CLEAR)" +.br +The mode word of the inode \fII\fP indicates that the inode is not a +special block inode, special character inode, socket inode, regular inode, +symbolic link, or directory inode. +.LP +Possible responses to the CLEAR prompt are: +.IP YES +de-allocate inode \fII\fP by zeroing its contents. +This will always invoke the UNALLOCATED error condition in Phase 2 +for each directory entry pointing to this inode. +.IP NO +ignore this error condition. +.sp +.LP +.B "PARTIALLY TRUNCATED INODE I=\fII\fP (SALVAGE)" +.br +.I Fsck_ffs +has found inode \fII\fP whose size is shorter than the number of +blocks allocated to it. +This condition should only occur if the system crashes while in the +midst of truncating a file. +When preen'ing the file system, +.I fsck_ffs +completes the truncation to the specified size. +.LP +Possible responses to SALVAGE are: +.IP YES +complete the truncation to the size specified in the inode. +.IP NO +ignore this error condition. +.sp +.LP +.B "LINK COUNT TABLE OVERFLOW (CONTINUE)" +.br +An internal table for +.I fsck_ffs +containing allocated inodes with a link count of +zero cannot allocate more memory. +Increase the virtual memory for +.I fsck_ffs . +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +continue with the program. +This error condition will not allow a complete check of the file system. +A second run of +.I fsck_ffs +should be made to re-check this file system. +If another allocated inode with a zero link count is found, +this error condition is repeated. +.IP NO +terminate the program. +.sp +.LP +.B "\fIB\fP BAD I=\fII\fP" +.br +Inode \fII\fP contains block number \fIB\fP with a number +lower than the number of the first data block in the file system or +greater than the number of the last block +in the file system. +This error condition may invoke the +.B "EXCESSIVE BAD BLKS" +error condition in Phase 1 (see next paragraph) if +inode \fII\fP has too many block numbers outside the file system range. +This error condition will always invoke the +.B "BAD/DUP" +error condition in Phase 2 and Phase 4. +.sp +.LP +.B "EXCESSIVE BAD BLKS I=\fII\fP (CONTINUE)" +.br +There is more than a tolerable number (usually 10) of blocks with a number +lower than the number of the first data block in the file system or greater than +the number of last block in the file system associated with inode \fII\fP. +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +ignore the rest of the blocks in this inode +and continue checking with the next inode in the file system. +This error condition will not allow a complete check of the file system. +A second run of +.I fsck_ffs +should be made to re-check this file system. +.IP NO +terminate the program. +.sp +.LP +.B "BAD STATE DDD TO BLKERR" +.br +An internal error has scrambled +.I fsck_ffs 's +state map to have the impossible value \fIDDD\fP. +.I Fsck_ffs +exits immediately. +See a guru. +.sp +.LP +.B "\fIB\fP DUP I=\fII\fP" +.br +Inode \fII\fP contains block number \fIB\fP that is already claimed by +another inode. +This error condition may invoke the +.B "EXCESSIVE DUP BLKS" +error condition in Phase 1 if +inode \fII\fP has too many block numbers claimed by other inodes. +This error condition will always invoke Phase 1b and the +.B "BAD/DUP" +error condition in Phase 2 and Phase 4. +.sp +.LP +.B "EXCESSIVE DUP BLKS I=\fII\fP (CONTINUE)" +.br +There is more than a tolerable number (usually 10) of blocks claimed by other +inodes. +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +ignore the rest of the blocks in this inode +and continue checking with the next inode in the file system. +This error condition will not allow a complete check of the file system. +A second run of +.I fsck_ffs +should be made to re-check this file system. +.IP NO +terminate the program. +.sp +.LP +.B "DUP TABLE OVERFLOW (CONTINUE)" +.br +An internal table in +.I fsck_ffs +containing duplicate block numbers cannot allocate any more space. +Increase the amount of virtual memory available to +.I fsck_ffs . +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +continue with the program. +This error condition will not allow a complete check of the file system. +A second run of +.I fsck_ffs +should be made to re-check this file system. +If another duplicate block is found, this error condition will repeat. +.IP NO +terminate the program. +.sp +.LP +.B "PARTIALLY ALLOCATED INODE I=\fII\fP (CLEAR)" +.br +Inode \fII\fP is neither allocated nor unallocated. +.LP +Possible responses to the CLEAR prompt are: +.IP YES +de-allocate inode \fII\fP by zeroing its contents. +.IP NO +ignore this error condition. +.sp +.LP +.B "INCORRECT BLOCK COUNT I=\fII\fP (\fIX\fP should be \fIY\fP) (CORRECT)" +.br +The block count for inode \fII\fP is \fIX\fP blocks, +but should be \fIY\fP blocks. +When preen'ing the count is corrected. +.LP +Possible responses to the CORRECT prompt are: +.IP YES +replace the block count of inode \fII\fP with \fIY\fP. +.IP NO +ignore this error condition. +.NH 2 +Phase 1B: Rescan for More Dups +.PP +When a duplicate block is found in the file system, the file system is +rescanned to find the inode that previously claimed that block. +This section lists the error condition when the duplicate block is found. +.sp +.LP +.B "\fIB\fP DUP I=\fII\fP" +.br +Inode \fII\fP contains block number \fIB\fP that +is already claimed by another inode. +This error condition will always invoke the +.B "BAD/DUP" +error condition in Phase 2. +You can determine which inodes have overlapping blocks by examining +this error condition and the DUP error condition in Phase 1. +.NH 2 +Phase 2 \- Check Pathnames +.PP +This phase concerns itself with removing directory entries +pointing to +error conditioned inodes +from Phase 1 and Phase 1b. +This section lists error conditions resulting from +root inode mode and status, +directory inode pointers in range, +and directory entries pointing to bad inodes, +and directory integrity checks. +All errors in this phase are fatal if the file system is being preen'ed, +except for directories not being a multiple of the blocks size +and extraneous hard links. +.sp +.LP +.B "ROOT INODE UNALLOCATED (ALLOCATE)" +.br +The root inode (usually inode number 2) has no allocate mode bits. +This should never happen. +.LP +Possible responses to the ALLOCATE prompt are: +.IP YES +allocate inode 2 as the root inode. +The files and directories usually found in the root will be recovered +in Phase 3 and put into +.I lost+found . +If the attempt to allocate the root fails, +.I fsck_ffs +will exit with the message: +.br +.B "CANNOT ALLOCATE ROOT INODE" . +.IP NO +.I fsck_ffs +will exit. +.sp +.LP +.B "ROOT INODE NOT DIRECTORY (REALLOCATE)" +.br +The root inode (usually inode number 2) +is not directory inode type. +.LP +Possible responses to the REALLOCATE prompt are: +.IP YES +clear the existing contents of the root inode +and reallocate it. +The files and directories usually found in the root will be recovered +in Phase 3 and put into +.I lost+found . +If the attempt to allocate the root fails, +.I fsck_ffs +will exit with the message: +.br +.B "CANNOT ALLOCATE ROOT INODE" . +.IP NO +.I fsck_ffs +will then prompt with +.B "FIX" +.LP +Possible responses to the FIX prompt are: +.IP YES +replace the root inode's type to be a directory. +If the root inode's data blocks are not directory blocks, +many error conditions will be produced. +.IP NO +terminate the program. +.sp +.LP +.B "DUPS/BAD IN ROOT INODE (REALLOCATE)" +.br +Phase 1 or Phase 1b have found duplicate blocks +or bad blocks in the root inode (usually inode number 2) for the file system. +.LP +Possible responses to the REALLOCATE prompt are: +.IP YES +clear the existing contents of the root inode +and reallocate it. +The files and directories usually found in the root will be recovered +in Phase 3 and put into +.I lost+found . +If the attempt to allocate the root fails, +.I fsck_ffs +will exit with the message: +.br +.B "CANNOT ALLOCATE ROOT INODE" . +.IP NO +.I fsck_ffs +will then prompt with +.B "CONTINUE" . +.LP +Possible responses to the CONTINUE prompt are: +.IP YES +ignore the +.B "DUPS/BAD" +error condition in the root inode and +attempt to continue to run the file system check. +If the root inode is not correct, +then this may result in many other error conditions. +.IP NO +terminate the program. +.sp +.LP +.B "NAME TOO LONG \fIF\fP" +.br +An excessively long path name has been found. +This usually indicates loops in the file system name space. +This can occur if the super user has made circular links to directories. +The offending links must be removed (by a guru). +.sp +.LP +.B "I OUT OF RANGE I=\fII\fP NAME=\fIF\fP (REMOVE)" +.br +A directory entry \fIF\fP has an inode number \fII\fP that is greater than +the end of the inode list. +.LP +Possible responses to the REMOVE prompt are: +.IP YES +the directory entry \fIF\fP is removed. +.IP NO +ignore this error condition. +.sp +.LP +.B "UNALLOCATED I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP \fItype\fP=\fIF\fP (REMOVE)" +.br +A directory or file entry \fIF\fP points to an unallocated inode \fII\fP. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, modify time \fIT\fP, +and name \fIF\fP are printed. +.LP +Possible responses to the REMOVE prompt are: +.IP YES +the directory entry \fIF\fP is removed. +.IP NO +ignore this error condition. +.sp +.LP +.B "DUP/BAD I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP \fItype\fP=\fIF\fP (REMOVE)" +.br +Phase 1 or Phase 1b have found duplicate blocks or bad blocks +associated with directory or file entry \fIF\fP, inode \fII\fP. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, modify time \fIT\fP, +and directory name \fIF\fP are printed. +.LP +Possible responses to the REMOVE prompt are: +.IP YES +the directory entry \fIF\fP is removed. +.IP NO +ignore this error condition. +.sp +.LP +.B "ZERO LENGTH DIRECTORY I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (REMOVE)" +.br +A directory entry \fIF\fP has a size \fIS\fP that is zero. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, modify time \fIT\fP, +and directory name \fIF\fP are printed. +.LP +Possible responses to the REMOVE prompt are: +.IP YES +the directory entry \fIF\fP is removed; +this will always invoke the BAD/DUP error condition in Phase 4. +.IP NO +ignore this error condition. +.sp +.LP +.B "DIRECTORY TOO SHORT I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (FIX)" +.br +A directory \fIF\fP has been found whose size \fIS\fP +is less than the minimum size directory. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, modify time \fIT\fP, +and directory name \fIF\fP are printed. +.LP +Possible responses to the FIX prompt are: +.IP YES +increase the size of the directory to the minimum directory size. +.IP NO +ignore this directory. +.sp +.LP +.B "DIRECTORY \fIF\fP LENGTH \fIS\fP NOT MULTIPLE OF \fIB\fP (ADJUST) +.br +A directory \fIF\fP has been found with size \fIS\fP that is not +a multiple of the directory blocksize \fIB\fP. +.LP +Possible responses to the ADJUST prompt are: +.IP YES +the length is rounded up to the appropriate block size. +This error can occur on 4.2BSD file systems. +Thus when preen'ing the file system only a warning is printed +and the directory is adjusted. +.IP NO +ignore the error condition. +.sp +.LP +.B "DIRECTORY CORRUPTED I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (SALVAGE)" +.br +A directory with an inconsistent internal state has been found. +.LP +Possible responses to the FIX prompt are: +.IP YES +throw away all entries up to the next directory boundary (usually 512-byte) +boundary. +This drastic action can throw away up to 42 entries, +and should be taken only after other recovery efforts have failed. +.IP NO +skip up to the next directory boundary and resume reading, +but do not modify the directory. +.sp +.LP +.B "BAD INODE NUMBER FOR `.' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (FIX)" +.br +A directory \fII\fP has been found whose inode number for `.' does +does not equal \fII\fP. +.LP +Possible responses to the FIX prompt are: +.IP YES +change the inode number for `.' to be equal to \fII\fP. +.IP NO +leave the inode number for `.' unchanged. +.sp +.LP +.B "MISSING `.' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (FIX)" +.br +A directory \fII\fP has been found whose first entry is unallocated. +.LP +Possible responses to the FIX prompt are: +.IP YES +build an entry for `.' with inode number equal to \fII\fP. +.IP NO +leave the directory unchanged. +.sp +.LP +.B "MISSING `.' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP" +.br +.B "CANNOT FIX, FIRST ENTRY IN DIRECTORY CONTAINS \fIF\fP" +.br +A directory \fII\fP has been found whose first entry is \fIF\fP. +.I Fsck_ffs +cannot resolve this problem. +The file system should be mounted and the offending entry \fIF\fP +moved elsewhere. +The file system should then be unmounted and +.I fsck_ffs +should be run again. +.sp +.LP +.B "MISSING `.' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP" +.br +.B "CANNOT FIX, INSUFFICIENT SPACE TO ADD `.'" +.br +A directory \fII\fP has been found whose first entry is not `.'. +.I Fsck_ffs +cannot resolve this problem as it should never happen. +See a guru. +.sp +.LP +.B "EXTRA `.' ENTRY I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (FIX)" +.br +A directory \fII\fP has been found that has more than one entry for `.'. +.LP +Possible responses to the FIX prompt are: +.IP YES +remove the extra entry for `.'. +.IP NO +leave the directory unchanged. +.sp +.LP +.B "BAD INODE NUMBER FOR `..' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (FIX)" +.br +A directory \fII\fP has been found whose inode number for `..' does +does not equal the parent of \fII\fP. +.LP +Possible responses to the FIX prompt are: +.IP YES +change the inode number for `..' to be equal to the parent of \fII\fP +(``\fB..\fP'' in the root inode points to itself). +.IP NO +leave the inode number for `..' unchanged. +.sp +.LP +.B "MISSING `..' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (FIX)" +.br +A directory \fII\fP has been found whose second entry is unallocated. +.LP +Possible responses to the FIX prompt are: +.IP YES +build an entry for `..' with inode number equal to the parent of \fII\fP +(``\fB..\fP'' in the root inode points to itself). +.IP NO +leave the directory unchanged. +.sp +.LP +.B "MISSING `..' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP" +.br +.B "CANNOT FIX, SECOND ENTRY IN DIRECTORY CONTAINS \fIF\fP" +.br +A directory \fII\fP has been found whose second entry is \fIF\fP. +.I Fsck_ffs +cannot resolve this problem. +The file system should be mounted and the offending entry \fIF\fP +moved elsewhere. +The file system should then be unmounted and +.I fsck_ffs +should be run again. +.sp +.LP +.B "MISSING `..' I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP" +.br +.B "CANNOT FIX, INSUFFICIENT SPACE TO ADD `..'" +.br +A directory \fII\fP has been found whose second entry is not `..'. +.I Fsck_ffs +cannot resolve this problem. +The file system should be mounted and the second entry in the directory +moved elsewhere. +The file system should then be unmounted and +.I fsck_ffs +should be run again. +.sp +.LP +.B "EXTRA `..' ENTRY I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP DIR=\fIF\fP (FIX)" +.br +A directory \fII\fP has been found that has more than one entry for `..'. +.LP +Possible responses to the FIX prompt are: +.IP YES +remove the extra entry for `..'. +.IP NO +leave the directory unchanged. +.sp +.LP +.B "\fIN\fP IS AN EXTRANEOUS HARD LINK TO A DIRECTORY \fID\fP (REMOVE) +.br +.I Fsck_ffs +has found a hard link, \fIN\fP, to a directory, \fID\fP. +When preen'ing the extraneous links are ignored. +.LP +Possible responses to the REMOVE prompt are: +.IP YES +delete the extraneous entry, \fIN\fP. +.IP NO +ignore the error condition. +.sp +.LP +.B "BAD INODE \fIS\fP TO DESCEND" +.br +An internal error has caused an impossible state \fIS\fP to be passed to the +routine that descends the file system directory structure. +.I Fsck_ffs +exits. +See a guru. +.sp +.LP +.B "BAD RETURN STATE \fIS\fP FROM DESCEND" +.br +An internal error has caused an impossible state \fIS\fP to be returned +from the routine that descends the file system directory structure. +.I Fsck_ffs +exits. +See a guru. +.sp +.LP +.B "BAD STATE \fIS\fP FOR ROOT INODE" +.br +An internal error has caused an impossible state \fIS\fP to be assigned +to the root inode. +.I Fsck_ffs +exits. +See a guru. +.NH 2 +Phase 3 \- Check Connectivity +.PP +This phase concerns itself with the directory connectivity seen in +Phase 2. +This section lists error conditions resulting from +unreferenced directories, +and missing or full +.I lost+found +directories. +.sp +.LP +.B "UNREF DIR I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP (RECONNECT)" +.br +The directory inode \fII\fP was not connected to a directory entry +when the file system was traversed. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, and +modify time \fIT\fP of directory inode \fII\fP are printed. +When preen'ing, the directory is reconnected if its size is non-zero, +otherwise it is cleared. +.LP +Possible responses to the RECONNECT prompt are: +.IP YES +reconnect directory inode \fII\fP to the file system in the +directory for lost files (usually \fIlost+found\fP). +This may invoke the +.I lost+found +error condition in Phase 3 +if there are problems connecting directory inode \fII\fP to \fIlost+found\fP. +This may also invoke the CONNECTED error condition in Phase 3 if the link +was successful. +.IP NO +ignore this error condition. +This will always invoke the UNREF error condition in Phase 4. +.sp +.LP +.B "NO lost+found DIRECTORY (CREATE)" +.br +There is no +.I lost+found +directory in the root directory of the file system; +When preen'ing +.I fsck_ffs +tries to create a \fIlost+found\fP directory. +.LP +Possible responses to the CREATE prompt are: +.IP YES +create a \fIlost+found\fP directory in the root of the file system. +This may raise the message: +.br +.B "NO SPACE LEFT IN / (EXPAND)" +.br +See below for the possible responses. +Inability to create a \fIlost+found\fP directory generates the message: +.br +.B "SORRY. CANNOT CREATE lost+found DIRECTORY" +.br +and aborts the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.IP NO +abort the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.sp +.LP +.B "lost+found IS NOT A DIRECTORY (REALLOCATE)" +.br +The entry for +.I lost+found +is not a directory. +.LP +Possible responses to the REALLOCATE prompt are: +.IP YES +allocate a directory inode, and change \fIlost+found\fP to reference it. +The previous inode reference by the \fIlost+found\fP name is not cleared. +Thus it will either be reclaimed as an UNREF'ed inode or have its +link count ADJUST'ed later in this Phase. +Inability to create a \fIlost+found\fP directory generates the message: +.br +.B "SORRY. CANNOT CREATE lost+found DIRECTORY" +.br +and aborts the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.IP NO +abort the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.sp +.LP +.B "NO SPACE LEFT IN /lost+found (EXPAND)" +.br +There is no space to add another entry to the +.I lost+found +directory in the root directory +of the file system. +When preen'ing the +.I lost+found +directory is expanded. +.LP +Possible responses to the EXPAND prompt are: +.IP YES +the +.I lost+found +directory is expanded to make room for the new entry. +If the attempted expansion fails +.I fsck_ffs +prints the message: +.br +.B "SORRY. NO SPACE IN lost+found DIRECTORY" +.br +and aborts the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +Clean out unnecessary entries in +.I lost+found . +This error is fatal if the file system is being preen'ed. +.IP NO +abort the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.sp +.LP +.B "DIR I=\fII1\fP CONNECTED. PARENT WAS I=\fII2\fP" +.br +This is an advisory message indicating a directory inode \fII1\fP was +successfully connected to the +.I lost+found +directory. +The parent inode \fII2\fP of the directory inode \fII1\fP is +replaced by the inode number of the +.I lost+found +directory. +.sp +.LP +.B "DIRECTORY \fIF\fP LENGTH \fIS\fP NOT MULTIPLE OF \fIB\fP (ADJUST) +.br +A directory \fIF\fP has been found with size \fIS\fP that is not +a multiple of the directory blocksize \fIB\fP +(this can reoccur in Phase 3 if it is not adjusted in Phase 2). +.LP +Possible responses to the ADJUST prompt are: +.IP YES +the length is rounded up to the appropriate block size. +This error can occur on 4.2BSD file systems. +Thus when preen'ing the file system only a warning is printed +and the directory is adjusted. +.IP NO +ignore the error condition. +.sp +.LP +.B "BAD INODE \fIS\fP TO DESCEND" +.br +An internal error has caused an impossible state \fIS\fP to be passed to the +routine that descends the file system directory structure. +.I Fsck_ffs +exits. +See a guru. +.NH 2 +Phase 4 \- Check Reference Counts +.PP +This phase concerns itself with the link count information +seen in Phase 2 and Phase 3. +This section lists error conditions resulting from +unreferenced files, +missing or full +.I lost+found +directory, +incorrect link counts for files, directories, symbolic links, or special files, +unreferenced files, symbolic links, and directories, +and bad or duplicate blocks in files, symbolic links, and directories. +All errors in this phase are correctable if the file system is being preen'ed +except running out of space in the \fIlost+found\fP directory. +.sp +.LP +.B "UNREF FILE I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP (RECONNECT)" +.br +Inode \fII\fP was not connected to a directory entry +when the file system was traversed. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, and +modify time \fIT\fP of inode \fII\fP are printed. +When preen'ing the file is cleared if either its size or its +link count is zero, +otherwise it is reconnected. +.LP +Possible responses to the RECONNECT prompt are: +.IP YES +reconnect inode \fII\fP to the file system in the directory for +lost files (usually \fIlost+found\fP). +This may invoke the +.I lost+found +error condition in Phase 4 +if there are problems connecting inode \fII\fP to +.I lost+found . +.IP NO +ignore this error condition. +This will always invoke the CLEAR error condition in Phase 4. +.sp +.LP +.B "(CLEAR)" +.br +The inode mentioned in the immediately previous error condition can not be +reconnected. +This cannot occur if the file system is being preen'ed, +since lack of space to reconnect files is a fatal error. +.LP +Possible responses to the CLEAR prompt are: +.IP YES +de-allocate the inode mentioned in the immediately previous error condition by zeroing its contents. +.IP NO +ignore this error condition. +.sp +.LP +.B "NO lost+found DIRECTORY (CREATE)" +.br +There is no +.I lost+found +directory in the root directory of the file system; +When preen'ing +.I fsck_ffs +tries to create a \fIlost+found\fP directory. +.LP +Possible responses to the CREATE prompt are: +.IP YES +create a \fIlost+found\fP directory in the root of the file system. +This may raise the message: +.br +.B "NO SPACE LEFT IN / (EXPAND)" +.br +See below for the possible responses. +Inability to create a \fIlost+found\fP directory generates the message: +.br +.B "SORRY. CANNOT CREATE lost+found DIRECTORY" +.br +and aborts the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.IP NO +abort the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.sp +.LP +.B "lost+found IS NOT A DIRECTORY (REALLOCATE)" +.br +The entry for +.I lost+found +is not a directory. +.LP +Possible responses to the REALLOCATE prompt are: +.IP YES +allocate a directory inode, and change \fIlost+found\fP to reference it. +The previous inode reference by the \fIlost+found\fP name is not cleared. +Thus it will either be reclaimed as an UNREF'ed inode or have its +link count ADJUST'ed later in this Phase. +Inability to create a \fIlost+found\fP directory generates the message: +.br +.B "SORRY. CANNOT CREATE lost+found DIRECTORY" +.br +and aborts the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.IP NO +abort the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.sp +.LP +.B "NO SPACE LEFT IN /lost+found (EXPAND)" +.br +There is no space to add another entry to the +.I lost+found +directory in the root directory +of the file system. +When preen'ing the +.I lost+found +directory is expanded. +.LP +Possible responses to the EXPAND prompt are: +.IP YES +the +.I lost+found +directory is expanded to make room for the new entry. +If the attempted expansion fails +.I fsck_ffs +prints the message: +.br +.B "SORRY. NO SPACE IN lost+found DIRECTORY" +.br +and aborts the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +Clean out unnecessary entries in +.I lost+found . +This error is fatal if the file system is being preen'ed. +.IP NO +abort the attempt to linkup the lost inode. +This will always invoke the UNREF error condition in Phase 4. +.sp +.LP +.B "LINK COUNT \fItype\fP I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP COUNT=\fIX\fP SHOULD BE \fIY\fP (ADJUST)" +.br +The link count for inode \fII\fP, +is \fIX\fP but should be \fIY\fP. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, and modify time \fIT\fP +are printed. +When preen'ing the link count is adjusted unless the number of references +is increasing, a condition that should never occur unless precipitated +by a hardware failure. +When the number of references is increasing under preen mode, +.I fsck_ffs +exits with the message: +.br +.B "LINK COUNT INCREASING" +.LP +Possible responses to the ADJUST prompt are: +.IP YES +replace the link count of file inode \fII\fP with \fIY\fP. +.IP NO +ignore this error condition. +.sp +.LP +.B "UNREF \fItype\fP I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP (CLEAR)" +.br +Inode \fII\fP, was not connected to a directory entry when the +file system was traversed. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, +and modify time \fIT\fP of inode \fII\fP +are printed. +When preen'ing, +this is a file that was not connected because its size or link count was zero, +hence it is cleared. +.LP +Possible responses to the CLEAR prompt are: +.IP YES +de-allocate inode \fII\fP by zeroing its contents. +.IP NO +ignore this error condition. +.sp +.LP +.B "BAD/DUP \fItype\fP I=\fII\fP OWNER=\fIO\fP MODE=\fIM\fP SIZE=\fIS\fP MTIME=\fIT\fP (CLEAR)" +.br +Phase 1 or Phase 1b have found duplicate blocks +or bad blocks associated with +inode \fII\fP. +The owner \fIO\fP, mode \fIM\fP, size \fIS\fP, +and modify time \fIT\fP of inode \fII\fP +are printed. +This error cannot arise when the file system is being preen'ed, +as it would have caused a fatal error earlier. +.LP +Possible responses to the CLEAR prompt are: +.IP YES +de-allocate inode \fII\fP by zeroing its contents. +.IP NO +ignore this error condition. +.NH 2 +Phase 5 - Check Cyl groups +.PP +This phase concerns itself with the free-block and used-inode maps. +This section lists error conditions resulting from +allocated blocks in the free-block maps, +free blocks missing from free-block maps, +and the total free-block count incorrect. +It also lists error conditions resulting from +free inodes in the used-inode maps, +allocated inodes missing from used-inode maps, +and the total used-inode count incorrect. +.sp +.LP +.B "CG \fIC\fP: BAD MAGIC NUMBER" +.br +The magic number of cylinder group \fIC\fP is wrong. +This usually indicates that the cylinder group maps have been destroyed. +When running manually the cylinder group is marked as needing +to be reconstructed. +This error is fatal if the file system is being preen'ed. +.sp +.LP +.B "BLK(S) MISSING IN BIT MAPS (SALVAGE)" +.br +A cylinder group block map is missing some free blocks. +During preen'ing the maps are reconstructed. +.LP +Possible responses to the SALVAGE prompt are: +.IP YES +reconstruct the free block map. +.IP NO +ignore this error condition. +.sp +.LP +.B "SUMMARY INFORMATION BAD (SALVAGE)" +.br +The summary information was found to be incorrect. +When preen'ing, +the summary information is recomputed. +.LP +Possible responses to the SALVAGE prompt are: +.IP YES +reconstruct the summary information. +.IP NO +ignore this error condition. +.sp +.LP +.B "FREE BLK COUNT(S) WRONG IN SUPERBLOCK (SALVAGE)" +.br +The superblock free block information was found to be incorrect. +When preen'ing, +the superblock free block information is recomputed. +.LP +Possible responses to the SALVAGE prompt are: +.IP YES +reconstruct the superblock free block information. +.IP NO +ignore this error condition. +.NH 2 +Cleanup +.PP +Once a file system has been checked, a few cleanup functions are performed. +This section lists advisory messages about +the file system +and modify status of the file system. +.sp +.LP +.B "\fIV\fP files, \fIW\fP used, \fIX\fP free (\fIY\fP frags, \fIZ\fP blocks)" +.br +This is an advisory message indicating that +the file system checked contained +\fIV\fP files using +\fIW\fP fragment sized blocks leaving +\fIX\fP fragment sized blocks free in the file system. +The numbers in parenthesis breaks the free count down into +\fIY\fP free fragments and +\fIZ\fP free full sized blocks. +.sp +.LP +.B "***** REBOOT UNIX *****" +.br +This is an advisory message indicating that +the root file system has been modified by +.I fsck_ffs. +If UNIX is not rebooted immediately, +the work done by +.I fsck_ffs +may be undone by the in-core copies of tables +UNIX keeps. +When preen'ing, +.I fsck_ffs +will exit with a code of 4. +The standard auto-reboot script distributed with 4.3BSD +interprets an exit code of 4 by issuing a reboot system call. +.sp +.LP +.B "***** FILE SYSTEM WAS MODIFIED *****" +.br +This is an advisory message indicating that +the current file system was modified by +.I fsck_ffs. +If this file system is mounted or is the current root file system, +.I fsck_ffs +should be halted and UNIX rebooted. +If UNIX is not rebooted immediately, +the work done by +.I fsck_ffs +may be undone by the in-core copies of tables +UNIX keeps. diff --git a/share/doc/smm/03.fsck/Makefile b/share/doc/smm/03.fsck/Makefile index fbdc009..88d1ec3 100644 --- a/share/doc/smm/03.fsck/Makefile +++ b/share/doc/smm/03.fsck/Makefile @@ -4,6 +4,5 @@ VOLUME= smm/03.fsck SRCS= 0.t 1.t 2.t 3.t 4.t MACROS= -ms -SRCDIR= ${.CURDIR}/../../../../sbin/fsck_ffs/SMM.doc .include <bsd.doc.mk> diff --git a/share/doc/smm/07.lpr/0.t b/share/doc/smm/07.lpr/0.t new file mode 100644 index 0000000..65ecd4e --- /dev/null +++ b/share/doc/smm/07.lpr/0.t @@ -0,0 +1,68 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)0.t 8.1 (Berkeley) 6/8/93 +.\" +.if n .ND +.TL +4.3BSD Line Printer Spooler Manual +.EH 'SMM:7-%''4.3BSD Line Printer Spooler Manual' +.OH '4.3BSD Line Printer Spooler Manual''SMM:7-%' +.AU +Ralph Campbell +.AI +Computer Systems Research Group +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, CA 94720 +.AB +.FS +* UNIX is a trademark of Bell Laboratories. +.FE +This document describes the structure and installation procedure +for the line printer spooling system +developed for the 4.3BSD version +of the UNIX* operating system. +.de D? +.ie \\n(.$>1 Revised \\$1 \\$2 \\$3 +.el DRAFT of \n(mo/\n(dy/\n(yr +.. +.sp 2 +.LP +.D? June 8, 1993 +.AE +.de IR +\fI\\$1\fP\\$2 +.. +.de DT +.TA 8 16 24 32 40 48 56 64 72 80 +.. diff --git a/share/doc/smm/07.lpr/1.t b/share/doc/smm/07.lpr/1.t new file mode 100644 index 0000000..1d34e9e --- /dev/null +++ b/share/doc/smm/07.lpr/1.t @@ -0,0 +1,77 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)1.t 8.1 (Berkeley) 6/8/93 +.\" +.NH 1 +Overview +.PP +The line printer system supports: +.IP \(bu 3 +multiple printers, +.IP \(bu 3 +multiple spooling queues, +.IP \(bu 3 +both local and remote +printers, and +.IP \(bu 3 +printers attached via serial lines that require +line initialization such as the baud rate. +.LP +Raster output devices +such as a Varian or Versatec, and laser printers such as an Imagen, +are also supported by the line printer system. +.PP +The line printer system consists mainly of the +following files and commands: +.DS +.TS +l l. +/etc/printcap printer configuration and capability data base +/usr/lib/lpd line printer daemon, does all the real work +/usr/ucb/lpr program to enter a job in a printer queue +/usr/ucb/lpq spooling queue examination program +/usr/ucb/lprm program to delete jobs from a queue +/etc/lpc program to administer printers and spooling queues +/dev/printer socket on which lpd listens +.TE +.DE +The file /etc/printcap is a master data base describing line +printers directly attached to a machine and, also, printers +accessible across a network. The manual page entry +.IR printcap (5) +provides the authoritative definition of +the format of this data base, as well as +specifying default values for important items +such as the directory in which spooling is performed. +This document introduces some of the +information that may be placed +.IR printcap . diff --git a/share/doc/smm/07.lpr/2.t b/share/doc/smm/07.lpr/2.t new file mode 100644 index 0000000..9da2ae2 --- /dev/null +++ b/share/doc/smm/07.lpr/2.t @@ -0,0 +1,141 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)2.t 8.1 (Berkeley) 6/8/93 +.\" +.NH 1 +Commands +.NH 2 +lpd \- line printer daemon +.PP +The program +.IR lpd (8), +usually invoked at boot time from the /etc/rc file, acts as +a master server for coordinating and controlling +the spooling queues configured in the printcap file. +When +.I lpd +is started it makes a single pass through the +.I printcap +database restarting any printers that have jobs. +In normal operation +.I lpd +listens for service requests on multiple sockets, +one in the UNIX domain (named ``/dev/printer'') for +local requests, and one in the Internet domain +(under the ``printer'' service specification) +for requests for printer access from off machine; +see \fIsocket\fP\|(2) and \fIservices\fP\|(5) +for more information on sockets and service +specifications, respectively. +.I Lpd +spawns a copy of itself to process the request; the master daemon +continues to listen for new requests. +.PP +Clients communicate with +.I lpd +using a simple transaction oriented protocol. +Authentication of remote clients is done based +on the ``privilege port'' scheme employed by +\fIrshd\fP\|(8C) and \fIrcmd\fP\|(3X). +The following table shows the requests +understood by +.IR lpd . +In each request the first byte indicates the +``meaning'' of the request, followed by the name +of the printer to which it should be applied. Additional +qualifiers may follow, depending on the request. +.DS +.TS +l l. +Request Interpretation +_ +^Aprinter\en check the queue for jobs and print any found +^Bprinter\en receive and queue a job from another machine +^Cprinter [users ...] [jobs ...]\en return short list of current queue state +^Dprinter [users ...] [jobs ...]\en return long list of current queue state +^Eprinter person [users ...] [jobs ...]\en remove jobs from a queue +.TE +.DE +.PP +The \fIlpr\fP\|(1) command +is used by users to enter a print job in a local queue and to notify +the local +.I lpd +that there are new jobs in the spooling area. +.I Lpd +either schedules the job to be printed locally, or if +printing remotely, attempts to forward +the job to the appropriate machine. +If the printer cannot be opened or the destination +machine is unreachable, the job will remain queued until it is +possible to complete the work. +.NH 2 +lpq \- show line printer queue +.PP +The \fIlpq\fP\|(1) +program works recursively backwards displaying the queue of the machine with +the printer and then the queue(s) of the machine(s) that lead to it. +.I Lpq +has two forms of output: in the default, short, format it +gives a single line of output per queued job; in the long +format it shows the list of files, and their sizes, that +comprise a job. +.NH 2 +lprm \- remove jobs from a queue +.PP +The \fIlprm\fP\|(1) command deletes jobs from a spooling +queue. If necessary, \fIlprm\fP will first kill off a +running daemon that is servicing the queue and restart +it after the required files are removed. When removing +jobs destined for a remote printer, \fIlprm\fP acts +similarly to \fIlpq\fP except it first checks locally +for jobs to remove and then +tries to remove files in queues off-machine. +.NH 2 +lpc \- line printer control program +.PP +The +.IR lpc (8) +program is used by the system administrator to control the +operation of the line printer system. +For each line printer configured in /etc/printcap, +.I lpc +may be used to: +.IP \(bu +disable or enable a printer, +.IP \(bu +disable or enable a printer's spooling queue, +.IP \(bu +rearrange the order of jobs in a spooling queue, +.IP \(bu +find the status of printers, and their associated +spooling queues and printer daemons. diff --git a/share/doc/smm/07.lpr/3.t b/share/doc/smm/07.lpr/3.t new file mode 100644 index 0000000..8c950a9 --- /dev/null +++ b/share/doc/smm/07.lpr/3.t @@ -0,0 +1,73 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)3.t 8.1 (Berkeley) 6/8/93 +.\" +.NH 1 +Access control +.PP +The printer system maintains protected spooling areas so that +users cannot circumvent printer accounting or +remove files other than their own. +The strategy used to maintain protected +spooling areas is as follows: +.IP \(bu 3 +The spooling area is writable only by a \fIdaemon\fP user +and \fIdaemon\fP group. +.IP \(bu 3 +The \fIlpr\fP program runs set-user-id to \fIroot\fP and +set-group-id to group \fIdaemon\fP. The \fIroot\fP access permits +reading any file required. Accessibility is verified +with an \fIaccess\fP\|(2) call. The group ID +is used in setting up proper ownership of files +in the spooling area for \fIlprm\fP. +.IP \(bu 3 +Control files in a spooling area are made with \fIdaemon\fP +ownership and group ownership \fIdaemon\fP. Their mode is 0660. +This insures control files are not modified by a user +and that no user can remove files except through \fIlprm\fP. +.IP \(bu 3 +The spooling programs, +\fIlpd\fP, \fIlpq\fP, and \fIlprm\fP run set-user-id to \fIroot\fP +and set-group-id to group \fIdaemon\fP to access spool files and printers. +.IP \(bu 3 +The printer server, \fIlpd\fP, +uses the same verification procedures as \fIrshd\fP\|(8C) +in authenticating remote clients. The host on which a client +resides must be present in the file /etc/hosts.equiv or /etc/hosts.lpd and +the request message must come from a reserved port number. +.PP +In practice, none of \fIlpd\fP, \fIlpq\fP, or +\fIlprm\fP would have to run as user \fIroot\fP if remote +spooling were not supported. In previous incarnations of +the printer system \fIlpd\fP ran set-user-id to \fIdaemon\fP, +set-group-id to group \fIspooling\fP, and \fIlpq\fP and \fIlprm\fP ran +set-group-id to group \fIspooling\fP. diff --git a/share/doc/smm/07.lpr/4.t b/share/doc/smm/07.lpr/4.t new file mode 100644 index 0000000..8800bc0 --- /dev/null +++ b/share/doc/smm/07.lpr/4.t @@ -0,0 +1,206 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)4.t 8.1 (Berkeley) 6/8/93 +.\" +.NH 1 +Setting up +.PP +The 4.3BSD release comes with the necessary programs +installed and with the default line printer queue +created. If the system must be modified, the +makefile in the directory /usr/src/usr.lib/lpr +should be used in recompiling and reinstalling +the necessary programs. +.PP +The real work in setting up is to create the +.I printcap +file and any printer filters for printers not supported +in the distribution system. +.NH 2 +Creating a printcap file +.PP +The +.I printcap +database contains one or more entries per printer. +A printer should have a separate spooling directory; +otherwise, jobs will be printed on +different printers depending on which printer daemon starts first. +This section describes how to create entries for printers that do not +conform to the default printer description (an LP-11 style interface to a +standard, band printer). +.NH 3 +Printers on serial lines +.PP +When a printer is connected via a serial communication line +it must have the proper baud rate and terminal modes set. +The following example is for a DecWriter III printer connected +locally via a 1200 baud serial line. +.DS +.DT +lp|LA-180 DecWriter III:\e + :lp=/dev/lp:br#1200:fs#06320:\e + :tr=\ef:of=/usr/lib/lpf:lf=/usr/adm/lpd-errs: +.DE +The +.B lp +entry specifies the file name to open for output. Here it could +be left out since ``/dev/lp'' is the default. +The +.B br +entry sets the baud rate for the tty line and the +.B fs +entry sets CRMOD, no parity, and XTABS (see \fItty\fP\|(4)). +The +.B tr +entry indicates that a form-feed should be printed when the queue +empties so the paper can be torn off without turning the printer off-line and +pressing form feed. +The +.B of +entry specifies the filter program +.I lpf +should be used for printing the files; +more will be said about filters later. +The last entry causes errors +to be written to the file ``/usr/adm/lpd-errs'' +instead of the console. Most errors from \fIlpd\fP are logged using +\fIsyslogd\fP\|(8) and will not be logged in the specified file. The +filters should use \fIsyslogd\fP to report errors; only those that +write to standard error output will end up with errors in the \fBlf\fP file. +(Occasionally errors sent to standard error output have not appeared +in the log file; the use of \fIsyslogd\fP is highly recommended.) +.NH 3 +Remote printers +.PP +Printers that reside on remote hosts should have an empty +.B lp +entry. +For example, the following printcap entry would send output to the printer +named ``lp'' on the machine ``ucbvax''. +.DS +.DT +lp|default line printer:\e + :lp=:rm=ucbvax:rp=lp:sd=/usr/spool/vaxlpd: +.DE +The +.B rm +entry is the name of the remote machine to connect to; this name must +be a known host name for a machine on the network. +The +.B rp +capability indicates +the name of the printer on the remote machine is ``lp''; +here it could be left out since this is the default value. +The +.B sd +entry specifies ``/usr/spool/vaxlpd'' +as the spooling directory instead of the +default value of ``/usr/spool/lpd''. +.NH 2 +Output filters +.PP +Filters are used to handle device dependencies and to +do accounting functions. The output filtering of +.B of +is used when accounting is +not being done or when all text data must be passed through a filter. +It is not intended to do accounting since it is started only once, +all text files are filtered through it, and no provision is made for passing +owners' login name, identifying the beginning and ending of jobs, etc. +The other filters (if specified) are started for each file +printed and do accounting if there is an +.B af +entry. +If entries for both +.B of +and other filters are specified, +the output filter is used only to print the banner page; +it is then stopped to allow other filters access to the printer. +An example of a printer that requires output filters +is the Benson-Varian. +.DS +.DT +va|varian|Benson-Varian:\e + :lp=/dev/va0:sd=/usr/spool/vad:of=/usr/lib/vpf:\e + :tf=/usr/lib/rvcat:mx#2000:pl#58:px=2112:py=1700:tr=\ef: +.DE +The +.B tf +entry specifies ``/usr/lib/rvcat'' as the filter to be +used in printing \fItroff\fP\|(1) output. +This filter is needed to set the device into print mode +for text, and plot mode for printing +.I troff +files and raster images (see \fIva\fP\|(4V)). +Note that the page length is set to 58 lines by the +.B pl +entry for 8.5" by 11" fan-fold paper. +To enable accounting, the varian entry would be +augmented with an +.B af +filter as shown below. +.DS +.DT +va|varian|Benson-Varian:\e + :lp=/dev/va0:sd=/usr/spool/vad:of=/usr/lib/vpf:\e + :if=/usr/lib/vpf:tf=/usr/lib/rvcat:af=/usr/adm/vaacct:\e + :mx#2000:pl#58:px=2112:py=1700:tr=\ef: +.DE +.NH 2 +Access Control +.PP +Local access to printer queues is controlled with the +.B rg +printcap entry. +.DS + :rg=lprgroup: +.DE +Users must be in the group +.I lprgroup +to submit jobs to the specified printer. +The default is to allow all users access. +Note that once the files are in the local queue, they can be printed +locally or forwarded to another host depending on the configuration. +.PP +Remote access is controlled by listing the hosts in either the file +/etc/hosts.equiv or /etc/hosts.lpd, one host per line. Note that +.IR rsh (1) +and +.IR rlogin (1) +use /etc/hosts.equiv to determine which hosts are equivalent for allowing logins +without passwords. The file /etc/hosts.lpd is only used to control +which hosts have line printer access. +Remote access can be further restricted to only allow remote users with accounts +on the local host to print jobs by using the \fBrs\fP printcap entry. +.DS + :rs: +.DE diff --git a/share/doc/smm/07.lpr/5.t b/share/doc/smm/07.lpr/5.t new file mode 100644 index 0000000..137a342 --- /dev/null +++ b/share/doc/smm/07.lpr/5.t @@ -0,0 +1,116 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)5.t 8.1 (Berkeley) 6/8/93 +.\" +.NH 1 +Output filter specifications +.PP +The filters supplied with 4.3BSD +handle printing and accounting for most common +line printers, the Benson-Varian, the wide (36") and +narrow (11") Versatec printer/plotters. For other devices or accounting +methods, it may be necessary to create a new filter. +.PP +Filters are spawned by \fIlpd\fP +with their standard input the data to be printed, and standard output +the printer. The standard error is attached to the +.B lf +file for logging errors or \fIsyslogd\fP may be used for logging errors. +A filter must return a 0 exit +code if there were no errors, 1 if the job should be reprinted, +and 2 if the job should be thrown away. +When \fIlprm\fP +sends a kill signal to the \fIlpd\fP process controlling +printing, it sends a SIGINT signal +to all filters and descendents of filters. +This signal can be trapped by filters that need +to do cleanup operations such as +deleting temporary files. +.PP +Arguments passed to a filter depend on its type. +The +.B of +filter is called with the following arguments. +.DS +\fIfilter\fP \fB\-w\fPwidth \fB\-l\fPlength +.DE +The \fIwidth\fP and \fIlength\fP values come from the +.B pw +and +.B pl +entries in the printcap database. +The +.B if +filter is passed the following parameters. +.DS +\fIfilter\fP [\|\fB\-c\fP\|] \fB\-w\fPwidth \fB\-l\fPlength \fB\-i\fPindent \fB\-n\fP login \fB\-h\fP host accounting_file +.DE +The +.B \-c +flag is optional, and only supplied when control characters +are to be passed uninterpreted to the printer (when using the +.B \-l +option of +.I lpr +to print the file). +The +.B \-w +and +.B \-l +parameters are the same as for the +.B of +filter. +The +.B \-n +and +.B \-h +parameters specify the login name and host name of the job owner. +The last argument is the name of the accounting file from +.IR printcap . +.PP +All other filters are called with the following arguments: +.DS +\fIfilter\fP \fB\-x\fPwidth \fB\-y\fPlength \fB\-n\fP login \fB\-h\fP host accounting_file +.DE +The +.B \-x +and +.B \-y +options specify the horizontal and vertical page +size in pixels (from the +.B px +and +.B py +entries in the printcap file). +The rest of the arguments are the same as for the +.B if +filter. diff --git a/share/doc/smm/07.lpr/6.t b/share/doc/smm/07.lpr/6.t new file mode 100644 index 0000000..7087790 --- /dev/null +++ b/share/doc/smm/07.lpr/6.t @@ -0,0 +1,94 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)6.t 8.1 (Berkeley) 6/8/93 +.\" +.NH 1 +Line printer Administration +.PP +The +.I lpc +program provides local control over line printer activity. +The major commands and their intended use will be described. +The command format and remaining commands are described in +.IR lpc (8). +.LP +\fBabort\fP and \fBstart\fP +.IP +.I Abort +terminates an active spooling daemon on the local host immediately and +then disables printing (preventing new daemons from being started by +.IR lpr ). +This is normally used to forcibly restart a hung line printer daemon +(i.e., \fIlpq\fP reports that there is a daemon present but nothing is +happening). It does not remove any jobs from the queue +(use the \fIlprm\fP command instead). +.I Start +enables printing and requests \fIlpd\fP to start printing jobs. +.LP +\fBenable\fP and \fBdisable\fP +.IP +\fIEnable\fP and \fIdisable\fP allow spooling in the local queue to be +turned on/off. +This will allow/prevent +.I lpr +from putting new jobs in the spool queue. It is frequently convenient +to turn spooling off while testing new line printer filters since the +.I root +user can still use +.I lpr +to put jobs in the queue but no one else can. +The other main use is to prevent users from putting jobs in the queue +when the printer is expected to be unavailable for a long time. +.LP +\fBrestart\fP +.IP +.I Restart +allows ordinary users to restart printer daemons when +.I lpq +reports that there is no daemon present. +.LP +\fBstop\fP +.IP +.I Stop +halts a spooling daemon after the current job completes; +this also disables printing. This is a clean way to shutdown a +printer to do maintenance, etc. Note that users can still enter jobs in a +spool queue while a printer is +.IR stopped . +.LP +\fBtopq\fP +.IP +.I Topq +places jobs at the top of a printer queue. This can be used +to reorder high priority jobs since +.I lpr +only provides first-come-first-serve ordering of jobs. diff --git a/share/doc/smm/07.lpr/7.t b/share/doc/smm/07.lpr/7.t new file mode 100644 index 0000000..a6f6bea --- /dev/null +++ b/share/doc/smm/07.lpr/7.t @@ -0,0 +1,226 @@ +.\" Copyright (c) 1983, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)7.t 8.1 (Berkeley) 6/8/93 +.\" +.NH 1 +Troubleshooting +.PP +There are several messages that may be generated by the +the line printer system. This section +categorizes the most common and explains the cause +for their generation. Where the message implies a failure, +directions are given to remedy the problem. +.PP +In the examples below, the name +.I printer +is the name of the printer from the +.I printcap +database. +.NH 2 +LPR +.SH +lpr: \fIprinter\fP\|: unknown printer +.IP +The +.I printer +was not found in the +.I printcap +database. Usually this is a typing mistake; however, it may indicate +a missing or incorrect entry in the /etc/printcap file. +.SH +lpr: \fIprinter\fP\|: jobs queued, but cannot start daemon. +.IP +The connection to +.I lpd +on the local machine failed. +This usually means the printer server started at +boot time has died or is hung. Check the local socket +/dev/printer to be sure it still exists (if it does not exist, +there is no +.I lpd +process running). +Usually it is enough to get a super-user to type the following to +restart +.IR lpd . +.DS +% /usr/lib/lpd +.DE +You can also check the state of the master printer daemon with the following. +.DS +% ps l`cat /usr/spool/lpd.lock` +.DE +.IP +Another possibility is that the +.I lpr +program is not set-user-id to \fIroot\fP, set-group-id to group \fIdaemon\fP. +This can be checked with +.DS +% ls \-lg /usr/ucb/lpr +.DE +.SH +lpr: \fIprinter\fP\|: printer queue is disabled +.IP +This means the queue was turned off with +.DS +% lpc disable \fIprinter\fP +.DE +to prevent +.I lpr +from putting files in the queue. This is normally +done by the system manager when a printer is +going to be down for a long time. The +printer can be turned back on by a super-user with +.IR lpc . +.NH 2 +LPQ +.SH +waiting for \fIprinter\fP to become ready (offline ?) +.IP +The printer device could not be opened by the daemon. +This can happen for several reasons, +the most common is that the printer is turned off-line. +This message can also be generated if the printer is out +of paper, the paper is jammed, etc. +The actual reason is dependent on the meaning +of error codes returned by system device driver. +Not all printers supply enough information +to distinguish when a printer is off-line or having +trouble (e.g. a printer connected through a serial line). +Another possible cause of this message is +some other process, such as an output filter, +has an exclusive open on the device. Your only recourse +here is to kill off the offending program(s) and +restart the printer with +.IR lpc . +.SH +\fIprinter\fP is ready and printing +.IP +The +.I lpq +program checks to see if a daemon process exists for +.I printer +and prints the file \fIstatus\fP located in the spooling directory. +If the daemon is hung, a super user can use +.I lpc +to abort the current daemon and start a new one. +.SH +waiting for \fIhost\fP to come up +.IP +This implies there is a daemon trying to connect to the remote +machine named +.I host +to send the files in the local queue. +If the remote machine is up, +.I lpd +on the remote machine is probably dead or +hung and should be restarted as mentioned for +.IR lpr . +.SH +sending to \fIhost\fP +.IP +The files should be in the process of being transferred to the remote +.IR host . +If not, the local daemon should be aborted and started with +.IR lpc . +.SH +Warning: \fIprinter\fP is down +.IP +The printer has been marked as being unavailable with +.IR lpc . +.SH +Warning: no daemon present +.IP +The \fIlpd\fP process overseeing +the spooling queue, as specified in the ``lock'' file +in that directory, does not exist. This normally occurs +only when the daemon has unexpectedly died. +The error log file for the printer and the \fIsyslogd\fP logs +should be checked for a +diagnostic from the deceased process. +To restart an \fIlpd\fP, use +.DS +% lpc restart \fIprinter\fP +.DE +.SH +no space on remote; waiting for queue to drain +.IP +This implies that there is insufficient disk space on the remote. +If the file is large enough, there will never be enough space on +the remote (even after the queue on the remote is empty). The solution here +is to move the spooling queue or make more free space on the remote. +.NH 2 +LPRM +.SH +lprm: \fIprinter\fP\|: cannot restart printer daemon +.IP +This case is the same as when +.I lpr +prints that the daemon cannot be started. +.NH 2 +LPD +.PP +The +.I lpd +program can log many different messages using \fIsyslogd\fP\|(8). +Most of these messages are about files that can not +be opened and usually imply that the +.I printcap +file or the protection modes of the files are +incorrect. Files may also be inaccessible if people +manually manipulate the line printer system (i.e. they +bypass the +.I lpr +program). +.PP +In addition to messages generated by +.IR lpd , +any of the filters that +.I lpd +spawns may log messages using \fIsyslogd\fP or to the error log file +(the file specified in the \fBlf\fP entry in \fIprintcap\fP\|). +.NH 2 +LPC +.PP +.SH +couldn't start printer +.IP +This case is the same as when +.I lpr +reports that the daemon cannot be started. +.SH +cannot examine spool directory +.IP +Error messages beginning with ``cannot ...'' are usually because of +incorrect ownership or protection mode of the lock file, spooling +directory or the +.I lpc +program. diff --git a/share/doc/smm/07.lpr/Makefile b/share/doc/smm/07.lpr/Makefile new file mode 100644 index 0000000..20455e1 --- /dev/null +++ b/share/doc/smm/07.lpr/Makefile @@ -0,0 +1,9 @@ +# From: @(#)Makefile 8.1 (Berkeley) 6/8/93 +# $FreeBSD$ + +VOLUME= smm/07.lpd +SRCS= 0.t 1.t 2.t 3.t 4.t 5.t 6.t 7.t +MACROS= -ms +USE_TBL= + +.include <bsd.doc.mk> diff --git a/share/doc/smm/07.lpr/spell.ok b/share/doc/smm/07.lpr/spell.ok new file mode 100644 index 0000000..bf31319 --- /dev/null +++ b/share/doc/smm/07.lpr/spell.ok @@ -0,0 +1,70 @@ +Aprinter +Bprinter +CRMOD +Cprinter +DecWriter +Dprinter +Eprinter +LPC +LPD +Lpd +Manual''SMM:5 +SIGINT +SMM:5 +Topq +XTABS +adm +af +br +daemon +daemons +dev +f:of +fs +hosts.equiv +hosts.lpd +lf +lg +lib +lp:br +lp:sd +lpc +lpd +lpd.lock +lpf +lpf:lf +lprgroup +makefile +mx +offline +pl +printcap +pw +py +rc +rcmd +rg +rlogin +rp +rs +rsh +rshd +rvcat +rvcat:af +rvcat:mx +sd +src +syslogd +tf +topq +ucb +ucbvax +ucbvax:rp +usr.lib +va0:sd +vaacct +vad:of +varian +vaxlpd +vpf +vpf:tf diff --git a/share/doc/smm/11.timedop/Makefile b/share/doc/smm/11.timedop/Makefile index ad09e78..aec9918 100644 --- a/share/doc/smm/11.timedop/Makefile +++ b/share/doc/smm/11.timedop/Makefile @@ -4,6 +4,5 @@ VOLUME= smm/11.timedop SRCS= timed.ms MACROS= -ms -SRCDIR= ${.CURDIR}/../../../../usr.sbin/timed/SMM.doc/timedop .include <bsd.doc.mk> diff --git a/share/doc/smm/11.timedop/timed.ms b/share/doc/smm/11.timedop/timed.ms new file mode 100644 index 0000000..feea0b5 --- /dev/null +++ b/share/doc/smm/11.timedop/timed.ms @@ -0,0 +1,279 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)timed.ms 8.1 (Berkeley) 6/8/93 +.\" +.TL +Timed Installation and Operation Guide +.AU +Riccardo Gusella, Stefano Zatti, James M. Bloom +.AI +Computer Systems Research Group +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, CA 94720 +.AU +Kirk Smith +.AI +Engineering Computer Network +Department of Electrical Engineering +Purdue University +West Lafayette, IN 47906 +.FS +This work was sponsored by the Defense Advanced Research Projects Agency +(DoD), monitored by the Naval Electronics Systems +Command under contract No. N00039-84-C-0089, and by the CSELT +Corporation of Italy. +The views and conclusions contained in this document are those of the +authors and should not be interpreted as representing official policies, +either expressed or implied, of the Defense Research Projects Agency, +of the US Government, or of CSELT. +.FE +.LP +.EH 'SMM:11-%''Timed Installation and Operation' +.OH 'Timed Installation and Operation''SMM:11-%' +.SH +Introduction +.PP +The clock synchronization service for +the UNIX 4.3BSD operating system is composed of a collection of +time daemons (\fItimed\fP) running on the machines in a local +area network. +The algorithms implemented by the service is based on a master-slave scheme. +The time daemons communicate with each other using the +\fITime Synchronization Protocol\fP (TSP) which +is built on the DARPA UDP protocol and described in detail in [4]. +.PP +A time daemon has a twofold function. +First, it supports the synchronization of the clocks +of the various hosts in a local area network. +Second, it starts (or takes part in) the election that occurs +among slave time daemons when, for any reason, the master disappears. +The synchronization mechanism and the election procedure +employed by the program \fItimed\fP are described +in other documents [1,2,3]. +The next paragraphs are a brief overview of how the time daemon works. +This document is mainly concerned with the administrative and technical +issues of running \fItimed\fP at a particular site. +.PP +A \fImaster time daemon\fP measures the time +differences between the clock of the machine on which it +is running and those of all other machines. +The master computes the \fInetwork time\fP as the average of the +times provided by nonfaulty clocks.\** +.FS +A clock is considered to be faulty when its value +is more than a small specified +interval apart from the majority of the clocks +of the other machines [1,2]. +.FE +It then sends to each \fIslave time daemon\fP the +correction that should be performed on the clock of its machine. +This process is repeated periodically. +Since the correction is expressed as a time difference rather than an +absolute time, transmission delays do not interfere with +the accuracy of the synchronization. +When a machine comes up and joins the network, +it starts a slave time daemon which +will ask the master for the correct time and will reset the machine's clock +before any user activity can begin. +The time daemons are able to maintain a single network time in spite of +the drift of clocks away from each other. +The present implementation keeps processor clocks synchronized +within 20 milliseconds. +.PP +To ensure that the service provided is continuous and reliable, +it is necessary to implement an election algorithm to elect a +new master should the machine running the current master crash, the master +terminate (for example, because of a run-time error), or +the network be partitioned. +Under our algorithm, slaves are able to realize when the master has +stopped functioning and to elect a new master from among themselves. +It is important to note that, since the failure of the master results +only in a gradual divergence of clock values, the election +need not occur immediately. +.PP +The machines that are gateways between distinct local area +networks require particular care. +A time daemon on such machines may act as a \fIsubmaster\fP. +This artifact depends on the current inability of +transmission protocols to broadcast a message on a network +other than the one to which the broadcasting machine is connected. +The submaster appears as a slave on one network, and as a master +on one or more of the other networks to which it is connected. +.PP +A submaster classifies each network as one of three types. +A \fIslave network\fP is a network on which the submaster acts as a slave. +There can only be one slave network. +A \fImaster network\fP is a network on which the submaster acts as a master. +An \fIignored network\fP is any other network which already has a valid master. +The submaster tries periodically to become master on an ignored +network, but gives up immediately if a master already exists. +.SH +Guidelines +.PP +While the synchronization algorithm is quite general, the election +one, requiring a broadcast mechanism, puts constraints on +the kind of network on which time daemons can run. +The time daemon will only work on networks with broadcast capability +augmented with point-to-point links. +Machines that are only connected to point-to-point, +non-broadcast networks may not use the time daemon. +.PP +If we exclude submasters, there will normally be, at most, one master time +daemon in a local area internetwork. +During an election, only one of the slave time daemons +will become the new master. +However, because of the characteristics of its machine, +a slave can be prevented from becoming the master. +Therefore, a subset of machines must be designated as potential +master time daemons. +A master time daemon will require CPU resources +proportional to the number of slaves, in general, more than +a slave time daemon, so it may be advisable to limit master time +daemons to machines with more powerful processors or lighter loads. +Also, machines with inaccurate clocks should not be used as masters. +This is a purely administrative decision: an organization may +well allow all of its machines to run master time daemons. +.PP +At the administrative level, a time daemon on a machine +with multiple network interfaces, may be told to ignore all +but one network or to ignore one network. +This is done with the \fI\-n network\fP and \fI\-i network\fP +options respectively at start-up time. +Typically, the time daemon would be instructed to ignore all but +the networks belonging to the local administrative control. +.PP +There are some limitations to the current +implementation of the time daemon. +It is expected that these limitations will be removed in future releases. +The constant NHOSTS in /usr/src/etc/timed/globals.h limits the +maximum number of machines that may be directly controlled by one +master time daemon. +The current maximum is 29 (NHOSTS \- 1). +The constant must be changed and the program recompiled if a site wishes to +run \fItimed\fP on a larger (inter)network. +.PP +In addition, there is a \fIpathological situation\fP to +be avoided at all costs, that might occur when +time daemons run on multiply-connected local area networks. +In this case, as we have seen, time daemons running on gateway machines +will be submasters and they will act on some of those +networks as master time daemons. +Consider machines A and B that are both gateways between +networks X and Y. +If time daemons were started on both A and B without constraints, it would be +possible for submaster time daemon A to be a slave on network X +and the master on network Y, while submaster time daemon B is a slave on +network Y and the master on network X. +This \fIloop\fP of master time daemons will not function properly +or guarantee a unique time on both networks, and will cause +the submasters to use large amounts of system resources in the form +of network bandwidth and CPU time. +In fact, this kind of \fIloop\fP can also be generated with more +than two master time daemons, +when several local area networks are interconnected. +.SH +Installation +.PP +In order to start the time daemon on a given machine, +the following lines should be +added to the \fIlocal daemons\fP section in the file \fI/etc/rc.local\fP: +.sp 2 +.in 1i +.nf +if [ -f /etc/timed ]; then + /etc/timed \fIflags\fP & echo -n ' timed' >/dev/console +fi +.fi +.in -1i +.sp +.LP +In any case, they must appear after the network +is configured via ifconfig(8). +.PP +Also, the file \fI/etc/services\fP should contain the following +line: +.sp 2 +.ti 1i +timed 525/udp timeserver +.sp +.LP +The \fIflags\fP are: +.IP "-n network" 13 +to consider the named network. +.IP "-i network" +to ignore the named network. +.IP -t +to place tracing information in \fI/usr/adm/timed.log\fP. +.IP -M +to allow this time daemon to become a master. +A time daemon run without this option will be forced in the state of +slave during an election. +.SH +Daily Operation +.PP +\fITimedc(8)\fP is used to control the operation of the time daemon. +It may be used to: +.IP \(bu +measure the differences between machines' clocks, +.IP \(bu +find the location where the master \fItimed\fP is running, +.IP \(bu +cause election timers on several machines to expire at the same time, +.IP \(bu +enable or disable tracing of messages received by \fItimed\fP. +.LP +See the manual page on \fItimed\fP\|(8) and \fItimedc\fP\|(8) +for more detailed information. +.PP +The \fIdate(1)\fP command can be used to set the network date. +In order to set the time on a single machine, the \fI-n\fP flag +can be given to date(1). +.bp +.SH +References +.IP 1. +R. Gusella and S. Zatti, +\fITEMPO: A Network Time Controller for Distributed Berkeley UNIX System\fP, +USENIX Summer Conference Proceedings, Salt Lake City, June 1984. +.IP 2. +R. Gusella and S. Zatti, \fIClock Synchronization in a Local Area Network\fP, +University of California, Berkeley, Technical Report, \fIto appear\fP. +.IP 3. +R. Gusella and S. Zatti, +\fIAn Election Algorithm for a Distributed Clock Synchronization Program\fP, +University of California, Berkeley, CS Technical Report #275, Dec. 1985. +.IP 4. +R. Gusella and S. Zatti, +\fIThe Berkeley UNIX 4.3BSD Time Synchronization Protocol\fP, +UNIX Programmer's Manual, 4.3 Berkeley Software Distribution, Volume 2c. diff --git a/share/doc/smm/12.timed/Makefile b/share/doc/smm/12.timed/Makefile index 1d9ed5c..f844568 100644 --- a/share/doc/smm/12.timed/Makefile +++ b/share/doc/smm/12.timed/Makefile @@ -7,6 +7,5 @@ EXTRA= date loop time unused MACROS= -ms USE_SOELIM= USE_TBL= -SRCDIR= ${.CURDIR}/../../../../usr.sbin/timed/SMM.doc/timed .include <bsd.doc.mk> diff --git a/share/doc/smm/12.timed/date b/share/doc/smm/12.timed/date new file mode 100644 index 0000000..e4e4d58 --- /dev/null +++ b/share/doc/smm/12.timed/date @@ -0,0 +1,53 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)date 8.1 (Berkeley) 6/8/93 +.\" +.ft B +.TS +center; +ce | ce | ce | ce +| c | c | c | s | +| c s s s |. +Byte 1 Byte 2 Byte 3 Byte 4 += +Type Version No. Sequence No. +_ +Seconds of Time to Set +_ +Microseconds of Time to Set +_ +Machine Name +_ +\&. . . +_ +.TE +.ft R diff --git a/share/doc/smm/12.timed/loop b/share/doc/smm/12.timed/loop new file mode 100644 index 0000000..11ccb4d --- /dev/null +++ b/share/doc/smm/12.timed/loop @@ -0,0 +1,54 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)loop 8.1 (Berkeley) 6/8/93 +.\" +.ft B +.TS +center; +ce | ce | ce | ce +| c | c | c | s | +| c | c s s | +| c s s s |. +Byte 1 Byte 2 Byte 3 Byte 4 += +Type Version No. Sequence No. +_ +Hop Count ( unused ) +_ +( unused ) +_ +Machine Name +_ +\&. . . +_ +.TE +.ft R diff --git a/share/doc/smm/12.timed/spell.ok b/share/doc/smm/12.timed/spell.ok new file mode 100644 index 0000000..8ecfe15 --- /dev/null +++ b/share/doc/smm/12.timed/spell.ok @@ -0,0 +1,34 @@ +ACK +ADJTIME +Adjtime +CS +CSELT +Candidature +DATEACK +DoD +Gusella +MASTERACK +MASTERREQ +MASTERUP +MSITE +MSITEREQ +Protocol''SMM:22 +Riccardo +SETDATE +SETDATEREQ +SETTIME +SLAVEUP +SMM:22 +Stefano +TRACEOFF +TRACEON +TSP +Timedc +UDP +USENIX +Zatti +candidature +ce +daemon +daemons +timedc diff --git a/share/doc/smm/12.timed/time b/share/doc/smm/12.timed/time new file mode 100644 index 0000000..619d171 --- /dev/null +++ b/share/doc/smm/12.timed/time @@ -0,0 +1,53 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)time 8.1 (Berkeley) 6/8/93 +.\" +.ft B +.TS +center; +ce | ce | ce | ce +| c | c | c | s | +| c s s s |. +Byte 1 Byte 2 Byte 3 Byte 4 += +Type Version No. Sequence No. +_ +Seconds of Adjustment +_ +Microseconds of Adjustment +_ +Machine Name +_ +\&. . . +_ +.TE +.ft R diff --git a/share/doc/smm/12.timed/timed.ms b/share/doc/smm/12.timed/timed.ms new file mode 100644 index 0000000..412399a --- /dev/null +++ b/share/doc/smm/12.timed/timed.ms @@ -0,0 +1,462 @@ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)timed.ms 8.1 (Berkeley) 6/8/93 +.\" +.TL +The Berkeley +.UX +.br +Time Synchronization Protocol +.AU +Riccardo Gusella, Stefano Zatti, and James M. Bloom +.AI +Computer Systems Research Group +Computer Science Division +Department of Electrical Engineering and Computer Science +University of California, Berkeley +Berkeley, CA 94720 +.FS +This work was sponsored by the Defense Advanced Research Projects Agency +(DoD), monitored by the Naval Electronics Systems +Command under contract No. N00039-84-C-0089, and by the Italian CSELT +Corporation. +The views and conclusions contained in this document are those of the +authors and should not be interpreted as representing official policies, +either expressed or implied, of the Defense Research Projects Agency, +of the US Government, or of CSELT. +.FE +.LP +.OH 'The Berkeley UNIX Time Synchronization Protocol''SMM:12-%' +.EH 'SMM:12-%''The Berkeley UNIX Time Synchronization Protocol' +.SH +Introduction +.PP +The Time Synchronization Protocol (TSP) +has been designed for specific use by the program \fItimed\fP, +a local area network clock synchronizer for +the UNIX 4.3BSD operating +system. +Timed is built on the DARPA UDP protocol [4] and +is based on a master slave scheme. +.PP +TSP serves a dual purpose. +First, it supports messages for the synchronization of the clocks +of the various hosts in a local area network. +Second, it supports messages for the election that occurs +among slave time daemons when, for any reason, the master disappears. +The synchronization mechanism and the election procedure +employed by the program timed are described +in other documents [1,2,3]. +.PP +Briefly, the synchronization software, which works in a +local area network, consists of a collection of \fItime daemons\fP +(one per machine) and is based on a master-slave +structure. +The present implementation keeps processor clocks synchronized +within 20 milliseconds. +A \fImaster time daemon\fP measures the time +difference between the clock of the machine on which it +is running and those of all other machines. The current implementation +uses ICMP \fITime Stamp Requests\fP [5] to measure the clock difference +between machines. +The master computes the \fInetwork time\fP as the average of the +times provided by nonfaulty clocks.\** +.FS +A clock is considered to be faulty when its value +is more than a small specified +interval apart from the majority of the clocks +of the machines on the same network. +See [1,2] for more details. +.FE +It then sends to each \fIslave time daemon\fP the +correction that should be performed on the clock of its machine. +This process is repeated periodically. +Since the correction is expressed as a time difference rather than an +absolute time, transmission delays do not interfere with synchronization. +When a machine comes up and joins the network, +it starts a slave time daemon, which +will ask the master for the correct time and will reset the machine's clock +before any user activity can begin. +The time daemons therefore maintain a single network time in spite of +the drift of clocks away from each other. +.PP +Additionally, a time daemon on gateway machines may run as +a \fIsubmaster\fP. +A submaster time daemon functions as a slave on one network that +already has a master and as master on other networks. +In addition, a submaster is responsible for propagating broadcast +packets from one network to the other. +.PP +To ensure that service provided is continuous and reliable, +it is necessary to implement an election algorithm that will elect a +new master should the machine running the current master crash, the master +terminate (for example, because of a run-time error), or the network be +partitioned. +Under our algorithm, slaves are able to realize when the master has +stopped functioning and to elect a new master from among themselves. +It is important to note that since the failure of the master results +only in a gradual divergence of clock values, the election +need not occur immediately. +.PP +All the communication occurring among time daemons uses the TSP +protocol. +While some messages need not be sent in a reliable way, +most communication in TSP requires reliability not provided by the underlying +protocol. +Reliability is achieved by the use of acknowledgements, sequence numbers, and +retransmission when message losses occur. +When a message that requires acknowledgment is not acknowledged after +multiple attempts, +the time daemon that has sent the message will assume that the +addressee is down. +This document will not describe the details of how reliability is +implemented, but will only point out when +a message type requires a reliable transport mechanism. +.PP +The message format in TSP is the same for all message types; +however, in some instances, one or more fields are not used. +The next section describes the message format. +The following sections describe +in detail the different message types, their use and the contents +of each field. NOTE: The message format is likely to change in +future versions of timed. +.sp 2 +.SH +Message Format +.PP +All fields are based upon 8-bit bytes. Fields should be sent in +network byte order if they are more than one byte long. +The structure of a TSP message is the following: +.IP 1) +A one byte message type. +.IP 2) +A one byte version number, specifying the protocol version which the +message uses. +.IP 3) +A two byte sequence number to be used for recognizing duplicate messages +that occur when messages are retransmitted. +.IP 4) +Eight bytes of packet specific data. This field contains two 4 byte time +values, a one byte hop count, or may be unused depending on the type +of the packet. +.IP 5) +A zero-terminated string of up to 256 \s-2ASCII\s+2 characters with the name of +the machine sending the message. +.PP +The following charts describe the message types, +show their fields, and explain their usages. +For the purpose of the following discussion, a time daemon can +be considered to be in +one of three states: slave, master, or candidate for election to master. +Also, the term \fIbroadcast\fP refers to +the sending of a message to all active time daemons. +.sp 1 +.SH +Adjtime Message +.so time +.LP +Type: TSP_ADJTIME (1) +.sp 1 +.PP +The master sends this message to a slave to communicate +the difference between +the clock of the slave and +the network time the master has just computed. +The slave will accordingly +adjust the time of its machine. +This message requires an acknowledgment. +.sp 1 +.SH +Acknowledgment Message +.so unused +.LP +Type: TSP_ACK (2) +.sp 1 +.PP +Both the master and the slaves use this message for +acknowledgment only. +It is used in several different contexts, for example +in reply to an Adjtime message. +.sp 1 +.SH +Master Request Message +.so unused +.LP +Type: TSP_MASTERREQ (3) +.sp 1 +.PP +A newly-started time daemon broadcasts this message to +locate a master. No other action is implied by this packet. +It requires a Master Acknowledgment. +.sp 1 +.SH +Master Acknowledgement +.so unused +.LP +Type: TSP_MASTERACK (4) +.sp 1 +.PP +The master sends this message to acknowledge the Master Request message +and the Conflict Resolution Message. +.sp 1 +.SH +Set Network Time Message +.so date +.LP +Type: TSP_SETTIME (5) +.sp 1 +.PP +The master sends this message to slave time daemons to set their time. +This packet is sent to newly started time daemons and when the network +date is changed. +It contains the master's time as an approximation of the network time. +It requires an acknowledgment. +The next +synchronization round will eliminate the small time difference +caused by the random delay in the communication channel. +.sp 1 +.SH +Master Active Message +.so unused +.LP +Type: TSP_MASTERUP (6) +.sp 1 +.PP +The master broadcasts this message to +solicit the names of the active slaves. +Slaves will reply with a Slave Active message. +.sp 1 +.SH +Slave Active Message +.so unused +.LP +Type: TSP_SLAVEUP (7) +.sp 1 +.PP +A slave sends this message to the master in answer to a Master Active message. +This message is also sent when a new slave starts up to inform the master that +it wants to be synchronized. +.sp 1 +.SH +Master Candidature Message +.so unused +.LP +Type: TSP_ELECTION (8) +.sp 1 +.PP +A slave eligible to become a master broadcasts this message when its election +timer expires. +The message declares that the slave wishes to become the new master. +.sp 1 +.SH +Candidature Acceptance Message +.so unused +.LP +Type: TSP_ACCEPT (9) +.sp 1 +.PP +A slave sends this message to accept the candidature of the time daemon +that has broadcast an Election message. +The candidate will add the slave's name to the list of machines that it +will control should it become the master. +.sp 1 +.SH +Candidature Rejection Message +.so unused +.LP +Type: TSP_REFUSE (10) +.sp 1 +.PP +After a slave accepts the candidature of a time daemon, it will reply +to any election messages from other slaves +with this message. +This rejects any candidature other than the first received. +.sp 1 +.SH +Multiple Master Notification Message +.so unused +.LP +Type: TSP_CONFLICT (11) +.sp 1 +.PP +When two or more masters reply to a Master Request message, the slave +uses this message to inform one of them that more than one master exists. +.sp 1 +.SH +Conflict Resolution Message +.so unused +.LP +Type: TSP_RESOLVE (12) +.sp 1 +.PP +A master which has been informed of the existence of other masters +broadcasts this message to determine who the other masters are. +.sp 1 +.SH +Quit Message +.so unused +.LP +Type: TSP_QUIT (13) +.sp 1 +.PP +This message is sent by the master in three different contexts: +1) to a candidate that broadcasts a Master Candidature message, +2) to another master when notified of its existence, +3) to another master if a loop is detected. +In all cases, the recipient time daemon will become a slave. +This message requires an acknowledgement. +.sp 1 +.SH +Set Date Message +.so date +.LP +Type: TSP_SETDATE (22) +.sp 1 +.PP +The program \fIdate\fP\|(1) sends this message to the local time daemon +when a super-user wants to set the network date. +If the local time daemon is the master, it will set the date; +if it is a slave, it will communicate the desired date to the master. +.sp 1 +.SH +Set Date Request Message +.so date +.LP +Type: TSP_SETDATEREQ (23) +.sp 1 +.PP +A slave that has received a Set Date message will communicate the +desired date to the master using this message. +.sp 1 +.SH +Set Date Acknowledgment Message +.so unused +.LP +Type: TSP_DATEACK (16) +.sp 1 +.PP +The master sends this message to a slave in acknowledgment of a +Set Date Request Message. +The same message is sent by the local time daemon to the program +\fIdate(1)\fP to confirm that the network date has been set by the +master. +.sp 1 +.SH +Start Tracing Message +.so unused +.LP +Type: TSP_TRACEON (17) +.sp 1 +.PP +The controlling program \fItimedc\fP sends this message to the local +time daemon to start the recording in a system file of +all messages received. +.sp 1 +.SH +Stop Tracing Message +.so unused +.LP +Type: TSP_TRACEOFF (18) +.sp 1 +.PP +\fITimedc\fP sends this message to the local +time daemon to stop the recording of +messages received. +.sp 1 +.SH +Master Site Message +.so unused +.LP +Type: TSP_MSITE (19) +.sp 1 +.PP +\fITimedc\fP sends this message to the local time daemon to find out +where the master is running. +.sp 1 +.SH +Remote Master Site Message +.so unused +.LP +Type: TSP_MSITEREQ (20) +.sp 1 +.PP +A local time daemon broadcasts this message to find the location +of the master. +It then uses the Acknowledgement message to +communicate this location to \fItimedc\fP. +.sp 1 +.SH +Test Message +.so unused +.LP +Type: TSP_TEST (21) +.sp 1 +.PP +For testing purposes, \fItimedc\fP sends this message to a slave +to cause its election timer to expire. NOTE: \fItimed\fP +is not normally compiled to support this. +.sp 1 +.SH +.SH +Loop Detection Message +.so loop +.LP +Type: TSP_LOOP (24) +.sp 1 +.PP +This packet is initiated by all masters occasionally to attempt to detect loops. +All submasters forward this packet onto the networks over which they are master. +If a master receives a packet it sent out initially, +it knows that a loop exists and tries to correct the problem. +.SH +References +.IP 1. +R. Gusella and S. Zatti, +\fITEMPO: A Network Time Controller for Distributed Berkeley UNIX System\fP, +USENIX Summer Conference Proceedings, Salt Lake City, June 1984. +.IP 2. +R. Gusella and S. Zatti, \fIClock Synchronization in a Local Area Network\fP, +University of California, Berkeley, Technical Report, \fIto appear\fP. +.IP 3. +R. Gusella and S. Zatti, +\fIAn Election Algorithm for a Distributed Clock Synchronization Program\fP, +University of California, Berkeley, CS Technical Report #275, Dec. 1985. +.IP 4. +Postel, J., \fIUser Datagram Protocol\fP, RFC 768. +Network Information Center, SRI International, Menlo Park, California, +August 1980. +.IP 5. +Postel, J., \fIInternet Control Message Protocol\fP, RFC 792. +Network Information Center, SRI International, Menlo Park, California, +September 1981. diff --git a/share/doc/smm/12.timed/unused b/share/doc/smm/12.timed/unused new file mode 100644 index 0000000..adadfc3 --- /dev/null +++ b/share/doc/smm/12.timed/unused @@ -0,0 +1,53 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)unused 8.1 (Berkeley) 6/8/93 +.\" +.ft B +.TS +center; +ce | ce | ce | ce +| c | c | c | s | +| c s s s |. +Byte 1 Byte 2 Byte 3 Byte 4 += +Type Version No. Sequence No. +_ +( unused ) +_ +( unused ) +_ +Machine Name +_ +\&. . . +_ +.TE +.ft R |
