diff options
Diffstat (limited to 'share/man/man7')
| -rw-r--r-- | share/man/man7/Makefile | 6 | ||||
| -rw-r--r-- | share/man/man7/hier.7 | 4 | ||||
| -rw-r--r-- | share/man/man7/man.7 | 343 | ||||
| -rw-r--r-- | share/man/man7/mdoc.7 | 10 | ||||
| -rw-r--r-- | share/man/man7/mdoc.samples.7 | 44 | ||||
| -rw-r--r-- | share/man/man7/ports.7 | 24 | ||||
| -rw-r--r-- | share/man/man7/security.7 | 446 |
7 files changed, 36 insertions, 841 deletions
diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index e0e17ef56aa4..1c77b690aa00 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -1,9 +1,9 @@ # @(#)Makefile 8.1 (Berkeley) 6/5/93 -# $Id: Makefile,v 1.8 1998/11/26 00:21:24 jkoshy Exp $ +# $Id: Makefile,v 1.6 1997/03/07 03:28:12 jmg Exp $ -#MISSING: eqnchar.7 ms.7 term.7 +#MISSING: eqnchar.7 man.7 ms.7 term.7 MAN7= ascii.7 clocks.7 environ.7 hier.7 hostname.7 intro.7 mailaddr.7 \ - man.7 mdoc.7 mdoc.samples.7 operator.7 ports.7 security.7 + mdoc.7 mdoc.samples.7 operator.7 ports.7 MLINKS= intro.7 miscellaneous.7 .include <bsd.prog.mk> diff --git a/share/man/man7/hier.7 b/share/man/man7/hier.7 index bade82e7b607..6712a6ae5e2e 100644 --- a/share/man/man7/hier.7 +++ b/share/man/man7/hier.7 @@ -30,7 +30,7 @@ .\" SUCH DAMAGE. .\" .\" @(#)hier.7 8.1 (Berkeley) 6/5/93 -.\" $Id: hier.7,v 1.15 1997/09/13 17:52:36 wosch Exp $ +.\" $Id: hier.7,v 1.14 1997/03/21 20:14:10 mpp Exp $ .\" .Dd June 5, 1993 .Dt HIER 7 @@ -301,7 +301,7 @@ ports collection (optional). .It Li sbin/ system daemons & system utilities (executed by users) .It Li share/ -architecture-independent files +architecture-independent ascii text files .Pp .Bl -tag -width "calendar/" -compact .It Li calendar/ diff --git a/share/man/man7/man.7 b/share/man/man7/man.7 deleted file mode 100644 index bccc9bf0e60c..000000000000 --- a/share/man/man7/man.7 +++ /dev/null @@ -1,343 +0,0 @@ -.\" Copyright (c) 1998. -.\" The FreeBSD Project. 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. -.\" -.\" $Id$ -.\" -.Dd November 30, 1998 -.Os -.Dt MAN 7 -.Sh NAME -.Nm man -.Nd quick reference guide for the -.Nm \-man -macro package -.Sh SYNOPSIS -.Nm groff -.Fl m Ns Ar an -.Ar -.Sh DESCRIPTION -The -.Nm \-man -package is a set of macros used to format -.Ux -manual pages. On -.Bx -systems, the use of -.Nm -is deprecated and the more expressive -.Nm mdoc -package is recommended in its place. -.Sh USAGE -.Ss Conventions -.Nm -macros are named using one or two upper case alphabetic characters. -Following regular -.Xr troff 1 -convention, each macro request starts with a -.Li "." -as the first character of a line. Arguments to macro requests -expecting printable text may consist of zero to six words. Some macros will -process the next input line if no arguments are supplied. For -example, a -.Li ".I" -request on a line by itself will cause the next input line to be set -in italics. -Whitespace characters may be embedded in an argument by enclosing -it in quotes. Type font and size are reset to their defaults before -each paragraph and after processing font size and face changing macros. -.Ss Indentation -The prevailing indent distance is remembered between successive -indented paragraphs and is reset to the default on reaching a -non-indented paragraph. Default units for indents are -.Dq ens . -.Ss Preprocessing -The -.Xr man 1 -program is conventionally used to format and display manual pages. If -the first line of the manual page source starts with the literal string -.Li \&\'\e" -.\" " bring emacs's font-lock mode back in sync ... -then the remaining letters on the line indicate preprocessors that -need to be run prior to formatting with -.Xr troff 1 . -Supported preprocessing directives are: -.Bl -column "Letter" "Preprocessor" -offset indent -.It Em Letter Ta Em Preprocessor -.It e Ta Xr eqn 1 -.It g Ta Xr grap 1 -.It p Ta Xr pic 1 -.It r Ta Xr refer 1 -.It t Ta Xr tbl 1 -.It v Ta Xr vgrind 1 -.El -.Ss Available Strings -The -.Nm -package has the following predefined strings: -.Bl -column "String" "XXXXXXXXXXXXXXXXXXXXXXXXXXXX" -offset indent -.It Em String Ta Em Description -.It "\e*R" Ta "registration symbol" -.It "\e*S" Ta "change to default font size" -.It "\e*(Tm" Ta "trademark symbol" -.It "\e*(lq" Ta "left quote" -.It "\e*(rq" Ta "right quote" -.El -.Pp -.Ss Available Macros -The available macros are presented in alphabetical order. -.Bl -tag -width "XXX XX" -.It ".B" Op Ar words -typeset -.Ar words -using a bold face. Does not cause a line break. If no -arguments are given the next text line is processed. -.It ".BI" Op Ar words -join -.Ar words -alternating bold and italic faces. Does not cause a line break. If -no arguments are given the next text line is processed. -.It ".BR" Op Ar words -join -.Ar words -alternating bold and roman faces. Does not cause a line break. If no -arguments are given the next text line is processed. -.It ".DT" -restore the default tab spacing of 0.5 inches. Does not cause a line -break. -.It ".HP" Op Ar indent -Begin a paragraph with a hanging indent and sets the prevailing indent -to -.Ar indent . -This request forces a line break. If -.Ar indent -is not specified, the value of the prevailing indent is used. -.It ".I" Op Ar words -typeset -.Ar words -using an italic face. Does not cause a line break. If no -arguments are given the next text line is processed. -.It ".IB" Op Ar words -join -.Ar words -alternating italic and bold faces. Does not cause a line break. If no -arguments are given the next text line is processed. -.It ".IP" Op Ar tag Op Ar indent -Begin an indented paragraph with tag -.Ar tag -and prevailing indent set to -.Ar indent . -If -.Ar tag -is not specified it is taken to be the null string -.Qq "" . -If -.Ar indent -is not specified it is taken to be the prevailing indent. -.It ".IR" Op Ar words -join -.Ar words -alternating italic and roman faces. Does not cause a line break. If no -arguments are given the next text line is processed. -.It ".LP" -begin a left-aligned paragraph. The prevailing indent is set to the -default. This request forces a line break. -.It "\&.P" -aliased to \&.LP. -.It ".PD" Op Ar distance -set the vertical distance between paragraphs to -.Ar distance . -If argument -.Ar distance -is not specified a value of 0.4v is used. -.It ".PP" -aliased to \&.LP. -.It ".RE" -end of a relative indent (see \&.RS below). This request forces a -line break and restores the prevailing indent to its previous value. -.It ".RB" Op Ar words -join -.Ar words -alternating roman and bold faces. Does not cause a line break. If no -arguments are given the next text line is processed. -.It ".RI" Op Ar words -join -.Ar words -alternating roman and italic faces. Does not cause a line break. If no -arguments are given the next text line is processed. -.It ".RS" Op Ar indent -start a relative indent, increasing the indentation by -.Ar indent . -If argument -.Ar indent -is not specified, the value of the prevailing indent is used. -.It ".SB" Op Ar words -typeset -.Ar words -using a bold face after reducing the font size by 1 point. -Does not cause a line break. If no arguments are given the next text -line is processed. -.It ".SH" Op Ar words -specifies a section heading. This request forces a line break. -It resets the prevailing indent and margins to their defaults. -.It ".SM" Op Ar words -typeset -.Ar words -after reducing the font size by 1 point. Does not cause a line break. -If no arguments are given the next text line is processed. -.It ".SS" Op Ar words -specifies a section subheading. This request forces a line -break. If no arguments are given the next text line is processed. -It resets the prevailing indent and margins to their defaults. -.It ".TH" Ar name Ar section Ar date Xo -.Op Ar footer Op Ar center -.Xc -Begin reference page -.Ar name -belonging to section -.Ar section . -The third argument -.Ar date , -is the date of the most recent change. If present, -.Ar footer -specifies the left page footer text and -.Ar center -specifies the center header text. This request must the very first -request in the manual page. -.It ".TP" Op Ar indent -begin an indented paragraph with the tag specified in the next text -line. If argument -.Ar indent -is given, it specifies the new value of the prevailing indent. -This request forces a line break. -.El -.Sh PAGE STRUCTURE -Most manual pages follow the general structure outlined below: -.Bl -tag -width ".SH NAME" -.It ".TH" Ar title Op Ar section-number -The very first macro request in a manual page has to be the \&.TH -request which establishes the name and title of the manual page. The -\&.TH request also establishes the number of the manual page section. -.It ".SH NAME" -The name, or list of names, by which the command is called, followed -by a dash and a one-line summary of the action performed. This -section should not contain any -.Nm troff -commands or escapes, or any macro requests. This section is used to -generate the database used by the -.Xr whatis 1 -command. -.It ".SH SYNOPSIS" -A brief summary of the usage of the command or function being -described. -.Bl -tag -width "Commands" -.It Commands -The syntax of the command and its arguments as would be typed on the -command line. Words that have to be typed exactly as printed are to -be presented in bold face. Arguments are indicated by the use of an -italic face. Arguments and command names so indicated should not be -capitalized, even when starting a sentence. -.Pp -Syntactic symbols used should appear in roman face: -.Bl -tag -width "XXX" -.It "[]" -square brackets are used to indicate optional arguments. -.It "|" -vertical bars are used to indicate a one of many exclusive choice. -Only one item from a list separated by vertical bars is to be selected. -.It "..." -an ellipsis following an argument is used to indicate that the -arguments can be repeated. When an ellipsis follows a bracketed set, -the expression within the brackets can be repeated. -.El -.It Functions -Required data declarations or -.Li "#include" -directives are to be shown first, followed by the function declaration. -.El -.It ".SH DESCRIPTION" -An overview of the command or functions external behavior, including -its interactions with files or data, how standard input, standard -output and standard error are handled. Internals and implementation -details are not normally specified. The question answered by this -section is "what does it do?" or "what is it for?". -.Pp -Literal text, filenames and references to items that appear elsewhere -in the reference manuals should be presented using a constant width -face. Arguments should be presented using an italic face. -.It ".SH OPTIONS" -The list of options together with a description of how each affects -the commands operation. -.It ".SH USAGE" -This section is optional and contains a detailed description of the -subcommands and input grammar understood by the command. -.It ".SH RETURN VALUES" -The list of return values a library routine could return to the caller, -with the conditions that cause these values to be returned. -.It ".SH EXIT STATUS" -The list of values returned as the exit status of the command, with -the conditions that cause these values to be returned. -.It ".SH FILES" -The list of files associated with the command or function. -.It ".SH SEE ALSO" -A comma separated list of related manual pages followed by references -to other published documentation. -.It ".SH DIAGNOSTICS" -A list of diagnostic messages with corresponding explanations. -.It ".SH BUGS" -Known defects and limitations, if any. -.El -.Sh FILES -.Bl -tag -width "/usr/share/lib/tmac/tmac.groff_an" -.It "/usr/share/lib/tmac/tmac.an" -Initial file defining the -.Nm -package. -.It "/usr/share/lib/tmac/tmac.groff_an" -.Nm groff -source for macro definitions. -.It "/usr/share/lib/tmac/man.local" -local modifications to the -.Nm -package. -.El -.Sh SEE ALSO -.Xr apropos 1 , -.Xr groff 1 , -.Xr man 1 , -.Xr nroff 1 , -.Xr troff 1 , -.Xr whatis 1 , -.Xr mdoc 7 , -.Xr mdoc.samples 7 -.Sh HISTORY -This manual page was written by -.An "Joseph Koshy" -.Ad Aq jkoshy@freebsd.org . diff --git a/share/man/man7/mdoc.7 b/share/man/man7/mdoc.7 index 48e8dba3924c..2117a633d306 100644 --- a/share/man/man7/mdoc.7 +++ b/share/man/man7/mdoc.7 @@ -30,7 +30,7 @@ .\" SUCH DAMAGE. .\" .\" @(#)mdoc.7 8.2 (Berkeley) 12/30/93 -.\" $Id: mdoc.7,v 1.7 1998/12/01 19:58:58 billf Exp $ +.\" $Id: mdoc.7,v 1.5 1997/03/19 20:31:37 mpp Exp $ .\" .Dd December 30, 1993 .Os @@ -342,11 +342,11 @@ Produces .It Li \&Pf Ta Yes Ta \&No Ta "Prefix string." .It Li \&Po Ta Yes Ta Yes Ta "Parenthesis open quote." .It Li \&Pq Ta Yes Ta Yes Ta "Parentheses quote." -.It Li \&Qc Ta Yes Ta Yes Ta "Straight Double close quote." +.It Li \&Qc Ta Yes Ta Yes Ta "Strait Double close quote." .It Li \&Ql Ta Yes Ta Yes Ta "Quoted literal." -.It Li \&Qo Ta Yes Ta Yes Ta "Straight Double open quote." -.It Li \&Qq Ta Yes Ta Yes Ta "Straight Double quote." -.It Li \&Re Ta \&No Ta \&No Ta "Reference end." +.It Li \&Qo Ta Yes Ta Yes Ta "Strait Double open quote." +.It Li \&Qq Ta Yes Ta Yes Ta "Strait Double quote." +.It Li \&Re Ta \&No Ta \&No Ta "Reference start." .It Li \&Rs Ta \&No Ta \&No Ta "Reference start." .It Li \&Rv Ta \&No Ta \&No Ta "Return values (sections two and three only)." .It Li \&Sc Ta Yes Ta Yes Ta "Single close quote." diff --git a/share/man/man7/mdoc.samples.7 b/share/man/man7/mdoc.samples.7 index 6de33236dbcc..d8a949585d50 100644 --- a/share/man/man7/mdoc.samples.7 +++ b/share/man/man7/mdoc.samples.7 @@ -30,7 +30,7 @@ .\" SUCH DAMAGE. .\" .\" @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93 -.\" $Id: mdoc.samples.7,v 1.16 1997/12/08 07:44:20 charnier Exp $ +.\" $Id: mdoc.samples.7,v 1.15 1997/03/20 16:04:04 mpp Exp $ .\" .\" This tutorial sampler invokes every macro in the package several .\" times and is guaranteed to give a worst case performance @@ -120,7 +120,7 @@ outlined as follows: .It "A manual page template" . .El .It -.Tn "TITLE MACROS" . +.Tn "INTRODUCTION OF TITLE MACROS" . .It .Tn "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS" . .Bl -tag -width flag -compact -offset indent @@ -156,7 +156,6 @@ outlined as follows: .Bl -tag -width flag -compact -offset indent .It "AT&T Macro" . .It "BSD Macro" . -.It "FreeBSD Macro" . .It "UNIX Macro" . .It "Enclosure/Quoting Macros" .Bl -tag -width flag -compact -offset indent @@ -167,13 +166,13 @@ outlined as follows: .It "Single Quotes/Enclosure" . .It "Prefix Macro" . .El +.It "Extended Arguments" . .It "No\-Op or Normal Text Macro" . .It "No Space Macro" . .It "Section Cross References" . .It "References and Citations" . .It "Return Values (sections two and three only)" .It "Trade Names (Acronyms and Type Names)" . -.It "Extended Arguments" . .El .It .Tn "PAGE STRUCTURE DOMAIN" @@ -395,7 +394,7 @@ is created by .Ql \&.Fn fetch char\e *str .It Fn fetch "char *str" can also be created by -.Ql \&.Fn fetch "\\*qchar *str\\*q" +.Ql \&.Fn fetch "\\*q*char *str\\*q" .El .Pp If the @@ -445,7 +444,6 @@ Several example man pages can also be found in .Pa /usr/share/examples/mdoc . .Pp -.Ss A manual page template .Bd -literal -offset indent \&.\e" The following requests are required for all man pages. \&.Dd Month day, year @@ -596,7 +594,7 @@ The date should be written formally: .ne 5 .Dl January 25, 1989 .El -.Sh INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS +.Sh MANUAL DOMAIN .Ss What's in a name... The manual domain macro names are derived from the day to day informal language used to describe commands, subroutines and related @@ -804,7 +802,6 @@ escape them with Typical syntax is shown in the first content macro displayed below, .Ql \&.Ad . -.Sh MANUAL DOMAIN .Ss Address Macro The address macro identifies an address construct of the form addr1[,addr2[,addr3]]. @@ -824,9 +821,9 @@ of the form addr1[,addr2[,addr3]]. .El .Pp It is an error to call -.Ql \&.Ad +.Li \&.Ad without arguments. -.Ql \&.Ad +.Li \&.Ad is callable by other macros and is parsed. .Ss Author Name The @@ -857,7 +854,7 @@ without any arguments. .Ss Argument Macro The -.Ql \&.Ar +.Li \&.Ar argument macro may be used whenever a command line argument is referenced. .Pp @@ -878,12 +875,12 @@ a command line argument is referenced. .El .Pp If -.Ql \&.Ar +.Li \&.Ar is called without arguments .Ql Ar is assumed. The -.Ql \&.Ar +.Li \&.Ar macro is parsed and is callable. .Ss Configuration Declaration (section four only) The @@ -1173,7 +1170,7 @@ anywhere else in the man page without problems, but its main purpose is to present the function type in kernel normal form for the .Sx SYNOPSIS of sections two and three -(it causes a line break allowing the function name to appear +(it causes a page break allowing the function name to appear on the next line). .Pp .Dl Usage: .Ft type ... \*(Pu @@ -1561,7 +1558,7 @@ example of macro usage at its worst. .Ss No\-Op or Normal Text Macro The macro -.Ql \&.No +.Li \&.No is a hack for words in a macro command line which should .Em not @@ -1681,9 +1678,9 @@ macro is parsed and is callable by other macros. .Ss Extended Arguments The -.Ql \&.Xo +.Li \&.Xo and -.Ql \&.Xc +.Li \&.Xc macros allow one to extend an argument list on a macro boundary. Argument lists cannot @@ -1854,8 +1851,7 @@ name macro .Ql \&.Nm is required for sections 1, 5, 6, 7, 8. Section 4 manuals require a -.Ql ".Nm" , -.Ql ".Fd" +.Ql ".Nm" , ".Fd" or a .Ql ".Cd" configuration device usage macro. @@ -1999,14 +1995,12 @@ User specified sections may be added, for example, this section was set with: .Bd -literal -offset 14n -\&.Sh PAGE STRUCTURE DOMAIN +\&.Sh PAGE LAYOUT MACROS .Ed .Ss Paragraphs and Line Spacing. .Bl -tag -width 6n .It \&.Pp -The -.Ql \&.Pp -paragraph command may +The \&.Pp paragraph command may be used to specify a line space where necessary. The macro is not necessary after a .Ql \&.Sh @@ -2147,7 +2141,7 @@ and .Ql \&.Ek (end-keep). The only option that -.Ql \&.Bk +.Ql \&.Bl accepts is .Fl words and is useful for preventing line breaks in the middle of options. @@ -2532,7 +2526,7 @@ Here is the source text which produced the above example: \&.El .Ed .Pp -Here is a hanged list with two items: +Here is a hanged list with just one item: .Bl -hang -offset indent .It Em Hanged labels appear similar to tagged lists when the diff --git a/share/man/man7/ports.7 b/share/man/man7/ports.7 index 9669f881a0a9..d86d3a6713ce 100644 --- a/share/man/man7/ports.7 +++ b/share/man/man7/ports.7 @@ -23,7 +23,7 @@ .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $Id: ports.7,v 1.8 1998/06/29 06:54:34 hoek Exp $ +.\" $Id: ports.7,v 1.7 1998/06/23 04:38:50 hoek Exp $ .\" .Dd January 25, 1998 .Dt PORTS 7 @@ -51,21 +51,14 @@ simply type .Ic make install to install the application. .Pp -It is possible to download and use ports from the FreeBSD repository -that are newer than the installed system; however it is important to -install the appropriate "Upgrade Kit" from http://www.FreeBSD.ORG/ports/ -first! The -.Xr portcheckout 1 -script (also a port, of course!) will help to download new ports. -.Pp For more information about using ports, see .Nm The Ports Collection (file:/usr/share/doc/handbook/ports.html --or-- -http://www.FreeBSD.ORG/handbook/ports.html). +http://www.freebsd.org/handbook/ports.html). For information about creating new ports, see .Nm Porting applications (file:/usr/share/doc/handbook/porting.html --or-- -http://www.FreeBSD.ORG/handbook/porting.html). +http://www.freebsd.org/handbook/porting.html). Both are part of the FreeBSD Handbook. .Pp .Sh TARGETS @@ -73,8 +66,7 @@ Both are part of the FreeBSD Handbook. Some of the targets work recursively through subdirectories. This lets you, for example, install all of the biology ports. The targets that do this are -.Ar build , checksum , clean , configure , -.Ar depends , extract , fetch , install , +.Ar build , checksum , clean , configure , extract , fetch , install , and .Ar package . .Pp @@ -254,6 +246,8 @@ Command to use to fetch files. Normally If set, overwrite any existing package registration on the system. .It Ev MOTIFLIB Location of libXm.{a,so}. +.It Ev PATCH_DEBUG +If defined, display verbose output when applying each patch. .It Ev INTERACTIVE If defined, only operate on a port if it requires interaction. .It Ev BATCH @@ -272,11 +266,7 @@ The big Kahuna. .Xr pkg_add 1 , .Xr pkg_create 1 , .Xr pkg_delete 1 , -.Xr pkg_info 1 , -.Xr portcheckout 1 -(a port), -.Xr pib 1 -(also a port). +.Xr pkg_info 1 . .Pp The FreeBSD handbook .Pp diff --git a/share/man/man7/security.7 b/share/man/man7/security.7 deleted file mode 100644 index d1d34eb5830c..000000000000 --- a/share/man/man7/security.7 +++ /dev/null @@ -1,446 +0,0 @@ -.\" Copyright (c) 1998, Matthew Dillon. Terms and conditions are those of -.\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in -.\" the source tree. -.\" -.\" $Id: security.7,v 1.3 1998/12/25 23:39:01 obrien Exp $ -.\" -.Dd December 20, 1998 -.Dt SECURITY 7 -.Os -.Sh NAME -.Nm security -.Nd introduction to security under FreeBSD -.Sh DESCRIPTION -.Pp -Security is a function that begins and ends with the system administrator. -While all -.Bx -systems are inherently multi-user capable, the job of building and -maintaining security mechanisms to keep those users 'honest' is probably -one of the single largest undertakings of the sysadmin. Machines are -only as secure as you make them, and security concerns are ever competing -with the human necessity for convenience. UNIX systems, -in general, are capable of running a huge number of simultaneous processes -and many of these processes operate as servers - meaning that external entities -can connect and talk to them. As yesterday's mini-computers and mainframes -become today's desktops, and as computers become networked and internetworked, -security becomes an ever bigger issue. -.Pp -Security concerns can be split up into several categories: -.Bl -enum -offset indent -.It -Denial of service attacks -.It -User account compromises -.It -Root compromise through accessible servers -.It -Root compromise via user accounts -.El -.Pp -A denial of service attack is an action that deprives the machine of needed -resources. Typically, D.O.S. attacks are brute-force mechanisms that attempt -to crash or otherwise make a machine unusable by overwhelming its servers or -network stack. Some D.O.S. attacks try to take advantages of bugs in the -networking stack to crash a machine with a single packet. The latter can -only be fixed by applying a bug fix to the kernel. Attacks on servers can -often be fixed by properly specifying options to servers to limit the load -they incur on the system under adverse conditions. Brute-force network -attacks are harder to deal with. A spoofed-packet attack, for example, is -nearly impossible to stop short of cutting your system off from the internet. -.Pp -A user account compromise is even more common then a D.O.S. attack. Many -sysadmins still run standard telnetd, rlogind, rshd, and ftpd servers on their -machines. These servers, by default, do not operate over encrypted -connections. The result is that if you have any moderate-sized user base, -one or more of your users logging into your system from a remote location -(which is the most common and convenient way to login to a system) will -have his or her password sniffed. The attentive system admin will analyze -his remote access logs occasionally looking for suspicious source addresses -even for successful logins. -.Pp -One must always assume that once an attacker has access to a user account, -the attacker can break root. However, the reality is that in a well secured -and maintained system, access to a user account does not necessarily give the -attacker access to root. The distinction is important because without access -to root the attacker cannot generally hide his tracks and may, at best, be -able to remove that user's files and crash the machine, but not touch anyone -else's files. -.Pp -System administrators must keep in mind that there are several ways to break -root on a machine. The attacker may know the root password, the attacker -may find a bug in a root-run server and be able to break root over a network -connection to that server, or the attacker may know of a bug in an suid-root -program that allows the attacker to break root once he has broken into a -user's account. -.Pp -Security remedies are always implemented in a multi-layered 'onion peel' -approach and can be categorized as follows: -.Bl -enum -offset indent -.It -Securing root and staff accounts -.It -Securing root - root-run servers and suid/sgid binaries -.It -Securing user accounts -.It -Securing the password file -.It -Securing the kernel core, raw devices, and filesystems -.It -Checking file integrity: binaries, configuration files, and so forth -.It -Paranoia -.El -.Sh SECURING THE ROOT ACCOUNT AND SECURING STAFF ACCOUNTS -.Pp -Don't bother securing staff accounts if you haven't secured the root -account. Most systems have a password assigned to the root account. The -first thing you do is assume that the password is 'always' compromised. -To secure the root account you make sure that it is not possible to login -to the root account using the root password from a random user account or -over the network. If you haven't already, configure telnetd, rlogind, and -all other servers that handle login operations to refuse root logins, period, -whether the right password is given or not. Allow direct root logins only -via the system console. The '/etc/ttys' file comes in handy here and is -secure by default on most systems, but a good sysadmin always checks to make -sure. -.Pp -Of course, as a sysadmin you have to be able to get to root, so we open up -a few holes. But we make sure these holes require additional password -verification to operate. One way to make root accessible is to add appropriate -staff accounts to the wheel group (in /etc/group). The staff members placed -in the wheel group are allowed to 'su' to root. You should never give staff -members native wheel access via their entry in the password file... put staff -in a 'staff' group or something and only add those that really need root to -the wheel group. Unfortunately the wheel mechanism still allows an intruder to -break root if the intruder has gotten hold of your password file - he need only -break the root password and the password of one of the staff accounts that -happens to be in the wheel group. So while the wheel mechanism is usable, -it isn't much safer then not having a wheel group at all. -.Pp -An indirect way to secure the root account is to secure your staff accounts -by using an alternative login access method and *'ing out the crypted password -for the staff accounts. This way an intruder may be able to steal the password -file but will not be able to break into any staff accounts (or, indirectly, -root, even if root has a crypted password associated with it). Staff members -get into their staff accounts through a secure login mechanism such as -kerberos(1) or ssh(1) (see /usr/ports/security/ssh) using a private/public -key pair. When you use something like kerberos you generally must secure -the machines which run the kerberos servers and your desktop workstation. -When you use a public/private key pair with ssh, you must generally secure -the machine you are logging in FROM (typically your workstation), but you can -also add an additional layer of protection to the key pair by password -protecting the key pair when you create it with ssh-keygen(1). Being able -to *-out the passwords for staff accounts also guarantees that staff members -can only login through secure access methods that you have setup. You can -thus force all staff members to use secure, encrypted connections for -all their sessions which closes an important hole used by many intruders: That -of sniffing the network from an unrelated, less secure machine. -.Pp -The more indirect security mechanisms also assume that you are logging in -from a more restrictive server to a less restrictive server. For example, -if your main box is running all sorts of servers, your workstation shouldn't - be running any. In order for your workstation to be reasonably secure -you should run as few servers as possible, up to and including no servers -at all, and you should run a password-protected screen blanker. - Of course, given physical access to -a workstation an attacker can break any sort of security you put on it. -This is definitely a problem that you should consider but you should also -consider the fact that the vast majority of break-ins occur remotely, over -a network, from people who do not have physical access to your workstation or -servers. -.Pp -Using something like kerberos also gives you the ability to disable or -change the password for a staff account in one place and have it immediately -effect all the machine the staff member may have an account on. If a staff -member's account gets compromised, the ability to instantly change his -password on all machines should not be underrated. With discrete passwords, -changing a password on N machines can be a mess. You can also impose -re-passwording restrictions with kerberos: not only can a kerberos ticket -be made to timeout after a while, but the kerberos system can require that -the user choose a new password after a certain period of time (say, once a -month). -.Sh SECURING ROOT - ROOT-RUN SERVERS AND SUID/SGID BINARIES -.Pp -The prudent sysadmin only runs the servers he needs to, no more, no less. Be -aware that third party servers are often the most bug-prone. For example, -running an old version of imapd or popper is like giving a universal root -ticket out to the entire world. Never run a server that you have not checked -out carefully. Many servers do not need to be run as root. For example, -the ntalk, comsat, and finger daemons can be run in special user 'sandboxes'. -A sandbox isn't perfect unless you go to a large amount of trouble, but the -onion approach to security still stands: If someone is able to break in -through a server running in a sandbox, they still have to break out of the -sandbox. The more layers the attacker must break through, the lower the -likelihood of his success. Root holes have historically been found in -virtually every server ever run as root, including basic system servers. -If you are running a machine through which people only login via sshd and -never login via telnetd or rshd or rlogind, then turn off those services! -.Pp -FreeBSD now defaults to running ntalkd, comsat, and finger in a sandbox. -Another program which may be a candidate for running in a sandbox is -named(8). The default rc.conf includes the arguments necessary to run -named in a sandbox in a commented-out form. Depending on whether you -are installing a new system or upgrading an existing system, the special -user accounts used by these sandboxes may not be installed. The prudent -sysadmin would research and implement sandboxes for servers whenever possible. -.Pp -There are a number of other servers that typically do not run in sandboxes: -sendmail, popper, imapd, ftpd, and others. There are alternatives to -some of these, but installing them may require more work then you are willing -to put (the convenience factor strikes again). You may have to run these -servers as root and rely on other mechanisms to detect break-ins that might -occur through them. -.Pp -The other big potential root hole in a system are the suid-root and sgid -binaries installed on the system. Most of these binaries, such as rlogin, -reside in /bin, /sbin, /usr/bin, or /usr/sbin. While nothing is 100% safe, -the system-default suid and sgid binaries can be considered reasonably safe. -Still, root holes are occasionally found in these binaries. A root hole -was found in Xlib in 1998 that made xterm (which is typically suid) vulnerable. -It is better to be safe then sorry and the prudent sysadmin will restrict suid -binaries that only staff should run to a special group that only staff can -access, and get rid of (chmod 000) any suid binaries that nobody uses. A -server with no display generally does not need an xterm binary. Sgid binaries -can be almost as dangerous. If an intruder can break an sgid-kmem binary the -intruder might be able to read /dev/kmem and thus read the crypted password -file, potentially compromising any passworded account. An intruder that breaks -the tty group can write to almost user's tty. If a user is running a terminal -program or emulator with a talk-back feature, the intruder can potentially -generate a data stream that causes the user's terminal to echo a command, which -is then run as that user. -.Sh SECURING USER ACCOUNTS -.Pp -User accounts are usually the most difficult to secure. While you can impose -Draconian access restrictions on your staff and *-out their passwords, you -may not be able to do so with any general user accounts you might have. If -you do have sufficient control then you may win out and be able to secure the -user accounts properly. If not, you simply have to be more vigilant in your -monitoring of those accounts. Use of ssh and kerberos for user accounts is -more problematic, but still a very good solution compared to a crypted -password. -.Sh SECURING THE PASSWORD FILE -.Pp -The only sure fire way is to *-out as many passwords as you can and -use ssh or kerberos for access to those accounts. Even though the -crypted password file (/etc/spwd.db) can only be read by root, it may -be possible for a intruder to obtain read access to that file even if the -attacker cannot obtain root-write access. -.Pp -Your security scripts should always check for and report changes to -the password file (see 'Checking file integrity' below). -.Sh SECURING THE KERNEL CORE, RAW DEVICES, AND FILESYSTEMS -.Pp -If an attacker breaks root he can do just about anything, but there -are certain conveniences. For example, most modern kernels have a -packet sniffing device driver built in. Under FreeBSD it is called -the 'bpf' device. A intruder will commonly attempt to run a packet sniffer -on a compromised machine. You do not need to give the intruder the -capability and most systems should not have the bpf device compiled in. -Unfortunately, there is another kernel feature called the Loadable Kernel -Module interface. An enterprising intruder can use an LKM to install -his own bpf device or other sniffing device on a running kernel. If you -do not need to use the module loader, turn it off in the kernel configuration -with the NO_LKM option. -.Pp -But even if you turn off the bpf device, and turn off the module loader, -you still have /dev/mem and /dev/kmem to worry about. For that matter, -the intruder can still write raw devices. To avoid this you have to run -the kernel at a higher secure level... at least securelevel 1. The securelevel -can be set with a sysctl on the kern.securelevel variable. Once you have -set the securelevel to 1, write access to raw devices will be denied and -special chflags flags, such as 'schg', will be enforced. You must also ensure -that the 'schg' flag is set on critical startup binaries, directories, and -script files - everything that gets run up to the point where the securelevel -is set. This might be overdoing it, and upgrading the system is much more -difficult when you operate at a higher secure level. You may compromise and -run the system at a higher secure level but not set the schg flag for every -system file and directory under the sun. -.Sh CHECKING FILE INTEGRITY: BINARIES, CONFIG FILES, ETC -.Pp -When it comes right down to it, you can only protect your core system -configuration and control files so much before the convenience factor -rears its ugly head. The last layer of your security onion is perhaps -the most important - detection. -.Pp -The only correct way to check a system's file integrity is via another, -more secure system. It is fairly easy to setup a 'secure' system: you -simply do not run any services on it. With a secure system in place you -can then give it access to other system's root spaces via ssh. This may -seem like a security breech, but you have to put your trust somewhere and -as long as you don't do something stupid like run random servers it really -is possible to build a secure machine. When I say 'secure' here, I assuming -physical access security as well, of course. Given a secure machine with -root access on all your other machines, you can then write security scripts -ON the secure machine to check the other machines on the system. The most -common way of checking is to have the security script scp(1) over a find -and md5 binary and then ssh a shell command to the remote machine to md5 -all the files in the system (or, at least, the /, /var, and /usr partitions!). -The security machine copies the results to a file and diff's them against -results from a previous run (or compares the results against its own -binaries), then emails each staff member a daily report of differences. -.Pp -Another way to do this sort of check is to NFS export the major filesystems -from every other machine to the security machine. This is somewhat more -network intensive but also virtually impossible for an intruder to detect -or spoof. -.Pp -A good security script will also check for changes to user and staff members -access configuration files: .rhosts, .shosts, .ssh/authorized_keys, and -so forth... files that might fall outside the prevue of the MD5 check. -.Pp -A good security script will check for suid and sgid binaries on all -filesystems and report their absolute existence as well as a diff against -the previous report or some baseline (say, make a baseline once a week). -While you can turn off the ability to run suid and sgid binaries on certain -filesystems through the 'nosuid' option in fstab/mount, you cannot turn this -off on root and anyone who breaks root can just install their binary their. -If you have a huge amount of user disk space, though, it may be useful to -disallow suid binaries and devices ('nodev' option) on the user partitions -so you do not have to scan them for such. I would scan them anyway, though, -at least once a week, since the object of this onion layer is detection of -a break-in. -.Pp -Process accounting (see accton(1)) is a relatively low-overhead feature of -the operating system which I recommend using as a post-break-in evaluation -mechanism. It is especially useful in tracking down how an intruder has -actually broken root on a system, assuming the file is still intact after -the break-in occurs. -.Pp -Finally, security scripts should process the log files and the logs themselves -should be generated in as secured a manner as possible - remote syslog can be -very useful. An intruder tries to cover his tracks, and log files are critical -to the sysadmin trying to track down the time and method of the initial break-in. -.Sh PARANOIA -.Pp -A little paranoia never hurts. As a rule, a sysadmin can add any number -of security features as long as they do not effect convenience, and -can add security features that do effect convenience with some added -thought. -.Sh SPECIAL SECTION ON D.O.S. ATTACKS -.Pp -This section covers Denial of Service attacks. A DOS attack is typically -a packet attack. While there isn't much you can do about modern spoofed -packet attacks that saturate your network, you can generally limit the damage -by ensuring that the attacks cannot take down your servers. -.Bl -enum -offset indent -.It -Limiting server forks -.It -Limiting springboard attacks (ICMP response attacks, ping broadcast, etc...) -.It -Kernel Route Cache -.El -.Pp -A common DOS attack is against a forking server that attempts to cause the -server to eat processes, file descriptors, and memory until the machine -dies. Inetd (see inetd(8)) has several options to limit this sort of attack. -It should be noted that while it is possible to prevent a machine from going -down it is not generally possible to prevent a service from being disrupted -by the attack. Read the inetd manual page carefully and pay specific attention -to the -c, -C, and -R options. Note that spoofed-IP attacks will circumvent -the -C option to inetd, so typically a combination of options must be used. -Some standalone servers have self-fork-limitation parameters. -.Pp -Sendmail has its -OMaxDaemonChildren option which tends to work much -better then trying to use sendmail's load limiting options due to the -load lag. You should specify a MaxDaemonChildren parameter when you start -sendmail high enough to handle your expected load but no so high that the -computer cannot handle that number of sendmails without falling on its face. -It is also prudent to run sendmail in queued mode (-ODeliveryMode=queued) -and to run the daemon (sendmail -bd) separate from the queue-runs -(sendmail -q15m). If you still want realtime delivery you can run the queue -at a much lower interval, such as -q1m, but be sure to specify a reasonable -MaxDaemonChildren option for that sendmail to prevent cascade failures. -.Pp -Syslogd can be attacked directly and it is strongly recommended that you use -the -s option whenever possible, and the -a option otherwise. -.Pp -You should also be fairly careful -with connect-back services such as tcpwrapper's reverse-identd, which can -be attacked directly. You generally do not want to use the reverse-ident -feature of tcpwrappers for this reason. -.Pp -It is a very good idea to protect internal services from external access -by firewalling them off at your border routers. The idea here is to prevent -saturation attacks from outside your LAN, not so much to protect internal -services from root network-based root compromise. Always configure an exclusive -firewall, i.e. 'firewall everything *except* ports A, B, C, D, and M-Z'. This -way you can firewall off all of your low ports except for certain specific -services such as named (if you are primary for a zone), ntalkd, sendmail, -and other internet-accessible services. -If you try to configure the firewall the other -way - as an inclusive or permissive firewall, there is a good chance that you -will forget to 'close' a couple of services or that you will add a new internal -service and forget to update the firewall. You can still open up the -high-numbered port range on the firewall to allow permissive-like operation -without compromising your low ports. Also take note that FreeBSD allows you to -control the range of port numbers used for dynamic binding via the various -net.inet.ip.portrange sysctl's (sysctl -a | fgrep portrange), which can also -ease the complexity of your firewall's configuration. I usually use a normal -first/last range of 4000 to 5000, and a hiport range of 49152 to 65535, then -block everything under 4000 off in my firewall ( except for certain specific -internet-accessible ports, of course ). -.Pp -Another common DOS attack is called a springboard attack - to attack a server -in a manner that causes the server to generate responses which then overload -the server, the local network, or some other machine. The most common attack -of this nature is the ICMP PING BROADCAST attack. The attacker spoofed ping -packets sent to your LAN's broadcast address with the source IP address set -to the actual machine they wish to attack. If your border routers are not -configured to stomp on ping's to broadcast addresses, your LAN winds up -generating sufficient responses to the spoofed source address to saturate the -victim, especially when the attacker uses the same trick on several dozen -broadcast addresses over several dozen different networks at once. Broadcast -attacks of over a hundred and twenty megabits have been measured. A second -common springboard attack is against the ICMP error reporting system. By -constructing packets that generate ICMP error responses, an attacker can -saturate a server's incoming network and cause the server to saturate its -outgoing network with ICMP responses. This type of attack can also crash the -server by running it out of mbuf's, especially if the server cannot drain the -ICMP responses it generates fast enough. The FreeBSD kernel has a new kernel -compile option called ICMP_BANDLIM which limits the effectiveness of these -sorts of attacks. The last major class of springboard attacks is related to -certain internal inetd services such as the udp echo service. An attacker -simply spoofs a UDP packet with the source address being server A's echo port, -and the destination address being server B's echo port, where server A and B -are both on your LAN. The two servers then bounce this one packet back and -forth between each other. The attacker can overload both servers and their -LANs simply by injecting a few packets in this manner. Similar problems -exist with the internal chargen port. A competent sysadmin will turn off all -of these inetd-internal test services. -.Pp -Spoofed packet attacks may also be used to overload the kernel route cache. -Refer to the net.inet.ip.rtexpire, rtminexpire, and rtmaxcache sysctl -parameters. A spoofed packet attack that uses a random source IP will cause -the kernel to generate a temporary cached route in the route table, viewable -with 'netstat -rna | fgrep W3'. These routes typically timeout in 1600 -seconds or so. If the kernel detects that the cached route table has gotten -too big it will dynamically reduce the rtexpire but will never decrease it to -less then rtminexpire. There are two problems: (1) The kernel does not react -quickly enough when a lightly loaded server is suddenly attacked, and (2) The -rtminexpire is not low enough for the kernel to survive a sustained attack. -If your servers are connected to the internet via a T3 or better it may be -prudent to manually override both rtexpire and rtminexpire via sysctl(8). -Never set either parameter to zero (unless you want to crash the machine :-)). -Setting both parameters to 2 seconds should be sufficient to protect the route -table from attack. - -.Sh SEE ALSO -.Pp -.Xr accton 1 , -.Xr chflags 1 , -.Xr find 1 , -.Xr kerberos 1 , -.Xr md5 1 , -.Xr ssh 1 , -.Xr sshd 1 , -.Xr syslogd 1 , -.Xr xdm 1 , -.Xr sysctl 8 -.Sh HISTORY -The -.Nm -manual page was originally written by Matthew Dillon and first appeared -in FreeBSD-3.0.1, December 1998. |