Index: stable/4/share/man/man0/title.urm =================================================================== --- stable/4/share/man/man0/title.urm (revision 139702) +++ stable/4/share/man/man0/title.urm (revision 139703) @@ -1,1911 +1,1911 @@ .\" Copyright (c) 1980, 1993 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. .\" .\" @(#)title.urm 8.7 (Berkeley) 4/20/94 .\" $FreeBSD$ .\" .af % i .EH '''' .OH '''' .OF '''\s10- % -\s0' .EF '\s10- % -\s0''' \& .sp |2.75i .nr PS 24 .nr VS 28 .LP .ft B .ce 2 FreeBSD User's Reference Manual (URM) .nr LL 5.5i .nr PO 1.5i .bp \& .sp |1.5i .nr PS 11 .nr VS 13 .LP This stiff doesn't really belong here... The USENIX Association, the UNIX and Advanced Computing Systems professional and technical organization, is a not-for-profit membership association of individuals and institutions with an interest in UNIX and UNIX-like systems, and, by extension, C++, X Window System, and other programming tools. It is dedicated to: .IP \(bu fostering innovation and communicating research and technological developments, .IP \(bu sharing ideas and experience relevant to UNIX, UNIX-related, and advanced computing systems, and .IP \(bu providing a neutral forum for the exercise of critical thought and airing of technical issues. .LP USENIX publishes a journal (\fBComputing Systems\fP), Conference and Workshop Proceedings, and a Book Series. .nr LL 6i .nr PO 1i .bp \& .sp |2.75i .nr PS 18 .nr VS 22 .LP .ft B .ce 2 FreeBSD User's Reference Manual (URM) .sp |4i .ce 2 For FreeBSD version 2.1 (March, 1995) .sp 3 .nr PS 15 .nr VS 18 .LP .ce 2 The FreeBSD Project .sp |8.2i .nr PS 12 .nr VS 15 .LP .ce 4 foo - publisher? .bp .hy 0 .nr PS 9 .nr VS 11 .LP First Printing, 1995 .sp 1 .LP Copyright 1979, 1980, 1983, 1986, 1993 The Regents of the University of California. All rights reserved. .sp 1 .LP Other than the specific manual pages and documents listed below as copyrighted by AT&T, redistribution and use of this manual in source and binary forms, with or without modification, are permitted provided that the following conditions are met: .IP 1) Redistributions of this manual must retain the copyright notices on this page, this list of conditions and the following disclaimer. .IP 2) Software or documentation that incorporates part of this manual must reproduce the copyright notices on this page, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. .IP 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.'' .IP 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. .LP \fB\s-1THIS 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.\s+1\fP .sp 1 .LP The Institute of Electrical and Electronics Engineers and the American National Standards Committee X3, on Information Processing Systems have given us permission to reprint portions of their documentation. .sp 0.5 .LP In the following statement, the phrase ``this text'' refers to portions of the system documentation. .LP ``Portions of this text are reprinted and reproduced in electronic form in 4.4BSD from IEEE Std 1003.1-1988, IEEE Standard Portable Operating System Interface for Computer Environments (POSIX), copyright 1988 by the Institute of Electrical and Electronics Engineers, Inc. In the event of any discrepancy between these versions and the original IEEE Standard, the original IEEE Standard is the referee document.'' .sp 0.5 .LP In the following statement, the phrase ``This material'' refers to portions of the system documentation. .LP ``This material is reproduced with permission from American National Standards Committee X3, on Information Processing Systems. Computer and Business Equipment Manufacturers Association (CBEMA), 311 First St., NW, Suite 500, Washington, DC 20001-2178. The developmental work of Programming Language C was completed by the X3J11 Technical Committee.'' .sp 1 .LP The views and conclusions contained in this manual are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of the Regents of the University of California. .sp 1 .LP This book was printed and bound in the United States of America. .bp \& .sp |1.5i .nr PS 11 .nr VS 13 .LP .ce 1 \s+4\fBContents\fP\s-4 .sp 3 .TS expand; l r. The Computer Systems Research Group, 1979\-1993 vii Prefaces xi Introduction xvii List of Manual Pages xxiii Permuted Index xli Reference Manual Sections 1, 6, 7 tabbed pages List of Documents inside back cover .TE .if o .bp \& .bp .\" .\" The contributor list below is derived from the file that resides in .\" vangogh:~admin/contrib/contrib: .\" .\" @(#)contrib 5.54 (Berkeley) 4/17/94 .\" .\" This file should not be editted, rather the original contrib file .\" should be used to recrete this one following the directions at its top. .\" Contrib starts here and continues to the comment `END OF CONTRIB'. .\" \& .sp |1i .ps 16 .ce \fBThe Computer Systems Research Group 1979 \- 1993\fP .sp 3 .nr PS 11 .nr VS 12 .LP .nf .in +0.5i \fBCSRG Technical Staff\fP .sp 1 .in +1i Jim Bloom Keith Bostic Ralph Campbell Kevin Dunlap William N. Joy Michael J. Karels Samuel J. Leffler Marshall Kirk McKusick Miriam Amos Nihart Keith Sklower Marc Teitelbaum Michael Toy .in -1i .sp 3 \fBCSRG Administration and Support\fP .sp 1 .in +1i Robert Fabry Domenico Ferrari Susan L. Graham Bob Henry Anne Hughes Bob Kridle David Mosher Pauline Schwartz Mark Seiden Jean Wood .in -1i .fi .sp 3 \fBOrganizations that funded the CSRG with grants, gifts, personnel, and/or hardware.\fP .sp 1 .nf .in +1i Center for Advanced Aviation System Development, The MITRE Corp. Compaq Computer Corporation Cray Research Inc. Department of Defense Advance Research Projects Agency (DARPA) Digital Equipment Corporation The Hewlett-Packard Company NASA Ames Research Center The National Science Foundation The Open Software Foundation UUNET Technologies Inc. .in -1.5i .fi .bp .nr PS 10 .nr VS 11 .LP \fBThe following are people and organizations that provided a large subsystem for the BSD releases.\fP .sp .TS l l. ANSI C library Chris Torek ANSI C prototypes Donn Seeley and John Kohl Autoconfiguration Robert Elz C library documentation American National Standards Committee X3 CCI 6/32 support Computer Consoles Inc. DEC 3000/5000 support Ralph Campbell Disklabels Symmetric Computer Systems Documentation Cynthia Livingston and The USENIX Association Franz Lisp Richard Fateman, John Foderaro, Keith Sklower, Kevin Layer GCC, GDB The Free Software Foundation Groff James Clark (The FSF) HP300 support Jeff Forys, Mike Hibler, Jay Lepreau, Donn Seeley and the Systems Programming Group; University of Utah Computer Science Department ISODE Marshall Rose Ingres Mike Stonebraker, Gene Wong, and the Berkeley Ingres Research Group Intel 386/486 support Bill Jolitz and TeleMuse Job control Jim Kulp Kerberos Project Athena and MIT Kernel support Bill Shannon and Sun Microsystems Inc. LFS Margo Seltzer, Mendel Rosenblum, Carl Staelin MIPS support Trent Hein Math library K.C. Ng, Zhishun Alex Liu, S. McDonald, P. Tang and W. Kahan NFS Rick Macklem NFS automounter Jan-Simon Pendry Network device drivers Micom-Interlan and Excelan Omron Luna support Akito Fujita and Shigeto Mochida Quotas Robert Elz RPC support Sun Microsystems Inc. Shared library support Rob Gingell and Sun Microsystems Inc. Sony News 3400 support Kazumasa Utashiro Sparc I/II support Computer Systems Engineering Group, Lawrence Berkeley Laboratory Stackable file systems John Heidemann Stdio Chris Torek System documentation The Institute of Electrical and Electronics Engineers, Inc. TCP/IP Rob Gurwitz and Bolt Beranek and Newman Inc. Timezone support Arthur David Olson Transport/Network OSI layers IBM Corporation and the University of Wisconsin Kernel XNS assistance William Nesheim, J. Q. Johnson, Chris Torek, and James O'Toole User level XNS Cornell University VAX 3000 support Mt. Xinu and Tom Ferrin VAX BI support Chris Torek VAX device support Digital Equipment Corporation and Helge Skrivervik Versatec printer/plotter support University of Toronto Virtual memory implementation Avadis Tevanian, Jr., Michael Wayne Young, and the Carnegie-Mellon University Mach project X25 University of British Columbia .TE .bp .LP \fBThe following are people and organizations that provided a specific item, program, library routine or program maintenance for the BSD system. (Their contribution may not be part of the final 4.4BSD release.)\fP .sp 0.4 .nr PS 9 .nr VS 10 .ps 9 .vs 10 .TS l l. 386 device drivers Carnegie-Mellon University Mach project 386 device drivers Don Ahn, Sean Fagan and Tim Tucker HCX device drivers Harris Corporation Kernel enhancements Robert Elz, Peter Ivanov, Ian Johnstone, Piers Lauder, - John Lions, Tim Long, Chris Maltby, Greg Rose and John Wainwright + John Lions, Tim Long, Chris Maltby, Greg Rose and John Wainwright ISO-9660 filesystem Pace Willisson, Atsushi Murai .TE .TS l l l l. adventure(6) Don Woods log(3) Peter McIlroy adventure(6) Jim Gillogly look(1) David Hitz adventure(6) Will Crowther ls(1) Elan Amir apply(1) Rob Pike ls(1) Michael Fischbein ar(1) Hugh A. Smith lsearch(3) Roger L. Snyder arithmetic(6) Eamonn McManus m4(1) Ozan Yigit arp(8) Sun Microsystems Inc. mail(1) Kurt Schoens at(1) Steve Wall make(1) Adam de Boor atc(6) Ed James me(7) Eric Allman awk(1) Arnold Robbins mergesort(3) Peter McIlroy awk(1) David Trueman mh(1) Marshall Rose backgammon(6) Alan Char mh(1) The Rand Corporation banner(1) Mark Horton mille(6) Ken Arnold battlestar(6) David Riggle mknod(8) Kevin Fall bcd(6) Steve Hayman monop(6) Ken Arnold bdes(1) Matt Bishop more(1) Eric Shienbrood berknet(1) Eric Schmidt more(1) Mark Nudleman bib(1) Dain Samples mountd(8) Herb Hasler bib(1) Gary M. Levin mprof(1) Ben Zorn bib(1) Timothy A. Budd msgs(1) David Wasley bitstring(3) Paul Vixie multicast Stephen Deering boggle(6) Barry Brachman mv(1) Ken Smith bpf(4) Steven McCanne named/bind(8) Douglas Terry btree(3) Mike Olson named/bind(8) Kevin Dunlap byte-range locking Scooter Morris news(1) Rick Adams (and a cast of thousands) caesar(6) John Eldridge nm(1) Hans Huebner caesar(6) Stan King pascal(1) Kirk McKusick cal(1) Kim Letkeman pascal(1) Peter Kessler cat(1) Kevin Fall paste(1) Adam S. Moskowitz chess(6) Stuart Cracraft (The FSF) patch(1) Larry Wall ching(6) Guy Harris pax(1) Keith Muller cksum(1) James W. Williams phantasia(6) C. Robertson clri(8) Rich $alz phantasia(6) Edward A. Estes col(1) Michael Rendell ping(8) Mike Muuss comm(1) Case Larsen pom(6) Keith E. Brandt compact(1) Colin L. McMaster pr(1) Keith Muller compress(1) James A. Woods primes(6) Landon Curt Noll compress(1) Joseph Orost qsort(3) Doug McIlroy compress(1) Spencer Thomas qsort(3) Earl Cohen courier(1) Eric Cooper qsort(3) Jon Bentley cp(1) David Hitz quad(3) Chris Torek cpio(1) AT&T quiz(6) Jim R. Oldroyd crypt(3) Tom Truscott quiz(6) Keith Gabryelski csh(1) Christos Zoulas radixsort(3) Dan Bernstein csh(1) Len Shar radixsort(3) Peter McIlroy curses(3) Elan Amir rain(6) Eric P. Scott curses(3) Ken Arnold ranlib(1) Hugh A. Smith cut(1) Adam S. Moskowitz rcs(1) Walter F. Tichy cut(1) Marciano Pitargue rdist(1) Michael Cooper dbx(1) Mark Linton regex(3) Henry Spencer dd(1) Keith Muller robots(6) Ken Arnold dd(1) Lance Visser rogue(6) Timothy C. Stoehr des(1) Jim Gillogly rs(1) John Kunze des(1) Phil Karn sail(6) David Riggle des(1) Richard Outerbridge sail(6) Edward Wang dipress(1) Xerox Corporation sccs(1) Eric Allman disklabel(8) Symmetric Computer Systems scsiformat(1) Lawrence Berkeley Laboratory du(1) Chris Newcomb sdb(1) Howard Katseff dungeon(6) R.M. Supnik sed(1) Diomidis Spinellis ed(1) Rodney Ruddock sendmail(8) Eric Allman emacs(1) Richard Stallman setmode(3) Dave Borman erf(3) Peter McIlroy, K.C. Ng sh(1) Kenneth Almquist error(1) Robert R. Henry slattach(8) Rick Adams ex(1) Mark Horton slip(8) Rick Adams factor(6) Landon Curt Noll spms(1) Peter J. Nicklin file(1) Ian Darwin strtod(3) David M. Gay find(1) Cimarron Taylor swab(3) Jeffrey Mogul finger(1) Tony Nardo sysconf(3) Sean Eric Fagan fish(6) Muffy Barkocy sysline(1) J.K. Foderaro fmt(1) Kurt Schoens syslog(3) Eric Allman fnmatch(3) Guido van Rossum systat(1) Bill Reeves fold(1) Kevin Ruddy systat(1) Robert Elz fortune(6) Ken Arnold tail(1) Edward Sze-Tyan Wang fpr(1) Robert Corbett talk(1) Clem Cole fsdb(8) Computer Consoles Inc. talk(1) Kipp Hickman fsplit(1) Asa Romberger talk(1) Peter Moore fsplit(1) Jerry Berkman telnet(1) Dave Borman gcc/groff integration UUNET Technologies, Inc. telnet(1) Paul Borman gcore(1) Eric Cooper termcap(5) John A. Kunze getcap(3) Casey Leedom termcap(5) Mark Horton glob(3) Guido van Rossum test(1) Kenneth Almquist gprof(1) Peter Kessler tetris(6) Chris Torek gprof(1) Robert R. Henry tetris(6) Darren F. Provine hack(6) Andries Brouwer (and a cast of thousands) timed(8) Riccardo Gusella hangman(6) Ken Arnold timed(8) Stefano Zatti hash(3) Margo Seltzer tn3270(1) Gregory Minshall heapsort(3) Elmer Yglesias tr(1) Igor Belchinskiy heapsort(3) Kevin Lew traceroute(8) Van Jacobson heapsort(3) Ronnie Kon trek(6) Eric Allman hunt(6) Conrad Huang tset(1) Eric Allman hunt(6) Greg Couch tsort(1) Michael Rendell icon(1) Bill Mitchell unifdef(1) Dave Yost icon(1) Ralph Griswold uniq(1) Case Larsen indent(1) David Willcox uucpd(8) Rick Adams indent(1) Eric Schmidt uudecode(1) Mark Horton indent(1) James Gosling uuencode(1) Mark Horton indent(1) Sun Microsystems uuq(1) Lou Salkind init(1) Donn Seeley uuq(1) Rick Adams j0(3) Sun Microsystems, Inc. uusnap(8) Randy King j1(3) Sun Microsystems, Inc. uusnap(8) Rick Adams jn(3) Sun Microsystems, Inc. vacation(1) Eric Allman join(1) David Goodenough vi(1) Steve Kirkendall join(1) Michiro Hikida which(1) Peter Kessler join(1) Steve Hayman who(1) Michael Fischbein jot(1) John Kunze window(1) Edward Wang jove(1) Jonathon Payne worm(6) Michael Toy kermit(1) Columbia University worms(6) Eric P. Scott kvm(3) Peter Shipley write(1) Craig Leres kvm(3) Steven McCanne write(1) Jef Poskanzer lam(1) John Kunze wump(6) Dave Taylor larn(6) Noah Morgan X25/Ethernet Univ. of Erlangen-Nuremberg lastcomm(1) Len Edmondson X25/LLC2 Dirk Husemann lex(1) Vern Paxson xargs(1) John B. Roll Jr. libm(3) Peter McIlroy xneko(6) Masayuki Koba libm(3) UUNET Technologies, Inc. XNSrouted(1) Bill Nesheim locate(1) James A. Woods xroach(6) J.T. Anderson lock(1) Bob Toxen yacc(1) Robert Paul Corbett .TE .\" .\" END OF CONTRIB: Contrib ends here. .\" .if o .bp \& .bp .nr PS 10 .nr VS 12 \& .sp |1.5i .LP .ce \fB\s+4PREFACE\s-4\fP .sp 3 .NH 1 Introduction .PP The major new facilities available in the 4.4BSD release are -a new virtual memory system, +a new virtual memory system, the addition of ISO/OSI networking support, a new virtual filesystem interface supporting filesystem stacking, a freely redistributable implementation of NFS, a log-structured filesystem, enhancement of the local filesystems to support files and filesystems that are up to 2^63 bytes in size, enhanced security and system management support, and the conversion to and addition of the IEEE Std1003.1 (``POSIX'') facilities and many of the IEEE Std1003.2 facilities. In addition, many new utilities and additions have been made to the C-library. The kernel sources have been reorganized to collect all machine-dependent files for each architecture under one directory, and most of the machine-independent code is now free of code conditional on specific machines. The user structure and process structure have been reorganized to eliminate the statically-mapped user structure and to make most of the process resources shareable by multiple processes. The system and include files have been converted to be compatible with ANSI C, including function prototypes for most of the exported functions. There are numerous other changes throughout the system. .NH 1 Changes in the Kernel .PP This release includes several important structural kernel changes. The kernel uses a new internal system call convention; the use of global (``u-dot'') variables for parameters and error returns has been eliminated, and interrupted system calls no longer abort using non-local goto's (longjmp's). A new sleep interface separates signal handling from scheduling priority, returning characteristic errors to abort or restart the current system call. This sleep call also passes a string describing the process state, which is used by the ps(1) program. The old sleep interface can be used only for non-interruptible sleeps. .PP Many data structures that were previously statically allocated are now allocated dynamically. These structures include mount entries, file entries, user open file descriptors, the process entries, the vnode table, the name cache, and the quota structures. .PP The 4.4BSD distribution adds support for several new architectures including SPARC-based Sparcstations 1 and 2, MIPS-based Decstation 3100 and 5000 and Sony NEWS, 68000-based Hewlett-Packard 9000/300 and Omron Luna, and 386-based Personal Computers. Both the HP300 and SPARC ports feature the ability to run binaries built for the native operating system (HP-UX or SunOS) by emulating their system calls. Though this native operating system compatibility was provided by the developers as needed for their purposes and is by no means complete, it is complete enough to run several non-trivial applications including those that require HP-UX or SunOS shared libraries. For example, the vendor supplied X11 server and windowing environment can be used on both the HP300 and SPARC. .NH 2 Virtual memory changes .PP The new virtual memory implementation is derived from the MACH operating system developed at Carnegie-Mellon, and was ported to the BSD kernel at the University of Utah. The MACH virtual memory system call interface has been replaced with the ``mmap''-based interface described in the ``Berkeley Software Architecture Manual''. The interface is similar to the interfaces shipped by several commercial vendors such as Sun, USL, and Convex Computer Corp. The integration of the new virtual memory is functionally complete, but, like most MACH-based virtual memory systems, still has serious performance problems under heavy memory load. .NH 2 Networking additions and changes .PP The ISO/OSI Networking consists of a kernel implementation of transport class 4 (TP-4), connectionless networking protocol (CLNP), and 802.3-based link-level support (hardware-compatible with Ethernet*). .FS *Ethernet is a trademark of the Xerox Corporation. .FE We also include support for ISO Connection-Oriented Network Service, X.25, TP-0. The session and presentation layers are provided outside the kernel by the ISO development environment (ISODE). Included in this development environment are file transfer and management (FTAM), virtual terminals (VT), a directory services implementation (X.500), and miscellaneous other utilities. .PP Several important enhancements have been added to the TCP/IP protocols including TCP header prediction and serial line IP (SLIP) with header compression. The routing implementation has been completely rewritten to use a hierarchical routing tree with a mask per route to support the arbitrary levels of routing found in the ISO protocols. The routing table also stores and caches route characteristics to speed the adaptation of the throughput and congestion avoidance algorithms. .NH 2 Additions and changes to filesystems .PP The 4.4BSD distribution contains most of the interfaces specified in the IEEE Std1003.1 system interface standard. Filesystem additions include IEEE Std1003.1 FIFOs, byte-range file locking, and saved user and group identifiers. .PP A new virtual filesystem interface has been added to the kernel to support multiple filesystems. In comparison with other interfaces, the Berkeley interface has been structured for more efficient support of filesystems that maintain state (such as the local filesystem). The interface has been extended with support for stackable filesystems done at UCLA. These extensions allow for filesystems to be layered on top of each other and allow new vnode operations to be added without requiring changes to existing filesystem implementations. For example, the umap filesystem is used to mount a sub-tree of an existing filesystem that uses a different set of uids and gids than the local system. Such a filesystem could be mounted from a remote site via NFS or it could be a filesystem on removable media brought from some foreign location that uses a different password file. .PP In addition to the local ``fast filesystem'', we have added an implementation of the network filesystem (NFS) that fully interoperates with the NFS shipped by Sun and its licensees. Because our NFS implementation was implemented using only the publicly available NFS specification, it does not require a license from Sun to use in source or binary form. By default it runs over UDP to be compatible with Sun's implementation. However, it can be configured on a per-mount basis to run over TCP. Using TCP allows it to be used quickly and efficiently through gateways and over long-haul networks. Using an extended protocol, it supports Leases to allow a limited callback mechanism that greatly reduces the network traffic necessary to maintain cache consistency between the server and its clients. .PP A new log-structured filesystem has been added that provides near disk-speed output and fast crash recovery. It is still experimental in the 4.4BSD release, so we do not recommend it for production use. We have also added a memory-based filesystem that runs in pageable memory, allowing large temporary filesystems without requiring dedicated physical memory. .PP -The local ``fast filesystem'' has been enhanced to do +The local ``fast filesystem'' has been enhanced to do clustering which allows large pieces of files to be allocated contiguously resulting in near doubling of filesystem throughput. The filesystem interface has been extended to allow files and filesystems to grow to 2^63 bytes in size. The quota system has been rewritten to support both user and group quotas (simultaneously if desired). Quota expiration is based on time rather than the previous metric of number of logins over quota. This change makes quotas more useful on fileservers onto which users seldom login. .PP The system security has been greatly enhanced by the addition of additional file flags that permit a file to be marked as immutable or append only. Once set, these flags can only be cleared by the super-user when the system is running single user. To protect against indiscriminate reading or writing of kernel memory, all writing and most reading of kernel data structures must be done using a new ``sysctl'' interface. The information to be access is described through an extensible ``Management Information Base'' (MIB). .NH 2 POSIX terminal driver changes .PP The biggest area of change is a new terminal driver. The terminal driver is similar to the System V terminal driver with the addition of the necessary extensions to get the functionality previously available in the 4.3BSD terminal driver. 4.4BSD also adds the IEEE Std1003.1 job control interface, which is similar to the 4.3BSD job control interface, but adds a security model that was missing in the 4.3BSD job control implementation. A new system call, \fIsetsid\fP, creates a job-control session consisting of a single process group with one member, the caller, that becomes a session leader. Only a session leader may acquire a controlling terminal. This is done explicitly via a \s-1TIOCSCTTY\s+1 \fIioctl\fP call, not implicitly by an \fIopen\fP call. The call fails if the terminal is in use. .PP For backward compatibility, both the old \fIioctl\fP calls and old options to \fIstty\fP are emulated. .NH 1 Changes to the utilities .PP There are several new tools and utilities included in this release. A new version of ``make'' allows much-simplified makefiles for the system software and allows compilation for multiple architectures from the same source tree (which may be mounted read-only). Notable additions to the libraries include functions to traverse a filesystem hierarchy, database interfaces to btree and hashing functions, a new, fast implementation of stdio and a radix sort function. The additions to the utility suite include greatly enhanced versions of programs that display system status information, implementations of various traditional tools described in the IEEE Std1003.2 standard, and many others. .PP We have been tracking the IEEE Std1003.2 shell and utility work and have included prototypes of many of the proposed utilities. Most of the traditional utilities have been replaced with implementations conformant to the POSIX standards. Almost the entire manual suite has been rewritten to reflect the POSIX defined interfaces. In rewriting this software, we have generally been rewarded with significant performance improvements. Most of the libraries and header files have been converted to be compliant with ANSI C. The system libraries and utilities all compile with either ANSI or traditional C. .PP The Kerberos (version 4) authentication software has been integrated into much of the system (including NFS) to provide the first real network authentication on BSD. .PP A new implementation of the \fIex/vi\fP text editors is available in this release. It is intended as a bug-for-bug compatible version of the editors. It also has a few new features: 8-bit clean data, lines and files limited only by memory and disk space, split screens, tags stacks and left-right scrolling among them. \fINex/nvi\fP is not yet production quality; future versions of this software may be retrieved by anonymous ftp from ftp.cs.berkeley.edu, in the directory ucb/4bsd. .PP The \fIfind\fP utility has two new options that are important to be aware of if you intend to use NFS. The ``fstype'' and ``prune'' options can be used together to prevent find from crossing NFS mount points. .NH 2 Additions and changes to the libraries .PP The \fIcurses\fP library has been largely rewritten. Important additional features include support for scrolling and \fItermios\fP. .PP An application front-end editing library, named libedit, has been added to the system. .PP A superset implementation of the SunOS kernel memory interface library, \fIlibkvm\fP, has been integrated into the system. .PP Nearly the entire C-library has been rewritten. Some highlights of the changes to the 4.4BSD C-library: .IP \(bu The newly added \fIfts\fP functions will do either physical or logical traversal of a file hierarchy as well as handle essentially infinite depth filesystems and filesystems with cycles. All the utilities in 4.4BSD that traverse file hierarchies have been converted to use \fIfts\fP. The conversion has always resulted in a significant performance gain, often of four or five to one in system time. .IP \(bu The newly added \fIdbopen\fP functions are intended to be a family of database access methods. Currently, they consist of \fIhash\fP, an extensible, dynamic hashing scheme, \fIbtree\fP, a sorted, balanced tree structure (B+tree's), and \fIrecno\fP, a flat-file interface for fixed or variable length records referenced by logical record number. Each of the access methods stores associated key/data pairs and uses the same record oriented interface for access. Future versions of this software may be retrieved by anonymous ftp from ftp.cs.berkeley.edu, in the directory ucb/4bsd. .IP \(bu The \fIqsort\fP function has been rewritten for additional performance. In addition, three new types of sorting functions, \fIheapsort\fP, \fImergesort\fP, and \fIradixsort\fP have been added to the system. The \fImergesort\fP function is optimized for data with pre-existing order, in which case it usually significantly outperforms \fIqsort\fP. The \fIradixsort\fP functions are variants of most-significant-byte radix sorting. They take time linear to the number of bytes to be sorted, usually significantly outperforming \fIqsort\fP on data that can be sorted in this fashion. An implementation of the POSIX 1003.2 standard \fIsort\fP based on \fIradixsort\fP is included in 4.4BSD. .IP \(bu The floating point support in the C-library has been replaced and is now accurate. .IP \(bu The C functions specified by both ANSI C, POSIX 1003.1 and 1003.2 are now part of the C-library. This includes support for file name matching, shell globbing and both basic and extended regular expressions. .IP \(bu ANSI C multibyte and wide character support has been integrated. The rune functionality from the Bell Labs' Plan 9 system is provided as well. .IP \(bu The \fItermcap\fP functions have been generalized and replaced with a general purpose interface named \fIgetcap\fP. .IP \(bu The \fIstdio\fP routines have been replaced, and are usually much faster. In addition, the \fIfunopen\fP interface permits applications to provide their own I/O stream function support. .NH 1 Acknowledgements .PP We were greatly assisted by the past employees of the Computer Systems Research Group: Mike Karels, Keith Sklower, and Marc Tietelbaum. Our distribution coordinator, Pauline Schwartz, has reliably managed the finances and the mechanics of shipping distributions for nearly the entire fourteen years of the group's existence. Without the help of lawyers Mary MacDonald, Joel Linzner, and Carla Shapiro, the 4.4BSD-Lite distribution would never have seen the light of day. Much help was provided by Chris Demetriou in getting bug fixes from NetBSD integrated back into the 4.4BSD-Lite distribution. .PP The vast majority of the 4.4BSD distribution comes from the numerous people in the UNIX community that provided their time and energy in creating the software contained in this release. We dedicate this distribution to them. .sp 1 .in 4i .nf M. K. McKusick K. Bostic .fi .in 0 .sp 3 .nr PS 9 .nr VS 10 .LP .ne 1i .ce \fIPreface to the 4.3 Berkeley distribution\fP .sp 1 .LP This update to the 4.2 distribution of August 1983 provides substantially improved performance, reliability, and security, the addition of Xerox Network System (NS) to the set of networking domains, and partial support for the VAX 8600 and MICROVAXII. .LP We were greatly assisted by the DEC UNIX Engineering group who provided two full time employees, Miriam Amos and Kevin Dunlap, to work at Berkeley. They were responsible for developing and debugging the distributed domain based name server and integrating it into the mail system. Mt Xinu provided the bug list distribution service as well as donating their MICROVAXII port to 4.3BSD. Drivers for the MICROVAXII were done by Rick Macklem at the University of Guelph. Sam Leffler provided valuable assistance and advice with many projects. -Keith Sklower coordinated with William Nesheim and J. Q. Johnson at Cornell, +Keith Sklower coordinated with William Nesheim and J. Q. Johnson at Cornell, and Chris Torek and James O'Toole at the University of Maryland to do the Xerox Network Systems implementation. Robert Elz at the University of Melbourne contributed greatly to the performance work in the kernel. Donn Seeley and Jay Lepreau at the University of Utah relentlessly dealt with a myriad of details; Donn completed the unfinished performance work on Fortran 77 and fixed numerous C compiler bugs. Ralph Campbell handled innumerable questions and problem reports and had time left to write rdist. George Goble was invaluable in shaking out the bugs on his production systems long before we were confident enough to inflict it on our users. -Bill Shannon at Sun Microsystems has been helpful in +Bill Shannon at Sun Microsystems has been helpful in providing us with bug fixes and improvements. Tom Ferrin, in his capacity as Board Member of Usenix Association, handled the logistics of large-scale reproduction of the 4.2BSD and 4.3BSD manuals. Mark Seiden helped with the typesetting and indexing of the 4.3BSD manuals. Special mention goes to Bob Henry for keeping ucbvax running in spite of new and improved software and an ever increasing mail, news, and uucp load. .LP Numerous others contributed their time and energy in creating the user contributed software for the release. -As always, we are grateful to the UNIX user community for -encouragement and support. +As always, we are grateful to the UNIX user community for +encouragement and support. .LP Once again, the financial support of the Defense Advanced Research Projects Agency is gratefully acknowledged. .sp 1 .in 4i .nf M. K. McKusick M. J. Karels J. M. Bloom .fi .in 0 .sp 2 .ne 2i .ce \fIPreface to the 4.2 Berkeley distribution\fP .sp 1 This update to the 4.1 distribution of June 1981 provides support for the VAX 11/730, full networking and interprocess communication support, an entirely new file system, and many other new features. It is certainly the most ambitious release of software ever prepared here and represents many man-years of work. Bill Shannon (both at DEC and at Sun Microsystems) and Robert Elz of the University of Melbourne contributed greatly to this distribution through new device drivers and painful debugging episodes. Rob Gurwitz of BBN wrote the initial version of the code upon which the current networking support is based. Eric Allman of Britton-Lee donated countless hours to the mail system. Bill Croft (both at SRI and Sun Microsystems) aided in the debugging and development of the networking facilities. Dennis Ritchie of Bell Laboratories also contributed greatly to this distribution, providing valuable advise and guidance. Helge Skrivervik worked on the device drivers which enabled the distribution to be delivered with a TU58 console cassette and RX01 console flopppy disk, and rewrote major portions of the standalone i/o system to support formatting of non-DEC peripherals. .LP Numerous others contributed their time and energy in organizing the user software for release, while many groups of people on campus suffered patiently through the low spots of development. -As always, we are grateful to the UNIX user community for -encouragement and support. +As always, we are grateful to the UNIX user community for +encouragement and support. .LP Once again, the financial support of the Defense Advanced Research Projects Agency is gratefully acknowledged. .sp 1 .in 4i .nf S. J. Leffler W. N. Joy M. K. McKusick .fi .in 0 .sp 2 .ne 1i .ce \fIPreface to the 4.1 Berkeley distribution\fP .sp 1 This update to the fourth distribution of November 1980 provides support for the VAX 11/750 and for the full interconnect architecture of the VAX 11/780. Robert Elz of the University of Melbourne contributed greatly to this distribution especially in the boot-time system configuration code; Bill Shannon of DEC supplied us with the implementation of DEC standard bad block handling. The research group at Bell Laboratories and DEC Merrimack provided us with access to 11/750's in order to debug its support. .LP Other individuals too numerous to mention provided us with bug reports, fixes and other enhancements which are reflected in the system. We are grateful to the UNIX user community for encouragement and support. .LP The financial support of the Defence Advanced Research Projects Agency in support of this work is gratefully acknowledged. .sp 1 .in 4i .nf W. N. Joy R. S. Fabry K. Sklower .fi .in 0 .sp 2 .ne 1i .ce \fIPreface to the Fourth Berkeley distribution\fP .sp 1 This manual reflects the Berkeley system mid-October, 1980. A large amount of tuning has been done in the system since the last release; we hope this provides as noticeable an improvement for you as it did for us. This release finds the system in transition; a number of facilities have been added in experimental versions (job control, resource limits) and the implementation of others is imminent (shared-segments, higher performance from the file system, etc.). Applications which use facilities that are in transition should be aware that some of the system calls and library routines will change in the near future. We have tried to be conscientious and make it very clear where this is likely. .LP A new group has been formed at Berkeley, to assume responsibility for the future development and support of a version of UNIX on the VAX. The group has received funding from the Defense Advanced Research Projects Agency (DARPA) to supply a standard version of the system to DARPA contractors. The same version of the system will be made available to other licensees of UNIX on the VAX for a duplication charge. We gratefully acknowledge the support of this contract. .LP We wish to acknowledge the contribution of a number of individuals to the system. .LP We would especially like to thank Jim Kulp of IIASA, Laxenburg Austria and his colleagues, who first put job control facilities into UNIX; Eric Allman, Robert Henry, Peter Kessler and Kirk McKusick, who contributed major new pieces of software; Mark Horton, who contributed to the improvement of facilities and substantially improved the quality of our bit-mapped fonts, our hardware support staff: Bob Kridle, Anita Hirsch, Len Edmondson and Fred Archibald, who helped us to debug a number of new peripherals; Ken Arnold who did much of the leg-work in getting this version of the manual prepared, and did the final editing of sections 2-6, some special individuals within Bell Laboratories: Greg Chesson, Stuart Feldman, Dick Haight, Howard Katseff, Brian Kernighan, Tom London, John Reiser, Dennis Ritchie, Ken Thompson, and Peter Weinberger who helped out by answering questions; our excellent local DEC field service people, Kevin Althaus and Frank Chargois who kept our machine running virtually all the time, and fixed it quickly when things broke; and, Mike Accetta of Carnegie-Mellon University, Robert Elz of the University of Melbourne, George Goble of Purdue University, and David Kashtan of the Stanford Research Institute for their technical advice and support. .LP Special thanks to Bill Munson of DEC who helped by augmenting our computing facility and to Eric Allman for carefully proofreading the ``last'' draft of the manual and finding the bugs which we knew were -there but couldn't see. +there but couldn't see. .LP We dedicate this to the memory of David Sakrison, late chairman of our department, who gave his support to the establishment of our VAX computing facility, and to our department as a whole. .sp 1 .in 4i .nf W. N. Joy \v'-3p'\h'2p'\*:\v'3p'\h'-2p'O. Babao\*~glu R. S. Fabry K. Sklower .fi .in 0 .sp 2 .ne 1i .ce \fIPreface to the Third Berkeley distribution\fP .sp 1 This manual reflects the state of the Berkeley system, December 1979. We would like to thank all the people at Berkeley who have contributed to the system, and particularly thank Prof. Richard Fateman for creating and administrating a hospitable environment, Mark Horton who helped prepare this manual, and Eric Allman, Bob Kridle, Juan Porcar and Richard Tuck for their contributions to the kernel. .LP The cooperation of Bell Laboratories in providing us with an early version of \s-2UNIX\s0/32V is greatly appreciated. We would especially like to thank Dr. Charles Roberts of Bell Laboratories for helping us obtain this release, and acknowledge T. B. London, J. F. Reiser, K. Thompson, D. M. Ritchie, G. Chesson and H. P. Katseff for their advice and support. .sp 1 .in 4i W. N. Joy .br \v'-3p'\h'2p'\*:\v'3p'\h'-2p'O. Babao\*~glu .in 0 .sp 2 .ne 1i .ce \fIPreface to the UNIX/32V distribution\fP .sp 1 The .UX operating system for the VAX*-11 .FS *VAX and PDP are Trademarks of Digital Equipment Corporation. .FE provides substantially the same facilities as the \s-2UNIX\s0 system for the PDP*-11. .LP We acknowledge the work of many who came before us, and particularly thank G. K. Swanson, W. M. Cardoza, D. K. Sharma, and J. F. Jarvis for assistance with the implementation for the VAX-11/780. .sp 1 .in 4i T. B. London .br J. F. Reiser .in 0 .sp 2 .ne 1i .ce \fIPreface to the Seventh Edition\fP .sp 1 .LP Although this Seventh Edition no longer bears their byline, Ken Thompson and Dennis Ritchie remain the fathers and preceptors of the \s-2UNIX\s0 time-sharing system. Many of the improvements here described bear their mark. Among many, many other people who have contributed to the further flowering of \s-2UNIX\s0, we wish especially to acknowledge the contributions of A. V. Aho, S. R. Bourne, L. L. Cherry, G. L. Chesson, S. I. Feldman, C. B. Haley, R. C. Haight, S. C. Johnson, M. E. Lesk, T. L. Lyon, L. E. McMahon, R. Morris, R. Muha, D. A. Nowitz, L. Wehr, and P. J. Weinberger. -We appreciate also +We appreciate also the effective advice and criticism of T. A. Dolotta, A. G. Fraser, J. F. Maranzano, and J. R. Mashey; and we remember the important work of the late Joseph F. Ossanna. .sp 1 .in 4i B. W. Kernighan .br M. D. McIlroy .in 0 .if o .bp \& .bp .de IR \fI\\$1\^\fR\\$2 .. .de RI \fR\\$1\fI\\$2\^\fR\\$3 .. .ce \fB\s+4INTRODUCTION\s-4\fP .sp 1 .nr PS 10 .nr VS 12 .LP The documentation for 4.4BSD is in a format similar to the one used for the 4.2BSD and 4.3BSD manuals. It is divided into three sets; each set consists of one or more volumes. The abbreviations for the volume names are listed in square brackets; the abbreviations for the manual sections are listed in parenthesis. .DS I. User's Documents User's Reference Manual [URM] Commands (1) Games (6) Macro packages and language conventions (7) User's Supplementary Documents [USD] Getting Started Basic Utilities Communicating with the World Text Editing Document Preparation Amusements II. Programmer's Documents Programmer's Reference Manual [PRM] System calls (2) Subroutines (3) Special files (4) File formats and conventions (5) Programmer's Supplementary Documents [PSD] Documents of Historic Interest Languages in common use Programming Tools Programming Libraries General Reference III. System Manager's Manual [SMM] Maintenance commands (8) System Installation and Administration .DE .LP References to individual documents are given as ``volume:document'', thus USD:1 refers to the first document in the ``User's Supplementary Documents''. References to manual pages are given as ``\fIname\fP(section)'' thus .IR sh (1) refers to the shell manual entry in section 1. .LP The manual pages give descriptions of the features of the 4.4BSD system, as developed at the University of California at Berkeley. They do not attempt to provide perspective or tutorial information about the 4.4BSD operating system, its facilities, or its implementation. Various documents on those topics are contained in the ``\s-1UNIX\s+1 User's Supplementary Documents'' (USD), the ``\s-1UNIX\s+1 Programmer's Supplementary Documents'' (PSD), and ``\s-1UNIX\s+1 System Manager's Manual'' (SMM). In particular, for an overview see ``The \s-1UNIX\s+1 Time-Sharing System'' (PSD:1) by Ritchie and Thompson; for a tutorial see ``\s8\s-1UNIX\s+1\s10 for Beginners'' (USD:1) by Kernighan, and for an guide to the new features of this latest version, see ``Berkeley Software Architecture Manual (4.4 Edition)'' (PSD:5). .LP Within the area it surveys, this volume attempts to be timely, complete and concise. Where the latter two objectives conflict, the obvious is often left unsaid in favor of brevity. It is intended that each program be described as it is, not as it should be. Inevitably, this means that various sections will soon be out of date. .LP Commands are programs intended to be invoked directly by the user, in contrast to subroutines, that are intended to be called by the user's programs. User commands are described in URM section 1. Commands generally reside in directory .I /bin (for .IR bin \|ary programs). Some programs also reside in .I /\|usr/\|bin, .R to save space in .I /\|bin. .R These directories are searched automatically by the command interpreters. Additional directories that may be of interest include .I /\|usr/\|contrib/\|bin, .R which has contributed software .I /\|usr/\|old/\|bin, .R which has old but sometimes still useful software and .I /\|usr/\|local/\|bin, .R which contains software local to your site. .LP Games have been relegated to URM section 6 and .I /\|usr/\|games, .R to keep them from contaminating the more staid information of URM section 1. .LP Miscellaneous collection of information necessary for -writing in various specialized languages such as character codes, +writing in various specialized languages such as character codes, macro packages for typesetting, etc is contained in URM section 7. .LP System calls are entries into the BSD kernel. The system call interface is identical to a C language procedure call; the equivalent C procedures are described in PRM section 2. .LP An assortment of subroutines is available; they are described in PRM section 3. The primary libraries in which they are kept are described in .IR intro (3). The functions are described in terms of C. .LP PRM section 4 discusses the characteristics of each system ``file'' that refers to an I/O device. The names in this section refer to the HP300 device names for the hardware, instead of the names of the special files themselves. .LP The file formats and conventions (PRM section 5) documents the structure of particular kinds of files; for example, the form of the output of the loader and assembler is given. Excluded are files used by only one command, for example the assembler's intermediate files. .LP Commands and procedures intended for use primarily by the system administrator are described in SMM section 8. The files described here are almost all kept in the directory .I /\|etc. The system administration binaries reside in .I /\|sbin, .R and .I /\|usr/\|sbin. .LP Each section consists of independent entries of a page or so each. The name of the entry is in the upper corners of its pages, together with the section number. Entries within each section are alphabetized. The page numbers of each entry start at 1; -it is infeasible to number consecutively the pages of +it is infeasible to number consecutively the pages of a document like this that is republished in many variant forms. .LP All entries are based on a common format; not all subsections always appear. .RS .LP The .I name subsection lists the exact names of the commands and subroutines covered under the entry and gives a short description of their purpose. .LP The .IR synopsis "" summarizes the use of the program being described. A few conventions are used, particularly in the Commands subsection: .LP .RS .B Boldface words are considered literals, and are typed just as they appear. .LP Square brackets [ ] around an argument show that the argument is optional. When an argument is given as ``name'', it always refers to a file name. .LP Ellipses ``.\|.\|.'' are used to show that the previous argument-prototype may be repeated. .LP A final convention is used by the commands themselves. An argument beginning with a minus sign ``\-'' usually means that it is an option-specifying argument, even if it appears in a position where a file name could appear. Therefore, it is unwise to have files whose names begin with ``\-''. .LP .RE The .IR description "" subsection discusses in detail the subject at hand. .LP The .IR files "" subsection gives the names of files that are built into the program. .LP A .I see also .R subsection gives pointers to related information. .LP A .I diagnostics subsection discusses the diagnostic indications that may be produced. Messages that are intended to be self-explanatory are not listed. .LP The .IR bugs "" subsection gives known bugs and sometimes deficiencies. Occasionally the suggested fix is also described. .LP .RE At the beginning of URM is a table of contents, organized by section and alphabetically within each section. There is also a permuted index derived from the table of contents. Within each index entry, the title of the writeup to which it refers is followed by the appropriate section number in parentheses. This fact is important because there is considerable name duplication among the sections, arising principally from commands that exist only to exercise a particular system call. Finally, there is a list of documents on the inside back cover of each volume. .SH HOW TO GET STARTED .LP This section sketches the basic information you need to get started on \s-1UNIX\s+1; how to log in and log out, how to communicate through your terminal, and how to run a program. See ``\s-1UNIX\s+1 for Beginners'' in (USD:1) for a more complete introduction to the system. .LP .I -Logging in.\ \ +Logging in.\ \ .R Almost any ASCII terminal capable of full duplex operation and generating the entire character set can be used. You must have a valid user name, which may be obtained from the system administration. If you will be accessing \s-1UNIX\s+1 remotely, you will also need to obtain the telephone number for the system that you will be using. .LP After a data connection is established, the login procedure depends on what type of terminal you are using and local system conventions. If your terminal is directly connected to the computer, it generally runs at 9600 or 19200 baud. If you are using a modem running over a phone line, the terminal must be set at the speed appropriate for the modem you are using, typically 1200, 2400, or 9600 baud. The half/full duplex switch should always be set at full-duplex. (This switch will often have to be changed since many other systems require half-duplex). .LP When a connection is established, the system types ``login:''; you type your user name, followed by the ``return'' key. If you have a password, the system asks for it and suppresses echo to the terminal so the password will not appear. After you have logged in, the ``return'', ``new line'', or ``linefeed'' keys will give exactly the same results. A message-of-the-day usually greets you before your first prompt. .LP If the system types out a few garbage characters after you have established a data connection (the ``login:'' message at the wrong speed), depress the ``break'' (or ``interrupt'') key. This is a speed-independent signal to \s-1UNIX\s+1 that a different speed terminal is in use. The system then will type ``login:,'' this time at another speed. Continue depressing the break key until ``login:'' appears clearly, then respond with your user name. .LP For all these terminals, it is important that you type your name in lower-case if possible; if you type upper-case letters, \s-1UNIX\s+1 will assume that your terminal cannot generate lower-case letters and will translate all subsequent lower-case letters to upper case. .LP The evidence that you have successfully logged in is that a shell program will type a prompt (``$'' or ``%'') to you. (The shells are described below under ``How to run a program.'') .LP For more information, consult .IR tset (1), and .IR stty (1), which tell how to adjust terminal behavior; .IR getty (8) discusses the login sequence in more detail, and .IR tty (4) discusses terminal I/O. .LP .I -Logging out.\ \ +Logging out.\ \ .R There are three ways to log out: .IP By typing ``logout'' or an end-of-file indication (EOT character, control-D) to the shell. The shell will terminate and the ``login:'' message will appear again. .IP You can log in directly as another user by giving a .IR login (1) command. .IP If worse comes to worse, you can simply hang up the phone; but beware \- some machines may lack the necessary hardware to detect that the phone has been hung up. Ask your system administrator if this is a problem on your machine. .LP .I -How to communicate through your terminal.\ \ +How to communicate through your terminal.\ \ .R When you type characters, a gnome deep in the system gathers your characters and saves them in a secret place. The characters will not be given to a program until you type a return (or newline), as described above in .I Logging in. .R .LP \s-1UNIX\s+1 terminal I/O is full-duplex. It has full read-ahead, which means that you can type at any time, even while a program is typing at you. Of course, if you type during output, the printed output will have the input characters interspersed. However, whatever you type will be saved up and interpreted in correct sequence. There is a limit to the amount of read-ahead, but it is generous and not likely to be exceeded unless the system is in trouble. When the read-ahead limit is exceeded, the system throws away all the saved characters (or beeps, if your prompt was a ``%''). .LP The ^U (control-U) character in typed input kills all the preceding characters in the line, so typing mistakes can be repaired on a single line. Also, the delete character (DEL) or sometimes the backspace character (control-H) erases the last character typed. .IR Tset (1) or .IR stty (1) can be used to change these defaults. Successive uses of delete (or backspace) erases characters back to, but not beyond, the beginning of the line. DEL and ^U (control-U) can be transmitted to a program by preceding them with ^V (control-V). (So, to erase ^V (control-V), you need two deletes or backspaces). .LP An .I interrupt signal .R is sent to a program by typing ^C (control-C) or the ``break'' key which is not passed to programs. This signal generally causes whatever program you are running to terminate. It is typically used to stop a long printout that you do not want. However, programs can arrange either to ignore this signal altogether, or to be notified when it happens (instead of being terminated). The editor, for example, catches interrupts and stops what it is doing, instead of terminating, so that an interrupt can be used to halt an editor printout without losing the file being edited. The interrupt character can also be changed with .IR tset (1) or .IR stty (1). .LP It is also possible to suspend output temporarily using ^S (control-S) and later resume output with ^Q (control-Q). Output can be thrown away without interrupting the program by typing ^O (control-O); see .IR tty (4). .LP The .IR quit "" signal is generated by typing the \s8ASCII\s10 FS character. (FS appears many places on different terminals, most commonly as control-\e or control-\^|\^.) It not only causes a running program to terminate but also generates a file with the core image of the terminated process. Quit is useful for debugging. .LP Besides adapting to the speed of the terminal, \s-1UNIX\s+1 tries to be intelligent about whether you have a terminal with the newline function or whether it must be simulated with carriage-return and line-feed. In the latter case, all input carriage returns are turned to newline characters (the standard line delimiter) and both a carriage return and a line feed are echoed to the terminal. If you get into the wrong mode, the .IR reset (1) command will rescue you. If the terminal does not appear to be echoing anything that you type, it may be stuck in ``no-echo'' or ``raw'' mode. Try typing ``(control-J)reset(control-J)'' to recover. .LP Tab characters are used freely in \s-1UNIX\s+1 source programs. If your terminal does not have the tab function, you can arrange to have them turned into spaces during output, and echoed as spaces during input. The system assumes that tabs are set every eight columns. Again, the .IR tset (1) or .IR stty (1) command can be used to change these defaults. .IR Tset (1) can be used to set the tab stops automatically when necessary. .LP .I -How to run a program; the shells.\ \ +How to run a program; the shells.\ \ .R When you have successfully logged in, a program called a shell is listening to your terminal. The shell reads typed-in lines, splits them up into a command name and arguments, and executes the command. A command is simply an executable program. The shell looks in several system directories to find the command. You can also place commands in your own directory and have the shell find them there. There is nothing special about system-provided commands except that they are kept in a directory where the shell can find them. .LP The command name is always the first word on an input line; it and its arguments are separated from one another by spaces. .LP -When a program terminates, the shell will ordinarily regain control and type +When a program terminates, the shell will ordinarily regain control and type a prompt at you to show that it is ready for another command. .LP The shells have many other capabilities, that are described in detail in sections .IR sh (1) and .IR csh (1). If the shell prompts you with ``$'', then it is an instance of .IR sh (1), the original \s-1UNIX\s+1 shell. If it prompts with ``%'' then it is an instance of .IR csh (1), a shell written at Berkeley. The shells are different for all but the most simple terminal usage. Most users at Berkeley choose .IR csh (1) because of the .I history mechanism and the .I alias feature, that greatly enhance its power when used interactively. .I Csh also supports the job-control facilities; see .IR csh (1) or the Csh introduction in USD:4 for details. .LP You can change from one shell to the other by using the .I chpass (1) command, which takes effect at your next login. .LP .I -The current directory.\ \ +The current directory.\ \ .R \s-1UNIX\s+1 has a file system arranged as a hierarchy of directories. When the system administrator gave you a user name, they also created a directory for you (ordinarily with the same name as your user name). When you log in, any file name you type is by default in this directory. Since you are the owner of this directory, you have full permission to read, write, alter, or destroy its contents. Permissions to have your will with other directories and files will have been granted or denied to you by their owners. As a matter of observed fact, few \s-1UNIX\s+1 users protect their files from perusal by other users. .LP To change the current directory (but not the set of permissions you were endowed with at login) use .IR cd (1). .LP .I -Path names.\ \ +Path names.\ \ .R To refer to files not in the current directory, you must use a path name. Full path names begin with ``/\|'', the name of the root directory of the whole file system. After the slash comes the name of each directory containing the next sub-directory (followed by a ``/\|'') until finally the file name is reached. For example, .I /\^var/\^tmp/\^filex .R refers to the file .I filex .R in the directory .I tmp; tmp .R is itself a subdirectory of .I var; var .R springs directly from the root directory. .LP If your current directory has subdirectories, the path names of files therein begin with the name of the subdirectory with no prefixed ``/\|''. .LP A path name may be used anywhere a file name is required. .LP Important commands that modify the contents of files are .IR cp (1), .IR mv (1), and .IR rm (1), which respectively copy, move (i.e. rename) and remove files. -To find out the status of files or directories, use +To find out the status of files or directories, use .IR ls (1). See .IR mkdir (1) for making directories and .IR rmdir (1) for destroying them. .LP For a fuller discussion of the file system, see ``A Fast File System for \s-1UNIX\s+1'' (SMM:5) by McKusick, Joy, Leffler, and Fabry. It may also be useful to glance through PRM section 2, that discusses system calls, even if you do not intend to deal with the system at that level. .LP .I -Writing a program.\ \ +Writing a program.\ \ .R To enter the text of a source program into a \s-1UNIX\s+1 file, use the standard display editor .IR vi (1) or its \s-1WYSIWYG\s+1 counterparts .IR jove (1) and .IR emacs (1). (The old standard editor .IR ed (1) is also available.) The principle language in \s-1UNIX\s+1 is provided by the C compiler .IR cc (1). User contributed software in the latest release of the system supports the programming languages perl and C++. After the program text has been entered through the editor and written to a file, you can give the file to the appropriate language processor as an argument. The output of the language processor will be left on a file in the current directory named ``a.out''. If the output is precious, use .IR mv (1) to move it to a less exposed name after successful compilation. .LP When you have finally gone through this entire process without provoking any diagnostics, the resulting program can be run by giving its name to the shell in response to the shell (``$'' or ``%'') prompt. .LP Your programs can receive arguments from the command line just as system programs do, see ``\s-1UNIX\s+1 Programming - Second Edition'' (PSD:4), or for a more terse description .IR execve (2). .LP .I -Text processing.\ \ +Text processing.\ \ .R Almost all text is entered through an editor such as .IR vi (1), .IR jove (1), or .IR emacs (1). The commands most often used to write text on a terminal are: .IR cat (1), .IR more (1), and .IR nroff (1). .LP The .IR cat (1) command simply dumps \s8ASCII\s10 text on the terminal, with no processing at all. .IR More (1) is useful for preventing the output of a command from scrolling off the top of your screen. It is also well suited to perusing files. .IR Nroff (1) is an elaborate text formatting program. Used naked, it requires careful forethought, but for ordinary documents it has been tamed; see .IR me (7) and .IR ms (7). .LP .IR Groff (1) converts documents to postscript for output to a Laserwriter or Phototypesetter. -It is similar to +It is similar to .IR nroff (1), and often works from exactly the same source text. It was used to produce this manual. .LP .IR Script (1) lets you keep a record of your session in a file, which can then be printed, mailed, etc. It provides the advantages of a hard-copy terminal even when using a display terminal. .LP .I -Status inquiries.\ \ +Status inquiries.\ \ .R Various commands exist to provide you with useful information. .IR w (1) prints a list of users currently logged in, and what they are doing. .IR date (1) prints the current time and date. .IR ls (1) will list the files in your directory or give summary information about particular files. .LP .I -Surprises.\ \ +Surprises.\ \ .R Certain commands provide inter-user communication. Even if you do not plan to use them, it would be well to learn something about them, because someone else may aim them at you. .LP To communicate with another user currently logged in, .IR write (1) or .IR talk (1) is used; .IR mail (1) will leave a message whose presence will be announced to another user when they next log in. The write-ups in the manual also suggest how to respond to the these commands if you are a target. .LP If you use .IR csh (1) the key ^Z (control-Z) will cause jobs to ``stop''. If this happens before you learn about it, you can simply continue by saying ``fg'' (for foreground) to bring the job back. .LP We hope that you will come to enjoy using the BSD system. Although it is very large and contains many commands, you can become very productive using only a small subset of them. As your needs expand to doing new tasks, you will almost always find that the system has the facilities that you need to accomplish them easily and quickly. .LP Most importantly, the source code to the BSD system is cheaply available to anyone that wants it. On many BSD systems, it can be found in the directory .IR /\|usr/\|src . You may simply want to find out how something works or fix some important bug without waiting months for your vendor to respond. It is also particularly useful if you want to grab another piece of code to bootstrap a new project. Provided that you retain the copyrights and acknowledgements at the top of each file, you are free to redistribute your work for fun or profit. Naturally, we hope that you will allow others to also redistribute your code, though you are not required to do so unless you use copyleft code (which is primarily found in the software contributed from the Free Software Foundation and is clearly identified). .LP Good luck and enjoy BSD. .OH '''\s10- % -\s0' .EH '\s10- % -\s0''' .if o .bp \& .bp .EF '\s9\\\\*(Dt''\\\\*(Ed\s0' .OF '\s9\\\\*(Ed''\\\\*(Dt\s0' .ce \s+4\fBLIST \|OF \|MANUAL \|PAGES\fP\s-4 .nr x 0.5 .in +\nxi .nf .ta \n(.lu-\nxuR .de xx \\$1\f3 \a \fP\\$2 .. .de t .sp 1v .ne .5i .cs 3 .ti -\\nxi .ss 18 \f3\s9\\$2. \\$3\s0\fP .ss 12 .if t .sp .5v .cs 3 36 .ds Ed Section \\$2 .ds Dt \\$3 .so \\$1 .. .t toc1 1 "Commands and Application Programs" .t toc2 2 "System Calls" .t toc3 3 "C Library Subroutines" .t toc4 4 "Special Files" .t toc5 5 "File Formats" .t toc6 6 "Games" .t toc7 7 "Miscellaneous" .t toc8 8 "System Maintenance" .in -\nxi .cs 3 .ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i 6.5i .if o .bp \& .bp \& .OH '\s9\fIPermuted Index\fP''- % -\s0' .EH '\s9- % -''\fIPermuted Index\fP\s0' .ds Ed 4.4BSD .ds Dt June \|1993 .ce \s+4\fBPERMUTED \|INDEX\fP\s-4 .sp 1 .nr PS 8 .nr VS 9 .LP .\" backup from slotput 1, slot, 2 .tr ~ .nf .cs 3 36 .de xx .ds s1\" .if \w\\$2 .ds s1 ~~\" .ds s2 ~~~\" .ds s3\" .if \w\\$4 .ds s3 ~~\" .ds s4 ~~\" .ds s5 ~~\" .ds y \\*(s4\f3\fP\\*(s5 .ta 6i-\w\\*(s5u \h"3i-\w\\$1\\*(s1\\$2\\*(s2u"\\$1\\*(s1\\$2\\*(s2\\$3\\*(s3\\$4\\*y\\$5 .. .so ptxx .cs 3 .ta .5i 1i 1.5i 2i 2.5i 3i 3.5i 4i 4.5i 5i 5.5i 6i 6.5i Index: stable/4/share/man/man4/an.4 =================================================================== --- stable/4/share/man/man4/an.4 (revision 139702) +++ stable/4/share/man/man4/an.4 (revision 139703) @@ -1,122 +1,122 @@ .\" Copyright (c) 1997, 1998, 1999 .\" Bill Paul . 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 Bill Paul. .\" 4. Neither the name of the author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY Bill Paul 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 Bill Paul OR THE VOICES IN HIS HEAD .\" 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$ .\" .Dd September 10, 1999 .Dt AN 4 .Os .Sh NAME .Nm an .Nd "Aironet Communications 4500/4800 wireless network adapter driver" .Sh SYNOPSIS .Cd "device an" .Cd "device an0 at isa? port 0x140 irq 5" .Sh DESCRIPTION The .Nm driver provides support for Aironet Communications 4500 and 4800 wireless network adapters. This includes the ISA, PCI and PCMCIA varieties. The 4500 series adapters operate at 1 and 2Mbps while the 4800 series can operate at 1, 2, 5.5 and 11Mbps. The ISA, PCI and PCMCIA devices are all based on the same core PCMCIA modules and all have the same programming interface, however unlike the Lucent WaveLAN/IEEE cards, the ISA and PCI cards appear to the host as normal ISA and PCI devices and do not require any PCCARD support. .Pp The PCMCIA Aironet cards require PCCARD support, including the kernel -.Xr pccard 4 +.Xr pccard 4 driver support and the .Xr pccardd 8 daemon. ISA cards can either be configured to use ISA Plug and Play or to use a particular I/O address and IRQ by properly setting the DIP switches on the board. (The default switch setting is for Plug and Play.) The .Nm driver has Plug and Play support and will work in either configuration, however when using a hard-wired I/O address and IRQ, the driver configuration and the NIC's switch settings must agree. PCI cards require no switch settings of any kind and will be automatically probed and attached. .Pp All host/device interaction with the Aironet cards is via programmed I/O. The Aironet devices support 802.11 and 802.3 frames, power management, BSS (infrastructure) and IBSS (ad-hoc) operation modes. The .Nm driver encapsulates all IP and ARP traffic as 802.11 frames, however it can receive either 802.11 or 802.3 frames. Transmit speed is selectable between 1Mbps, 2Mbps, 5.5Mbps, 11Mbps or "auto" (the NIC automatically chooses the best speed). .Pp By default, the .Nm driver configures the Aironet card for infrastructure operation. .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh DIAGNOSTICS .Bl -diag .It "an%d: init failed" The Aironet card failed to become ready after an initialization command was issued. .It "an%d: failed to allocate %d bytes on NIC" The driver was unable to allocate memory for transmit frames in the NIC's on-board RAM. .It "an%d: device timeout" The Aironet card failed to generate an interrupt to acknowledge a transmit command. .El .Sh SEE ALSO .Xr arp 4 , .Xr miibus 4 , .Xr netintro 4 , .Xr ancontrol 8 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 4.0 . .Sh AUTHORS The .Nm driver was written by .An Bill Paul Aq wpaul@ee.columbia.edu . Index: stable/4/share/man/man4/ata.4 =================================================================== --- stable/4/share/man/man4/ata.4 (revision 139702) +++ stable/4/share/man/man4/ata.4 (revision 139703) @@ -1,260 +1,260 @@ .\" .\" Copyright (c) 2000 Jeroen Ruigrok van der Werven .\" Copyright (c) 2000,2001,2002 Søren Schmidt .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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$ .\" .Dd January 27, 2000 .Dt ATA 4 .Os .Sh NAME .Nm ata , .Nm acd , .Nm ad , .Nm afd , .Nm ast .Nd generic ATA/ATAPI disk controller driver .Sh SYNOPSIS For ISA based ATA/ATAPI support: .Cd device isa .Cd device ata0 at isa? port IO_WD1 irq 14 .Cd device ata1 at isa? port IO_WD2 irq 15 .Pp For PCI based ATA/ATAPI support: .Cd device pci .Cd device ata .Pp To support ATA compliant disk drives: .Cd device atadisk .Pp To support ATAPI CD-ROM, CDR, CDRW, DVD-ROM and DVD-RAM drives: .Cd device atapicd .Pp To support ATAPI floppy drives, such as the ZIP and LS120: .Cd device atapifd .Pp To support ATAPI tape drives: .Cd device atapist .Pp The following tunables are settable from the loader: .Bl -ohang .It Va hw.ata.ata_dma set to 1 for DMA access, 0 for PIO (default is DMA). .It Va hw.ata.atapi_dma set to 1 for DMA access, 0 for PIO (default is PIO). .It Va hw.ata.wc set to 1 to enable Write Caching, 0 to disable (default is enabled). (WARNING: might cause data loss on power failures.) .It Va hw.ata.tags set to 1 to enable Tagged Queuing support, 0 to disable (default is disabled). (Only IBM DPTA, DTLA, ICxxxxxxAT, ICxxxxxxAV drives support that.) .It Va hw.ata.suspend sets the disk's automatic standby timer to the specified number of seconds. The value 0 (the default) disables the automatic standby timer. The precision of the timer specification is 5 seconds for values up to 20 minutes, and 30 minutes for values up to 5.5 hours. Higher values set the timer to a period between 8 and 12 hours. Some drives may use a non-standard, vendor-specific encoding scheme for the timer value. In such a case the driver will log a message to that effect (timer value is vendor-specific); -consult the drive's documentation for the value to use in the +consult the drive's documentation for the value to use in the tunable parameter. .El .Sh DESCRIPTION This driver provides access to ATA (IDE) and SerialATA disk drives, ATAPI CD-ROM and DVD drives, ZIP drives and tape streamers connected to controllers according to the ATA and ATAPI standards. These devices are also commonly known as IDE or EIDE devices. .Pp The currently supported controllers with their maximum speed include: .Pp .Bl -tag -width "Promise Ultra/Fasttrak-100 TX2/TX2000" -compact .It Acerlabs Aladdin Ultra DMA 100 (UDMA5), 100 MB/sec (depending on model, max stated at boot) .It AMD 756 Ultra DMA 66 (UDMA4), 66 MB/sec .It AMD 766 Ultra DMA 100 (UDMA5), 100 MB/sec .It CMD 646 DMA 2 (WDMA2), 16 MB/sec .It CMD 648 Ultra DMA 66 (UDMA4), 66 MB/sec .It CMD 649 Ultra DMA 100 (UDMA5), 100 MB/sec .It Cypress 82C693 DMA 2 (WDMA2), 16 MB/sec .It Cyrix 5530 Ultra DMA 33 (UDMA2), 33 MB/sec .It HighPoint HPT366 Ultra DMA 66 (UDMA4), 66 MB/sec .It HighPoint HPT370 Ultra DMA 100 (UDMA5), 100 MB/sec .It HighPoint HPT372 Ultra DMA 133 (UDMA6), 133 MB/sec .It HighPoint HPT374 Ultra DMA 133 (UDMA6), 133 MB/sec .It Intel PIIX DMA 2 (WDMA2), 16 MB/sec .It Intel PIIX3 DMA 2 (WDMA2), 16 MB/sec .It Intel PIIX4 Ultra DMA 33 (UDMA2), 33 MB/sec .It Intel ICH0 Ultra DMA 33 (UDMA2), 33 MB/sec .It Intel ICH Ultra DMA 66 (UDMA4), 66 MB/sec .It Intel ICH2 Ultra DMA 100 (UDMA5), 100 MB/sec .It Intel ICH3 Ultra DMA 100 (UDMA5), 100 MB/sec .It Intel ICH4 Ultra DMA 100 (UDMA5), 100 MB/sec .It Intel ICH5 SATA 150, 150 MB/sec .It Promise Ultra/Fasttrak-33 Ultra DMA 33 (UDMA2), 33 MB/sec .It Promise Ultra/Fasttrak-66 Ultra DMA 66 (UDMA4), 66 MB/sec .It Promise Ultra/Fasttrak-100 Ultra DMA 100 (UDMA5), 100 MB/sec .It Promise Ultra/Fasttrak-100 TX2/TX4 Ultra DMA 100 (UDMA5), 100 MB/sec .It Promise Ultra/Fasttrak-133 TX2/TX2000 Ultra DMA 133 (UDMA6), 133 MB/sec .It ServerWorks ROSB4 Ultra DMA 33 (UDMA2), 33 MB/sec .It ServerWorks CSB5 Ultra DMA 100 (UDMA5), 100 MB/sec (depending on model, max stated at boot) .It Sil 0680 Ultra DMA 133 (UDMA6), 133 MB/sec (depending on model, max stated at boot) .It SiS 5591 Ultra DMA 100 (UDMA5), 100 MB/sec (depending on model, max stated at boot) .It VIA 82C586 Ultra DMA 33 (UDMA2), 33 MB/sec .It VIA 82C596 Ultra DMA 66 (UDMA4), 66 MB/sec (depending on model, max stated at boot) .It VIA 82C686a Ultra DMA 66 (UDMA4), 66 MB/sec .It VIA 82C686b Ultra DMA 100 (UDMA5), 100 MB/sec .It VIA 8233/8235 Ultra DMA 133 (UDMA6), 133 MB/sec (depending on model, max stated at boot) .It VIA 8237 SATA 150, 150 MB/sec .El .Pp All unknown chipsets are supported at the maximum speed of 16 MB/sec. .Pp The .Nm driver also allows for changes to the transfer mode of the devices at a later time when the system is up and running, see .Xr atacontrol 8 . .Pp The driver attempts to set the maximum performance transfer mode on your disk -drives by selecting the highest possible DMA mode. However the +drives by selecting the highest possible DMA mode. However the .Nm -driver sometimes issue the message +driver sometimes issue the message "DMA limited to UDMA33, non-ATA66 cable or device", if the cable is ATA66 (or above) compliant, it is because the other device on this channel states it can only accept upto UDMA2/ATA33 signals. ATAPI devices are left in PIO mode because DMA problems are common despite the device specifications. You can always try to set DMA mode on an ATAPI device using .Xr atacontrol 8 , but be aware that your hardware might .Em not support it and can .Em hang the system. .Sh FILES .Bl -tag -width "/sys/i386/conf/GENERIC " -compact .It Pa /dev/ad* ATA disk device nodes .It Pa /dev/acd* ATAPI CD-ROM device nodes .It Pa /dev/afd* ATAPI floppy drive device nodes .It Pa /dev/ast* ATAPI tape drive device nodes .It Pa /sys/i386/conf/GENERIC sample generic kernel config file for .Nm based systems .El .Sh NOTES Static numbering (enabled with the .Dv ATA_STATIC_ID kernel option) reserves a number for each possibly connected disk, even when not present. This may result in odd situations where, for example, ad0 and ad2 exist in the absence of ad1. The advantage is that the addition of the formerly absent drive does not cause the numbers of the other drives to change. .Pp The .Nm driver does not support MFM/RLL/ESDI (ST-506) style disks. .Pp Remember that in order to use UDMA4 (and above) mode you .Em have to use a special 80 conductor cable, and the driver tries to determine if you have such a cable attached before setting UDMA4 mode. .Pp The use of UDMA4(66MHz) and higher together with non-UDMA4 devices on the same ATA channel is not recommended, unless they are run at the non-UDMA4 device's lower speed. The driver has been designed to handle that kind of setup but lots of older devices do not like this. .Sh SEE ALSO .Xr atacontrol 8 , .Xr burncd 8 .Sh HISTORY The .Nm driver first appeared in .Fx 4.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An S\(/oren Schmidt .Aq sos@FreeBSD.org . .Pp This manual page was written by .An Jeroen Ruigrok van der Werven .Aq asmodai@FreeBSD.org and .An S\(/oren Schmidt .Aq sos@FreeBSD.org . Index: stable/4/share/man/man4/bridge.4 =================================================================== --- stable/4/share/man/man4/bridge.4 (revision 139702) +++ stable/4/share/man/man4/bridge.4 (revision 139703) @@ -1,199 +1,199 @@ .\" .\" $FreeBSD$ .\" .Dd February 15, 2002 .Dt BRIDGE 4 .Os .Sh NAME .Nm bridge .Nd bridging support .Sh SYNOPSIS .Cd "options BRIDGE" .Cd kldload /modules/bridge.ko .Sh DESCRIPTION .Fx supports bridging on Ethernet-type interfaces, including VLANs. Bridging support can be either compiled into the kernel, or loaded at runtime as a kernel module. .Pp A single .Fx host can do bridging on independent sets of interfaces, which are called .Ar clusters . Each cluster connects a set of interfaces, and is identified by a "cluster-id" which is a number in the range 1..65535. A cluster in fact is very similar to what commercial switches call a "VLAN". Note however that there is no relation whatsoever between the cluster-id and the IEEE 802.1q VLAN-id which appears in the header of packets transmitted on the wire. In fact, in most cases there is no relation between the so-called "VLAN identifier" used in most commercial switches, and the IEEE 802.1q VLAN-id. .Pp By putting both physical and logical (vlanX) interfaces in the same cluster, a FreeBSD box can also implement what in commercial terms is called a "trunk" interface. This means packets coming from one of the interfaces in the cluster, will appear on the wire on the "parent" interfaces of any vlan interface belonging to the cluster, with the proper VLAN tag. Similarly, packets coming from a parent interface, will have the VLAN tag stripped and will be forwarded to other interfaces on the same cluster. See the .Sx EXAMPLES section for more details. .Pp Runtime operation of the .Nm is controlled by several .Xr sysctl 8 variables, as follows. .Pp .Bl -tag -width indent .It Va net.link.ether.bridge set to .Li 1 to enable bridging, set to .Li 0 to disable it. .Pp .It Va net.link.ether.bridge_ipfw set to .Li 1 to enable .Xr ipfw 8 filtering on bridged packets. Note that .Xr ipfw 8 rules only apply to IP packets. Non-IP packets are accepted by default. See the .Sx BUGS section and the .Xr ipfw 8 manpage for more details on the interaction of bridging and the firewall. .Pp .It Va net.link.ether.bridge_cfg contains a list of interfaces on which bridging is to be performed. Interfaces are separated by spaces, commas or tabs. Each interface can be optionally followed by a colon and an integer indicating the cluster it belongs to (defaults to 1 if the cluster-id is missing), e.g. .Pp .Ar dc0:1,dc1,vlan0:3 dc2:3 .Pp will put dc0 and dc1 in cluster number 1, and vlan0 and dc2 in cluster number 3. See the .Sx EXAMPLES section for more examples. .Pp The list of interfaces is rescanned every time the list is modified, bridging is enabled, or new interfaces are created or destroyed. Interfaces that are in the list but cannot be used for bridging (because they are non-existing, or not Ethernet or VLAN) are not used and a warning message is generated. .Pp .El .Pp Bridging requires interfaces to be put in promiscuous mode, and transmit packets with Ethernet source addresses. Some interfaces (e.g. .Xr wi 4 ) do not support this functionality. Also, bridging is not compatible with interfaces which use hardware loopback, because there is no way to tell locally generated packets from externally generated ones. .Pp .Sh EXAMPLES A simple bridge configuration with three interfaces in the same cluster can be set as follows. No cluster-id is specified here, which will cause the interfaces to appear as part of cluster #1. .Pp .Dl sysctl net.link.ether.bridge_cfg=dc0,dc1,fxp1 .Pp If you do not know what actual interfaces will be present on your system, you can just put all existing interfaces in the configuration, as follows: .Pp .Dl sysctl net.link.ether.bridge_cfg="`ifconfig -l`" .Pp This will result in a space-separated list of interfaces. Out of the list, only Ethernet or VLAN interfaces will be used for bridging, whereas for others the kernel will produce a warning message. .Pp More complex configurations can be used to create multiple clusters, e.g. .Pp .Dl sysctl net.link.ether.bridge_cfg=dc0:3,dc1:3,fxp0:4,fxp1:4 .Pp will create two completely independent clusters. .Pp Finally, interesting configurations involve vlans and parent interfaces. As an example, the following configuration will use interface dc0 as a "trunk" interface, and pass packets for 802.1q vlans 10 and 20 to physical interfaces dc1 and dc2: .Pp .Dl sysctl net.link.ether.bridge_cfg=vlan0:34,dc1:34,vlan1:56,dc2:56 .Dl ifconfig vlan0 vlan 10 vlandev dc0 .Dl ifconfig vlan1 vlan 20 vlandev dc0 .Pp Note how there is no relation between the 802.1q vlan identifiers (10 and 20) and the cluster-id's (34 and 56) used in the bridge_cfg variable. .Pp Note also that the trunk interface does not even appear in the bridge_cfg, as vlan tag insertion/removal is performed by the .Xr vlan 4 devices. When using vlan devices, care must be taken by not creating loops between these devices and their parent interfaces. .Pp .Sh BUGS Care must be taken not to construct loops in the .Nm topology. The kernel supports only a primitive form of loop detection, by disabling some interfaces when a loop is detected. No support for a daemon running the spanning tree algorithm is currently provided. .Pp With bridging active, interfaces are in promiscuous mode, thus causing some load on the system to receive and filter out undesired traffic. .Pp When passing bridged packets to .Xr ipfw 8 , remember that only IP packets are passed to the firewall, while other packets are silently accepted. Also remember that bridged packets are accepted after the first pass through the firewall irrespective of the setting of the sysctl variable .Nm net.inet.ip.fw.one_pass , and that some .Nm ipfw actions such as -.Nm divert +.Nm divert do not apply to bridged packets. It might be useful to have a rule of the form .Pp .Dl skipto 20000 ip from any to any bridged .Pp near the beginning of your ruleset to implement specific rulesets for bridged packets. .Sh SEE ALSO .Xr ip 4 , .Xr ng_bridge 4 , .Xr vlan 4 , .Xr ipfw 8 , .Xr sysctl 8 .Sh HISTORY Bridging was introduced in .Fx 2.2.8 by .An Luigi Rizzo Aq luigi@iet.unipi.it . Index: stable/4/share/man/man4/cd.4 =================================================================== --- stable/4/share/man/man4/cd.4 (revision 139702) +++ stable/4/share/man/man4/cd.4 (revision 139703) @@ -1,526 +1,526 @@ .\" Copyright (c) 1996 .\" Julian Elischer . 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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$ .\" .Dd September 2, 2003 .Dt CD 4 .Os .Sh NAME .Nm cd .Nd SCSI CD-ROM driver .Sh SYNOPSIS .Cd device cd .Cd device cd1 at scbus0 target 4 unit 0 .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11"" .Sh DESCRIPTION The .Nm driver provides support for a .Tn SCSI .Tn CD-ROM (Compact Disc-Read Only Memory) drive. In an attempt to look like a regular disk, the .Nm driver synthesizes a partition table, with one partition covering the entire .Tn CD-ROM . It is possible to modify this partition table using .Xr disklabel 8 , but it will only last until the .Tn CD-ROM is unmounted. In general the interfaces are similar to those described by .Xr ad 4 and .Xr da 4 . .Pp As the .Tn SCSI adapter is probed during boot, the .Tn SCSI bus is scanned for devices. Any devices found which answer as CDROM (type 5) or WORM (type 4) type devices will be `attached' to the .Nm driver. Prior to .Fx 2.1 , the first device found will be attached as .Li cd0 the next, .Li cd1 , etc. Beginning in .Fx 2.1 it is possible to specify what cd unit a device should come on line as; refer to .Xr scsi 4 for details on kernel configuration. .Pp The .Cd target string is followed by the device's standard .Tn SCSI device ID number. The .Cd unit string is followed by the Logical Unit Number .Pq Tn LUN of the .Tn SCSI device's sub-device, if any, or zero. .Pp The system utility .Xr disklabel 8 may be used to read the synthesized disk label structure, which will contain correct figures for the size of the .Tn CD-ROM should that information be required. .Sh KERNEL CONFIGURATION Any number of .Tn CD-ROM devices may be attached to the system regardless of system configuration as all resources are dynamically allocated. .Sh IOCTLS The following .Xr ioctl 2 calls which apply to .Tn SCSI .Tn CD-ROM drives are defined in the header files .Aq Pa sys/cdio.h and .Aq Pa sys/disklabel.h . .Pp .Bl -tag -width CDIOCREADSUBCHANNEL .It Dv DIOCGDINFO .It Dv DIOCSDINFO .Pq Li "struct disklabel" Read or write the in-core copy of the disklabel for the drive. The disklabel is initialized with information read from the scsi inquiry commands, and should be the same as the information printed at boot. This structure is defined in .Xr disklabel 5 . .It Dv CDIOCCAPABILITY .Pq Li "struct ioc_capability" Retrieve information from the drive on what features it supports. The information is returned in the following structure: .Bd -literal -offset indent struct ioc_capability { u_long play_function; #define CDDOPLAYTRK 0x00000001 /* Can play tracks/index */ #define CDDOPLAYMSF 0x00000002 /* Can play msf to msf */ #define CDDOPLAYBLOCKS 0x00000004 /* Can play range of blocks */ #define CDDOPAUSE 0x00000100 /* Output can be paused */ #define CDDORESUME 0x00000200 /* Output can be resumed */ #define CDDORESET 0x00000400 /* Drive can be completely reset */ #define CDDOSTART 0x00000800 /* Audio can be started */ #define CDDOSTOP 0x00001000 /* Audio can be stopped */ #define CDDOPITCH 0x00002000 /* Audio pitch can be changed */ u_long routing_function; #define CDREADVOLUME 0x00000001 /* Volume settings can be read */ #define CDSETVOLUME 0x00000002 /* Volume settings can be set */ #define CDSETMONO 0x00000100 /* Output can be set to mono */ #define CDSETSTEREO 0x00000200 /* Output can be set to stereo (def) */ #define CDSETLEFT 0x00000400 /* Output can be set to left only */ #define CDSETRIGHT 0x00000800 /* Output can be set to right only */ #define CDSETMUTE 0x00001000 /* Output can be muted */ #define CDSETPATCH 0x00008000 /* Direct routing control allowed */ u_long special_function; #define CDDOEJECT 0x00000001 /* The tray can be opened */ #define CDDOCLOSE 0x00000002 /* The tray can be closed */ #define CDDOLOCK 0x00000004 /* The tray can be locked */ #define CDREADHEADER 0x00000100 /* Can read Table of Contents */ #define CDREADENTRIES 0x00000200 /* Can read TOC Entries */ #define CDREADSUBQ 0x00000200 /* Can read Subchannel info */ #define CDREADRW 0x00000400 /* Can read subcodes R-W */ #define CDHASDEBUG 0x00004000 /* The tray has dynamic debugging */ }; .Ed .It Dv CDIOCPLAYTRACKS .Pq Li "struct ioc_play_track" Start audio playback given a track address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_track { u_char start_track; u_char start_index; u_char end_track; u_char end_index; }; .Ed .It Dv CDIOCPLAYBLOCKS .Pq Li "struct ioc_play_blocks" Start audio playback given a block address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_blocks { int blk; int len; }; .Ed .It Dv CDIOCPLAYMSF .Pq Li "struct ioc_play_msf" Start audio playback given a `minutes-seconds-frames' address and length. The structure is defined as follows: .Bd -literal -offset indent struct ioc_play_msf { u_char start_m; u_char start_s; u_char start_f; u_char end_m; u_char end_s; u_char end_f; }; .Ed .It Dv CDIOCREADSUBCHANNEL .Pq Li "struct ioc_read_subchannel" Read information from the subchannel at the location specified by this structure: .Bd -literal -offset indent struct ioc_read_subchannel { u_char address_format; #define CD_LBA_FORMAT 1 #define CD_MSF_FORMAT 2 u_char data_format; #define CD_SUBQ_DATA 0 #define CD_CURRENT_POSITION 1 #define CD_MEDIA_CATALOG 2 #define CD_TRACK_INFO 3 u_char track; int data_len; struct cd_sub_channel_info *data; }; .Ed .It Dv CDIOREADTOCHEADER .Pq Li "struct ioc_toc_header" Return summary information about the table of contents for the mounted .Tn CD-ROM . The information is returned into the following structure: .Bd -literal -offset indent struct ioc_toc_header { u_short len; u_char starting_track; u_char ending_track; }; .Ed .It Dv CDIOREADTOCENTRYS .Pq Li "struct ioc_read_toc_entry" Return information from the table of contents entries mentioned. .Pq Yes, this command name is misspelled. The argument structure is defined as follows: .Bd -literal -offset indent struct ioc_read_toc_entry { u_char address_format; u_char starting_track; u_short data_len; struct cd_toc_entry *data; }; .Ed The requested data is written into an area of size .Li data_len and pointed to by .Li data . .It Dv CDIOCSETPATCH .Pq Li "struct ioc_patch" Attach various audio channels to various output channels. The argument structure is defined thusly: .Bd -literal -offset indent struct ioc_patch { u_char patch[4]; /* one for each channel */ }; .Ed .It Dv CDIOCGETVOL .It Dv CDIOCSETVOL .Pq Li "struct ioc_vol" Get (set) information about the volume settings of the output channels. The argument structure is as follows: .Bd -literal -offset indent struct ioc_vol { u_char vol[4]; /* one for each channel */ }; .Ed .It Dv CDIOCSETMONO Patch all output channels to all source channels. .It Dv CDIOCSETSTEREO Patch left source channel to the left output channel and the right source channel to the right output channel. .It Dv CDIOCSETMUTE Mute output without changing the volume settings. .It Dv CDIOCSETLEFT .It Dv CDIOCSETRIGHT Attach both output channels to the left (right) source channel. .It Dv CDIOCSETDEBUG .It Dv CDIOCCLRDEBUG Turn on (off) debugging for the appropriate device. .It Dv CDIOCPAUSE .It Dv CDIOCRESUME Pause (resume) audio play, without resetting the location of the read-head. .It Dv CDIOCRESET Reset the drive. .It Dv CDIOCSTART .It Dv CDIOCSTOP Tell the drive to spin-up (-down) the .Tn CD-ROM . .It Dv CDIOCALLOW .It Dv CDIOCPREVENT Tell the drive to allow (prevent) manual ejection of the .Tn CD-ROM disc. Not all drives support this feature. .It Dv CDIOCEJECT Eject the .Tn CD-ROM . .It Dv CDIOCCLOSE Tell the drive to close its door and load the media. Not all drives support this feature. .It Dv CDIOCPITCH .Pq Li "struct ioc_pitch" For drives that support it, this command instructs the drive to play the audio at a faster or slower rate than normal. Values of .Li speed between -32767 and -1 result in slower playback; a zero value indicates normal speed; and values from 1 to 32767 give faster playback. Drives with less than 16 bits of resolution will silently ignore less-significant bits. The structure is defined thusly: .Bd -literal -offset indent struct ioc_pitch { short speed; }; .Ed .El .Sh NOTES When a .Tn CD-ROM is changed in a drive controlled by the .Nm driver, then the act of changing the media will invalidate the disklabel and information held within the kernel. To stop corruption, all accesses to the device will be discarded until there are no more open file descriptors referencing the device. During this period, all new open attempts will be rejected. When no more open file descriptors reference the device, the first next open will load a new set of parameters (including disklabel) for the drive. .Pp The audio code in the .Nm driver only support .Tn SCSI-2 standard audio commands. Because many .Tn CD-ROM manufacturers have not followed the standard, there are many .Tn CD-ROM drives for which audio will not work. Some work is planned to support some of the more common `broken' .Tn CD-ROM drives; however, this is not yet under way. .Pp The .Nm driver attempts to automatically determine whether the drive it is talking to supports 6 byte or 10 byte MODE SENSE/MODE SELECT operations. Many .Tn SCSI drives only support 6 byte commands, and .Tn ATAPI drives only support 10 byte commands. The .Nm driver first attempts to determine whether the protocol in use typically supports 6 byte commands by issuing a CAM Path Inquiry CCB. It will then default to 6 byte or 10 byte commands as appropriate. After that, the .Nm driver defaults to using 6 byte commands (assuming the protocol the drive speaks claims to support 6 byte commands), until one fails with a -.Tn SCSI +.Tn SCSI ILLEGAL REQUEST error. Then it tries the 10 byte version of the command to see if that works instead. Users can change the default via per-drive sysctl variables and loader tunables. The variable names are the same in both instances: .Pp .Va kern.cam.cd.%d.minimum_cmd_size .Pp -Where +Where .Dq %d is the unit number of the drive in question. Valid minimum command sizes are 6 and 10. Any value above 6 will be rounded to 10, and any value below 6 will be rounded to 6. .Sh CHANGER OPERATION This driver has built-in support for LUN-based CD changers. A LUN-based CD changer is a drive that can hold two or more CDs, but only has one CD player mechanism. Each CD in the drive shows up as a separate logical unit on the .Tn SCSI bus. The .Nm driver automatically recognizes LUN-based changers, and routes commands for changers through an internal scheduler. The scheduler prevents changer "thrashing", which is caused by sending commands to different LUNs in the changer at the same time. .Pp The scheduler honors minimum and maximum time quanta that the driver will spend on a particular LUN. The minimum time is the guaranteed minimum amount of time that the driver will spend on a given LUN, even if there is no outstanding I/O for that LUN. The maximum time is the maximum amount of time the changer will spend on a LUN if there is outstanding I/O for another LUN. If there is no outstanding I/O for another LUN, the driver will allow indefinite access to a given LUN. .Pp The minimum and maximum time quanta are configurable via kernel options and also via sysctl and kernel tunable variables. The kernel options are: .Pp .Bl -item -compact .It .Cd "options ""CHANGER_MIN_BUSY_SECONDS=3""" .It .Cd "options ""CHANGER_MAX_BUSY_SECONDS=11""" .El .Pp The sysctl/kernel tunable variables are: .Pp .Bl -item -compact .It .Va kern.cam.cd.changer.min_busy_seconds .It .Va kern.cam.cd.changer.max_busy_seconds .El .Pp It is suggested that the user try experimenting with the minimum and maximum timeouts via the sysctl variables to arrive at the proper values for your changer. Once you have settled on the proper timeouts for your changer, you can then put them in your kernel config file. .Pp If your system does have a LUN-based changer, you may notice that the probe messages for the various LUNs of the changer will continue to appear while the boot process is going on. This is normal, and is caused by the changer scheduling code. .Sh FILES .Bl -tag -width /dev/cd[0-9][a-h] -compact .It Pa /dev/cd[0-9][a-h] raw mode .Tn CD-ROM devices .El .Sh DIAGNOSTICS None. .Sh SEE ALSO .Xr da 4 , .Xr scsi 4 , .Xr disklabel 5 , .Xr disklabel 8 , .Xr cd 9 .Sh BUGS The names of the structures used for the third argument to .Fn ioctl were poorly chosen, and a number of spelling errors have survived in the names of the .Fn ioctl commands. .Pp There is no mechanism currently to set different minimum and maximum timeouts for different CD changers; the timeout values set by the kernel options or the sysctl variables apply to all LUN-based CD changers in the system. It is possible to implement such support, but the sysctl implementation at least would be rather inelegant, because of the current inability of the sysctl code to handle the addition of nodes after compile time. Thus, it would take one dynamically sized sysctl variable and a userland utility to get/set the timeout values. Implementation of separate timeouts for different CD devices in the kernel config file would likely require modification of .Xr config 8 to support the two timeouts when hardwiring .Nm devices. .Sh HISTORY This .Nm driver is based upon the .Nm driver written by Julian Elischer, which appeared in .Bx 386 0.1 . The CAM version of the .Nm driver was written by Kenneth Merry and first appeared in .Fx 3.0 . Index: stable/4/share/man/man4/dcons.4 =================================================================== --- stable/4/share/man/man4/dcons.4 (revision 139702) +++ stable/4/share/man/man4/dcons.4 (revision 139703) @@ -1,102 +1,102 @@ .\" Copyright (c) 2003 Hidetoshi Shimokawa .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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$ .\" .\" .Dd February 11, 2003 .Dt DCONS 4 .Os .Sh NAME .Nm dcons .Nd dumb console device driver .Sh SYNOPSIS .Cd device dcons .Pp .Cd options DDB .Cd options ALT_BREAK_TO_DEBUGGER .Pp .Cd device firewire .Sh DESCRIPTION The .Nm device is a simple console device which just reads from and writes to an allocated buffer for input and output respectively. It is of no use by itself and it is supposed that the buffer is accessed via a bus like .Xr firewire 4 or .Xr kvm 3 for interaction. .Pp The buffer consists of 4 channels. There are 2 ports, one for the console TTY and another is GDB port, then each port has an input channel and an output channel. .Sh EXAMPLES If you want to run .Xr getty 8 -on +on .Nm , -insert the following line into +insert the following line into .Xr /etc/ttys 5 and send a .Dv HUP signal to .Xr init 8 using .Xr kill 1 . .Bd -literal -offset indent dcons "/usr/libexec/getty std.9600" vt100 on secure .Ed .Pp Once the .Xr fwochi 4 device is initialized to allow physical access, the buffer can be accessed from another host via a .Xr firewire 4 bus using the .Xr dconschat 8 application. See .Xr dconschat 8 for more details. .Sh FILES .Bl -tag -width indent -compact .It Pa /dev/dcons .It Pa /etc/ttys .El .Sh SEE ALSO .Xr dcons_crom 4 , .Xr ddb 4 , .Xr firewire 4 , .Xr fwohci 4 , .Xr ttys 5 , .Xr dconschat 8 , .Xr fwcontrol 8 .Sh AUTHORS .An Hidetoshi Shimokawa Aq simokawa@FreeBSD.org .Sh BUGS This driver is .Ud . .Pp Index: stable/4/share/man/man4/em.4 =================================================================== --- stable/4/share/man/man4/em.4 (revision 139702) +++ stable/4/share/man/man4/em.4 (revision 139703) @@ -1,149 +1,149 @@ .\" Copyright (c) 2001-2004, Intel Corporation .\" 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. Neither the name of the Intel Corporation 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd November 24, 2004 .Dt EM 4 .Os .Sh NAME .Nm em .Nd "Intel(R) PRO/1000 gigabit Ethernet driver for the FreeBSD operating system" .Sh SYNOPSIS .Cd "device em" .Sh DESCRIPTION The .Nm driver provides support for PCI gigabit Ethernet adapters based on -the Intel 82540, 82541, 82542, 82543, 82544, 82545, 82546, and 82547 Ethernet -controller chips. The driver does not support Transmit/Receive checksum -offload and Jumbo Frames on 82542-based adapters. +the Intel 82540, 82541, 82542, 82543, 82544, 82545, 82546, and 82547 Ethernet +controller chips. The driver does not support Transmit/Receive checksum +offload and Jumbo Frames on 82542-based adapters. For a list of supported adapters, see the .Pa README included with the driver. .Pp For questions related to hardware requirements, refer to the documentation supplied with your Intel PRO/1000 adapter. All hardware requirements listed apply to use with .Fx . .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 16114. .Pp This driver version supports VLANs. For information on enabling VLANs, see the .Pa README . The .Nm driver supports the following media types: .Bl -tag -width ".Cm 10baseT/UTP" .It Cm autoselect Enables auto-negotiation for speed and duplex. .It Cm 10baseT/UTP Sets 10Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 100baseTX Sets 100Mbps operation. Use the .Cm mediaopt option to select .Cm full-duplex mode. .It Cm 1000baseSX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .It Cm 1000baseTX Sets 1000Mbps operation. Only .Cm full-duplex mode is supported at this speed. .El .Pp The .Nm driver supports both full-duplex and half-duplex. Use mediaopt to force the driver to either of these settings. Note that the only valid parameter for mediaopt is full-duplex; to force the driver to half-duplex when running at less than gibabit speed, leave mediaopt unspecifed. .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh DIAGNOSTICS .Bl -diag .It "em%d: Unable to allocate bus resource: memory" A fatal initialization error has occurred. .It "em%d: Unable to allocate bus resource: interrupt" A fatal initialization error has occurred. .It "em%d: watchdog timeout -- resetting" The device has stopped responding to the network, or there is a problem with the network connection (cable). .El .Sh SUPPORT For additional information regarding building and installation, see the .Pa README included with the driver. For general information and support, go to the Intel support website at: .Pa http://support.intel.com . .Pp If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to .Aq freebsdnic@mailbox.intel.com . .Sh SEE ALSO .Xr arp 4 , .Xr gx 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr polling 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 4.4 . .Sh AUTHORS The .Nm driver was written by .An Intel Corporation Aq freebsdnic@mailbox.intel.com . Index: stable/4/share/man/man4/ixgb.4 =================================================================== --- stable/4/share/man/man4/ixgb.4 (revision 139702) +++ stable/4/share/man/man4/ixgb.4 (revision 139703) @@ -1,108 +1,108 @@ .\" Copyright (c) 2001-2004, Intel Corporation .\" 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. Neither the name of the Intel Corporation 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 COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd March 1, 2004 .Dt IXGB 4 .Os .Sh NAME -.Nm ixgb +.Nm ixgb .Nd "Intel(R) PRO/10GbE Ethernet driver for the FreeBSD operating system" .Sh SYNOPSIS .Cd "device ixgb" .Sh DESCRIPTION The .Nm driver provides support for PCI gigabit Ethernet adapters based on the Intel 82597EX Ethernet controller chips. The driver supports Transmit/Receive checksum offload and Jumbo Frames. For a list of supported adapters, see the .Pa README included with the driver. .Pp For questions related to hardware requirements, refer to the documentation supplied with your Intel PRO/10GbE adapter. All hardware requirements listed apply to use with .Fx . .Pp Support for Jumbo Frames is provided via the interface MTU setting. Selecting an MTU larger than 1500 bytes with the .Xr ifconfig 8 utility configures the adapter to receive and transmit Jumbo Frames. The maximum MTU size for Jumbo Frames is 16114. .Pp This driver version supports VLANs. For information on enabling VLANs, see the .Pa README . .Sh DIAGNOSTICS .Bl -diag .It "ixgb%d: Unable to allocate bus resource: memory" A fatal initialization error has occurred. .It "ixgb%d: Unable to allocate bus resource: interrupt" A fatal initialization error has occurred. .It "ixgb%d: watchdog timeout -- resetting" The device has stopped responding to the network, or there is a problem with the network connection (cable). .El .Sh SUPPORT For additional information regarding building and installation, see the .Pa README included with the driver. For general information and support, go to the Intel support website at: .Pa http://support.intel.com . .Pp If an issue is identified with the released source code on the supported kernel with a supported adapter, email the specific information related to the issue to .Aq freebsdnic@mailbox.intel.com . .Sh SEE ALSO .Xr arp 4 , .Xr gx 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr vlan 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 4.11 and .Fx 5.3 . .Sh AUTHORS The .Nm driver was written by .An Intel Corporation Aq freebsdnic@mailbox.intel.com . Index: stable/4/share/man/man4/man4.i386/arl.4 =================================================================== --- stable/4/share/man/man4/man4.i386/arl.4 (revision 139702) +++ stable/4/share/man/man4/man4.i386/arl.4 (revision 139703) @@ -1,99 +1,99 @@ .\" Copyright (c) 2004 .\" Ivan Sharov . 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 Ivan Sharov. .\" 4. Neither the name of the author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY Ivan Sharov 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 Ivan Sharov OR THE VOICES IN HIS HEAD .\" 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$ .\" -.Dd August 26, 2003 +.Dd August 26, 2003 .Dt ARL 4 i386 .Os .Sh NAME .Nm arl .Nd "Aironet Arlan 655 wireless network adapter driver" .Sh SYNOPSIS .Cd "device arl0 at isa? irq 9 iomem 0xd0000" .Sh DESCRIPTION The .Nm -driver provides support for Aironet Arlan 655 +driver provides support for Aironet Arlan 655 wireless network adapters. The Arlan 655 series adapters operate at 354kbps, 512kbps, 1Mbps and 2Mbps. .Pp -The Aironet Arlan 655 devices support Aironet TMA, Aironet Non-TMA +The Aironet Arlan 655 devices support Aironet TMA, Aironet Non-TMA and PSP operating modes. .Pp By default, the .Nm driver configures the Aironet Arlan 655 card for TMA operation. .Pp -To set up Radio Network parameters, use +To set up Radio Network parameters, use .Xr arlcontrol 8 . .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr arlcontrol 8 , .Xr ifconfig 8 .Sh LIMITATIONS When using .Xr ifconfig 8 for setting .Ar SSID you must use a 4-byte even hexadecimal digit value and it must start with 00 or 02. .Pp You can change .Ar channel -for current +for current .Ar country only through -.Xr ifconfig 8 . +.Xr ifconfig 8 . You must use -.Xr arlcontrol 8 +.Xr arlcontrol 8 for changing .Ar country . .Pp Can't change lladdr. .Sh HISTORY The .Nm device driver first appeared in .Fx 5.3 . .Sh AUTHORS .An -nosplit The .Nm driver was initially written by .An Ivan Sharov Aq ivan.sharov@iname.com . -.Aq ran@styx.aic.net +.Aq ran@styx.aic.net wrote the arlcontrol utility and added ioctl support to the driver. .An Stanislav Svirid Aq count@riss-telecom.ru -ported this driver to the new ISA architecture, merged some al driver changes, +ported this driver to the new ISA architecture, merged some al driver changes, fixed some bugs and made it a module. .An Yuri Kurenkov Aq y.kurenkov@init.ru wrote this manpage. Index: stable/4/share/man/man4/man4.i386/ct.4 =================================================================== --- stable/4/share/man/man4/man4.i386/ct.4 (revision 139702) +++ stable/4/share/man/man4/man4.i386/ct.4 (revision 139703) @@ -1,138 +1,138 @@ .\" Copyright (c) 2003 Noriaki MITSUNAGA. All rights reserved. .\" Copyright (c) 2003 Hideyuki KURASHINA. 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. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR 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 AUTHOR 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$ .\" .Dd November 18, 2003 .Dt CT 4 .Os .Sh NAME .Nm ct .Nd "WD33C93[ABC] based CBUS SCSI host adapter driver" .Sh SYNOPSIS .Cd "device scbus" .Pp For most PC-9801-55, -92 and compatibles: .Cd "device ct0 at isa?" .Pp For ELECOM bus-master -.Tn SCSI +.Tn SCSI adapters: .Cd "device ct0 at isa? flags=0x30000" .Pp For I-O DATA SC98 adapters: .Cd "device ct0 at isa? flags=0x10000" .Pp For LOGITEC adapters: .Cd "device ct0 at isa? flags=0x50000" .Pp For TEXA adapters: .Cd "device ct0 at isa? flags=0x20000" .Pp For adapters with SMIT transfer mode to enable SMIT transfer: .Cd "device ct0 at isa? iomem 0xdc000 flags=0x40000" .Pp .Ar Flag meaning: .Bl -tag -offset indent -compact -width 0x000000 .It 0x00000 -DMA transfer mode for an NEC PC-9801-55, -92 (or -compatibles), ICM IF-2660, Midori-Denshi MDC-554NA, or +DMA transfer mode for an NEC PC-9801-55, -92 (or +compatibles), ICM IF-2660, Midori-Denshi MDC-554NA, or Logitec LHA-N151 .It 0x10000 DMA transfer mode for an I-O DATA SC-98II .It 0x20000 -bus-master transfer mode for a TEXA HA-55BS2, its +bus-master transfer mode for a TEXA HA-55BS2, its successors, or Midori-Denshi MDC-926R .It 0x30000 -bus-master transfer mode for an ELECOM bus-master SCSI +bus-master transfer mode for an ELECOM bus-master SCSI adapter .It 0x40000 SMIT transfer mode (for supported adapters only) .It 0x50000 -bus-master transfer mode for a Logitec LHA-20x series, +bus-master transfer mode for a Logitec LHA-20x series, ICM IF-2766, IF-2766ET, IF-2767 or IF-2769 .Sh DESCRIPTION The .Nm -driver provides access to the -.Tn SCSI +driver provides access to the +.Tn SCSI bus connected to a WD33C93[ABC] based host adapter. The following adapters are supported: .Pp .Bl -bullet -compact .It -NEC PC-9801-55, 92 and compatibles, +NEC PC-9801-55, 92 and compatibles, .It -ELECOM bus-master -.Tn SCSI -adapters, +ELECOM bus-master +.Tn SCSI +adapters, .It -I-O DATA SC-98II, +I-O DATA SC-98II, .It -ICM IF-2660, IF-2766, IF-2766ET, IF-2767 and IF-2769, +ICM IF-2660, IF-2766, IF-2766ET, IF-2767 and IF-2769, .It -Logitec LHA-N151 and LHA-20x series, +Logitec LHA-N151 and LHA-20x series, .It -Midori-Denshi MDC-554NA and MDC-926R, +Midori-Denshi MDC-554NA and MDC-926R, .It -TEXA HA-55BS2 and its later models, and +TEXA HA-55BS2 and its later models, and .It -SMIT transfer type -.Tn SCSI +SMIT transfer type +.Tn SCSI host adapters. .El .Sh SEE ALSO .Xr cd 4 , .Xr ch 4 , .Xr ctau 4 , .Xr da 4 , .Xr intro 4 , .Xr sa 4 , .Xr scsi 4 .Sh NOTES Historically, the driver for the Cronyx Tau WAN adapters was ct. This device name was changed to ctau to avoid conflicts with this pc98 ct driver. The network device name for ctau is 'ct'. Please see .Xr ctau 4 for the details for that device. .Sh HISTORY The .Nm device driver has been developed for NetBSD/pc98 and ported for .Fx . It first appeared in .Fx 4.4 . .Sh AUTHORS The .Nm driver was written by .An Naofumi HONDA . .Pp This manual page was written by .An -nosplit -.An Noriaki MITSUNAGA Aq non@FreeBSD.org +.An Noriaki MITSUNAGA Aq non@FreeBSD.org and .An Hideyuki KURASHINA Aq rushani@FreeBSD.org . Index: stable/4/share/man/man4/man4.i386/sbni.4 =================================================================== --- stable/4/share/man/man4/man4.i386/sbni.4 (revision 139702) +++ stable/4/share/man/man4/man4.i386/sbni.4 (revision 139703) @@ -1,110 +1,110 @@ .\" Written by Denis I. Timofeev, 2002. -.\" +.\" .\" 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. -.\" +.\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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$ .\" .Dd January 8, 2002 .Dt SBNI 4 i386 .Os FreeBSD .Sh NAME .Nm sbni .Nd Granch SBNI12 leased line modem driver .Sh SYNOPSIS .Cd "device sbni0 at isa? port 0x210 irq 5" .Cd "device sbni1 at isa? port 0x2c0 irq 11 flags 0xe9123456" .Sh DESCRIPTION The .Nm sbni driver provides support for leased line modems of following models: .Pp .Bl -tag -compact .It Pa SBNI12-02, SBNI12D-02 .It Pa SBNI12-04, SBNI12D-04 .It Pa SBNI12-05, SBNI12D-05, ISA and PCI .It Pa SBNI12-10, SBNI12D-10, ISA and PCI .El .Pp and a kit for data link over a voice band SBNI12-11, SBNI12D-11, ISA and PCI. .Pp In addition to the standard port and irq specifications, the .Nm driver also supports a number of .Em flags which can set baud rate, receive level, and low three bytes of Ethernet MAC-address (high three always are 00:ff:01), because Granch modems is presented to the system as Ethernet-like netcards. .Pp The high byte of the .Em flags is a bit field, it's used to specify SBNI adapter receive level/baud rate: .Bd -literal Bits 0-3: receive level (0x00..0x0f) Bits 4-5: baud rate number: 00 - 0 baud rate (2Mb in fast mode/500kb in slow) 01 - 1 baud rate (1Mb/250kb) 10 - 2 baud rate (500kb/125kb) 11 - 3 baud rate (250kb/62.5kb) Bit 6 : use fixed receive level if bit 6 is set then receive level will be set according to bits 0-3 value, otherwise receive level will be autodetected Bit 7 : use fixed baud rate if bit 7 is set then baud rate will be set according to bits 4-5 value, otherwise baud rate is set to 2Mb E.g.: device sbni0 at isa? port 0x210 irq 5 flags 0xefdead - baud rate 2 Mb (default), receive level autodetected, MAC address will be 00:ff:01:ef:de:ad device sbni1 at isa? port 0x214 irq 7 flags 0xd6abcdef - baud rate 1 Mb, receive level 0x06 (fixed), MAC address 00:ff:01:ab:cd:ef .Sh FILES The sources for the driver reside in: .Pp .Bl -tag -compact .It Pa /sys/dev/sbni/if_sbni.c .It Pa /sys/dev/sbni/if_sbnireg.h .It Pa /sys/dev/sbni/if_sbnivar.h .El .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 4.6 . .Sh AUTHORS The .Nm sbni device driver for FreeBSD 4.x was written by Denis I. Timofeev, partially based on David Greenman's .Nm ed driver. Earlier versions (available on ftp.granch.com) were written by Alexey V. Zverev. .Pp SBNI12 hardware was designed by Alexey V. Chirkov. Index: stable/4/share/man/man4/multicast.4 =================================================================== --- stable/4/share/man/man4/multicast.4 (revision 139702) +++ stable/4/share/man/man4/multicast.4 (revision 139703) @@ -1,917 +1,917 @@ .\" Copyright (c) 2001-2003 International Computer Science Institute .\" .\" Permission is hereby granted, free of charge, to any person obtaining a .\" copy of this software and associated documentation files (the "Software"), .\" to deal in the Software without restriction, including without limitation .\" the rights to use, copy, modify, merge, publish, distribute, sublicense, .\" and/or sell copies of the Software, and to permit persons to whom the .\" Software is furnished to do so, subject to the following conditions: .\" .\" The above copyright notice and this permission notice shall be included in .\" all copies or substantial portions of the Software. .\" .\" The names and trademarks of copyright holders may not be used in .\" advertising or publicity pertaining to the software without specific .\" prior permission. Title to copyright in this software and any associated .\" documentation will at all times remain with the copyright holders. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE .\" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER .\" DEALINGS IN THE SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd September 4, 2003 .Dt MULTICAST 4 .Os .\" .Sh NAME .Nm multicast .Nd Multicast Routing .\" .Sh SYNOPSIS .Cd "options MROUTING" .Pp .In sys/types.h .In sys/socket.h .In netinet/in.h .In netinet/ip_mroute.h .In netinet6/ip6_mroute.h .Ft int .Fn getsockopt "int s" IPPROTO_IP MRT_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IP MRT_INIT "const void *optval" "socklen_t optlen" .Ft int .Fn getsockopt "int s" IPPROTO_IPV6 MRT6_INIT "void *optval" "socklen_t *optlen" .Ft int .Fn setsockopt "int s" IPPROTO_IPV6 MRT6_INIT "const void *optval" "socklen_t optlen" .Sh DESCRIPTION .Tn "Multicast routing" is used to efficiently propagate data packets to a set of multicast listeners in multipoint networks. If unicast is used to replicate the data to all listeners, then some of the network links may carry multiple copies of the same data packets. With multicast routing, the overhead is reduced to one copy (at most) per network link. .Pp All multicast-capable routers must run a common multicast routing protocol. The Distance Vector Multicast Routing Protocol (DVMRP) was the first developed multicast routing protocol. Later, other protocols such as Multicast Extensions to OSPF (MOSPF), Core Based Trees (CBT), Protocol Independent Multicast - Sparse Mode (PIM-SM), and Protocol Independent Multicast - Dense Mode (PIM-DM) were developed as well. .Pp To start multicast routing, the user must enable multicast forwarding in the kernel (see .Sx SYNOPSIS about the kernel configuration options), and must run a multicast routing capable user-level process. From developer's point of view, the programming guide described in the .Sx "Programming Guide" section should be used to control the multicast forwarding in the kernel. .\" .Ss Programming Guide This section provides information about the basic multicast routing API. The so-called .Dq advanced multicast API is described in the .Sx "Advanced Multicast API Programming Guide" section. .Pp First, a multicast routing socket must be open. That socket would be used to control the multicast forwarding in the kernel. Note that most operations below require certain privilege (i.e., root privilege): .Pp .Bd -literal /* IPv4 */ int mrouter_s4; mrouter_s4 = socket(AF_INET, SOCK_RAW, IPPROTO_IGMP); .Ed .Pp .Bd -literal int mrouter_s6; mrouter_s6 = socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6); .Ed .Pp Note that if the router needs to open an IGMP or ICMPv6 socket (in case of IPv4 and IPv6 respectively) for sending or receiving of IGMP or MLD multicast group membership messages, then the same mrouter_s4 or mrouter_s6 sockets should be used for sending and receiving respectively IGMP or MLD messages. In case of BSD-derived kernel, it may be possible to open separate sockets for IGMP or MLD messages only. However, some other kernels (e.g., Linux) require that the multicast routing socket must be used for sending and receiving of IGMP or MLD messages. Therefore, for portability reason the multicast routing socket should be reused for IGMP and MLD messages as well. .Pp After the multicast routing socket is open, it can be used to enable or disable multicast forwarding in the kernel: .Bd -literal /* IPv4 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s4, IPPROTO_IP, MRT_INIT, (void *)&v, sizeof(v)); .Ed .Pp .Bd -literal /* IPv6 */ int v = 1; /* 1 to enable, or 0 to disable */ setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_INIT, (void *)&v, sizeof(v)); \&... /* If necessary, filter all ICMPv6 messages */ struct icmp6_filter filter; ICMP6_FILTER_SETBLOCKALL(&filter); setsockopt(mrouter_s6, IPPROTO_ICMPV6, ICMP6_FILTER, (void *)&filter, sizeof(filter)); .Ed .Pp After multicast forwarding is enabled, the multicast routing socket can be used to enable PIM processing in the kernel if we are running PIM-SM or PIM-DM (see .Xr pim 4 ) . .Pp For each network interface (e.g., physical or a virtual tunnel) that would be used for multicast forwarding, a corresponding multicast interface must be added to the kernel: .Bd -literal /* IPv4 */ struct vifctl vc; memset(&vc, 0, sizeof(vc)); /* Assign all vifctl fields as appropriate */ vc.vifc_vifi = vif_index; vc.vifc_flags = vif_flags; vc.vifc_threshold = min_ttl_threshold; vc.vifc_rate_limit = max_rate_limit; memcpy(&vc.vifc_lcl_addr, &vif_local_address, sizeof(vc.vifc_lcl_addr)); if (vc.vifc_flags & VIFF_TUNNEL) memcpy(&vc.vifc_rmt_addr, &vif_remote_address, sizeof(vc.vifc_rmt_addr)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_VIF, (void *)&vc, sizeof(vc)); .Ed .Pp The .Dq vif_index must be unique per vif. The .Dq vif_flags contains the .Dq VIFF_* flags as defined in . The .Dq min_ttl_threshold contains the minimum TTL a multicast data packet must have to be forwarded on that vif. Typically, it would have value of 1. The .Dq max_rate_limit contains the maximum rate (in bits/s) of the multicast data packets forwarded on that vif. Value of 0 means no limit. -The +The .Dq vif_local_address contains the local IP address of the corresponding local interface. The .Dq vif_remote_address contains the remote IP address in case of DVMRP multicast tunnels. .Pp .Bd -literal /* IPv6 */ struct mif6ctl mc; memset(&mc, 0, sizeof(mc)); /* Assign all mif6ctl fields as appropriate */ mc.mif6c_mifi = mif_index; mc.mif6c_flags = mif_flags; mc.mif6c_pifi = pif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_ADD_MIF, (void *)&mc, sizeof(mc)); .Ed .Pp The .Dq mif_index must be unique per vif. The .Dq mif_flags contains the .Dq MIFF_* flags as defined in . The .Dq pif_index is the physical interface index of the corresponding local interface. .Pp A multicast interface is deleted by: .Bd -literal /* IPv4 */ vifi_t vifi = vif_index; setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_VIF, (void *)&vifi, sizeof(vifi)); .Ed .Pp .Bd -literal /* IPv6 */ mifi_t mifi = mif_index; setsockopt(mrouter_s6, IPPROTO_IPV6, MRT6_DEL_MIF, (void *)&mifi, sizeof(mifi)); .Ed .Pp After the multicast forwarding is enabled, and the multicast virtual interfaces are added, the kernel may deliver upcall messages (also called signals later in this text) on the multicast routing socket that was open earlier with .Dq MRT_INIT or .Dq MRT6_INIT . The IPv4 upcalls have .Dq struct igmpmsg header (see ) with field .Dq im_mbz set to zero. Note that this header follows the structure of .Dq struct ip with the protocol field .Dq ip_p set to zero. The IPv6 upcalls have .Dq struct mrt6msg header (see ) with field .Dq im6_mbz set to zero. Note that this header follows the structure of .Dq struct ip6_hdr with the next header field .Dq ip6_nxt set to zero. .Pp The upcall header contains field .Dq im_msgtype and .Dq im6_msgtype with the type of the upcall .Dq IGMPMSG_* and .Dq MRT6MSG_* for IPv4 and IPv6 respectively. The values of the rest of the upcall header fields and the body of the upcall message depend on the particular upcall type. .Pp If the upcall message type is .Dq IGMPMSG_NOCACHE or .Dq MRT6MSG_NOCACHE , this is an indication that a multicast packet has reached the multicast router, but the router has no forwarding state for that packet. Typically, the upcall would be a signal for the multicast routing user-level process to install the appropriate Multicast Forwarding Cache (MFC) entry in the kernel. .Pp A MFC entry is added by: .Bd -literal /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); mc.mfcc_parent = iif_index; for (i = 0; i < maxvifs; i++) mc.mfcc_ttls[i] = oifs_ttl[i]; setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp .Bd -literal /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); mc.mf6cc_parent = iif_index; for (i = 0; i < maxvifs; i++) if (oifs_ttl[i] > 0) IF_SET(i, &mc.mf6cc_ifset); setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_ADD_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp The .Dq source_addr and .Dq group_addr are the source and group address of the multicast packet (as set in the upcall message). The .Dq iif_index is the virtual interface index of the multicast interface the multicast packets for this specific source and group address should be received on. The .Dq oifs_ttl[] array contains the minimum TTL (per interface) a multicast packet should have to be forwarded on an outgoing interface. If the TTL value is zero, the corresponding interface is not included in the set of outgoing interfaces. Note that in case of IPv6 only the set of outgoing interfaces can be specified. .Pp A MFC entry is deleted by: .Bd -literal /* IPv4 */ struct mfcctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mfcc_origin, &source_addr, sizeof(mc.mfcc_origin)); memcpy(&mc.mfcc_mcastgrp, &group_addr, sizeof(mc.mfcc_mcastgrp)); setsockopt(mrouter_s4, IPPROTO_IP, MRT_DEL_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp .Bd -literal /* IPv6 */ struct mf6cctl mc; memset(&mc, 0, sizeof(mc)); memcpy(&mc.mf6cc_origin, &source_addr, sizeof(mc.mf6cc_origin)); memcpy(&mc.mf6cc_mcastgrp, &group_addr, sizeof(mf6cc_mcastgrp)); setsockopt(mrouter_s4, IPPROTO_IPV6, MRT6_DEL_MFC, (void *)&mc, sizeof(mc)); .Ed .Pp The following method can be used to get various statistics per installed MFC entry in the kernel (e.g., the number of forwarded packets per source and group address): .Bd -literal /* IPv4 */ struct sioc_sg_req sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s4, SIOCGETSGCNT, &sgreq); .Ed .Pp .Bd -literal /* IPv6 */ struct sioc_sg_req6 sgreq; memset(&sgreq, 0, sizeof(sgreq)); memcpy(&sgreq.src, &source_addr, sizeof(sgreq.src)); memcpy(&sgreq.grp, &group_addr, sizeof(sgreq.grp)); ioctl(mrouter_s6, SIOCGETSGCNT_IN6, &sgreq); .Ed .Pp The following method can be used to get various statistics per multicast virtual interface in the kernel (e.g., the number of forwarded packets per interface): .Bd -literal /* IPv4 */ struct sioc_vif_req vreq; memset(&vreq, 0, sizeof(vreq)); vreq.vifi = vif_index; ioctl(mrouter_s4, SIOCGETVIFCNT, &vreq); .Ed .Pp .Bd -literal /* IPv6 */ struct sioc_mif_req6 mreq; memset(&mreq, 0, sizeof(mreq)); mreq.mifi = vif_index; ioctl(mrouter_s6, SIOCGETMIFCNT_IN6, &mreq); .Ed .Pp .Ss Advanced Multicast API Programming Guide If we want to add new features in the kernel, it becomes difficult to preserve backward compatibility (binary and API), and at the same time to allow user-level processes to take advantage of the new features (if the kernel supports them). .Pp -One of the mechanisms that allows us to preserve the backward +One of the mechanisms that allows us to preserve the backward compatibility is a sort of negotiation between the user-level process and the kernel: .Bl -enum .It The user-level process tries to enable in the kernel the set of new features (and the corresponding API) it would like to use. .It The kernel returns the (sub)set of features it knows about and is willing to be enabled. .It The user-level process uses only that set of features the kernel has agreed on. .El .\" .Pp To support backward compatibility, if the user-level process doesn't ask for any new features, the kernel defaults to the basic multicast API (see the .Sx "Programming Guide" section). .\" XXX: edit as appropriate after the advanced multicast API is .\" supported under IPv6 Currently, the advanced multicast API exists only for IPv4; in the future there will be IPv6 support as well. .Pp Below is a summary of the expandable API solution. Note that all new options and structures are defined in and , unless stated otherwise. .Pp The user-level process uses new get/setsockopt() options to perform the API features negotiation with the kernel. This negotiation must be performed right after the multicast routing socket is open. The set of desired/allowed features is stored in a bitset (currently, in uint32_t; i.e., maximum of 32 new features). The new get/setsockopt() options are .Dq MRT_API_SUPPORT and .Dq MRT_API_CONFIG . Example: .Bd -literal uint32_t v; getsockopt(sock, IPPROTO_IP, MRT_API_SUPPORT, (void *)&v, sizeof(v)); .Ed .Pp would set in .Dq v the pre-defined bits that the kernel API supports. The eight least significant bits in uint32_t are same as the eight possible flags .Dq MRT_MFC_FLAGS_* that can be used in .Dq mfcc_flags as part of the new definition of .Dq struct mfcctl (see below about those flags), which leaves 24 flags for other new features. The value returned by getsockopt(MRT_API_SUPPORT) is read-only; in other words, setsockopt(MRT_API_SUPPORT) would fail. .Pp To modify the API, and to set some specific feature in the kernel, then: .Bd -literal uint32_t v = MRT_MFC_FLAGS_DISABLE_WRONGVIF; if (setsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)) != 0) { return (ERROR); } if (v & MRT_MFC_FLAGS_DISABLE_WRONGVIF) return (OK); /* Success */ else return (ERROR); .Ed .Pp In other words, when setsockopt(MRT_API_CONFIG) is called, the argument to it specifies the desired set of features to be enabled in the API and the kernel. The return value in .Dq v is the actual (sub)set of features that were enabled in the kernel. To obtain later the same set of features that were enabled, then: .Bd -literal getsockopt(sock, IPPROTO_IP, MRT_API_CONFIG, (void *)&v, sizeof(v)); .Ed .Pp The set of enabled features is global. In other words, setsockopt(MRT_API_CONFIG) should be called right after setsockopt(MRT_INIT). .Pp Currently, the following set of new features is defined: .Bd -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ #define MRT_MFC_RP (1 << 8) /* enable RP address */ #define MRT_MFC_BW_UPCALL (1 << 9) /* enable bw upcalls */ .Ed .\" .Pp .\" In the future there might be: .\" .Bd -literal .\" #define MRT_MFC_GROUP_SPECIFIC (1 << 10) /* allow (*,G) MFC entries */ .\" .Ed .\" .Pp .\" to allow (*,G) MFC entries (i.e., group-specific entries) in the kernel. .\" For now this is left-out until it is clear whether .\" (*,G) MFC support is the preferred solution instead of something more generic .\" solution for example. .\" .\" 2. The newly defined struct mfcctl2. .\" .Pp The advanced multicast API uses a newly defined .Dq struct mfcctl2 instead of the traditional .Dq struct mfcctl . The original .Dq struct mfcctl is kept as is. The new .Dq struct mfcctl2 is: .Bd -literal /* * The new argument structure for MRT_ADD_MFC and MRT_DEL_MFC overlays * and extends the old struct mfcctl. */ struct mfcctl2 { /* the mfcctl fields */ struct in_addr mfcc_origin; /* ip origin of mcasts */ struct in_addr mfcc_mcastgrp; /* multicast group associated*/ vifi_t mfcc_parent; /* incoming vif */ u_char mfcc_ttls[MAXVIFS];/* forwarding ttls on vifs */ /* extension fields */ uint8_t mfcc_flags[MAXVIFS];/* the MRT_MFC_FLAGS_* flags*/ struct in_addr mfcc_rp; /* the RP address */ }; .Ed .Pp The new fields are .Dq mfcc_flags[MAXVIFS] and .Dq mfcc_rp . Note that for compatibility reasons they are added at the end. .Pp The .Dq mfcc_flags[MAXVIFS] field is used to set various flags per interface per (S,G) entry. Currently, the defined flags are: .Bd -literal #define MRT_MFC_FLAGS_DISABLE_WRONGVIF (1 << 0) /* disable WRONGVIF signals */ #define MRT_MFC_FLAGS_BORDER_VIF (1 << 1) /* border vif */ .Ed .Pp The .Dq MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is used to explicitly disable the .Dq IGMPMSG_WRONGVIF kernel signal at the (S,G) granularity if a multicast data packet arrives on the wrong interface. Usually, this signal is used to complete the shortest-path switch in case of PIM-SM multicast routing, or to trigger a PIM assert message. However, it should not be delivered for interfaces that are not in the outgoing interface set, and that are not expecting to become an incoming interface. Hence, if the .Dq MRT_MFC_FLAGS_DISABLE_WRONGVIF flag is set for some of the interfaces, then a data packet that arrives on that interface for that MFC entry will NOT trigger a WRONGVIF signal. If that flag is not set, then a signal is triggered (the default action). .Pp The .Dq MRT_MFC_FLAGS_BORDER_VIF flag is used to specify whether the Border-bit in PIM Register messages should be set (in case when the Register encapsulation is performed inside the kernel). If it is set for the special PIM Register kernel virtual interface (see .Xr pim 4 ) , the Border-bit in the Register messages sent to the RP will be set. .Pp The remaining six bits are reserved for future usage. .Pp The .Dq mfcc_rp field is used to specify the RP address (in case of PIM-SM multicast routing) for a multicast group G if we want to perform kernel-level PIM Register encapsulation. The .Dq mfcc_rp field is used only if the .Dq MRT_MFC_RP advanced API flag/capability has been successfully set by setsockopt(MRT_API_CONFIG). .Pp .\" .\" 3. Kernel-level PIM Register encapsulation .\" If the .Dq MRT_MFC_RP flag was successfully set by setsockopt(MRT_API_CONFIG), then the kernel will attempt to perform the PIM Register encapsulation itself instead of sending the multicast data packets to user level (inside IGMPMSG_WHOLEPKT upcalls) for user-level encapsulation. The RP address would be taken from the .Dq mfcc_rp field inside the new .Dq struct mfcctl2 . However, even if the .Dq MRT_MFC_RP flag was successfully set, if the .Dq mfcc_rp field was set to .Dq INADDR_ANY , then the kernel will still deliver an IGMPMSG_WHOLEPKT upcall with the multicast data packet to the user-level process. .Pp In addition, if the multicast data packet is too large to fit within a single IP packet after the PIM Register encapsulation (e.g., if its size was on the order of 65500 bytes), the data packet will be fragmented, and then each of the fragments will be encapsulated separately. Note that typically a multicast data packet can be that large only if it was originated locally from the same hosts that performs the encapsulation; otherwise the transmission of the multicast data packet over Ethernet for example would have fragmented it into much smaller pieces. .\" .\" Note that if this code is ported to IPv6, we may need the kernel to .\" perform MTU discovery to the RP, and keep those discoveries inside .\" the kernel so the encapsulating router may send back ICMP .\" Fragmentation Required if the size of the multicast data packet is .\" too large (see "Encapsulating data packets in the Register Tunnel" .\" in Section 4.4.1 in the PIM-SM spec .\" draft-ietf-pim-sm-v2-new-05.{txt,ps}). .\" For IPv4 we may be able to get away without it, but for IPv6 we need .\" that. .\" .\" 4. Mechanism for "multicast bandwidth monitoring and upcalls". .\" .Pp Typically, a multicast routing user-level process would need to know the forwarding bandwidth for some data flow. For example, the multicast routing process may want to timeout idle MFC entries, or in case of PIM-SM it can initiate (S,G) shortest-path switch if the bandwidth rate is above a threshold for example. .Pp The original solution for measuring the bandwidth of a dataflow was that a user-level process would periodically query the kernel about the number of forwarded packets/bytes per (S,G), and then based on those numbers it would estimate whether a source has been idle, or whether the source's transmission bandwidth is above a threshold. That solution is far from being scalable, hence the need for a new mechanism for bandwidth monitoring. .Pp Below is a description of the bandwidth monitoring mechanism. .Bl -bullet .It If the bandwidth of a data flow satisfies some pre-defined filter, the kernel delivers an upcall on the multicast routing socket to the multicast routing process that has installed that filter. .It The bandwidth-upcall filters are installed per (S,G). There can be more than one filter per (S,G). .It Instead of supporting all possible comparison operations (i.e., < <= == != > >= ), there is support only for the <= and >= operations, because this makes the kernel-level implementation simpler, and because practically we need only those two. Further, the missing operations can be simulated by secondary user-level filtering of those <= and >= filters. For example, to simulate !=, then we need to install filter .Dq bw <= 0xffffffff , and after an upcall is received, we need to check whether .Dq measured_bw != expected_bw . .It The bandwidth-upcall mechanism is enabled by setsockopt(MRT_API_CONFIG) for the MRT_MFC_BW_UPCALL flag. .It The bandwidth-upcall filters are added/deleted by the new setsockopt(MRT_ADD_BW_UPCALL) and setsockopt(MRT_DEL_BW_UPCALL) respectively (with the appropriate .Dq struct bw_upcall argument of course). .El .Pp From application point of view, a developer needs to know about the following: .Bd -literal /* * Structure for installing or delivering an upcall if the * measured bandwidth is above or below a threshold. * * User programs (e.g. daemons) may have a need to know when the * bandwidth used by some data flow is above or below some threshold. * This interface allows the userland to specify the threshold (in * bytes and/or packets) and the measurement interval. Flows are * all packet with the same source and destination IP address. * At the moment the code is only used for multicast destinations * but there is nothing that prevents its use for unicast. * * The measurement interval cannot be shorter than some Tmin (currently, 3s). * The threshold is set in packets and/or bytes per_interval. * * Measurement works as follows: * - * For >= measurements: + * For >= measurements: * The first packet marks the start of a measurement interval. * During an interval we count packets and bytes, and when we * pass the threshold we deliver an upcall and we are done. * The first packet after the end of the interval resets the * count and restarts the measurement. * * For <= measurement: * We start a timer to fire at the end of the interval, and * then for each incoming packet we count packets and bytes. * When the timer fires, we compare the value with the threshold, * schedule an upcall if we are below, and restart the measurement * (reschedule timer and zero counters). */ struct bw_data { struct timeval b_time; uint64_t b_packets; uint64_t b_bytes; }; struct bw_upcall { struct in_addr bu_src; /* source address */ struct in_addr bu_dst; /* destination address */ uint32_t bu_flags; /* misc flags (see below) */ #define BW_UPCALL_UNIT_PACKETS (1 << 0) /* threshold (in packets) */ #define BW_UPCALL_UNIT_BYTES (1 << 1) /* threshold (in bytes) */ #define BW_UPCALL_GEQ (1 << 2) /* upcall if bw >= threshold */ #define BW_UPCALL_LEQ (1 << 3) /* upcall if bw <= threshold */ #define BW_UPCALL_DELETE_ALL (1 << 4) /* delete all upcalls for s,d*/ struct bw_data bu_threshold; /* the bw threshold */ struct bw_data bu_measured; /* the measured bw */ }; /* max. number of upcalls to deliver together */ #define BW_UPCALLS_MAX 128 /* min. threshold time interval for bandwidth measurement */ #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_SEC 3 #define BW_UPCALL_THRESHOLD_INTERVAL_MIN_USEC 0 .Ed .Pp The .Dq bw_upcall structure is used as an argument to setsockopt(MRT_ADD_BW_UPCALL) and setsockopt(MRT_DEL_BW_UPCALL). Each setsockopt(MRT_ADD_BW_UPCALL) installs a filter in the kernel for the source and destination address in the .Dq bw_upcall argument, and that filter will trigger an upcall according to the following pseudo-algorithm: .Bd -literal if (bw_upcall_oper IS ">=") { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets >= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes >= threshold_bytes))) SEND_UPCALL("measured bandwidth is >= threshold"); } if (bw_upcall_oper IS "<=" && measured_interval >= threshold_interval) { if (((bw_upcall_unit & PACKETS == PACKETS) && (measured_packets <= threshold_packets)) || ((bw_upcall_unit & BYTES == BYTES) && (measured_bytes <= threshold_bytes))) SEND_UPCALL("measured bandwidth is <= threshold"); } .Ed .Pp In the same .Dq bw_upcall the unit can be specified in both BYTES and PACKETS. However, the GEQ and LEQ flags are mutually exclusive. .Pp Basically, an upcall is delivered if the measured bandwidth is >= or <= the threshold bandwidth (within the specified measurement interval). For practical reasons, the smallest value for the measurement interval is 3 seconds. If smaller values are allowed, then the bandwidth estimation may be less accurate, or the potentially very high frequency of the generated upcalls may introduce too much overhead. For the >= operation, the answer may be known before the end of .Dq threshold_interval , therefore the upcall may be delivered earlier. For the <= operation however, we must wait until the threshold interval has expired to know the answer. .Pp Example of usage: .Bd -literal struct bw_upcall bw_upcall; /* Assign all bw_upcall fields as appropriate */ memset(&bw_upcall, 0, sizeof(bw_upcall)); memcpy(&bw_upcall.bu_src, &source, sizeof(bw_upcall.bu_src)); memcpy(&bw_upcall.bu_dst, &group, sizeof(bw_upcall.bu_dst)); bw_upcall.bu_threshold.b_data = threshold_interval; bw_upcall.bu_threshold.b_packets = threshold_packets; bw_upcall.bu_threshold.b_bytes = threshold_bytes; if (is_threshold_in_packets) bw_upcall.bu_flags |= BW_UPCALL_UNIT_PACKETS; if (is_threshold_in_bytes) bw_upcall.bu_flags |= BW_UPCALL_UNIT_BYTES; do { if (is_geq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_GEQ; break; } if (is_leq_upcall) { bw_upcall.bu_flags |= BW_UPCALL_LEQ; break; } return (ERROR); } while (0); setsockopt(mrouter_s4, IPPROTO_IP, MRT_ADD_BW_UPCALL, (void *)&bw_upcall, sizeof(bw_upcall)); .Ed .Pp To delete a single filter, then use MRT_DEL_BW_UPCALL, and the fields of bw_upcall must be set exactly same as when MRT_ADD_BW_UPCALL was called. .Pp To delete all bandwidth filters for a given (S,G), then only the .Dq bu_src and .Dq bu_dst fields in .Dq struct bw_upcall need to be set, and then just set only the .Dq BW_UPCALL_DELETE_ALL flag inside field .Dq bw_upcall.bu_flags . .Pp The bandwidth upcalls are received by aggregating them in the new upcall message: .Bd -literal #define IGMPMSG_BW_UPCALL 4 /* BW monitoring upcall */ .Ed .Pp This message is an array of .Dq struct bw_upcall elements (up to BW_UPCALLS_MAX = 128). The upcalls are delivered when there are 128 pending upcalls, or when 1 second has expired since the previous upcall (whichever comes first). In an .Dq struct upcall element, the .Dq bu_measured field is filled-in to indicate the particular measured values. However, because of the way the particular intervals are measured, the user should be careful how bu_measured.b_time is used. -For example, if the +For example, if the filter is installed to trigger an upcall if the number of packets is >= 1, then .Dq bu_measured may have a value of zero in the upcalls after the first one, because the measured interval for >= filters is .Dq clocked by the forwarded packets. Hence, this upcall mechanism should not be used for measuring the exact value of the bandwidth of the forwarded data. To measure the exact bandwidth, the user would need to get the forwarded packets statistics with the ioctl(SIOCGETSGCNT) mechanism (see the .Sx Programming Guide section) . .Pp Note that the upcalls for a filter are delivered until the specific filter is deleted, but no more frequently than once per .Dq bu_threshold.b_time . For example, if the filter is specified to deliver a signal if bw >= 1 packet, the first packet will trigger a signal, but the next upcall will be triggered no earlier than .Dq bu_threshold.b_time after the previous upcall. .Pp .\" .Sh SEE ALSO .Xr getsockopt 2 , .Xr recvfrom 2 , .Xr recvmsg 2 , .Xr setsockopt 2 , .Xr socket 2 , .Xr icmp6 4 , .Xr inet 4 , .Xr inet6 4 , .Xr intro 4 , .Xr ip 4 , .Xr ip6 4 , .Xr pim 4 .\" .Pp .Sh AUTHORS The original multicast code was written by David Waitzman (BBN Labs), and later modified by the following individuals: Steve Deering (Stanford), Mark J. Steiglitz (Stanford), Van Jacobson (LBL), Ajit Thyagarajan (PARC), Bill Fenner (PARC). The IPv6 multicast support was implemented by the KAME project (http://www.kame.net), and was based on the IPv4 multicast code. The advanced multicast API and the multicast bandwidth monitoring were implemented by Pavlin Radoslavov (ICSI) in collaboration with Chris Brown (NextHop). .Pp This manual page was written by Pavlin Radoslavov (ICSI). Index: stable/4/share/man/man4/ng_l2tp.4 =================================================================== --- stable/4/share/man/man4/ng_l2tp.4 (revision 139702) +++ stable/4/share/man/man4/ng_l2tp.4 (revision 139703) @@ -1,303 +1,303 @@ .\" Copyright (c) 2001-2002 Packet Design, LLC. .\" All rights reserved. -.\" +.\" .\" Subject to the following obligations and disclaimer of warranty, .\" use and redistribution of this software, in source or object code .\" forms, with or without modifications are expressly permitted by .\" Packet Design; provided, however, that: -.\" +.\" .\" (i) Any and all reproductions of the source or object code .\" must include the copyright notice above and the following .\" disclaimer of warranties; and .\" (ii) No rights are granted, in any manner or form, to use .\" Packet Design trademarks, including the mark "PACKET DESIGN" .\" on advertising, endorsements, or otherwise except as such .\" appears in the above copyright notice or in the software. -.\" +.\" .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE, .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 PACKET DESIGN IS ADVISED OF .\" THE POSSIBILITY OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" .\" $FreeBSD$ .\" .Dd April 22, 2002 .Dt NG_L2TP 4 .Os .Sh NAME .Nm ng_l2tp .Nd L2TP protocol netgraph node type .Sh SYNOPSIS .In netgraph/ng_l2tp.h .Sh DESCRIPTION The .Nm ng_l2tp node type implements the encapsulation layer of the L2TP protocol as described in RFC 2661. This includes adding the L2TP packet header for outgoing packets and verifying and removing it for incoming packets. The node maintains the L2TP sequence number state and handles control session packet acknowledgment and retransmission. .Sh HOOKS The .Nm ng_l2tp node type supports the following hooks: .Pp .Bl -tag -compact -offset 3n -width session_hhhh .It Dv lower L2TP frames .It Dv ctrl Control packets .It Dv session_hhhh Session 0xhhhh data packets .El .Pp L2TP control and data packets are transmitted to, and received from, the L2TP peer via the .Dv lower hook. Typically this hook would be connected to the .Dv "inet/dgram/udp" hook of an .Xr ng_ksocket 4 node for L2TP over UDP. .Pp The .Dv ctrl hook connects to the local L2TP management entity. L2TP control messages (without any L2TP headers) are transmitted and received on this hook. Messages written to this hook are guaranteed to be delivered to the peer reliably, in order, and without duplicates. .Pp Packets written to the .Dv ctrl hook must contain a two byte session ID prepended to the frame (in network order). This session ID is copied to the outgoing L2TP header. Similarly, packets read from the .Dv ctrl hook will have the received session ID prepended. .Pp Once an L2TP session has been created, the corresponding session hook may be used to transmit and receive the session's data frames: for the session with session ID .Dv 0xabcd , the hook is named .Dv session_abcd . .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width xx .It Dv NGM_L2TP_SET_CONFIG This command updates the configuration of the node. It takes a .Li "struct ng_l2tp_config" as an argument: .Bd -literal -offset 0n /* Configuration for a node */ struct ng_l2tp_config { u_char enabled; /* enables traffic flow */ u_char match_id; /* tunnel id must match 'tunnel_id' */ u_int16_t tunnel_id; /* local tunnel id */ u_int16_t peer_id; /* peer's tunnel id */ u_int16_t peer_win; /* peer's max recv window size */ u_int16_t rexmit_max; /* max retransmits before failure */ u_int16_t rexmit_max_to; /* max delay between retransmits */ }; .Ed .Pp The .Va enabled field enables packet processing. Each time this field is changed back to zero the sequence number state is reset. In this way, reuse of a node is possible. .Pp The .Va tunnel_id field configures the local tunnel ID for the control connection. The .Va match_id field determines how incoming L2TP packets with a tunnel ID field different from .Va tunnel_id are handled. If .Va match_id is non-zero, they will be dropped; otherwise, they will be dropped only if the tunnel ID is non-zero. Typically .Va tunnel_id is set to the local tunnel ID as soon as it is known and .Va match_id is set to non-zero after receipt of the SCCRP or SCCCN control message. .Pp The peer's tunnel ID should be set in .Va peer_id as soon as it is learned, typically after receipt of a SCCRQ or SCCRP control message. This value is copied into the L2TP header for outgoing packets. .Pp The .Va peer_win field should be set from the .Dq Receive Window Size AVP received from the peer. The default value for this field is one; zero is an invalid value. As long as .Va enabled is non-zero, this value may not be decreased. .Pp The .Va rexmit_max and .Va rexmit_max_to fields configure packet retransmission. .Va rexmit_max_to is the maximum retransmission delay between packets, in seconds. The retransmit delay will start at a small value and increase exponentially up to this limit. The .Va rexmit_max sets the maximum number of times a packet will be retransmitted without being acknowledged before a failure condition is declared. Once a failure condition is declared, each additional retransmission will cause the .Nm ng_l2tp node to send a .Dv NGM_L2TP_ACK_FAILURE control message back to the node that sent the last .Dv NGM_L2TP_SET_CONFIG . Appropriate action should then be taken to shutdown the control connection. .It Dv NGM_L2TP_GET_CONFIG Returns the current configuration as a .Dv "struct ng_l2tp_config" . .It Dv NGM_L2TP_SET_SESS_CONFIG This control message configures a single data session. The corresponding hook must already be connected before sending this command. The argument is a .Li "struct ng_l2tp_sess_config" : .Bd -literal -offset 0n /* Configuration for a session hook */ struct ng_l2tp_sess_config { u_int16_t session_id; /* local session id */ u_int16_t peer_id; /* peer's session id */ u_char control_dseq; /* we control data sequencing? */ u_char enable_dseq; /* enable data sequencing? */ u_char include_length; /* include length field? */ }; .Ed .Pp The .Va session_id and .Va peer_id fields configure the local and remote session ID's, respectively. .Pp The .Va control_dseq and .Va enable_dseq fields determine whether sequence numbers are used with L2TP data packets. If .Va enable_dseq is zero, then no sequence numbers are sent and incoming sequence numbers are ignored. Otherwise, sequence numbers are included on outgoing packets and checked on incoming packets. .Pp If .Va control_dseq is non-zero, then the setting of .Va enable_dseq will never change except by another .Dv NGM_L2TP_SET_SESS_CONFIG control message. If .Va control_dseq is zero, then the peer controls whether sequence numbers are used: if an incoming L2TP data packet contains sequence numbers, .Va enable_dseq is set to one, and conversely if an incoming L2TP data packet does not contain sequence numbers, .Va enable_dseq is set to zero. The current value of .Va enable_dseq is always accessible via the .Dv NGM_L2TP_GET_SESS_CONFIG control message (see below). Typically an LNS would set .Va control_dseq to one while a LAC would set .Va control_dseq to zero (if the Sequencing Required AVP were not sent), thus giving control of data packet sequencing to the LNS. .Pp The .Va include_length field determines whether the L2TP header length field is included in outgoing L2TP data packets. For incoming packets, the L2TP length field is always checked when present. .It Dv NGM_L2TP_GET_SESS_CONFIG This command takes a two byte session ID as an argument and returns the current configuration for the corresponding data session as a .Dv "struct ng_l2tp_sess_config" . The corresponding session hook must be connected. .It Dv NGM_L2TP_GET_STATS This command takes a two byte session ID as an argument and returns a .Dv "struct ng_l2tp_stats" containing statistics for the corresponding data session. The corresponding session hook must be connected. .It Dv NGM_L2TP_CLR_STATS This command takes a two byte session ID as an argument and clears the statistics for that data session. The corresponding session hook must be connected. .It Dv NGM_L2TP_GETCLR_STATS Same as .Dv NGM_L2TP_GET_STATS , but also atomically clears the statistics as well. .El .Pp .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh SEE ALSO .Xr netgraph 4 , .Xr ng_ksocket 4 , .Xr ng_ppp 4 , .Xr ng_pptp 4 , .Xr ngctl 8 .Rs .%A W. Townsley .%A A. Valencia .%A A. Rubens .%A G. Pall .%A G. Zorn .%A B. Palter .%T "Layer Two Tunneling Protocol L2TP" .%O RFC 2661 .Re .Sh HISTORY The .Nm node type was developed at Packet Design, LLC. .Dv "http://www.packetdesign.com/" .Sh AUTHORS .An Archie Cobbs Aq archie@packetdesign.com Index: stable/4/share/man/man4/nsp.4 =================================================================== --- stable/4/share/man/man4/nsp.4 (revision 139702) +++ stable/4/share/man/man4/nsp.4 (revision 139703) @@ -1,81 +1,81 @@ .\" Copyright (c) 2003 Noriaki MITSUNAGA. All rights reserved. .\" Copyright (c) 2003 Hideyuki KURASHINA. 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. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR 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 AUTHOR 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$ .\" .Dd November 18, 2003 .Dt NSP 4 .Os .Sh NAME .Nm nsp .Nd "Workbit Ninja SCSI-3 based PC-Card SCSI host adapter driver" .Sh SYNOPSIS .Cd "device nsp" .Cd "device scbus" .Sh DESCRIPTION The .Nm -driver provides access to the +driver provides access to the .Tn SCSI -bus connected to a PC-Card +bus connected to a PC-Card .Tn SCSI -host adapter based on a Ninja SCSI-3 controller by Workbit. +host adapter based on a Ninja SCSI-3 controller by Workbit. The following adapters are known to work: .Pp .Bl -bullet -compact .It Alpha-Data AD-PCS201 .It I-O DATA CBSC16 .El .Sh SEE ALSO .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr intro 4 , .Xr pccard 4 , .Xr sa 4 , .Xr scsi 4 .Sh BUGS SMIT mode is only supported under OLDCARD now. .Sh HISTORY The .Nm driver has been developped for NetBSD/pc98 and ported for .Fx . It first appeared in .Fx 3.4 with PAO3 and merged in .Fx 4.2 . .Sh AUTHORS The .Nm driver was written by .An Naofumi HONDA . .Pp This manual page was written by .An -nosplit .An Noriaki MITSUNAGA Aq non@FreeBSD.org and .An Hideyuki KURASHINA Aq rushani@FreeBSD.org . Index: stable/4/share/man/man4/pst.4 =================================================================== --- stable/4/share/man/man4/pst.4 (revision 139702) +++ stable/4/share/man/man4/pst.4 (revision 139703) @@ -1,63 +1,63 @@ .\" .\" Copyright (c) 2001,2002 Søren Schmidt .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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$ .\" .Dd November 21, 2001 .Dt PST 4 .Os .Sh NAME .Nm pst .Nd Device driver for Promise Supertrak SX6000 .Sh SYNOPSIS Include this line in the kernel config file: .Cd device pst .Pp .Sh DESCRIPTION This driver is for the Promise Supertrak SX6000 ATA hardware RAID controller. -It supports (in hardware) RAID levels 0, 1, 0+1, 3, 5 and JBOD on up to -6 ATA disk drives, including automatic rebuild and hotswap, and supports +It supports (in hardware) RAID levels 0, 1, 0+1, 3, 5 and JBOD on up to +6 ATA disk drives, including automatic rebuild and hotswap, and supports signalling disk status on LED's on Promise Superswap disk enclosures. The Supertrak lines of controllers does not support non-disk devices. .Pp .Sh NOTES The .Nm driver does not support manipulating the RAID from the OS, RAID's need to be setup from the onboard BIOS. However hot swap, hot spare, and automatic rebuilds are supported without reboot. .Pp .Sh HISTORY The .Nm driver first appeared in .Fx 4.7 . .Sh AUTHORS .An -nosplit The .Nm driver and man page was written by .An S\(/oren Schmidt .Aq sos@FreeBSD.org . Index: stable/4/share/man/man4/puc.4 =================================================================== --- stable/4/share/man/man4/puc.4 (revision 139702) +++ stable/4/share/man/man4/puc.4 (revision 139703) @@ -1,68 +1,68 @@ .\" Copyright (c) 2002 John Hay. .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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$ .\" .Dd February 7, 2002 .Dt PUC 4 .Os .Sh NAME .Nm puc .Nd PCI ``Universal'' Communications driver .Sh SYNOPSIS .Cd device pci .Cd device puc .Cd device sio .Cd options PUC_FASTINTR .Sh DESCRIPTION This driver acts as a shim to connect pci serial ports to the .Xr sio 4 driver. .Pp -The list of supported devices is in +The list of supported devices is in .Em src/sys/dev/puc/pucdata.c. Support for new cards should be added there. .Pp If the PUC_FASTINTR option is used the driver will try to use fast interrupts. This should lower the interrupt latency and should be used if the .Xr sio 4 driver reports .Em silo overflow errors. It cannot be used if the interrupt is shared. .Sh SEE ALSO .Xr sio 4 .Sh HISTORY This driver took the idea from the .Nx .Xr puc 4 driver and still use the same structure to describe cards to ease exchanging card info. .Sh BUGS Only serial ports are supported through the .Xr sio 4 driver at the moment. Someone should write support for parallel ports using the .Xr lpt 4 driver. Index: stable/4/share/man/man4/sbsh.4 =================================================================== --- stable/4/share/man/man4/sbsh.4 (revision 139702) +++ stable/4/share/man/man4/sbsh.4 (revision 139703) @@ -1,83 +1,83 @@ .\" Written by Denis I. Timofeev, 2003. -.\" +.\" .\" 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. -.\" +.\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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$ .\" .Dd April 11, 2003 .Dt SBSH 4 .Os .Sh NAME .Nm sbsh .Nd "Granch SBNI16 SHDSL modem device driver" .Sh SYNOPSIS .Cd "device sbsh" .Sh DESCRIPTION The .Nm driver provides support for an internal PCI modem SBNI16-SHDSL. A device is introduced to OS as common ethernet-like netcard which must be configured with .Xr ifconfig 8 (all standard network interface parameters could be set). Modem-specific parameters (master/slave mode, line rate etc.) must be set with the sb16config utility before interface activation. .Sh DIAGNOSTICS .Bl -diag .It "sbsh%d: couldn't map memory" .It "sbsh%d: couldn't map interrupt" .It "sbsh%d: couldn't set up irq" A fatal initialization error has occurred. .It "sbsh%d: unable to load firmware" A fatal error has occurred while sb16config running. .It "sbsh%d: firmware wasn't loaded" ifconfig...up has failed because device hadn't been configured with sb16config. .It "sbsh%d: transmit timeout" .It "sbsh%d: interrupt posted but not delivered" Probably, a hardware error or incompatibility. .It "sbsh%d: unable to get mbuf" .It "sbsh%d: unable to get mbuf cluster" The driver failed to allocate a memory buffer. .El .Sh FILES The sources for the driver reside in: .Pp .Bl -tag -compact .It Pa /sys/dev/sbsh/if_sbsh.c .It Pa /sys/dev/sbsh/if_sbshreg.h .El .Sh SEE ALSO .Xr arp 4 , .Xr netintro 4 , .Xr ifconfig 8 , .Xr /usr/ports/sysutils/sb16config .Sh HISTORY The .Nm device driver first appeared in .Fx 4.9 . .Sh AUTHORS The .Nm driver was written by .An Denis I. Timofeev Aq timofeev@granch.ru . Index: stable/4/share/man/man4/stg.4 =================================================================== --- stable/4/share/man/man4/stg.4 (revision 139702) +++ stable/4/share/man/man4/stg.4 (revision 139703) @@ -1,85 +1,85 @@ .\" .\" Copyright (c) 2003 Bob Bishop .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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$ .\" .Dd August 16, 2003 .Dt STG 4 .Os .Sh NAME .Nm stg .Nd driver for Future Domain based SCSI controllers .Sh SYNOPSIS .Cd "device stg" .Pp In .Pa /boot/device.hints (for ISA controllers): .Cd hint.stg.0.at="isa" .Sh DESCRIPTION The .Nm driver provides support for ISA, PCCARD and PCI controllers based on Future Domain SCSI controller chips including the TMC-16C30, 16C50 and 32C60. Supported controllers include: .Bl -dash -offset indent -compact .It Adaptec 2920/A .It Future Domain SCSI2GO .It Future Domain TMC-18XX/3260 .It IBM SCSI PCMCIA Card .It ICM PSC-2401 SCSI .It MELCO IFC-SC .It RATOC REX-5536, REX-5536AM, REX-5536M, REX-9836A .El .Pp -Note that the Adaptec 2920C is supported by the +Note that the Adaptec 2920C is supported by the .Sy ahc driver. .Sh SEE ALSO .Xr cd 4 , .Xr ch 4 , .Xr da 4 , .Xr intro 4 , .Xr sa 4 , .Xr scsi 4 .Sh HISTORY The .Nm device driver has been developed for NetBSD/pc98 and ported for .Fx . It first appeared in .Fx 2.2 with PAO and merged in .Fx 4.2 . .Sh AUTHORS The .Nm driver was written by .An Naofumi HONDA . Index: stable/4/share/man/man4/tcp.4 =================================================================== --- stable/4/share/man/man4/tcp.4 (revision 139702) +++ stable/4/share/man/man4/tcp.4 (revision 139703) @@ -1,444 +1,444 @@ .\" Copyright (c) 1983, 1991, 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. .\" .\" From: @(#)tcp.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd February 14, 1995 .Dt TCP 4 .Os .Sh NAME .Nm tcp .Nd Internet Transmission Control Protocol .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/in.h .Ft int .Fn socket AF_INET SOCK_STREAM 0 .Sh DESCRIPTION The .Tn TCP protocol provides reliable, flow-controlled, two-way transmission of data. It is a byte-stream protocol used to support the .Dv SOCK_STREAM abstraction. TCP uses the standard Internet address format and, in addition, provides a per-host collection of .Dq port addresses . Thus, each address is composed of an Internet address specifying the host and network, with a specific .Tn TCP port on the host identifying the peer entity. .Pp Sockets utilizing the tcp protocol are either .Dq active or .Dq passive . Active sockets initiate connections to passive sockets. By default .Tn TCP sockets are created active; to create a passive socket the .Xr listen 2 system call must be used after binding the socket with the .Xr bind 2 system call. Only passive sockets may use the .Xr accept 2 call to accept incoming connections. Only active sockets may use the .Xr connect 2 call to initiate connections. .Tn TCP also supports a more datagram-like mode, called Transaction .Tn TCP , which is described in .Xr ttcp 4 . .Pp Passive sockets may .Dq underspecify their location to match incoming connection requests from multiple networks. This technique, termed .Dq wildcard addressing , allows a single server to provide service to clients on multiple networks. To create a socket which listens on all networks, the Internet address .Dv INADDR_ANY must be bound. The .Tn TCP port may still be specified at this time; if the port is not specified the system will assign one. Once a connection has been established the socket's address is fixed by the peer entity's location. The address assigned the socket is the address associated with the network interface through which packets are being transmitted and received. Normally this address corresponds to the peer entity's network. .Pp .Tn TCP supports a number of socket options which can be set with .Xr setsockopt 2 and tested with .Xr getsockopt 2 : .Bl -tag -width TCP_MD5SIGx .It Dv TCP_NODELAY Under most circumstances, .Tn TCP sends data when it is presented; when outstanding data has not yet been acknowledged, it gathers small amounts of output to be sent in a single packet once an acknowledgement is received. For a small number of clients, such as window systems that send a stream of mouse events which receive no replies, this packetization may cause significant delays. The boolean option .Dv TCP_NODELAY defeats this algorithm. .It Dv TCP_MAXSEG By default, a sender\- and receiver-TCP will negotiate among themselves to determine the maximum segment size to be used for each connection. The .Dv TCP_MAXSEG option allows the user to determine the result of this negotiation, and to reduce it if desired. .It Dv TCP_NOOPT .Tn TCP usually sends a number of options in each packet, corresponding to various .Tn TCP extensions which are provided in this implementation. The boolean option .Dv TCP_NOOPT is provided to disable .Tn TCP option use on a per-connection basis. .It Dv TCP_NOPUSH By convention, the sender-TCP will set the .Dq push bit and begin transmission immediately (if permitted) at the end of every user call to .Xr write 2 or .Xr writev 2 . The .Dv TCP_NOPUSH option is provided to allow servers to easily make use of Transaction TCP (see .Xr ttcp 4 ) . When the option is set to a non-zero value, .Tn TCP will delay sending any data at all until either the socket is closed, or the internal send buffer is filled. .It Dv TCP_MD5SIG This option enables the use of MD5 digests (also known as TCP-MD5) on writes to the specified socket. In the current release, only outgoing traffic is digested; digests on incoming traffic are not verified. The current default behavior for the system is to respond to a system advertising this option with TCP-MD5; this may change. .Pp One common use for this in a FreeBSD router deployment is to enable based routers to interwork with Cisco equipment at peering points. Support for this feature conforms to RFC 2385. Only IPv4 (AF_INET) sessions are supported. .Pp In order for this option to function correctly, it is necessary for the administrator to add a tcp-md5 key entry to the system's security associations database (SADB) using the .Xr setkey 8 utility. This entry must have an SPI of 0x1000 and can therefore only be specified on a per-host basis at this time. .Pp If an SADB entry cannot be found for the destination, the outgoing traffic will have an invalid digest option prepended, and the following error message will be visible on the system console: .Em "tcp_signature_compute: SADB lookup failed for %d.%d.%d.%d" . .El .Pp The option level for the .Xr setsockopt 2 call is the protocol number for .Tn TCP , available from .Xr getprotobyname 3 , or .Dv IPPROTO_TCP . All options are declared in .Aq Pa netinet/tcp.h . .Pp Options at the .Tn IP transport level may be used with .Tn TCP ; see .Xr ip 4 . Incoming connection requests that are source-routed are noted, and the reverse source route is used in responding. .Sh MIB VARIABLES The .Nm protocol implements a number of variables in the .Li net.inet branch of the .Xr sysctl 3 MIB. .Bl -tag -width TCPCTL_DO_RFC1644 .It Dv TCPCTL_DO_RFC1323 .Pq tcp.rfc1323 Implement the window scaling and timestamp options of RFC 1323 (default true). .It Dv TCPCTL_DO_RFC1644 .Pq tcp.rfc1644 Implement Transaction .Tn TCP , as described in RFC 1644. .It Dv TCPCTL_MSSDFLT .Pq tcp.mssdflt The default value used for the maximum segment size .Pq Dq MSS when no advice to the contrary is received from MSS negotiation. .It Dv TCPCTL_SENDSPACE .Pq tcp.sendspace Maximum TCP send window. .It Dv TCPCTL_RECVSPACE .Pq tcp.recvspace Maximum TCP receive window. .It tcp.log_in_vain Log any connection attempts to ports where there is not a socket accepting connections. The value of 1 limits the logging to SYN (connection establishment) packets only. That of 2 results in any TCP packets to closed ports being logged. Any value unlisted above disables the logging (default is 0, i.e., the logging is disabled). .It tcp.slowstart_flightsize The number of packets allowed to be in-flight during the .Tn TCP slow-start phase on a non-local network. .It tcp.local_slowstart_flightsize The number of packets allowed to be in-flight during the .Tn TCP slow-start phase to local machines in the same subnet. .It tcp.msl The Maximum Segment Lifetime for a packet. .It tcp.keepinit Timeout for new, non-established TCP connections. .It tcp.keepidle Amount of time the connection should be idle before keepalive probes (if enabled) are sent. .It tcp.keepintvl The interval between keepalive probes sent to remote machines. After .Dv TCPTV_KEEPCNT (default 8) probes are sent, with no response, the connection is dropped. .It tcp.always_keepalive Assume that .Dv SO_KEEPALIVE is set on all .Tn TCP connections, the kernel will periodically send a packet to the remote host to verify the connection is still up. .It tcp.icmp_may_rst Certain .Tn ICMP unreachable messages may abort connections in .Tn SYN-SENT state. .It tcp.do_tcpdrain Flush packets in the .Tn TCP reassembly queue if the system is low on mbufs. .It tcp.blackhole If enabled, disable sending of RST when a connection is attempted to a port where there is not a socket accepting connections. See .Xr blackhole 4 . .It tcp.delayed_ack Delay ACK to try and piggyback it onto a data packet. .It tcp.delacktime Maximum amount of time before a delayed ACK is sent. .It tcp.newreno Enable TCP NewReno Fast Recovery algorithm, as described in RFC 2582. .It tcp.path_mtu_discovery Enable Path MTU Discovery .It tcp.tcbhashsize Size of the .Tn TCP control-block hashtable (read-only). This may be tuned using the kernel option .Dv TCBHASHSIZE or by setting .Va net.inet.tcp.tcbhashsize in the .Xr loader 8 . .It tcp.pcbcount Number of active process control blocks (read-only). .It tcp.syncookies Determines whether or not syn cookies should be generated for outbound syn-ack packets. Syn cookies are a great help during syn flood attacks, and are enabled by default. .It tcp.isn_reseed_interval The interval (in seconds) specifying how often the secret data used in RFC 1948 initial sequence number calculations should be reseeded. By default, this variable is set to zero, indicating that no reseeding will occur. Reseeding should not be necessary, and will break .Dv TIME_WAIT recycling for a few minutes. .It tcp.inet.tcp.rexmit_{min,slop} Adjust the retransmit timer calculation for TCP. The slop is typically added to the raw calculation to take into account occasional variances that the SRTT (smoothed round trip time) is unable to accomodate, while the minimum specifies an absolute minimum. While a number of TCP RFCs suggest a 1 second minimum these RFCs tend to focus on streaming behavior and fail to deal with the fact that a 1 second minimum has severe detrimental effects over lossy interactive connections, such as a 802.11b wireless link, and over very fast but lossy connections for those cases not covered by the fast retransmit code. For this reason we suggest changing the slop to 200ms and setting the minimum to something out of the way, like 20ms, which gives you an effective minimum of 200ms (similar to Linux). .It tcp.inflight_enable Enable .Tn TCP bandwidth delay product limiting. An attempt will be made to calculate the bandwidth delay product for each individual TCP connection and limit -the amount of inflight data being transmitted to avoid building up +the amount of inflight data being transmitted to avoid building up unnecessary packets in the network. This option is recommended if you are serving a lot of data over connections with high bandwidth-delay products, such as modems, GigE links, and fast long-haul WANs, and/or you have configured your machine to accomodate large TCP windows. In such situations, without this option, you may experience high interactive latencies or packet loss due to the overloading of intermediate routers and switches. Note that bandwidth delay product limiting only effects the transmit side of a TCP connection. .It tcp.inflight_debug Enable debugging for the bandwidth delay product algorithm. This may default to on (1) so if you enable the algorithm you should probably also disable debugging by setting this variable to 0. .It tcp.inflight_min This puts an lower bound on the bandwidth delay product window, in bytes. A value of 1024 is typically used for debugging. 6000-16000 is more typical in a production installation. Setting this value too low may result in slow ramp-up times for bursty connections. Setting this value too high effectively disables the algorithm. .It tcp.inflight_max This puts an upper bound on the bandwidth delay product window, in bytes. This value should not generally be modified but may be used to set a global per-connection limit on queued data, potentially allowing you to intentionally set a less then optimum limit to smooth data flow over a network while still being able to specify huge internal TCP buffers. .It tcp.inflight_stab The bandwidth delay product algorithm requires a slightly larger window then it otherwise calculates for stability. This parameter determines the -extra window in maximal packets / 10. The default value of 20 represents +extra window in maximal packets / 10. The default value of 20 represents 2 maximal packets. Reducing this value is not recommended but you may come across a situation with very slow links where the ping time reduction of the default inflight code is not sufficient. If this case occurs you should first try reducing tcp.inflight_min and, if that does not work, reduce both tcp.inflight_min and tcp.inflight_stab, trying values of 15, 10, or 5 for the latter. Never use a value less then 5. Reducing tcp.inflight_stab can lead to upwards of a 20% underutilization of the link as well as reducing the algorithm's ability to adapt to changing situations and should only be done as a last resort. .El .Sh ERRORS A socket operation may fail with one of the following errors returned: .Bl -tag -width Er .It Bq Er EISCONN when trying to establish a connection on a socket which already has one; .It Bq Er ENOBUFS when the system runs out of memory for an internal data structure; .It Bq Er ETIMEDOUT when a connection was dropped due to excessive retransmissions; .It Bq Er ECONNRESET when the remote peer forces the connection to be closed; .It Bq Er ECONNREFUSED when the remote peer actively refuses connection establishment (usually because no process is listening to the port); .It Bq Er EADDRINUSE when an attempt is made to create a socket with a port which has already been allocated; .It Bq Er EADDRNOTAVAIL when an attempt is made to create a socket with a network address for which no network interface exists. .It Bq Er EAFNOSUPPORT when an attempt is made to bind or connect a socket to a multicast address. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr socket 2 , .Xr sysctl 3 , .Xr blackhole 4 , .Xr inet 4 , .Xr intro 4 , .Xr ip 4 , .Xr ttcp 4 .Rs .%A V. Jacobson .%A R. Braden .%A D. Borman .%T "TCP Extensions for High Performance" .%O RFC 1323 .Re .Rs .%A R. Braden .%T "T/TCP \- TCP Extensions for Transactions" .%O RFC 1644 .Re .Sh HISTORY The .Nm protocol appeared in .Bx 4.2 . The RFC 1323 extensions for window scaling and timestamps were added in .Bx 4.4 . Index: stable/4/share/man/man5/kernel.conf.5 =================================================================== --- stable/4/share/man/man5/kernel.conf.5 (revision 139702) +++ stable/4/share/man/man5/kernel.conf.5 (revision 139703) @@ -1,99 +1,99 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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$ .\" .Dd May 23, 2003 .Dt KERNEL.CONF 5 .Os .Sh NAME .Nm kernel.conf .Nd configuration for legacy devices .Sh DESCRIPTION -The +The .Nm file contains configuration entries created by the USERCONFIG mechanism. This is typically used to force I/O port, memory and IRQ settings for legacy ISA devices on the i386 platform. It is typically created during first-time system installation by .Xr kget 8 . .Pp The file .Pa /boot/loader.conf must contain this line for the .Nm script to be loaded: .Pp .Dl userconfig_script_load="YES" .Pp The file .Pa /boot/defaults/loader.conf contains the following two lines: .Pp .Dl userconfig_script_name="/boot/kernel.conf" .Dl userconfig_script_type="userconfig_script" .Pp The kernel must be compiled with the following option: .Pp .Dl options USERCONFIG .Pp This option is normally present in the GENERIC kernel. .Sh SYNTAX Device names must contain both the name of the driver and the instance number, for example, ed0. .Pp .Bl -tag -width "iom
" -compact .It Sy di Disable the given device. .It Sy en Enable the given device. .It Sy po Set the beginning of the device's allocated port range. .It Sy ir Set the device's interrupt request line. .It Sy dr Set the device's dma channel. .It Sy iom
Set the beginning of the device's allocated memory window. .It Sy ios Set the size of the device's allocated memory window. .It Sy f Set arbitrary flags for the device. .It Sy q End the configuration file. .El .Sh SEE ALSO .Xr loader.conf 5 .Xr boot 8 , .Xr kget 8 , .Xr loader 8 , .Sh HISTORY The .Nm mechanism has been deprecated in .Fx 5.0 . .Sh AUTHORS This man page was written by .An Bruce M Simpson Aq bms@spc.org . Index: stable/4/share/man/man5/rc.conf.5 =================================================================== --- stable/4/share/man/man5/rc.conf.5 (revision 139702) +++ stable/4/share/man/man5/rc.conf.5 (revision 139703) @@ -1,1961 +1,1961 @@ .\" Copyright (c) 1995 .\" Jordan K. Hubbard .\" .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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$ .\" .Dd March 3, 2002 .Dt RC.CONF 5 .Os .Sh NAME .Nm rc.conf .Nd system configuration information .Sh DESCRIPTION The file .Nm contains descriptive information about the local host name, configuration details for any potential network interfaces and which services should be started up at system initial boot time. In new installations, the .Nm file is generally initialized by the system installation utility: .Pa /stand/sysinstall . .Pp The purpose of .Nm is not to run commands or perform system startup actions directly. Instead, it is included by the various generic startup scripts in .Pa /etc which conditionalize their internal actions according to the settings found there. .Pp The .Pa /etc/rc.conf file is included from the file .Pa /etc/defaults/rc.conf , which specifies the default settings for all the available options. Options need only be specified in .Pa /etc/rc.conf when the system administrator wishes to override these defaults. The file .Pa /etc/rc.conf.local is used to override settings in .Pa /etc/rc.conf for historical reasons. See the .Dq rc_conf_files option below. .Pp The following list provides a name and short description for each variable that can be set in the .Nm file: .Bl -tag -width Ar .It Va swapfile .Pq Vt str If set to .Dq NO then no swapfile is installed, otherwise the value is used as the full pathname to a file to use for additional swap space. .It Va apm_enable .Pq Vt bool If set to .Dq YES , enable support for Automatic Power Management with the .Xr apm 8 command. .It Va apmd_enable .Pq Vt bool Run .Xr apmd 8 to handle APM event from userland. This also enable support for APM. .It Va apmd_flags .Pq Vt str If .Va apmd_enable is set to .Dq YES , these are the flags to pass to the .Xr apmd 8 daemon. .It Va pccard_enable .Pq Vt bool If set to .Dq YES , enable PCCARD support at boot time. .It Va pccard_mem .Pq Vt str Set to PCCARD controller memory address or .Dq DEFAULT for the default value. .It Va pccard_ifconfig .Pq Vt str List of arguments to be passed to .Xr ifconfig 8 at boot time or on insertion of the card (e.g. "inet 192.168.1.1 netmask 255.255.255.0" for a fixed address or "DHCP" for a DHCP client). .It Va pccard_beep .Pq Vt int If 0, set the PCCARD controller to silent mode. If 1, set it to beep mode. If 2, set it to melody mode. .It Va pccard_conf .Pq Vt str Path to the configuration file for the .Xr pccardd 8 daemon. .It Va pccardd_flags .Pq Vt str If .Va pccard_enable is set to .Dq YES , these are the flags to pass to the .Xr pccardd 8 daemon. .It Va pccard_ether_delay .Pq Vt str Set the delay before starting .Xr dhclient 8 in .Xr pccard_ether 8 script. This defaults to 5 seconds to work around a bug in the .Xr ed 4 driver which can lead to system hangs when using some newer .Xr ed 4 based cards. .It Va local_startup .Pq Vt str List of directories to search for startup script files. .It Va script_name_sep .Pq Vt str The field separator to use for breaking down the list of startup script files into individual filenames. The default is a space. It is not necessary to change this unless there are startup scripts with names containing spaces. .It Va hostname .Pq Vt str The Fully Qualified Domain Name of this host on the network. This should almost certainly be set to something meaningful, even if there is no network connection. If .Xr dhclient 8 is used to set the hostname via DHCP, this variable should be set to an empty string. .It Va nisdomainname .Pq Vt str The NIS domain name of this host, or .Dq NO if NIS is not used. .It Va dhcp_program .Pq Vt str Path to the DHCP client program .Pa ( /sbin/dhclient , the ISC DHCP client, is the default). .It Va dhcp_flags .Pq Vt str Additional flags to pass to the DHCP client program. For the ISC DHCP client, see the .Xr dhclient 8 page for a description of the command line options available. .It Va firewall_enable .Pq Vt bool Set to .Dq YES to load firewall rules at startup. If the kernel was not built with .Dv IPFIREWALL , the ipfw kernel module will be loaded. See also .Va ipfilter_enable . .It Va firewall_script .Pq Vt str This variable specifies the full path to the firewall script to run. The default is .Pa /etc/rc.firewall . .It Va firewall_type .Pq Vt str Names the firewall type from the selection in .Pa /etc/rc.firewall , or the file which contains the local firewall ruleset. Valid selections from .Pa /etc/rc.firewall , are .Dq open - unrestricted IP access; .Dq closed - all IP services disabled, except via lo0; .Dq client - basic protection for a workstation; .Dq simple - basic protection for a LAN. If a filename is specified, the full path must be given. .It Va firewall_quiet .Pq Vt bool Set to .Dq YES to disable the display of ipfw rules on the console during boot. .It Va firewall_logging .Pq Vt bool Set to .Dq YES to enable ipfw event logging. This is equivalent to the .Dv IPFIREWALL_VERBOSE kernel option. .It Va firewall_flags .Pq Vt str Flags passed to .Xr ipfw 8 if .Va firewall_type specifies a filename. .It Va natd_program .Pq Vt str Path to .Xr natd 8 . .It Va natd_enable .Pq Vt bool Set to .Dq YES to enable natd. .Va firewall_enable must also be set to .Dq YES , and .Xr divert 4 sockets must be enabled in the kernel. .It Va natd_interface .Pq Vt str This is the name of the public interface on which natd should run. The interface may be given as an interface name or as an IP address. .It Va natd_flags .Pq Vt str Additional natd flags should be placed here. The .Fl n or .Fl a flag is automatically added with the above .Va natd_interface as an argument. .\" ----- ipfilter_enable setting -------------------------------- .It Va ipfilter_enable .Pq Vt bool Set to .Dq NO by default. Setting this to .Dq YES enables .Xr ipf 8 packet filtering. .Pp Typical usage will require putting .Bd -literal ipfilter_enable="YES" ipnat_enable="YES" ipmon_enable="YES" ipfs_enable="YES" .Ed .Pp into .Pa /etc/rc.conf and editing .Pa /etc/ipf.rules and .Pa /etc/ipnat.rules appropriately. .Pp Note that .Va ipfilter_enable and .Va ipnat_enable can be enabled independently. .Va ipmon_enable and .Va ipfs_enable both require at least one of .Va ipfilter_enable and .Va ipnat_enable to be enabled. .Pp Having .Bd -literal options IPFILTER options IPFILTER_LOG options IPFILTER_DEFAULT_BLOCK .Ed .Pp in the kernel configuration file is a good idea, too. .\" ----- ipfilter_program setting ------------------------------ .It Va ipfilter_program .Pq Vt str Path to .Xr ipf 8 (default .Pa /sbin/ipf ) . .\" ----- ipfilter_rules setting -------------------------------- .It Va ipfilter_rules .Pq Vt str Set to .Dq /etc/ipf.rules by default. This variable contains the name of the filter rule definition file. The file is expected to be readable for the .Xr ipf 8 command to execute. .\" ----- ipfilter_flags setting -------------------------------- .It Va ipfilter_flags .Pq Vt str Empty by default. This variable contains flags passed to the .Xr ipf 8 program. .\" ----- ipnat_enable setting ---------------------------------- .It Va ipnat_enable .Pq Vt bool Set to .Dq NO by default. Set it to .Dq YES to enable .Xr ipnat 1 network address translation. See .Va ipfilter_enable for a detailed discussion. .\" ----- ipnat_program setting --------------------------------- .It Va ipnat_program .Pq Vt str Path to .Xr ipnat 1 (default .Pa /sbin/ipnat ) . .\" ----- ipnat_rules setting ----------------------------------- .It Va ipnat_rules .Pq Vt str Set to .Dq /etc/ipnat.rules by default. This variable contains the name of the file holding the network address translation definition. This file is expected to be readable for the .Xr ipnat 1 command to execute. .\" ----- ipnat_flags setting ----------------------------------- .It Va ipnat_flags .Pq Vt str Empty by default. This variable contains flags passed to the .Xr ipnat 1 program. .\" ----- ipmon_enable setting ---------------------------------- .It Va ipmon_enable .Pq Vt bool Set to .Dq NO by default. Set it to .Dq YES to enable .Xr ipmon 8 monitoring (logging .Xr ipf 8 and .Xr ipnat 1 events). Setting this variable needs setting .Va ipfilter_enable or .Va ipnat_enable too. See .Va ipfilter_enable for a detailed discussion. .\" ----- ipmon_program setting --------------------------------- .It Va ipmon_program .Pq Vt str Path to .Xr ipmon 8 (default .Pa /sbin/ipmon ) . .\" ----- ipmon_flags setting ----------------------------------- .It Va ipmon_flags .Pq Vt str Set to .Dq -Ds by default. This variable contains flags passed to the .Xr ipmon 8 program. Another typical example would be .Dq -D /var/log/ipflog to have .Xr ipmon 8 log directly to a file bypassing .Xr syslogd 8 . Make sure to adjust .Pa /etc/newsyslog.conf in such case like this: .Bd -literal /var/log/ipflog 640 10 100 * Z /var/run/ipmon.pid .Ed .\" ----- ipfs_enable setting ----------------------------------- .It Va ipfs_enable .Pq Vt bool Set to .Dq NO by default. Set it to .Dq YES to enable .Xr ipfs 8 saving the filter and NAT state tables during shutdown and reloading them during startup again. Setting this variable needs setting .Va ipfilter_enable or .Va ipnat_enable to .Dq YES too. See .Va ipfilter_enable for a detailed discussion. Note that if .Va kern_securelevel is set to 3, .Va ipfs_enable cannot be used because the raised securelevel will prevent .Xr ipfs 8 from saving the state tables at shutdown time. .\" ----- ipfs_program setting ---------------------------------- .It Va ipfs_program .Pq Vt str Path to .Xr ipfs 8 (default .Pa /sbin/ipfs ) . .\" ----- ipfs_flags setting ------------------------------------ .It Va ipfs_flags .Pq Vt str Empty by default. This variable contains flags passed to the .Xr ipfs 8 program. .\" ----- end of added ipf hook --------------------------------- .It Va tcp_extensions .Pq Vt bool Set to .Dq YES by default. Setting this to NO disables certain TCP options as described by .Rs .%T RFC 1323 .Re Setting this to .Dq NO might help remedy such problems with connections as randomly hanging or other weird behavior. Some network devices are known to be broken with respect to these options. .It Va log_in_vain .Pq Vt int Set to 0 by default. The .Xr sysctl 8 variables, .Sy net.inet.tcp.log_in_vain and .Sy net.inet.udp.log_in_vain as described in .Xr tcp 4 and .Xr udp 4 , are set to the given value. .It Va tcp_keepalive .Pq Vt bool Set to .Dq YES by default. Setting to NO will disable probing idle TCP connections to verify that the peer is still up and reachable. .It Va tcp_drop_synfin .Pq Vt bool Set to .Dq NO by default. Setting to YES will cause the kernel to ignore TCP frames that have both the SYN and FIN flags set. This prevents OS fingerprinting, but may break some legitimate applications. This option is only available if the kernel was built with the .Dv TCP_DROP_SYNFIN option. .It Va icmp_drop_redirect .Pq Vt bool Set to .Dq NO by default. Setting to YES will cause the kernel to ignore ICMP REDIRECT packets. .It Va icmp_log_redirect .Pq Vt bool Set to .Dq NO by default. Setting to YES will cause the kernel to log ICMP REDIRECT packets. Note that the log messages are not rate-limited, so this option should only be used for troubleshooting networks. .It Va network_interfaces .Pq Vt str Set to the list of network interfaces to configure on this host. For example, if the only network devices in the system are the loopback device (lo0) and a NIC using the ed0 driver, this could be set to .Dq "lo0 ed0" An .Va ifconfig_ Ns Aq Ar interface variable is also assumed to exist for each value of .Ar interface . It is also possible to add IP alias entires here in cases where multiple IP addresses registered against a single interface are desired. Assuming that the interface in question was ed0, it might look something like this: .Bd -literal ifconfig_ed0_alias0="inet 127.0.0.253 netmask 0xffffffff" ifconfig_ed0_alias1="inet 127.0.0.254 netmask 0xffffffff" .Ed .Pp And so on. For each .Va ifconfig_ Ns Ao Ar interface Ac Ns Va _alias Ns Aq Ar n entry that is found, its contents are passed to .Xr ifconfig 8 . Execution stops at the first unsuccessful access, so if something like this is present: .Bd -literal ifconfig_ed0_alias0="inet 127.0.0.251 netmask 0xffffffff" ifconfig_ed0_alias1="inet 127.0.0.252 netmask 0xffffffff" ifconfig_ed0_alias2="inet 127.0.0.253 netmask 0xffffffff" ifconfig_ed0_alias4="inet 127.0.0.254 netmask 0xffffffff" .Ed .Pp Then note that alias4 would .Em not be added since the search would stop with the missing alias3 entry. .Pp It is possible to bring up an interface with DHCP by setting the .Va ifconfig_ Ns Aq Ar interface variable to .Dq DHCP . For instance, to initialize the ed0 device via DHCP, it is possible to use something like: .Bd -literal ifconfig_ed0="DHCP" .Ed .It Va cloned_interfaces .Pq Vt str Set to the list of clonable network interfaces to create on this host. Entries in .Va cloned_interfaces are automatically appended to .Va network_interfaces for configuration. .It Va gif_interfaces .Pq Vt str Set to the list of .Xr gif 4 tunnel interfaces to configure on this host. A .Va gifconfig_ Ns Aq Ar interface variable is assumed to exist for each value of .Ar interface . The value of this variable is used to configure the link layer of the tunnel according to the syntax of the .Cm tunnel option to .Xr ifconfig 8 . Additionaly, this option ensures that each listed interface is created via the .Cm create option to .Xr ifconfig 8 before attempting to configure it. .It Va ppp_enable .Pq Vt bool If set to .Dq YES , run the .Xr ppp 8 daemon. .It Va ppp_mode .Pq Vt str Mode in which to run the .Xr ppp 8 daemon. Accepted modes are .Dq auto , .Dq ddial , .Dq direct and .Dq dedicated . See the manual for a full description. .It Va ppp_nat .Pq Vt bool If set to .Dq YES , enables packet aliasing. Used in conjunction with .Va gateway_enable allows hosts on private network addresses access to the Internet using this host as a network address translating router. .It Va ppp_profile .Pq Vt str The name of the profile to use from .Pa /etc/ppp/ppp.conf . .It Va ppp_user .Pq Vt str The name of the user under which ppp should be started. By default, ppp is started as .Dq root . .\" ----- ipsec settings --------------------------------- .It Va ike_enable .Pq Vt bool If set to .Dq Li YES , run an Internet Key Exchange (IKE) daemon of some sort, based on the settings of .Va ike_program and .Va ike_flags . .It Va ike_program .Pq Vt str If .Va ike_enable is set to .Dq Li YES , this is the name of the IKE daemon to use. The default is .Pa /usr/local/sbin/isakmpd . .It Va ike_flags .Pq Vt str If .Va ike_enable is set to .Dq Li YES , these are the flags to pass to the IKE daemon. .It Va ipsec_enable .Pq Vt bool Set to .Dq Li YES to run .Xr setkey 8 on .Va ipsec_file at boot time. .It Va ipsec_file .Pq Vt str Configuration file for .Xr setkey 8 . .It Va rc_conf_files .Pq Vt str This option is used to specify a list of files that will override the settings in .Pa /etc/defaults/rc.conf . The files will be read in the order in which they are specified and should include the full path to the file. By default, the files specified are .Pa /etc/rc.conf and .Pa /etc/rc.conf.local .It Va fsck_y_enable .Pq Vt bool If set to .Dq YES , .Xr fsck 8 will be run with the -y flag if the initial preen of the filesystems fails. .It Va syslogd_enable .Pq Vt bool If set to .Dq YES , run the .Xr syslogd 8 daemon. .It Va syslogd_program .Pq Vt str Path to .Xr syslogd 8 (default .Pa /usr/sbin/syslogd ) . .It Va syslogd_flags .Pq Vt str If .Va syslogd_enable is set to .Dq YES , these are the flags to pass to .Xr syslogd 8 . .It Va inetd_enable .Pq Vt bool If set to .Dq YES , run the .Xr inetd 8 daemon. .It Va inetd_program .Pq Vt str Path to .Xr inetd 8 (default .Pa /usr/sbin/inetd ) . .It Va inetd_flags .Pq Vt str If .Va inetd_enable is set to .Dq YES , these are the flags to pass to .Xr inetd 8 . .It Va named_enable .Pq Vt bool If set to .Dq YES , run the .Xr named 8 daemon. .It Va named_program .Pq Vt str Path to .Xr named 8 (default .Pa /usr/sbin/named ) . .It Va named_flags .Pq Vt str If .Va named_enable is set to .Dq YES , these are the flags to pass to .Xr named 8 . .It Va kerberos_server_enable .Pq Vt bool Set to .Dq YES to start a Kerberos IV authentication server at boot time. .It Va kadmind_server_enable .Pq Vt bool Set to .Dq YES to start .Xr kadmind 8 , the Kerberos IV Administration Daemon; set to .Dq NO on a slave server. .It Va kerberos_stash .Pq Vt str If .Dq YES , instruct the Kerberos servers to use the stashed master key instead of prompting for it (only if .Va kerberos_server_enable is set to .Dq YES , and is used for both .Xr kerberos 1 and .Xr kadmind 8 ) . .It Va kerberos5_server_enable .Pq Vt bool Set to .Dq YES to start a Kerberos 5 authentication server at boot time. .It Va kadmind5_server_enable .Pq Vt bool Set to .Dq YES to start .Xr k5admind 8 , the Kerberos 5 Administration Daemon; set to .Dq NO on a slave server. .It Va rwhod_enable .Pq Vt bool If set to .Dq YES , run the .Xr rwhod 8 daemon at boot time. .It Va rwhod_flags .Pq Vt str If .Va rwhod_enable is set to .Dq YES , these are the flags to pass to it. .It Va amd_enable .Pq Vt bool If set to .Dq YES , run the .Xr amd 8 daemon at boot time. .It Va amd_flags .Pq Vt str If .Va amd_enable is set to .Dq YES , these are the flags to pass to it. See the .Xr amd 8 .Xr info 1 page for more information. .It Va amd_map_program .Pq Vt str If set, the specified program is run to get the list of .Xr amd 8 maps. For example, if the .Xr amd 8 maps are stored in NIS, one can set this to run .Xr ypcat 1 to get a list of .Xr amd 8 maps from the .Pa amd.master NIS map. .It Va update_motd .Pq Vt bool If set to .Dq YES , .Pa /etc/motd will be updated at boot time to reflect the kernel release being run. If set to .Dq NO , .Pa /etc/motd will not be updated .It Va nfs_client_enable .Pq Vt bool If set to .Dq YES , run the NFS client daemons at boot time. .It Va nfs_client_flags .Pq Vt str If .Va nfs_client_enable is set to .Dq YES , these are the flags to pass to the .Xr nfsiod 8 daemon. .It Va nfs_access_cache .Pq Vt int If .Va nfs_client_enable is set to .Dq YES , this can be set to .Dq 0 to disable NFS ACCESS RPC caching, or to the number of seconds for which NFS ACCESS results should be cached. A value of 2-10 seconds will substantially reduce network traffic for many NFS operations. .It Va nfs_server_enable .Pq Vt bool If set to .Dq YES , run the NFS server daemons at boot time. .It Va nfs_server_flags .Pq Vt str If .Va nfs_server_enable is set to .Dq YES , these are the flags to pass to the .Xr nfsd 8 daemon. .It Va single_mountd_enable .Pq Vt bool If set to .Dq YES , and no .Va nfs_server_enable is set, start .Xr mountd 8 , but not .Xr nfsd 8 daemon. It is commonly needed to run CFS without real NFS used. .It Va mountd_flags .Pq Vt str If .Va mountd_enable is set to .Dq Li YES , these are the flags to pass to the ,Xr mountd 8 daemon. .It Va weak_mountd_authentication .Pq Vt bool If set to .Dq YES , allow services like PCNFSD to make non-privileged mount requests. .It Va nfs_reserved_port_only .Pq Vt bool If set to .Dq YES , provide NFS services only on a secure port. .It Va nfs_bufpackets .Pq Vt int If set to a number, indicates the number of packets worth of socket buffer space to reserve on an NFS client. The kernel default is typically 4. Using a higher number may be useful on gigabit networks to improve performance. The minimum value is 2 and the maximum is 64. .It Va rpc_lockd_enable .Pq Vt bool If set to .Dq YES and also an NFS server, run .Xr rpc.lockd 8 at boot time. .It Va rpc_statd_enable .Pq Vt bool If set to .Dq YES and also an NFS server, run .Xr rpc.statd 8 at boot time. .It Va portmap_program .Pq Vt str Path to .Xr portmap 8 (default .Pa /usr/sbin/portmap ) . .It Va portmap_enable .Pq Vt bool If set to .Dq YES , run the .Xr portmap 8 service at boot time. .It Va portmap_flags .Pq Vt str If .Va portmap_enable is set to .Dq YES , these are the flags to pass to the .Xr portmap 8 daemon. .It Va xtend_enable .Pq Vt bool If set to .Dq YES then run the .Xr xtend 8 daemon at boot time. .It Va xtend_flags .Pq Vt str If .Va xtend_enable is set to .Dq YES , these are the flags to pass to the .Xr xtend 8 daemon. .It Va pppoed_enable .Pq Vt bool If set to .Dq YES then run the .Xr pppoed 8 daemon at boot time to provide PPP over Ethernet services. .It Va pppoed_ Ns Ar provider .Pq Vt str .Xr pppoed 8 listens to requests to this .Ar provider and ultimately runs .Xr ppp 8 with a .Ar system argument of the same name. .It Va pppoed_flags .Pq Vt str Additional flags to pass to .Xr pppoed 8 . .It Va pppoed_interface .Pq Vt str The network interface to run pppoed on. This is mandatory when .Va pppoed_enable is set to .Dq YES . .It Va timed_enable .Pq Vt boot If .Dq YES then run the .Xr timed 8 service at boot time. This command is intended for networks of machines where a consistent .Qq "network time" for all hosts must be established. This is often useful in large NFS environments where time stamps on files are expected to be consistent network-wide. .It Va timed_flags .Pq Vt str If .Va timed_enable is set to .Dq YES , these are the flags to pass to the .Xr timed 8 service. .It Va ntpdate_enable .Pq Vt bool If set to .Dq YES , run ntpdate at system startup. This command is intended to synchronize the system clock only .Em once from some standard reference. An option to set this up initially (from a list of known servers) is also provided by the .Pa /stand/sysinstall program when the system is first installed. .It Va ntpdate_program .Pq Vt str Path to .Xr ntpdate 8 (default .Pa /usr/sbin/ntpdate ) . .It Va ntpdate_flags .Pq Vt str If .Va ntpdate_enable is set to .Dq YES , these are the flags to pass to the .Xr ntpdate 8 command (typically a hostname). .It Va xntpd_enable .Pq Vt bool If set to .Dq YES then run the .Xr ntpd 8 command at boot time. .It Va xntpd_program .Pq Vt str Path to .Xr ntpd 8 (default .Pa /usr/sbin/ntpd ) . .It Va xntpd_flags .Pq Vt str If .Va xntpd_enable is set to .Dq YES , these are the flags to pass to the .Xr ntpd 8 daemon. .It Va nis_client_enable .Pq Vt bool If set to .Dq YES then run the .Xr ypbind 8 service at system boot time. .It Va nis_client_flags .Pq Vt str If .Va nis_client_enable is set to .Dq YES , these are the flags to pass to the .Xr ypbind 8 service. .It Va nis_ypset_enable .Pq Vt bool If set to .Dq YES then run the .Xr ypset 8 daemon at system boot time. .It Va nis_ypset_flags .Pq Vt str If .Va nis_ypset_enable is set to .Dq YES , these are the flags to pass to the .Xr ypset 8 daemon. .It Va nis_server_enable .Pq Vt bool If set to .Dq YES then run the .Xr ypserv 8 daemon at system boot time. .It Va nis_server_flags .Pq Vt str If .Va nis_server_enable is set to .Dq YES , these are the flags to pass to the .Xr ypserv 8 daemon. .It Va nis_ypxfrd_enable .Pq Vt bool If set to .Dq YES then run the .Xr rpc.ypxfrd 8 daemon at system boot time. .It Va nis_ypxfrd_flags .Pq Vt str If .Va nis_ypxfrd_enable is set to .Dq YES , these are the flags to pass to the .Xr rpc.ypxfrd 8 daemon. .It Va nis_yppasswdd_enable .Pq Vt bool If set to .Dq YES then run the .Xr rpc.yppasswdd 8 daemon at system boot time. .It Va nis_yppasswdd_flags .Pq Vt str If .Va nis_yppasswdd_enable is set to .Dq YES , these are the flags to pass to the .Xr rpc.yppasswdd 8 daemon. .It Va defaultrouter .Pq Vt str If not set to .Dq NO then create a default route to this host name or IP address (use an IP address if this router is also required to get to the name server!). .It Va static_routes .Pq Vt str Set to the list of static routes that are to be added at system boot time. If not set to .Dq NO then for each whitespace separated .Ar element in the value, a .Va route_ Ns Aq Ar element variable is assumed to exist whose contents will later be passed to a .Dq route add operation. .It Va gateway_enable .Pq Vt bool If set to .Dq YES , then configure host to at as an IP router, e.g. to forward packets between interfaces. .It Va router_enable .Pq Vt bool If set to .Dq YES then run a routing daemon of some sort, based on the settings of .Va router and .Va router_flags . .It Va router .Pq Vt str If .Va router_enable is set to .Dq YES , this is the name of the routing daemon to use. .It Va router_flags .Pq Vt str If .Va router_enable is set to .Dq YES , these are the flags to pass to the routing daemon. .It Va mrouted_enable .Pq Vt bool If set to .Dq YES then run the multicast routing daemon, .Xr mrouted 8 . .It Va mrouted_flags .Pq Vt str If .Va mrouted_enable is set to .Dq YES , these are the flags to pass to the multicast routing daemon. .It Va ipxgateway_enable .Pq Vt bool If set to .Dq YES then enable the routing of IPX traffic. .It Va ipxrouted_enable .Pq Vt bool If set to .Dq YES then run the .Xr IPXrouted 8 daemon at system boot time. .It Va ipxrouted_flags .Pq Vt str If .Va ipxrouted_enable is set to .Dq YES , these are the flags to pass to the .Xr IPXrouted 8 daemon. .It Va arpproxy_all .Pq Vt bool If set to .Dq YES then enable global proxy ARP. .It Va forward_sourceroute .Pq Vt bool If set to .Dq YES then when .Va gateway_enable is also set to .Dq YES , source routed packets are forwarded. .It Va accept_sourceroute .Pq Vt bool If set to .Dq YES then the system will accept source routed packets directed at it. .It Va rarpd_enable .Pq Vt bool If set to .Dq YES then run the .Xr rarpd 8 daemon at system boot time. .It Va rarpd_flags .Pq Vt str If .Va rarpd_enable is set to .Dq YES , these are the flags to pass to the .Xr rarpd 8 daemon. .It Va atm_enable .Pq Vt bool Set to .Dq YES to enable the configuration of ATM interfaces at system boot time. For all of the ATM variables described below, please refer to the .Xr atm 8 man page for further details on the available command parameters. Also refer to the files in .Pa /usr/share/examples/atm for more detailed configuration information. .It Va atm_netif_ .Pq Vt str For the ATM physical interface .Va , this variable defines the name prefix and count for the ATM network interfaces to be created. The value will be passed as the parameters of an .Dq atm set netif Va command. .It Va atm_sigmgr_ .Pq Vt str For the ATM physical interface .Va , this variable defines the ATM signalling manager to be used. The value will be passed as the parameters of an .Dq atm attach Va command. .It Va atm_prefix_ .Pq Vt str For the ATM physical interface .Va , this variable defines the NSAP prefix for interfaces using a UNI signalling manager. If set to .Em ILMI , then the prefix will automatically be set via the .Xr ilmid 8 daemon. Otherwise, the value will be passed as the parameters of an .Dq atm set prefix Va command. .It Va atm_macaddr_ .Pq Vt str For the ATM physical interface .Va , this variable defines the MAC address for interfaces using a UNI signalling manager. If set to .Dq NO , then the hardware MAC address contained in the ATM interface card will be used. Otherwise, the value will be passed as the parameters of an .Dq atm set mac Va command. .It Va atm_arpserver_ .Pq Vt str For the ATM network interface .Va , this variable defines the ATM address for a host which is to provide ATMARP service. This variable is only applicable to interfaces using a UNI signalling manager. If set to .Em local , then this host will become an ATMARP server. The value will be passed as the parameters of an .Dq atm set arpserver Va command. .It Va atm_scsparp_ .Pq Vt bool If set to .Dq YES , then SCSP/ATMARP service for the network interface .Va will be initiated using the .Xr scspd 8 and .Xr atmarpd 8 daemons. This variable is only applicable if .So .Va atm_arpserver_ Ns Aq Ar netif .No = Ns Qq local .Sc is defined. .It Va atm_pvcs .Pq Vt str Set to the list of ATM PVCs to be added at system boot time. For each whitespace separated .Ar element in the value, an .Va atm_pvc_ Ns Aq Ar element variable is assumed to exist. The value of each of these variables will be passed as the parameters of an .Dq atm add pvc command. .It Va atm_arps .Pq Vt str Set to the list of permanent ATM ARP entries to be added at system boot time. For each whitespace separated .Ar element in the value, an .Va atm_arp_ Ns Aq Ar element variable is assumed to exist. The value of each of these variables will be passed as the parameters of an .Dq atm add arp command. .It Va keymap .Pq Vt str If set to .Dq NO then no keymap is installed, otherwise the value is used to install the keymap file in .Pa /usr/share/syscons/keymaps/.kbd .It Va keyrate .Pq Vt str The keyboard repeat speed. Set to .Dq slow , .Dq normal , .Dq fast or .Dq NO if the default behavior is desired. .It Va keychange .Pq Vt str If not set to .Dq NO , attempt to program the function keys with the value. The value should be a single string of the form: .Qq Ar " [ ]..." .It Va cursor .Pq Vt str Can be set to the value of .Dq normal , .Dq blink , .Dq destructive or .Dq NO to set the cursor behavior explicitly or choose the default behavior. .It Va scrnmap .Pq Vt str If set to .Dq NO then no screen map is installed, otherwise the value is used to install the screen map file in .Pa /usr/share/syscons/scrnmaps/ . .It Va font8x16 .Pq Vt str If set to .Dq NO then the default 8x16 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ is used. .It Va font8x14 .Pq Vt str If set to .Dq NO then the default 8x14 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ is used. .It Va font8x8 .Pq Vt str If set to .Dq NO then the default 8x8 font value is used for screen size requests, otherwise the value in .Pa /usr/share/syscons/fonts/ is used. .It Va blanktime .Pq Vt int If set to .Dq NO then the default screen blanking interval is used, otherwise it is set to .Ar value seconds. .It Va saver .Pq Vt str If not set to .Dq NO , this is the actual screen saver to use (blank, snake, daemon, etc). .It Va moused_enable .Pq Vt str If set to .Dq YES , the .Xr moused 8 daemon is started for doing cut/paste selection on the console. .It Va moused_type .Pq Vt str This is the protocol type of the mouse connected to this host. This variable must be set if .Va moused_enable is set to .Dq YES . The .Xr moused 8 daemon is able to detect the appropriate mouse type automatically in many cases. Set this variable to .Dq auto to let the daemon detect it, or select one from the following list if the automatic detection fails. .Pp If the mouse is attached to the PS/2 mouse port, choose .Dq auto or .Dq ps/2 , regardless of the brand and model of the mouse. Likewise, if the mouse is attached to the bus mouse port, choose .Dq auto or .Dq busmouse . All other protocols are for serial mice and will not work with the PS/2 and bus mice. If this is a USB mouse, .Dq auto is the only protocol type which will work. .Bd -literal microsoft Microsoft mouse (serial) intellimouse Microsoft IntelliMouse (serial) mousesystems Mouse systems Corp mouse (serial) mmseries MM Series mouse (serial) logitech Logitech mouse (serial) busmouse A bus mouse mouseman Logitech MouseMan and TrackMan (serial) glidepoint ALPS GlidePoint (serial) thinkingmouse Kensington ThinkingMouse (serial) ps/2 PS/2 mouse mmhittab MM HitTablet (serial) x10mouseremote X10 MouseRemote (serial) versapad Interlink VersaPad (serial) .Ed .Pp Even if the mouse is not in the above list, it may be compatible with one in the list. Refer to the man page for .Xr moused 8 for compatibility information. .Pp It should also be noted that while this is enabled, any other client of the mouse (such as an X server) should access the mouse through the virtual mouse device: .Pa /dev/sysmouse and configure it as a sysmouse type mouse, since all mouse data is converted to this single canonical format when using .Xr moused 8 . If the client program does not support the sysmouse type, specify the mousesystems type. It is the second preferred type. .It Va moused_port .Pq Vt str If .Va moused_enable is set to .Dq YES , this is the actual port the mouse is on. It might be .Pa /dev/cuaa0 for a COM1 serial mouse, .Pa /dev/psm0 for a PS/2 mouse or .Pa /dev/mse0 for a bus mouse, for example. .It Va moused_flags .Pq Vt str If .Va moused_type is set, these are the additional flags to pass to the .Xr moused 8 daemon. .It Va allscreens_flags .Pq Vt str If set, .Xr vidcontrol 1 is run with these options for each of the virtual terminals .Pq Pa /dev/ttyv* . For example, .Dq -m on will enable the mouse pointer on all virtual terminals if .Va moused_enable is set to .Dq YES . .It Va cron_enable .Pq Vt bool If set to .Dq YES then run the .Xr cron 8 daemon at system boot time. .It Va cron_program .Pq Vt str Path to .Xr cron 8 (default .Pa /usr/sbin/cron ) . .It Va cron_flags .Pq Vt str If .Va cron_enable is set to .Dq YES , these are the flags to pass to .Xr cron 8 . .It Va lpd_program .Pq Vt str Path to .Xr lpd 8 (default .Pa /usr/sbin/lpd ) . .It Va lpd_enable .Pq Vt bool If set to .Dq YES then run the .Xr lpd 8 daemon at system boot time. .It Va lpd_flags .Pq Vt str If .Va lpd_enable is set to .Dq YES , these are the flags to pass to the .Xr lpd 8 daemon. .It Va mta_start_script .Pq Vt str This variable specifies the full path to the script to run to start a mail transfer agent. The default is .Pa /etc/rc.sendmail . The .Va sendmail_* variables which .Pa /etc/rc.sendmail uses are documented in the .Xr rc.sendmail 8 man page. .It Va dumpdev .Pq Vt str Indicates the device (usually a swap partition) to which a crash dump should be written in the event of a system crash. The value of this variable is passed as the argument to .Xr dumpon 8 . To disable crash dumps, set this variable to .Dq NO . .It Va dumpdir .Pq Vt str When the system reboots after a crash and a crash dump is found on the device specified by the .Va dumpdev variable, .Xr savecore 8 will save that crash dump and a copy of the kernel to the directory specified by the .Va dumpdir variable. The default value is .Dq /var/crash . Set to .Dq NO to not run .Xr savecore 8 at boot time when .Va dumpdir is set. .It Va savecore_flags .Pq Vt str If crash dumps are enabled, these are the flags to pass to the .Xr savecore 8 utility. .It Va enable_quotas .Pq Vt bool Set to .Dq YES to turn on user disk quotas on system startup via the .Xr quotaon 8 command. .It Va check_quotas .Pq Vt bool Set to .Dq YES to enable user disk quota checking via the .Xr quotacheck 8 command. .It Va accounting_enable .Pq Vt bool Set to .Dq YES to enable system accounting through the .Xr accton 8 facility. .It Va ibcs2_enable .Pq Vt bool Set to .Dq YES to enable iBCS2 (SCO) binary emulation at system initial boot time. .It Va ibcs2_loaders .Pq Vt str If not set to .Dq NO and if .Va ibcs2_enable is set to .Dq YES , this specifies a list of additional iBCS2 loaders to enable. .It Va linux_enable .Pq Vt bool Set to .Dq YES to enable Linux/ELF binary emulation at system initial boot time. .It Va osf1_enable .Pq Vt bool Set to .Dq YES to enable OSF/1 (Digital UNIX) binary emulation at system initial boot time. (alpha) .It Va rand_irqs .Pq Vt str Set to the list of IRQs to monitor for random number creation (see the man page for .Xr rndcontrol 8 ) . .It Va clear_tmp_enable .Pq Vt bool Set to .Dq YES to have .Pa /tmp cleaned at startup. .It Va ldconfig_paths .Pq Vt str Set to the list of shared library paths to use with .Xr ldconfig 8 . NOTE: .Pa /usr/lib will always be added first, so it need not appear in this list. .It Va ldconfig_insecure .Pq Vt bool The .Xr ldconfig 8 utility normally refuses to use directories which are writable by anyone except root. Set this variable to .Dq YES to disable that security check during system startup. .It Va kern_securelevel_enable .Pq Vt bool Set to .Dq YES to set the kernel security level at system startup. .It Va kern_securelevel .Pq Vt int The kernel security level to set at startup. The allowed range of .Ar value ranges from -1 (the compile time default) to 3 (the most secure). See .Xr init 8 for the list of possible security levels and their effect on system operation. .It Va start_vinum .Pq Vt bool Set to .Dq YES to start .Xr vinum 8 at system boot time. .It Va sshd_program .Pq Vt str Path to the SSH server program .Pa ( /usr/sbin/sshd is the default). .It Va sshd_enable .Pq Vt bool Set to .Dq YES to start .Xr sshd 8 at system boot time. .It Va sshd_flags .Pq Vt str If .Va sshd_enable is set to .Dq YES , these are the flags to pass to the .Xr sshd 8 daemon. .It Va usbd_enable .Pq Vt bool If set to .Dq Li YES , run the .Xr usbd 8 daemon at boot time. .It Va usbd_flags .Pq Vt str If -.Va usbd_enable +.Va usbd_enable is set to .Dq Li YES , these are the flags passed to the .Xr usbd 8 daemon. .It Va unaligned_print .Pq Vt bool If set to .Dq NO then unaligned access warnings will not be printed. (alpha) .\" ----- isdn settings --------------------------------- .It Va isdn_enable .Pq Vt bool Set to .Dq NO by default. When set to .Dq YES , starts the isdn daemon .Pa /usr/sbin/isdnd at system boot time. .It Va isdn_flags .Pq Vt str Set to .Dq -dn -d0x1f9 by default. Additional flags to pass to .Xr isdnd 8 (but see .Va isdn_fsdev and .Va isdn_ttype for certain tunable parameters). .It Va isdn_ttype .Pq Vt str Set to .Dq cons25 by default. The terminal type of the output device when .Xr isdnd 8 operates in fullscreen mode. .It Va isdn_screenflags .Pq Vt str Set to .Dq NO by default. The video mode for fullscreen mode (only for .Xr syscons 4 console driver, see .Xr vidcontrol 1 for valid modes). .It Va isdn_fsdev .Pq Vt str Set to .Dq /dev/ttyv4 by default. The output device for .Xr isdnd 8 in fullscreen mode (or .Dq NO for daemon mode). .It Va isdn_trace .Pq Vt bool Set to .Dq NO by default. When set to .Dq YES , enables the ISDN protocol trace utility .Pa /usr/sbin/isdntrace at system boot time. .It Va isdn_traceflags .Pq Vt str Set to .Dq -f /var/tmp/isdntrace0 by default. Flags for .Pa /usr/sbin/isdntrace . .\" ----------------------------------------------------- .El .Sh FILES .Bl -tag -width /etc/defaults/rc.conf -compact .It Pa /etc/defaults/rc.conf .It Pa /etc/rc.conf .It Pa /etc/rc.conf.local .El .Sh SEE ALSO .Xr catman 1 , .Xr gdb 1 , .Xr info 1 , .Xr makewhatis 1 , .Xr vidcontrol 1 , .Xr tcp 4 , .Xr udp 4 , .Xr exports 5 , .Xr motd 5 , .Xr accton 8 , .Xr amd 8 , .Xr apm 8 , .Xr atm 8 , .Xr cron 8 , .Xr dhclient 8 , .Xr gated 8 , .Xr ifconfig 8 , .Xr inetd 8 , .Xr isdnd 8 , .Xr isdntrace 8 , .Xr lpd 8 , .Xr mountd 8 , .Xr moused 8 , .Xr mrouted 8 , .Xr named 8 , .Xr nfsd 8 , .Xr nfsiod 8 , .Xr ntpd 8 , .Xr ntpdate 8 , .Xr pcnfsd 8 , .Xr portmap 8 , .Xr quotacheck 8 , .Xr quotaon 8 , .Xr rc 8 , .Xr rc.sendmail 8 , .Xr rndcontrol 8 , .Xr route 8 , .Xr routed 8 , .Xr rpc.lockd 8 , .Xr rpc.statd 8 , .Xr rpcbind 8 , .Xr rwhod 8 , .Xr savecore 8 , .Xr setkey 8 , .Xr sshd 8 , .Xr swapon 8 , .Xr sysctl 8 , .Xr syslogd 8 , .Xr timed 8 , .Xr vinum 8 , .Xr vnconfig 8 , .Xr xtend 8 , .Xr yp 8 , .Xr ypbind 8 , .Xr ypserv 8 , .Xr ypset 8 .Sh HISTORY The .Nm file appeared in .Fx 2.2.2 . .Sh AUTHORS .An Jordan K. Hubbard . Index: stable/4/share/man/man7/development.7 =================================================================== --- stable/4/share/man/man7/development.7 (revision 139702) +++ stable/4/share/man/man7/development.7 (revision 139703) @@ -1,484 +1,484 @@ .\" Copyright (c) 1998, Matthew Dillon. Terms and conditions are those of .\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in .\" the FreeBSD source tree. .\" .\" $FreeBSD$ .\" .Dd December 21, 2002 .Dt DEVELOPMENT 7 .Os .Sh NAME .Nm development .Nd introduction to development with the FreeBSD codebase .Sh DESCRIPTION This manual page describes how an ordinary sysop, .Ux admin, or developer can, without any special permission, obtain, maintain, and modify the .Fx codebase as well as how to maintaining a master build which can then be exported to other machines in your network. This manual page is targeted to system operators, programmers, and developers. .Pp Please note that what is being described here is based on a complete FreeBSD environment, not just the FreeBSD kernel. The methods described here are as applicable to production installations as it is to development environments. You need a good 12-17GB of disk space on one machine to make this work conveniently. .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER Your master server should always run a stable, production version of the .Fx operating system. This does not prevent you from doing -CURRENT builds or development. The last thing you want to do is to run an unstable environment on your master server which could lead to a situation where you lose the environment and/or cannot recover from a mistake. .Pp Create a huge partition called /FreeBSD. 8-12GB is recommended. This partition will contain nearly all the development environment, including the CVS tree, broken-out source, and possibly even object files. -You are going to export this partition to your other machines via a +You are going to export this partition to your other machines via a READ-ONLY NFS export so do not mix it with other more security-sensitive partitions. .Pp You have to make a choice in regards to .Pa /usr/obj . You can put .Pa /usr/obj in .Pa /FreeBSD or you can make .Pa /usr/obj its own partition. I recommend making it a separate partition for several reasons. First, as a safety measure since this partition is written to a great deal. Second, because you typically do not have to back it up. Third, because it makes it far easier to mix and match the development environments which are described later in this document. I recommend a .Pa /usr/obj partition of at least 5GB. .Pp On the master server, use cvsup to automatically pull down and maintain the .Fx CVS archive once a day. The first pull will take a long time, it is several gigabytes, but once you have it the daily syncs will be quite small. .Bd -literal -offset 4n mkdir /FreeBSD/FreeBSD-CVS rm -rf /home/ncvs ln -s /FreeBSD/FreeBSD-CVS /home/ncvs .Ed .Pp The cron job should look something like this (please randomize the time of day!). Note that you can use the cvsup file example directly from /usr/share/examples without modification by supplying appropriate arguments to cvsup. .Bd -literal -offset 4n 33 6 * * * /usr/local/bin/cvsup -g -r 20 -L 2 -h cvsup.freebsd.org /usr/share/examples/cvsup/cvs-supfile .Ed .Pp Run the cvsup manually the first time to pull down the archive. It could take all day depending on how fast your connection is! You will run all cvsup and cvs operations as root and you need to set up a ~/.cvsrc (/root/.cvsrc) file, as shown below, for proper cvs operation. Using ~/.cvsrc to specify cvs defaults is an excellent way to "file and forget", but you should never forget that you put them in there. .Bd -literal -offset 4n # cvs -q diff -u update -Pd checkout -P .Ed .Pp Now use cvs to checkout a -STABLE source tree and a -CURRENT source tree, -as well as ports and docs, to create your initial source environment. +as well as ports and docs, to create your initial source environment. Keeping the broken-out source and ports in /FreeBSD allows you to export it to other machines via read-only NFS. This also means you only need to edit/maintain files in one place and all your clients automatically pick up the changes. .Bd -literal -offset 4n mkdir /FreeBSD/FreeBSD-4.x mkdir /FreeBSD/FreeBSD-current cd /FreeBSD/FreeBSD-4.x cvs -d /home/ncvs checkout -rRELENG_4 src cd /FreeBSD/FreeBSD-current cvs -d /home/ncvs checkout src cvs -d /home/ncvs checkout ports cvs -d /home/ncvs checkout doc .Ed .Pp Now create a softlink for /usr/src and /usr/src2. On the main server I always point /usr/src at -STABLE and /usr/src2 at -CURRENT. On client machines I usually do not have a /usr/src2 and I make /usr/src point at whatever version of FreeBSD the client box is intended to run. .Bd -literal -offset 4n cd /usr rm -rf src src2 ln -s /FreeBSD/FreeBSD-4.x/src src (could be -CURRENT on a client) ln -s /FreeBSD/FreeBSD-current/src src2 (MASTER SERVER ONLY) .Ed .Pp Now you have to make a choice for /usr/obj. Well, hopefully you made it already and chose the partition method. If you chose poorly you probably intend to put it in /FreeBSD and, if so, this is what you want to do: .Bd -literal -offset 4n (ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /FreeBSD!) mkdir /FreeBSD/obj cd /usr rm -rf obj ln -s /FreeBSD/obj obj .Ed .Pp Alternatively you may chose simply to leave /usr/obj in /usr. If your -/usr is large enough this will work, but I do not recommend it for +/usr is large enough this will work, but I do not recommend it for safety reasons (/usr/obj is constantly being modified, /usr is not). .Pp Note that exporting /usr/obj via read-only NFS to your other boxes will allow you to build on your main server and install from your other boxes. If you also want to do builds on some or all of the clients you can simply have /usr/obj be a local directory on those clients. You should never export /usr/obj read-write, it will lead to all sorts of problems and issues down the line and presents a security problem as well. It is far easier to do builds on the master server and then only do installs on the clients. .Pp I usually maintain my ports tree via CVS. It is sitting right there in the master CVS archive and I've even told you to check it out (see above). With some fancy softlinks you can make the ports tree available both on your master server and on all of your other machines. Note that the ports tree exists only on the HEAD cvs branch, so its always -CURRENT even on a -STABLE box. This is what you do: .Bd -literal -offset 4n (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS) cd /usr rm -rf ports ln -s /FreeBSD/FreeBSD-current/ports ports cd /usr/ports (this pushes into the softlink) rm -rf distfiles (ON MASTER SERVER ONLY) ln -s /usr/ports.distfiles distfiles (ON MASTER SERVER ONLY) mkdir /usr/ports.distfiles mkdir /usr/ports.workdir .Ed .Pp Since /usr/ports is softlinked into what will be read-only on all of your clients, you have to tell the ports system to use a different working directory to hold ports builds. You want to add a line to your /etc/make.conf file on the master server and on all your clients: .Bd -literal -offset 4n WRKDIRPREFIX=/usr/ports.workdir .Ed .Pp You should try to make the directory you use for the ports working directory as well as the directory used to hold distfiles consistent across all of your machines. If there isn't enough room in /usr/ports.distfiles and /usr/ports.workdir I usually make those softlinks (since this is on /usr these are per-machine) to where the distfiles and working space really are. .Sh EXPORTING VIA NFS FROM THE MASTER SERVER The master server needs to export /FreeBSD and /usr/obj via NFS so all the rest of your machines can get at them. I strongly recommend using a read-only export for both security and safety. The environment I am describing in this manual page is designed primarily around read-only NFS exports. Your exports file on the master server should contain the following lines: .Bd -literal -offset 4n /FreeBSD -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK /usr/obj -ro -alldirs -maproot=root: -network YOURLAN -mask YOURLANMASK .Ed .Pp Of course, NFS server operations must also be configured on that machine. This is typically done via your /etc/rc.conf: .Bd -literal -offset 4n nfs_server_enable="YES" nfs_server_flags="-u -t -n 4" .Ed .Sh THE CLIENT ENVIRONMENT All of your client machines can import the development/build environment directory simply by NFS mounting /FreeBSD and /usr/obj from the master server. A typical /etc/fstab entry on your client machines will be something like this: .Bd -literal -offset 4n masterserver:/FreeBSD /FreeBSD nfs ro,bg 0 0 masterserver:/usr/obj /usr/obj nfs ro,bg 0 0 .Ed .Pp And, of course, you should configure the client for NFS client operations via /etc/rc.conf. In particular, this will turn on nfsiod which will improve client-side NFS performance: .Bd -literal -offset 4n nfs_client_enable="YES" .Ed .Pp Each client should create softlinks for /usr/ports and /usr/src that point into the NFS-mounted environment. If a particular client is running -CURRENT, /usr/src should be a softlink to /FreeBSD/FreeBSD-current/src. If it is running -STABLE, /usr/src should be a softlink to /FreeBSD/FreeBSD-4.x/src. I do not usually create a /usr/src2 softlink on clients, that is used as a convenient shortcut when working on the source code on the master server only and could create massive confusion (of the human variety) on a client. .Bd -literal -offset 4n (ON EACH CLIENT) cd /usr rm -rf ports src ln -s /FreeBSD/FreeBSD-current/ports ports ln -s /FreeBSD/FreeBSD-XXX/src src .Ed .Pp Don't forget to create the working directories so you can build ports, as previously described. If these are not good locations, make them softlinks to the correct location. Remember that /usr/ports/distfiles is exported by the master server and is therefore going to point to the same place (typically /usr/ports.distfiles) on every machine. .Bd -literal -offset 4n mkdir /usr/ports.distfiles mkdir /usr/ports.workdir .Ed .Sh BUILDING KERNELS Here is how you build a -STABLE kernel (on your main development box). If you want to create a custom kernel, cp GENERIC to YOURKERNEL and then edit it before configuring and building. The kernel configuration file lives in /usr/src/sys/i386/conf/KERNELNAME. .Bd -literal -offset 4n cd /usr/src make buildkernel KERNCONF=KERNELNAME .Ed .Pp .Sy WARNING! If you are familiar with the old config/cd/make method of building -a -STABLE kernel, note that the config method will put the build +a -STABLE kernel, note that the config method will put the build environment in /usr/src/sys/compile/KERNELNAME instead of in /usr/obj. .Pp Building a -CURRENT kernel .Bd -literal -offset 4n cd /usr/src2 (on the master server) make buildkernel KERNCONF=KERNELNAME .Ed .Sh INSTALLING KERNELS Installing a -STABLE kernel (typically done on a client. Only do this on your main development server if you want to install a new kernel for your main development server): .Bd -literal -offset 4n cd /usr/src make installkernel KERNCONF=KERNELNAME .Ed .Pp If you are using the older config/cd/make build mechanism for stable, you would install using: .Bd -literal -offset 4n cd /usr/src/sys/compile/KERNELNAME make install .Ed .Pp Installing a -CURRENT kernel (typically done only on a client) .Bd -literal -offset 4n (remember /usr/src is pointing to the client's specific environment) cd /usr/src make installkernel KERNCONF=KERNELNAME .Ed .Pp .Sh BUILDING THE WORLD This environment is designed such that you do all builds on the master server, and then install from each client. You can do builds on a client only if /usr/obj is local to that client. Building the world is easy: .Bd -literal -offset 4n cd /usr/src make buildworld .Ed .Pp If you are on the master server you are running in a -STABLE environment, but that does not prevent you from building the -CURRENT world. Just cd into the appropriate source directory and you are set. Do not accidentally install it on your master server though! .Bd -literal -offset 4n cd /usr/src2 make buildworld .Ed .Sh INSTALLING THE WORLD You can build on your main development server and install on clients. The main development server must export /FreeBSD and /usr/obj via read-only NFS to the clients. .Pp .Em NOTE!!! If /usr/obj is a softlink on the master server, it must also be the EXACT SAME softlink on each client. If /usr/obj is a directory in /usr or a mount point on the master server, then it must be (interchangeably) a directory in /usr or a mount point on each client. This is because the absolute paths are expected to be the same when building the world as when installing it, and you generally build it on your main development box and install it from a client. If you do not setup /usr/obj properly you will not be able to build on machine and install on another. .Bd -literal -offset 4n (ON THE CLIENT) (remember /usr/src is pointing to the client's specific environment) cd /usr/src make installworld .Ed .Pp .Sy WARNING! If builds work on the master server but installs do not work from the clients, for example you try to install and the client complains that the install tried to write into the read-only /usr/obj, then it is likely that the /etc/make.conf file on the client does not match the one on the master server closely enough and the install is trying to install something that was not built. .Sh DOING DEVELOPMENT ON A CLIENT (NOT JUST INSTALLING) Developers often want to run buildkernel's or buildworld's on client boxes simply to life-test the box. You do this in the same manner that you buildkernel and buildworld on your master server. All you have to do is make sure that /usr/obj is pointing to local storage. If you followed my advise and made /usr/obj its own partition on the master server, then it is typically going to be an NFS mount on the client. Simply unmounting /usr/obj will leave you with a /usr/obj that is a subdirectory in /usr which is typically local to the client. You can then do builds to your heart's content! .Sh MAINTAINING A LOCAL BRANCH I have described how to maintain two versions of the source tree, a stable version in /FreeBSD/FreeBSD-4.x and a current version in /FreeBSD/FreeBSD-current. There is absolutely nothing preventing you from breaking out other versions of the source tree into /FreeBSD/XXX. In fact, my /FreeBSD partition also contains .Ox , .Nx , and various flavors of Linux. You may not necessarily be able to build non-FreeBSD operating systems on your master server, but being able to collect and manage source distributions from a central server is a very useful thing to be able to do and you can certainly export to machines which can build those other operating systems. .Pp Many developers choose to maintain a local branch of .Fx to test patches or build a custom distribution. This can be done with CVS or another source code management system (SubVersion, Perforce, BitKeeper) with its own repository. -Since the main +Since the main .Fx tree is based on CVS, the former is convenient. .Pp First, you need to modify your cvsup environment to avoid it modifying the local changes you have committed to the repository. It is important to remove the "delete" keyword from your supfile and to add the CVSROOT subdirectory to your refuse file. For more information, see .Xr cvsup 1 . .Pp The .Fx version of CVS examines a custom environmental variable, CVS_LOCAL_BRANCH_NUM, which specifies an integer to use when doing a cvs tag/rtag. Set this number to something high (say 1000) to avoid colliding with potential future branches of the main repository. For example, branching a file with version 1.4 produces 1.4.1000. Future commits to this branch will produce revisions 1.4.1000.1, 1.4.1000.2, etc. .Pp To fork your local branch, do: .Bd -literal -offset 4n cvs rtag -r RELENG_4 -b LOCAL_RELENG_4 src .Ed .Pp After this, you can check out a copy from your local repository using the new tag and begin making changes and committing them. For more information on using cvs, see .Xr cvs 1 . .Pp .Sy WARNING! The cvsup utility may blow away changes made on a local branch in some situations. This has been reported to occur when the master CVS repository is directly manipulated or an RCS file is changed. At this point, cvsup notices that the client and server have entirely different RCS files, so it does a full replace instead of trying to send just deltas. Ideally this situation should never arise, but in the real world it happens all the time. .Pp While this is the only scenario where the problem should crop up, there have been some suspicious-sounding reports of CVS_LOCAL_BRANCH_NUM lossage that can't be explained by this alone. Bottom line is, if you value your local branch then you should back it up before every update. .Sh UPDATING VIA CVS The advantage of using cvsup to maintain an updated copy of the CVS repository instead of using it to maintain source trees directly is that you can then pick and choose when you bring your source tree (or pieces of your source tree) up to date. By using a cron job to maintain an updated CVS repository, you can update your source tree at any time without any network cost as follows: .Bd -literal -offset 4n (on the main development server) cd /usr/src cvs -d /home/ncvs update cd /usr/src2 cvs -d /home/ncvs update cd /usr/ports cvs -d /home/ncvs update .Ed .Pp It is that simple, and since you are exporting the whole lot to your clients, your clients have immediately visibility into the updated source. This is a good time to also remind you that most of the cvs operations you do will be done as root, and that certain options are required for CVS to operate properly on the .Fx repository. For example, .Fl Pd is necessary when running "cvs update". These options are typically placed in your ~/.cvsrc (as already described) so you do not have to respecify them every time you run a CVS command. Maintaining the CVS repository also gives you far more flexibility in regards to breaking out multiple versions of the source tree. It is a good idea to give your /FreeBSD partition a lot of space (I recommend 8-12GB) precisely for that reason. If you can make it 15GB I would do it. .Pp I generally do not cvs update via a cron job. This is because I generally want the source to not change out from under me when I am developing code. Instead I manually update the source every so often... when I feel it is a good time. My recommendation is to only keep the cvs repository synchronized via cron. .Sh SEE ALSO .Xr crontab 1 , .Xr crontab 5 , .Xr build 7 , .Xr firewall 7 , .Xr release 7 , .Xr tuning 7 , .Xr diskless 8 .Sh HISTORY The .Nm manual page was originally written by .An Matthew Dillon Aq dillon@FreeBSD.org and first appeared in .Fx 5.0 , December 2002. Index: stable/4/share/man/man7/firewall.7 =================================================================== --- stable/4/share/man/man7/firewall.7 (revision 139702) +++ stable/4/share/man/man7/firewall.7 (revision 139703) @@ -1,379 +1,379 @@ .\" Copyright (c) 2001, Matthew Dillon. Terms and conditions are those of .\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in .\" the source tree. .\" .\" $FreeBSD$ .\" .Dd May 26, 2001 .Dt FIREWALL 7 .Os .Sh NAME .Nm firewall .Nd simple firewalls under FreeBSD .Sh FIREWALL BASICS A Firewall is most commonly used to protect an internal network from an outside network by preventing the outside network from making arbitrary connections into the internal network. Firewalls are also used to prevent outside entities from spoofing internal IP addresses and to isolate services such as NFS or SMBFS (Windows file sharing) within LAN segments. .Pp The .Fx firewalling system also has the capability to limit bandwidth using .Xr dummynet 4 . This feature can be useful when you need to guarantee a certain amount of bandwidth for a critical purpose. For example, if you are doing video conferencing over the Internet via your office T1 (1.5 MBits/s), you may wish to bandwidth-limit all other T1 traffic to 1 MBit/s in order to reserve at least 0.5 MBits for your video conferencing connections. Similarly if you are running a popular web or ftp site from a colocation facility you might want to limit bandwidth to prevent excessive bandwidth charges from your provider. .Pp Finally, .Fx firewalls may be used to divert packets or change the next-hop address for packets to help route them to the correct destination. Packet diversion is most often used to support NAT (network address translation), which allows an internal network using a private IP space to make connections to the outside for browsing or other purposes. .Pp Constructing a firewall may appear to be trivial, but most people get them wrong. The most common mistake is to create an exclusive firewall rather then an inclusive firewall. An exclusive firewall allows all packets through except for those matching a set of rules. An inclusive firewall allows only packets matching the rulset through. Inclusive firewalls are much, much safer then exclusive firewalls but a tad more difficult to build properly. The second most common mistake is to blackhole everything except the particular port you want to let through. TCP/IP needs to be able to get certain types of ICMP errors to function properly - for example, to implement MTU discovery. Also, a number of common system daemons make reverse connections to the .Sy auth service in an attempt to authenticate the user making a connection. Auth is rather dangerous but the proper implementation is to return a TCP reset for the connection attempt rather then simply blackholing the packet. We cover these and other quirks involved with constructing a firewall in the sample firewall section below. .Sh IPFW KERNEL CONFIGURATION You do not need to create a customer kernel to use the IP firewalling features. If you enable firewalling in your -.Em /etc/rc.conf +.Em /etc/rc.conf (see below), the ipfw kernel module will be loaded automatically. However, if you are paranoid you can compile IPFW directly into the .Fx kernel by using the .Sy IPFIREWALL option set. If compiled in the kernel defaults its firewall to deny all packets by default, which means that if you do not load in a permissive ruleset via .Em /etc/rc.conf , rebooting into your new kernel will take the network offline and will prevent you from being able to access it if you are not sitting at the console. It is also quite common to update a kernel to a new release and reboot before updating the binaries. This can result in an incompatibility between the .Xr ipfw 8 program and the kernel which prevents it from running in the boot sequence, also resulting in an inaccessible machine. Because of these problems the .Sy IPFIREWALL_DEFAULT_TO_ACCEPT kernel option is also available which changes the default firewall to pass through all packets. Note, however, that using this option may open a small window of opportunity during booting where your firewall passes all packets. Still, it's a good option to use while getting up to speed with .Fx firewalling. Get rid of it once you understand how it all works to close the loophole, though. There is a third option called .Sy IPDIVERT which allows you to use the firewall to divert packets to a user program and is necessary if you wish to use .Xr natd 8 to give private internal networks access to the outside world. If you want to be able to limit the bandwidth used by certain types of traffic, the .Sy DUMMYNET option must be used to enable .Em ipfw pipe rules. .Sh SAMPLE IPFW-BASED FIREWALL Here is an example ipfw-based firewall taken from a machine with three interface cards. fxp0 is connected to the 'exposed' LAN. Machines on this LAN are dual-homed with both internal 10. IP addresses and Internet-routed IP addresses. In our example, 192.100.5.x represents the Internet-routed IP block while 10.x.x.x represents the internal networks. While it isn't relevant to the example, 10.0.1.x is assigned as the internal address block for the LAN on fxp0, 10.0.2.x for the LAN on fxp1, and 10.0.3.x for the LAN on fxp2. .Pp In this example we want to isolate all three LANs from the Internet as well as isolate them from each other, and we want to give all internal addresses access to the Internet through a NAT gateway running on this machine. To make the NAT gateway work, the firewall machine is given two Internet-exposed addresses on fxp0 in addition to an internal 10. address on fxp0: one exposed address (not shown) represents the machine's official address, and the second exposed address (192.100.5.5 in our example) represents the NAT gateway rendezvous IP. We make the example more complex by giving the machines on the exposed LAN internal 10.0.0.x addresses as well as exposed addresses. The idea here is that you can bind internal services to internal addresses even on exposed machines and still protect those services from the Internet. The only services you run on exposed IP addresses would be the ones you wish to expose to the Internet. .Pp It is important to note that the 10.0.0.x network in our example is not protected by our firewall. You must make sure that your Internet router protects this network from outside spoofing. Also, in our example, we pretty much give the exposed hosts free reign on our internal network when operating services through internal IP addresses (10.0.0.x). This is somewhat of security risk... what if an exposed host is compromised? To remove the risk and force everything coming in via LAN0 to go through the firewall, remove rules 01010 and 01011. .Pp Finally, note that the use of internal addresses represents a big piece of our firewall protection mechanism. With proper spoofing safeguards in place, nothing outside can directly access an internal (LAN1 or LAN2) host. .Bd -literal # /etc/rc.conf # firewall_enable="YES" firewall_type="/etc/ipfw.conf" # temporary port binding range let # through the firewall. # # NOTE: heavily loaded services running through the firewall may require # a larger port range for local-size binding. 4000-10000 or 4000-30000 # might be a better choice. ip_portrange_first=4000 ip_portrange_last=5000 \&... .Ed .Pp .Bd -literal # /etc/ipfw.conf # # FIREWALL: the firewall machine / nat gateway # LAN0 10.0.0.X and 192.100.5.X (dual homed) # LAN1 10.0.1.X # LAN2 10.0.2.X # sw: ethernet switch (unmanaged) # # 192.100.5.x represents IP addresses exposed to the Internet # (i.e. Internet routeable). 10.x.x.x represent internal IPs # (not exposed) # # [LAN1] # ^ # | # FIREWALL -->[LAN2] # | # [LAN0] # | # +--> exposed host A # +--> exposed host B # +--> exposed host C # | # INTERNET (secondary firewall) # ROUTER # | # [Internet] # # NOT SHOWN: The INTERNET ROUTER must contain rules to disallow # all packets with source IP addresses in the 10. block in order # to protect the dual-homed 10.0.0.x block. Exposed hosts are # not otherwise protected in this example - they should only bind # exposed services to exposed IPs but can safely bind internal # services to internal IPs. # # The NAT gateway works by taking packets sent from internal # IP addresses to external IP addresses and routing them to natd, which # is listening on port 8668. This is handled by rule 00300. Data coming # back to natd from the outside world must also be routed to natd using # rule 00301. To make the example interesting, we note that we do # NOT have to run internal requests to exposed hosts through natd # (rule 00290) because those exposed hosts know about our # 10. network. This can reduce the load on natd. Also note that we # of course do not have to route internal<->internal traffic through # natd since those hosts know how to route our 10. internal network. # The natd command we run from /etc/rc.local is shown below. See # also the in-kernel version of natd, ipnat. # # natd -s -u -a 208.161.114.67 # # add 00290 skipto 1000 ip from 10.0.0.0/8 to 192.100.5.0/24 add 00300 divert 8668 ip from 10.0.0.0/8 to not 10.0.0.0/8 add 00301 divert 8668 ip from not 10.0.0.0/8 to 192.100.5.5 # Short cut the rules to avoid running high bandwidths through # the entire rule set. Allow established tcp connections through, # and shortcut all outgoing packets under the assumption that # we need only firewall incoming packets. # # Allowing established tcp connections through creates a small # hole but may be necessary to avoid overloading your firewall. # If you are worried, you can move the rule to after the spoof # checks. # add 01000 allow tcp from any to any established add 01001 allow all from any to any out via fxp0 add 01001 allow all from any to any out via fxp1 add 01001 allow all from any to any out via fxp2 # Spoof protection. This depends on how well you trust your # internal networks. Packets received via fxp1 MUST come from # 10.0.1.x. Packets received via fxp2 MUST come from 10.0.2.x. # Packets received via fxp0 cannot come from the LAN1 or LAN2 # blocks. We can't protect 10.0.0.x here, the Internet router # must do that for us. # add 01500 deny all from not 10.0.1.0/24 in via fxp1 add 01500 deny all from not 10.0.2.0/24 in via fxp2 add 01501 deny all from 10.0.1.0/24 in via fxp0 add 01501 deny all from 10.0.2.0/24 in via fxp0 # In this example rule set there are no restrictions between # internal hosts, even those on the exposed LAN (as long as # they use an internal IP address). This represents a # potential security hole (what if an exposed host is # compromised?). If you want full restrictions to apply # between the three LANs, firewalling them off from each # other for added security, remove these two rules. # # If you want to isolate LAN1 and LAN2, but still want # to give exposed hosts free reign with each other, get # rid of rule 01010 and keep rule 01011. # # (commented out, uncomment for less restrictive firewall) #add 01010 allow all from 10.0.0.0/8 to 10.0.0.0/8 #add 01011 allow all from 192.100.5.0/24 to 192.100.5.0/24 # # SPECIFIC SERVICES ALLOWED FROM SPECIFIC LANS # # If using a more restrictive firewall, allow specific LANs # access to specific services running on the firewall itself. # In this case we assume LAN1 needs access to filesharing running # on the firewall. If using a less restrictive firewall # (allowing rule 01010), you don't need these rules. # add 01012 allow tcp from 10.0.1.0/8 to 10.0.1.1 139 add 01012 allow udp from 10.0.1.0/8 to 10.0.1.1 137,138 # GENERAL SERVICES ALLOWED TO CROSS INTERNAL AND EXPOSED LANS # # We allow specific UDP services through: DNS lookups, ntalk, and ntp. # Note that internal services are protected by virtue of having # spoof-proof internal IP addresses (10. net), so these rules # really only apply to services bound to exposed IPs. We have # to allow UDP fragments or larger fragmented UDP packets will # not survive the firewall. # # If we want to expose high-numbered temporary service ports # for things like DNS lookup responses we can use a port range, # in this example 4000-65535, and we set to /etc/rc.conf variables # on all exposed machines to make sure they bind temporary ports # to the exposed port range (see rc.conf example above) # add 02000 allow udp from any to any 4000-65535,domain,ntalk,ntp add 02500 allow udp from any to any frag # Allow similar services for TCP. Again, these only apply to # services bound to exposed addresses. NOTE: we allow 'auth' # through but do not actually run an identd server on any exposed # port. This allows the machine being authed to respond with a # TCP RESET. Throwing the packet away would result in delays # when connecting to remote services that do reverse ident lookups. # # Note that we do not allow tcp fragments through, and that we do # not allow fragments in general (except for UDP fragments). We # expect the TCP mtu discovery protocol to work properly so there # should be no TCP fragments. # add 03000 allow tcp from any to any http,https add 03000 allow tcp from any to any 4000-65535,ssh,smtp,domain,ntalk add 03000 allow tcp from any to any auth,pop3,ftp,ftp-data # It is important to allow certain ICMP types through, here is a list # of general ICMP types. Note that it is important to let ICMP type 3 # through. # # 0 Echo Reply # 3 Destination Unreachable (used by TCP MTU discovery, aka # packet-too-big) # 4 Source Quench (typically not allowed) # 5 Redirect (typically not allowed - can be dangerous!) # 8 Echo # 11 Time Exceeded # 12 Parameter Problem # 13 Timestamp # 14 Timestamp Reply # # Sometimes people need to allow ICMP REDIRECT packets, which is # type 5, but if you allow it make sure that your Internet router # disallows it. add 04000 allow icmp from any to any icmptypes 0,3,8,11,12,13,14 # log any remaining fragments that get through. Might be useful, # otherwise don't bother. Have a final deny rule as a safety to # guarantee that your firewall is inclusive no matter how the kernel # is configured. # add 05000 deny log ip from any to any frag add 06000 deny all from any to any .Ed .Sh PORT BINDING INTERNAL AND EXTERNAL SERVICES We've mentioned multi-homing hosts and binding services to internal or external addresses but we haven't really explained it. When you have a host with multiple IP addresses assigned to it, you can bind services run on that host to specific IPs or interfaces rather then all IPs. Take the firewall machine for example: With three interfaces and two exposed IP addresses on one of those interfaces, the firewall machine is known by 5 different IP addresses (10.0.0.1, 10.0.1.1, 10.0.2.1, 192.100.5.5, and say 192.100.5.1). If the firewall is providing file sharing services to the windows LAN segment (say it is LAN1), you can use samba's 'bind interfaces' directive to specifically bind it to just the LAN1 IP address. That way the file sharing services will not be made available to other LAN segments. The same goes for NFS. If LAN2 has your UNIX engineering workstations, you can tell nfsd to bind specifically to 10.0.2.1. You can specify how to bind virtually every service on the machine and you can use a light .Xr jail 8 to indirectly bind services that do not otherwise give you the option. .Sh SEE ALSO .Xr ipnat 1 , .Xr dummynet 4 , .Xr ipnat 5 , .Xr rc.conf 5 , .Xr smb.conf 5 [ /usr/ports/net/samba ] , .Xr samba 7 [ /usr/ports/net/samba ] , .Xr config 8 , .Xr ipfw 8 , .Xr jail 8 , .Xr natd 8 , .Xr nfsd 8 .Sh ADDITIONAL READING .Xr ipf 5 , .Xr ipf 8 , .Xr ipfstat 8 .Sh HISTORY The .Nm manual page was originally written by .An Matthew Dillon and first appeared in .Fx 4.3 , May 2001. Index: stable/4/share/man/man7/tuning.7 =================================================================== --- stable/4/share/man/man7/tuning.7 (revision 139702) +++ stable/4/share/man/man7/tuning.7 (revision 139703) @@ -1,913 +1,913 @@ .\" Copyright (c) 2001, Matthew Dillon. Terms and conditions are those of .\" the BSD Copyright as specified in the file "/usr/src/COPYRIGHT" in .\" the source tree. .\" .\" $FreeBSD$ .\" .Dd May 25, 2001 .Dt TUNING 7 .Os .Sh NAME .Nm tuning .Nd performance tuning under FreeBSD .Sh SYSTEM SETUP - DISKLABEL, NEWFS, TUNEFS, SWAP When using .Xr disklabel 8 or .Xr sysinstall 8 to lay out your filesystems on a hard disk it is important to remember that hard drives can transfer data much more quickly from outer tracks than they can from inner tracks. To take advantage of this you should try to pack your smaller filesystems and swap closer to the outer tracks, follow with the larger filesystems, and end with the largest filesystems. It is also important to size system standard filesystems such that you will not be forced to resize them later as you scale the machine up. I usually create, in order, a 128M root, 1G swap, 128M .Pa /var , 128M .Pa /var/tmp , 3G .Pa /usr , and use any remaining space for .Pa /home . .Pp You should typically size your swap space to approximately 2x main memory. If you do not have a lot of RAM, though, you will generally want a lot more swap. It is not recommended that you configure any less than 256M of swap on a system and you should keep in mind future memory expansion when sizing the swap partition. The kernel's VM paging algorithms are tuned to perform best when there is at least 2x swap versus main memory. Configuring too little swap can lead to inefficiencies in the VM page scanning code as well as create issues later on if you add more memory to your machine. Finally, on larger systems with multiple SCSI disks (or multiple IDE disks operating on different controllers), we strongly recommend that you configure swap on each drive (up to four drives). The swap partitions on the drives should be approximately the same size. The kernel can handle arbitrary sizes but internal data structures scale to 4 times the largest swap partition. Keeping the swap partitions near the same size will allow the kernel to optimally stripe swap space across the N disks. Do not worry about overdoing it a little, swap space is the saving grace of .Ux and even if you do not normally use much swap, it can give you more time to recover from a runaway program before being forced to reboot. .Pp How you size your .Pa /var partition depends heavily on what you intend to use the machine for. This partition is primarily used to hold mailboxes, the print spool, and log files. Some people even make .Pa /var/log its own partition (but except for extreme cases it is not worth the waste of a partition ID). If your machine is intended to act as a mail or print server, or you are running a heavily visited web server, you should consider creating a much larger partition \(en perhaps a gig or more. It is very easy to underestimate log file storage requirements. .Pp Sizing .Pa /var/tmp depends on the kind of temporary file usage you think you will need. 128M is the minimum we recommend. Also note that sysinstall will create a .Pa /tmp directory. Dedicating a partition for temporary file storage is important for two reasons: first, it reduces the possibility of filesystem corruption in a crash, and second it reduces the chance of a runaway process that fills up .Oo Pa /var Oc Ns Pa /tmp from blowing up more critical subsystems (mail, logging, etc). Filling up .Oo Pa /var Oc Ns Pa /tmp is a very common problem to have. .Pp In the old days there were differences between .Pa /tmp and .Pa /var/tmp , but the introduction of .Pa /var (and .Pa /var/tmp ) led to massive confusion by program writers so today programs haphazardly use one or the other and thus no real distinction can be made between the two. So it makes sense to have just one temporary directory and softlink to it from the other tmp directory locations. However you handle .Pa /tmp , the one thing you do not want to do is leave it sitting on the root partition where it might cause root to fill up or possibly corrupt root in a crash/reboot situation. .Pp The .Pa /usr partition holds the bulk of the files required to support the system and a subdirectory within it called .Pa /usr/local holds the bulk of the files installed from the .Xr ports 7 hierarchy. If you do not use ports all that much and do not intend to keep system source .Pq Pa /usr/src on the machine, you can get away with a 1 gigabyte .Pa /usr partition. However, if you install a lot of ports (especially window managers and Linux-emulated binaries), we recommend at least a 2 gigabyte .Pa /usr and if you also intend to keep system source on the machine, we recommend a 3 gigabyte .Pa /usr . Do not underestimate the amount of space you will need in this partition, it can creep up and surprise you! .Pp The .Pa /home partition is typically used to hold user-specific data. I usually size it to the remainder of the disk. .Pp Why partition at all? Why not create one big .Pa / partition and be done with it? Then I do not have to worry about undersizing things! Well, there are several reasons this is not a good idea. First, each partition has different operational characteristics and separating them allows the filesystem to tune itself to those characteristics. For example, the root and .Pa /usr partitions are read-mostly, with very little writing, while a lot of reading and writing could occur in .Pa /var and .Pa /var/tmp . By properly partitioning your system fragmentation introduced in the smaller more heavily write-loaded partitions will not bleed over into the mostly-read partitions. Additionally, keeping the write-loaded partitions closer to the edge of the disk (i.e. before the really big partitions instead of after in the partition table) will increase I/O performance in the partitions where you need it the most. Now it is true that you might also need I/O performance in the larger partitions, but they are so large that shifting them more towards the edge of the disk will not lead to a significant performance improvement whereas moving .Pa /var to the edge can have a huge impact. Finally, there are safety concerns. Having a small neat root partition that is essentially read-only gives it a greater chance of surviving a bad crash intact. .Pp Properly partitioning your system also allows you to tune .Xr newfs 8 , and .Xr tunefs 8 parameters. Tuning .Xr newfs 8 requires more experience but can lead to significant improvements in performance. There are three parameters that are relatively safe to tune: .Em blocksize , bytes/i-node , and .Em cylinders/group . .Pp .Fx performs best when using 8K or 16K filesystem block sizes. The default filesystem block size is 16K, which provides best performance for most applications, with the exception of those that perform random access on large files (such as database server software). Such applications tend to perform better with a smaller block size, although modern disk characteristics are such that the performance gain from using a smaller block size may not be worth consideration. Using a block size larger than 16K can cause fragmentation of the buffer cache and lead to lower performance. .Pp The defaults may be unsuitable for a filesystem that requires a very large number of i-nodes or is intended to hold a large number of very small files. Such a filesystem should be created with an 8K or 4K block size. This also requires you to specify a smaller fragment size. We recommend always using a fragment size that is 1/8 the block size (less testing has been done on other fragment size factors). The .Xr newfs 8 options for this would be .Dq Li "newfs -f 1024 -b 8192 ..." . .Pp If a large partition is intended to be used to hold fewer, larger files, such as database files, you can increase the .Em bytes/i-node ratio which reduces the number of i-nodes (maximum number of files and directories that can be created) for that partition. Decreasing the number of i-nodes in a filesystem can greatly reduce .Xr fsck 8 recovery times after a crash. Do not use this option unless you are actually storing large files on the partition, because if you overcompensate you can wind up with a filesystem that has lots of free space remaining but cannot accommodate any more files. Using 32768, 65536, or 262144 bytes/i-node is recommended. You can go higher but it will have only incremental effects on .Xr fsck 8 recovery times. For example, .Dq Li "newfs -i 32768 ..." . .Pp .Xr tunefs 8 may be used to further tune a filesystem. This command can be run in single-user mode without having to reformat the filesystem. However, this is possibly the most abused program in the system. Many people attempt to increase available filesystem space by setting the min-free percentage to 0. This can lead to severe filesystem fragmentation and we do not recommend that you do this. Really the only .Xr tunefs 8 option worthwhile here is turning on .Em softupdates with .Dq Li "tunefs -n enable /filesystem" . (Note: in .Fx 4.5 and later, softupdates can be turned on using the .Fl U option to .Xr newfs 8 , and .Xr sysinstall 8 will typically enable softupdates automatically for non-root filesystems). Softupdates drastically improves meta-data performance, mainly file creation and deletion. We recommend enabling softupdates on most filesystems; however, there are two limitations to softupdates that you should be aware of when determining whether to use it on a filesystem. First, softupdates guarantees filesystem consistency in the case of a crash but could very easily be several seconds (even a minute!) behind on pending writes to the physical disk. If you crash you may lose more work than otherwise. Secondly, softupdates delays the freeing of filesystem blocks. If you have a filesystem (such as the root filesystem) which is close to full, doing a major update of it, e.g.\& .Dq Li "make installworld" , can run it out of space and cause the update to fail. For this reason, softupdates will not be enabled on the root filesystem during a typical install. There is no loss of performance since the root filesystem is rarely written to. .Pp A number of run-time .Xr mount 8 options exist that can help you tune the system. The most obvious and most dangerous one is .Cm async . Do not ever use it; it is far too dangerous. A less dangerous and more useful .Xr mount 8 option is called .Cm noatime . .Ux filesystems normally update the last-accessed time of a file or directory whenever it is accessed. This operation is handled in .Fx with a delayed write and normally does not create a burden on the system. However, if your system is accessing a huge number of files on a continuing basis the buffer cache can wind up getting polluted with atime updates, creating a burden on the system. For example, if you are running a heavily loaded web site, or a news server with lots of readers, you might want to consider turning off atime updates on your larger partitions with this .Xr mount 8 option. However, you should not gratuitously turn off atime updates everywhere. For example, the .Pa /var filesystem customarily holds mailboxes, and atime (in combination with mtime) is used to determine whether a mailbox has new mail. You might as well leave atime turned on for mostly read-only partitions such as .Pa / and .Pa /usr as well. This is especially useful for .Pa / since some system utilities use the atime field for reporting. .Sh STRIPING DISKS In larger systems you can stripe partitions from several drives together to create a much larger overall partition. Striping can also improve the performance of a filesystem by splitting I/O operations across two or more disks. The .Xr vinum 8 and .Xr ccdconfig 8 utilities may be used to create simple striped filesystems. Generally speaking, striping smaller partitions such as the root and .Pa /var/tmp , or essentially read-only partitions such as .Pa /usr is a complete waste of time. You should only stripe partitions that require serious I/O performance, typically .Pa /var , /home , or custom partitions used to hold databases and web pages. Choosing the proper stripe size is also important. Filesystems tend to store meta-data on power-of-2 boundaries and you usually want to reduce seeking rather than increase seeking. This means you want to use a large off-center stripe size such as 1152 sectors so sequential I/O does not seek both disks and so meta-data is distributed across both disks rather than concentrated on a single disk. If you really need to get sophisticated, we recommend using a real hardware RAID controller from the list of .Fx supported controllers. .Sh SYSCTL TUNING .Xr sysctl 8 variables permit system behavior to be monitored and controlled at run-time. Some sysctls simply report on the behavior of the system; others allow the system behavior to be modified; some may be set at boot time using .Xr rc.conf 5 , but most will be set via .Xr sysctl.conf 5 . There are several hundred sysctls in the system, including many that appear to be candidates for tuning but actually are not. In this document we will only cover the ones that have the greatest effect on the system. .Pp The .Va kern.ipc.shm_use_phys sysctl defaults to 0 (off) and may be set to 0 (off) or 1 (on). Setting this parameter to 1 will cause all System V shared memory segments to be mapped to unpageable physical RAM. This feature only has an effect if you are either (A) mapping small amounts of shared memory across many (hundreds) of processes, or (B) mapping large amounts of shared memory across any number of processes. This feature allows the kernel to remove a great deal of internal memory management page-tracking overhead at the cost of wiring the shared memory into core, making it unswappable. .Pp The .Va vfs.vmiodirenable sysctl defaults to 1 (on). This parameter controls how directories are cached by the system. Most directories are small and use but a single fragment (typically 1K) in the filesystem and even less (typically 512 bytes) in the buffer cache. However, when operating in the default mode the buffer cache will only cache a fixed number of directories even if you have a huge amount of memory. Turning on this sysctl allows the buffer cache to use the VM Page Cache to cache the directories. The advantage is that all of memory is now available for caching directories. The disadvantage is that the minimum in-core memory used to cache a directory is the physical page size (typically 4K) rather than 512 bytes. We recommend turning this option off in memory-constrained environments; however, when on, it will substantially improve the performance of services that manipulate a large number of files. Such services can include web caches, large mail systems, and news systems. Turning on this option will generally not reduce performance even with the wasted memory but you should experiment to find out. .Pp The .Va vfs.write_behind sysctl defaults to 1 (on). This tells the filesystem to issue media writes as full clusters are collected, which typically occurs when writing large sequential files. The idea is to avoid saturating the buffer cache with dirty buffers when it would not benefit I/O performance. However, this may stall processes and under certain circumstances you may wish to turn it off. .Pp The .Va vfs.hirunningspace sysctl determines how much outstanding write I/O may be queued to disk controllers system wide at any given instance. The default is usually sufficient but on machines with lots of disks you may want to bump it up to four or five megabytes. Note that setting too high a value (exceeding the buffer cache's write threshold) can lead to extremely bad clustering performance. Do not set this value arbitrarily high! Also, higher write queueing values may add latency to reads occuring at the same time. .Pp There are various other buffer-cache and VM page cache related sysctls. We do not recommend modifying these values. As of .Fx 4.3 , the VM system does an extremely good job tuning itself. .Pp The .Va net.inet.tcp.sendspace and .Va net.inet.tcp.recvspace sysctls are of particular interest if you are running network intensive applications. They control the amount of send and receive buffer space allowed for any given TCP connection. The default sending buffer is 32K; the default receiving buffer is 64K. You can often improve bandwidth utilization by increasing the default at the cost of eating up more kernel memory for each connection. We do not recommend increasing the defaults if you are serving hundreds or thousands of simultaneous connections because it is possible to quickly run the system out of memory due to stalled connections building up. But if you need high bandwidth over a fewer number of connections, especially if you have gigabit Ethernet, increasing these defaults can make a huge difference. You can adjust the buffer size for incoming and outgoing data separately. For example, if your machine is primarily doing web serving you may want to decrease the recvspace in order to be able to increase the sendspace without eating too much kernel memory. Note that the routing table (see .Xr route 8 ) can be used to introduce route-specific send and receive buffer size defaults. .Pp As an additional management tool you can use pipes in your firewall rules (see .Xr ipfw 8 ) to limit the bandwidth going to or from particular IP blocks or ports. For example, if you have a T1 you might want to limit your web traffic to 70% of the T1's bandwidth in order to leave the remainder available for mail and interactive use. Normally a heavily loaded web server will not introduce significant latencies into other services even if the network link is maxed out, but enforcing a limit can smooth things out and lead to longer term stability. Many people also enforce artificial bandwidth limitations in order to ensure that they are not charged for using too much bandwidth. .Pp Setting the send or receive TCP buffer to values larger then 65535 will result in a marginal performance improvement unless both hosts support the window scaling extension of the TCP protocol, which is controlled by the .Va net.inet.tcp.rfc1323 sysctl. These extensions should be enabled and the TCP buffer size should be set to a value larger than 65536 in order to obtain good performance from certain types of network links; specifically, gigabit WAN links and high-latency satellite links. RFC1323 support is enabled by default. .Pp The .Va net.inet.tcp.always_keepalive sysctl determines whether or not the TCP implementation should attempt to detect dead TCP connections by intermittently delivering .Dq keepalives on the connection. By default, this is enabled for all applications; by setting this sysctl to 0, only applications that specifically request keepalives will use them. In most environments, TCP keepalives will improve the management of system state by expiring dead TCP connections, particularly for systems serving dialup users who may not always terminate individual TCP connections before disconnecting from the network. However, in some environments, temporary network outages may be incorrectly identified as dead sessions, resulting in unexpectedly terminated TCP connections. In such environments, setting the sysctl to 0 may reduce the occurrence of TCP session disconnections. .Pp The .Va net.inet.tcp.delayed_ack TCP feature is largly misunderstood. Historically speaking this feature was designed to allow the acknowledgement to transmitted data to be returned along with the response. For example, when you type over a remote shell the acknowledgement to the character you send can be returned along with the data representing the echo of the character. With delayed acks turned off the acknowledgement may be sent in its own packet before the remote service has a chance to echo the data it just received. This same concept also applies to any interactive protocol (e.g. SMTP, WWW, POP3) and can cut the number of tiny packets flowing across the network in half. The FreeBSD delayed-ack implementation also follows the TCP protocol rule that at least every other packet be acknowledged even if the standard 100ms timeout has not yet passed. Normally the worst a delayed ack can do is slightly delay the teardown of a connection, or slightly delay the ramp-up of a slow-start TCP connection. While we aren't sure we believe that the several FAQs related to packages such as SAMBA and SQUID which advise turning off delayed acks may be refering to the slow-start issue. In FreeBSD it would be more beneficial to increase the slow-start flightsize via the .Va net.inet.tcp.slowstart_flightsize sysctl rather then disable delayed acks. .Pp The .Va net.inet.tcp.inflight_enable sysctl turns on bandwidth delay product limiting for all TCP connections. The system will attempt to calculate the bandwidth delay product for each connection and limit the amount of data queued to the network to just the amount required to maintain optimum throughput. This feature is useful if you are serving data over modems, GigE, or high speed WAN links (or any other link with a high bandwidth*delay product), especially if you are also using window scaling or have configured a large send window. If you enable this option you should also be sure to set .Va net.inet.tcp.inflight_debug to 0 (disable debugging), and for production use setting .Va net.inet.tcp.inflight_min to at least 6144 may be beneficial. Note, however, that setting high minimums may effectively disable bandwidth limiting depending on the link. The limiting feature reduces the amount of data built up in intermediate router and switch packet queues as well as reduces the amount of data built up in the local host's interface queue. With fewer packets queued up, interactive connections, especially over slow modems, will also be able to operate with lower round trip times. However, note that this feature only effects data transmission (uploading / server-side). It does not effect data reception (downloading). .Pp Adjusting .Va net.inet.tcp.inflight_stab is not recommended. -This parameter defaults to 20, representing 2 maximal packets added +This parameter defaults to 20, representing 2 maximal packets added to the bandwidth delay product window calculation. The additional window is required to stabilize the algorithm and improve responsiveness to changing conditions, but it can also result in higher ping times -over slow links (though still much lower then you would get without +over slow links (though still much lower then you would get without the inflight algorithm). In such cases you may wish to try reducing this parameter to 15, 10, or 5, and you may also have to reduce .Va net.inet.tcp.inflight_min (for example, to 3500) to get the desired effect. Reducing these parameters should be done as a last resort only. .Pp The .Va net.inet.ip.portrange.* sysctls control the port number ranges automatically bound to TCP and UDP sockets. There are three ranges: A low range, a default range, and a -high range, selectable via an IP_PORTRANGE setsockopt() call. Most +high range, selectable via an IP_PORTRANGE setsockopt() call. Most network programs use the default range which is controlled by .Va net.inet.ip.portrange.first and .Va net.inet.ip.portrange.last , which defaults to 1024 and 5000 respectively. Bound port ranges are used for outgoing connections and it is possible to run the system out of ports under certain circumstances. This most commonly occurs when you are running a heavily loaded web proxy. The port range is not an issue when running serves which handle mainly incoming connections such as a normal web server, or has a limited number of outgoing connections such as a mail relay. For situations where you may run yourself out of ports we recommend increasing .Va net.inet.ip.portrange.last modestly. A value of 10000 or 20000 or 30000 may be reasonable. You should also consider firewall effects when changing the port range. Some firewalls may block large ranges of ports (usually low-numbered ports) and expect systems to use higher ranges of ports for outgoing connections. For this reason we do not recommend that .Va net.inet.ip.portrange.first be lowered. .Pp The .Va kern.ipc.somaxconn sysctl limits the size of the listen queue for accepting new TCP connections. The default value of 128 is typically too low for robust handling of new connections in a heavily loaded web server environment. For such environments, we recommend increasing this value to 1024 or higher. The service daemon may itself limit the listen queue size (e.g.\& .Xr sendmail 8 , apache) but will often have a directive in its configuration file to adjust the queue size up. Larger listen queues also do a better job of fending off denial of service attacks. .Pp The .Va kern.maxfiles sysctl determines how many open files the system supports. The default is typically a few thousand but you may need to bump this up to ten or twenty thousand if you are running databases or large descriptor-heavy daemons. The read-only .Va kern.openfiles sysctl may be interrogated to determine the current number of open files on the system. .Pp The .Va vm.swap_idle_enabled sysctl is useful in large multi-user systems where you have lots of users entering and leaving the system and lots of idle processes. Such systems tend to generate a great deal of continuous pressure on free memory reserves. Turning this feature on and adjusting the swapout hysteresis (in idle seconds) via .Va vm.swap_idle_threshold1 and .Va vm.swap_idle_threshold2 allows you to depress the priority of pages associated with idle processes more quickly then the normal pageout algorithm. This gives a helping hand to the pageout daemon. Do not turn this option on unless you need it, because the tradeoff you are making is to essentially pre-page memory sooner rather then later, eating more swap and disk bandwidth. In a small system this option will have a detrimental effect but in a large system that is already doing moderate paging this option allows the VM system to stage whole processes into and out of memory more easily. .Sh LOADER TUNABLES Some aspects of the system behavior may not be tunable at runtime because memory allocations they perform must occur early in the boot process. To change loader tunables, you must set their values in .Xr loader.conf 5 and reboot the system. .Pp .Va kern.maxusers controls the scaling of a number of static system tables, including defaults for the maximum number of open files, sizing of network memory resources, etc. As of .Fx 4.5 , .Va kern.maxusers is automatically sized at boot based on the amount of memory available in the system, and may be determined at run-time by inspecting the value of the read-only .Va kern.maxusers sysctl. Some sites will require larger or smaller values of .Va kern.maxusers and may set it as a loader tunable; values of 64, 128, and 256 are not uncommon. We do not recommend going above 256 unless you need a huge number of file descriptors; many of the tunable values set to their defaults by .Va kern.maxusers may be individually overridden at boot-time or run-time as described elsewhere in this document. Systems older than .Fx 4.4 must set this value via the kernel .Xr config 8 option .Cd maxusers instead. .Pp .Va kern.ipc.nmbclusters may be adjusted to increase the number of network mbufs the system is willing to allocate. Each cluster represents approximately 2K of memory, so a value of 1024 represents 2M of kernel memory reserved for network buffers. You can do a simple calculation to figure out how many you need. If you have a web server which maxes out at 1000 simultaneous connections, and each connection eats a 16K receive and 16K send buffer, you need approximately 32MB worth of network buffers to deal with it. A good rule of thumb is to multiply by 2, so 32MBx2 = 64MB/2K = 32768. So for this case you would want to set .Va kern.ipc.nmbclusters to 32768. We recommend values between 1024 and 4096 for machines with moderates amount of memory, and between 4096 and 32768 for machines with greater amounts of memory. Under no circumstances should you specify an arbitrarily high value for this parameter, it could lead to a boot-time crash. The .Fl m option to .Xr netstat 1 may be used to observe network cluster use. Older versions of .Fx do not have this tunable and require that the kernel .Xr config 8 option .Dv NMBCLUSTERS be set instead. .Pp More and more programs are using the .Xr sendfile 2 system call to transmit files over the network. The .Va kern.ipc.nsfbufs sysctl controls the number of filesystem buffers .Xr sendfile 2 is allowed to use to perform its work. This parameter nominally scales with .Va kern.maxusers so you should not need to modify this parameter except under extreme circumstances. .Sh KERNEL CONFIG TUNING There are a number of kernel options that you may have to fiddle with in a large-scale system. In order to change these options you need to be able to compile a new kernel from source. The .Xr config 8 manual page and the handbook are good starting points for learning how to do this. Generally the first thing you do when creating your own custom kernel is to strip out all the drivers and services you do not use. Removing things like .Dv INET6 and drivers you do not have will reduce the size of your kernel, sometimes by a megabyte or more, leaving more memory available for applications. .Pp .Dv SCSI_DELAY and .Dv IDE_DELAY may be used to reduce system boot times. The defaults are fairly high and can be responsible for 15+ seconds of delay in the boot process. Reducing .Dv SCSI_DELAY to 5 seconds usually works (especially with modern drives). Reducing .Dv IDE_DELAY also works but you have to be a little more careful. .Pp There are a number of .Dv *_CPU options that can be commented out. If you only want the kernel to run on a Pentium class CPU, you can easily remove .Dv I386_CPU and .Dv I486_CPU , but only remove .Dv I586_CPU if you are sure your CPU is being recognized as a Pentium II or better. Some clones may be recognized as a Pentium or even a 486 and not be able to boot without those options. If it works, great! The operating system will be able to better-use higher-end CPU features for MMU, task switching, timebase, and even device operations. Additionally, higher-end CPUs support 4MB MMU pages, which the kernel uses to map the kernel itself into memory, increasing its efficiency under heavy syscall loads. .Sh IDE WRITE CACHING .Fx 4.3 flirted with turning off IDE write caching. This reduced write bandwidth to IDE disks but was considered necessary due to serious data consistency issues introduced by hard drive vendors. Basically the problem is that IDE drives lie about when a write completes. With IDE write caching turned on, IDE hard drives will not only write data to disk out of order, they will sometimes delay some of the blocks indefinitely under heavy disk load. A crash or power failure can result in serious filesystem corruption. So our default was changed to be safe. Unfortunately, the result was such a huge loss in performance that we caved in and changed the default back to on after the release. You should check the default on your system by observing the .Va hw.ata.wc sysctl variable. If IDE write caching is turned off, you can turn it back on by setting the .Va hw.ata.wc loader tunable to 1. More information on tuning the ATA driver system may be found in the .Xr ata 4 man page. .Pp There is a new experimental feature for IDE hard drives called .Va hw.ata.tags (you also set this in the boot loader) which allows write caching to be safely turned on. This brings SCSI tagging features to IDE drives. As of this writing only IBM DPTA and DTLA drives support the feature. Warning! These drives apparently have quality control problems and I do not recommend purchasing them at this time. If you need performance, go with SCSI. .Sh CPU, MEMORY, DISK, NETWORK The type of tuning you do depends heavily on where your system begins to bottleneck as load increases. If your system runs out of CPU (idle times are perpetually 0%) then you need to consider upgrading the CPU or moving to an SMP motherboard (multiple CPU's), or perhaps you need to revisit the programs that are causing the load and try to optimize them. If your system is paging to swap a lot you need to consider adding more memory. If your system is saturating the disk you typically see high CPU idle times and total disk saturation. .Xr systat 1 can be used to monitor this. There are many solutions to saturated disks: increasing memory for caching, mirroring disks, distributing operations across several machines, and so forth. If disk performance is an issue and you are using IDE drives, switching to SCSI can help a great deal. While modern IDE drives compare with SCSI in raw sequential bandwidth, the moment you start seeking around the disk SCSI drives usually win. .Pp Finally, you might run out of network suds. The first line of defense for improving network performance is to make sure you are using switches instead of hubs, especially these days where switches are almost as cheap. Hubs have severe problems under heavy loads due to collision backoff and one bad host can severely degrade the entire LAN. Second, optimize the network path as much as possible. For example, in .Xr firewall 7 we describe a firewall protecting internal hosts with a topology where the externally visible hosts are not routed through it. Use 100BaseT rather than 10BaseT, or use 1000BaseT rather then 100BaseT, depending on your needs. Most bottlenecks occur at the WAN link (e.g.\& modem, T1, DSL, whatever). If expanding the link is not an option it may be possible to use the .Xr dummynet 4 feature to implement peak shaving or other forms of traffic shaping to prevent the overloaded service (such as web services) from affecting other services (such as email), or vice versa. In home installations this could be used to give interactive traffic (your browser, .Xr ssh 1 logins) priority over services you export from your box (web services, email). .Sh SEE ALSO .Xr netstat 1 , .Xr systat 1 , .Xr ata 4 , .Xr dummynet 4 , .Xr login.conf 5 , .Xr rc.conf 5 , .Xr sysctl.conf 5 , .Xr firewall 7 , .Xr hier 7 , .Xr ports 7 , .Xr boot 8 , .Xr ccdconfig 8 , .Xr config 8 , .Xr disklabel 8 , .Xr fsck 8 , .Xr ifconfig 8 , .Xr ipfw 8 , .Xr loader 8 , .Xr mount 8 , .Xr newfs 8 , .Xr route 8 , .Xr sysctl 8 , .Xr sysinstall 8 , .Xr tunefs 8 , .Xr vinum 8 .Sh HISTORY The .Nm manual page was originally written by .An Matthew Dillon and first appeared in .Fx 4.3 , May 2001. Index: stable/4/share/man/man8/diskless.8 =================================================================== --- stable/4/share/man/man8/diskless.8 (revision 139702) +++ stable/4/share/man/man8/diskless.8 (revision 139703) @@ -1,329 +1,329 @@ .\" Copyright (c) 1994 Gordon W. Ross, Theo de Raadt .\" Updated by Luigi Rizzo .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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$ .\" .Dd April 18, 2001 .Dt DISKLESS 8 .Os .Sh NAME .Nm diskless .Nd booting a system over the network .Sh DESCRIPTION The ability to boot a machine over the network is useful for .Em diskless or .Em dataless machines, or as a temporary measure while repairing or re-installing filesystems on a local disk. This file provides a general description of the interactions between a client and its server when a client is booting over the network. .Sh OPERATION When booting a system over the network, there are three phases of interaction between client and server: .Pp .Bl -enum -compact .It The stage-1 bootstrap loads a boot program, from .It The boot program loads a kernel. .It The kernel does NFS mounts for root. .El .Pp Each of these phases are described in further detail below. .Pp In phase 1, the stage-1 bootstrap code loads a boot program, which is typically able to control the network card. The boot program can be stored in the BIOS, in a BOOT ROM located on the network card (PXE, etherboot, netboot), or come from a disk unit (e.g. etherboot or netboot). .Pp In phase 2, the boot program loads a kernel. Operation in this phase depends on the design of the boot program. Typically, the boot program uses the .Tn BOOTP or .Tn DHCP protocol to get the client's IP address and other boot information, including but not limited to the IP addresses of the NFS server, router and nameserver, and the name of the kernel to load. Then the kernel is loaded, either directly using NFS (as it is the case for etherboot and netboot), or through an intermediate loader called pxeboot and loaded using TFTP or NFS. .Pp In phase 3, the kernel again uses DHCP or BOOTP to acquire configuration information, and proceeds to mount the root filesystem and start operation. The boot -scripts recognize a diskless startup and peform +scripts recognize a diskless startup and peform the actions found in .Pa /etc/rc.d/initdiskless and .Pa /etc/rc.d/diskless . In older systems the scripts are located in .Pa /etc/rc.diskless1 and .Pa /etc/rc.diskless2 . .Sh CONFIGURATION In order to run a diskless client, you need the following: .Bl -bullet .It An NFS server which exports a root and /usr partition with appropriate permissions. The diskless scripts work with readonly partitions, as long as root is exported with .Fl maproot Ns =0 so that some system files can be accessed. As an example, .Pa /etc/exports can contain the following lines: .Bd -literal -offset indent -ro -maproot=0 -alldirs /usr -ro -alldirs .Ed .Pp where .Aq ROOT is the mountpoint on the server of the root partition. The script .Pa /usr/share/examples/diskless/clone_root can be used to create a shared readonly root partition, but in many cases you may decide to export (again as readonly) the root directory used by the server itself. .It a .Tn BOOTP or .Tn DHCP server. .Xr bootpd 8 can be enabled by uncommenting the .Em bootps line in .Pa /etc/inetd.conf . A sample .Pa /etc/bootptab can be the following: .Bd -literal -offset indent .default:\\ hn:ht=1:vm=rfc1048:\\ :sm=255.255.255.0:\\ :sa=:\\ :gw=:\\ :rp=":": :ha=0123456789ab:tc=.default .Ed .Pp where .Aq SERVER , .Aq GATEWAY and .Aq ROOT have the obvious meanings. .It A properly initialized root partition. The script .Pa /usr/share/examples/diskless/clone_root can help in creating it, using the server's root partition -as a reference. If you are just starting out you should +as a reference. If you are just starting out you should simply use the server's own root directory, .Pa / , and not try to clone it. .Pp You often do not want to use the same .Pa rc.conf or .Pa rc.local files for the diskless boot as you do on the server. The diskless boot scripts provide a mechanism through which you can override various files in .Pa /etc (as well as other subdirectories of root). The scripts provide four overriding directories situated in .Pa /conf/base , .Pa /conf/default , .Pa /conf/(broadcast-ip) , and .Pa /conf/(machine-ip) . You should always create .Pa /conf/base/etc , which will entirely replace the server's .Pa /etc on the diskless machine. You can clone the server's .Pa /etc here or you can create a special file which tells the diskless boot scripts to remount the server's .Pa /etc onto .Pa /conf/base/etc . You do this by creating the file .Pa /conf/base/etc/diskless_remount containing the mount point to use as a basis of the diskless machine's .Pa /etc . For example, the file might contain: .Bd -literal -offset 4n 10.0.0.1:/etc .Ed .Pp Alternativly, if the server contains several independent roots, the file might contain: .Pp .Dl 10.0.0.1:/usr/diskless/4.7-RELEASE/etc .Pp This would work, but if you copied .Pa /usr/diskless/4.7-RELEASE to .Pa /usr/diskless/4.8-RELEASE and upgraded the installation, you would need to modify the .Pa diskless_remount files to reflect that move. To avoid that, paths in .Pa diskless_remount files begining with .Pa / have the actual path of the client's root prepended to them so the file could instead contain: .Pp .Dl /etc .Pp The diskless scripts create memory filesystems to hold the overriden directories. Only a 2MB partition is created by default, which may not be sufficient for your purposes. To override this you can create the file .Pa /conf/base/etc/md_size containing the size, in 512 byte sectors, of the memory disk to create for that directory. .Pp You then typically provide file-by-file overrides in the .Pa /conf/default/etc directory. At a minimum you must provides overrides for .Pa /etc/fstab , .Pa /etc/rc.conf , and .Pa /etc/rc.local via .Pa /conf/default/etc/fstab , .Pa /conf/default/etc/rc.conf , and .Pa /conf/default/etc/rc.local . .Pp Overrides are hierarchical. You can supply network-specific defaults in the .Pa /conf//etc directory, where represents the broadcast IP address of the diskless system as given to it via .Tn BOOTP . The .Pa diskless_remount and .Pa md_size features work in any of these directories. The configuration feature works on directories other then .Pa /etc , you simply create the directory you wish to replace or override in .Pa /conf/{base,default,,}/* and work it in the same way that you work .Pa /etc . .Pp As a minimum, you normally need to have the following in .Pa /conf/default/etc/fstab .Bd -literal -offset indent : / nfs ro 0 0 :/usr /usr nfs ro 0 0 proc /proc procfs rw 0 0 .Ed .Pp You also need to create a customized version of .Pa /conf/default/etc/rc.conf which should contain the startup options for the diskless client, and .Pa /conf/default/etc/rc.local which could be empty but prevents the server's own .Pa /etc/rc.local from leaking onto the diskless system. .Pp In .Pa rc.conf , most likely you will not need to set .Va hostname and .Va ifconfig_* because these will be already set by the startup code. Finally, it might be convenient to use a .Ic case statement using .Li `hostname` as the switch variable to do machine-specific configuration in case a number of diskless clients share the same configuration files. .It The kernel for the diskless clients, which will be loaded using NFS or TFTP, should be built with at least the following options: .Bd -literal -offset indent options MFS options BOOTP options BOOTP_NFSROOT options BOOTP_COMPAT .Ed .Pp If you use the firewall, remember to default to open or your kernel will not be able to send/receive the bootp packets. .El .Sh SECURITY ISSUES Be warned that using unencrypted NFS to mount root and user partitions may expose information such as encryption keys. .Sh BUGS This manpage is probably incomplete. .Pp .Fx sometimes requires to write onto the root partition, so the startup scripts mount MFS filesystems on some locations (e.g.\& .Pa /etc and .Pa /var ) , while trying to preserve the original content. The process might not handle all cases. .Sh SEE ALSO .Xr ethers 5 , .Xr exports 5 , .Xr bootpd 8 , .Xr mountd 8 , .Xr nfsd 8 , .Xr pxeboot 8 , .Xr reboot 8 , .Xr tftpd 8 , .Xr ports/net/etherboot Index: stable/4/share/man/man9/cd.9 =================================================================== --- stable/4/share/man/man9/cd.9 (revision 139702) +++ stable/4/share/man/man9/cd.9 (revision 139703) @@ -1,115 +1,115 @@ .\" Copyright (c) 1997 .\" John-Mark Gurney. 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. Neither the name of the author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY John-Mark Gurney 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 AUTHOR 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$ .\" .Dd September 2, 2003 .Dt CD 9 .Os .Sh NAME .Nm cd .Nd CDROM driver for the CAM SCSI subsystem .Sh DESCRIPTION The .Nm device driver provides a read only interface for CDROM drives .Tn ( SCSI type 5) and WORM drives .Tn ( SCSI type 4) that support CDROM type commands. Some drives don't behave as the driver expects. See the section QUIRKS for info on possible flags. .Sh QUIRKS Each .Tn CD-ROM device can have different interpretations of the .Tn SCSI spec. This can lead to drives requiring special handling in the driver. The following is a list of quirks that the driver recognize. .Bl -tag -width CD_Q_BCD_TRACKS .It Dv CD_Q_NO_TOUCH This flag tell the driver not to probe the drive at attach time to see if there is a disk in the drive and find out what size it is. This flag is currently unimplemented in the CAM .Nm driver. .It Dv CD_Q_BCD_TRACKS This flag is for broken drives that return the track numbers in packed BCD instead of straight decimal. If the drive seems to skip tracks (tracks 10-15 are skipped) then you have a drive that is in need of this flag. .It Dv CD_Q_NO_CHANGER This flag tells the driver that the device in question is not a changer. This is only necessary for a CDROM device with multiple luns that are not a part of a changer. .It Dv CD_Q_CHANGER This flag tells the driver that the given device is a multi-lun changer. In general, the driver will figure this out automatically when it sees a LUN greater than 0. Setting this flag only has the effect of telling the driver to run the initial read capacity command for LUN 0 of the changer through the changer scheduling code. .It Dv CD_Q_10_BYTE_ONLY This flag tells the driver that the given device only accepts 10 byte MODE SENSE/MODE SELECT commands. In general these types of quirks should not be added to the .Xr cd 4 driver. The reason is that the driver does several things to attempt to determine whether the drive in question needs 10 byte commands. First, it issues a CAM Path Inquiry command to determine whether the protocol that the drive speaks typically only allows 10 byte commands. (ATAPI and USB are two prominent examples of protocols where you generally only want to send 10 byte commands.) Then, if it gets an ILLEGAL REQUEST error back from a 6 byte MODE SENSE or MODE SELECT command, it attempts to send the 10 byte version of the command instead. The only reason you would need a -quirk is if your drive uses a protocol (e.g. +quirk is if your drive uses a protocol (e.g. .Tn SCSI ) that typically doesn't have a problem with 6 byte commands. .El .Sh FILES .Bl -tag -width /sys/cam/scsi/scsi_cd.c -compact .It Pa /sys/cam/scsi/scsi_cd.c is the driver source file. .El .Sh SEE ALSO .Xr cd 4 , .Xr scsi 4 .Sh HISTORY The .Nm manual page first appeared in .Fx 2.2 . .Sh AUTHORS .An -nosplit This manual page was written by .An John-Mark Gurney Aq gurney_j@efn.org . It was updated for CAM and .Fx 3.0 by .An Kenneth Merry Aq ken@FreeBSD.org . Index: stable/4/share/man/man9/malloc.9 =================================================================== --- stable/4/share/man/man9/malloc.9 (revision 139702) +++ stable/4/share/man/man9/malloc.9 (revision 139703) @@ -1,299 +1,299 @@ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" 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 NetBSD .\" Foundation, Inc. and its contributors. .\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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. .\" .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ .\" $FreeBSD$ .\" .Dd June 16, 1996 .Dt MALLOC 9 .Os .Sh NAME .Nm malloc , .Nm MALLOC , .Nm free , .Nm FREE .Nd kernel memory management routines .Sh SYNOPSIS .In sys/types.h .In sys/malloc.h .Ft void * .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" .Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags" .Ft void .Fn free "void *addr" "struct malloc_type *type" .Fn FREE "void *addr" "struct malloc_type *type" .Ft void * .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" .Ft void * .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" .Sh DESCRIPTION The .Fn malloc function allocates uninitialized memory in kernel address space for an object whose size is specified by .Fa size . .Pp .Fn free releases memory at address .Fa addr that was previously allocated by .Fn malloc for re-use. The memory is not zeroed. If .Fa addr is .Dv NULL , then .Fn free does nothing. .Pp The .Fn realloc function changes the size of the previously allocated memory referenced by .Fa addr to .Fa size bytes. The contents of the memory are unchanged up to the lesser of the new and old sizes. Note that the returned value may differ from .Fa addr . If the requested memory cannot be allocated, .Dv NULL is returned and the memory referenced by .Fa addr is valid and unchanged. If .Fa addr is .Dv NULL , the .Fn realloc function behaves identically to .Fn malloc for the specified size. .Pp The .Fn reallocf function call is identical to the realloc function call, except that it will free the passed pointer when the requested memory cannot be allocated. .Pp The .Fn MALLOC macro variant is functionally equivalent to .Bd -literal -offset indent (space) = (cast)malloc((u_long)(size), type, flags) .Ed .Pp and the .Fn FREE macro variant is equivalent to .Bd -literal -offset indent free((addr), type) .Ed .Pp Unlike its standard C library counterpart .Pq Xr malloc 3 , the kernel version takes two more arguments. The .Fa flags argument further qualifies .Fn malloc Ns 's operational characteristics as follows: .Bl -tag -width indent .It Dv M_NOWAIT Causes .Fn malloc , .Fn realloc , or .Fn reallocf to return .Dv NULL if the request cannot be immediately fulfilled due to resource shortage. Otherwise, the current process may be put to sleep to wait for resources to be released by other processes. If this flag is set, .Fn malloc will return .Dv NULL rather then block. Note that .Dv M_WAITOK is defined to be 0, meaning that blocking operation is the default. -Also note that +Also note that .Dv M_NOWAIT is required when running in an interrupt context. .It Dv M_ASLEEP Causes .Fn malloc , .Fn realloc , or .Fn reallocf to call .Fn asleep if the request cannot be immediately fulfilled due to a resource shortage. M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow the function to call .Fn asleep and return .Dv NULL immediately. It is expected that the caller will at some point call .Fn await and then retry the allocation. Depending on the routine in question, the caller may decide to propagate the temporary failure up the call chain and actually have some other higher level routine block on the async wait that the function queued. .It Dv M_WAITOK Indicates that it is Ok to wait for resources. It is unconveniently defined as 0 so care should be taken never to compare against this value directly or try to AND it as a flag. The default operation is to block until the memory allocation succeeds. .Fn malloc , .Fn realloc , and .Fn reallocf can only return .Dv NULL if .Dv M_NOWAIT is specified. .It Dv M_USE_RESERVE Indicates that the system can dig into its reserve in order to obtain the requested memory. This option used to be called M_KERNEL but has been renamed to something more obvious. This option has been deprecated and is slowly being removed from the kernel, and so should not be used with any new programming. .El .Pp The .Fa type argument is used to perform statistics on memory usage, and for basic sanity checks. The statistics can be examined by .Sq vmstat -m . .Pp A .Fa type is defined using the .Va malloc_type_t typedef via the .Fn MALLOC_DECLARE and .Fn MALLOC_DEFINE macros. .Bd -literal -offset indent /* sys/something/foo_extern.h */ MALLOC_DECLARE(M_FOOBUF); /* sys/something/foo_main.c */ MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); /* sys/something/foo_subr.c */ \&... MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); .Ed .Sh RETURN VALUES .Fn malloc , .Fn realloc , and -.Fn reallocf +.Fn reallocf return a kernel virtual address that is suitably aligned for storage of any type of object, or .Dv NULL if the request could not be satisfied (implying that .Dv M_NOWAIT was set). If .Dv M_ASLEEP was set and the function returns .Dv NULL , it will call .Fn asleep as a side effect. .Sh IMPLEMENTATION NOTES The memory allocator allocates memory in chunks that have size a power of two for requests up to the size of a page of memory. For larger requests, one or more pages is allocated. While it should not be relied upon, this information may be useful for optimizing the efficiency of memory use. .Sh SEE ALSO .Xr vmstat 8 .Sh DIAGNOSTICS A kernel compiled with the .Dv DIAGNOSTIC configuration option attempts to detect memory corruption caused by such things as writing outside the allocated area and imbalanced calls to the .Fn malloc and .Fn free functions. Failing consistency checks will cause a panic or a system console message: .Bl -bullet -offset indent -compact .Pp .It panic: .Dq malloc: bogus type .It panic: .Dq malloc: allocation too large .It panic: .Dq malloc: wrong bucket .It panic: .Dq malloc: lost data .It panic: .Dq free: address 0x%x out of range .It panic: .Dq free: type %d out of range .It panic: .Dq free: unaligned addr Aq description of object .It panic: .Dq free: item modified .It panic: .Dq free: multiple free[s] .It .Dq Data modified on freelist: Aq description of object .El