Annotation of wikisrc/guide/index.mdwn, revision 1.2

1.1       jdf         1: 
                      2: # The NetBSD Guide
                      3: 
                      4: ## Purpose of this guide
                      5: 
                      6: This guide describes the installation and the configuration of the NetBSD
                      7: operating system as well as the setup and administration of some of its
                      8: subsystems. It primarily addresses people coming from other Unix-like operating
                      9: systems, and aims to be a useful guide in the face of the many small problems
                     10: one encounters when using a new tool.
                     11: 
                     12: This guide is not a Unix tutorial: basic knowledge of some concepts and tools
                     13: is assumed. You should know, for example, what a file and a directory are, and
                     14: how to use an editor. There are plenty of books explaining basic Unix and
                     15: operating system concepts, and you should consult one if you need more
                     16: background information. It is better to choose a general book and avoid titles
                     17: like "Learning Unix-XYZ, version 1.2.3.4 in 10 days", but this is a matter of
                     18: personal taste.
                     19: 
                     20: Originally, the guide has been a book, which was subsequently moved to the wiki
                     21: to make it easier to contribute.
                     22: 
                     23: If you have additions or comments to the guide, but don't want to create an
                     24: account, feel free to post your submissions to the
                     25: [www team](mailto:www@netbsd.org) or the
                     26: [docs mailing list](netbsd-docs@netbsd.org). The text is maintained in
                     27: Markdown, and you can use the button in the top right corner to show the source
                     28: of an article.
                     29: 
                     30: ## Table of Contents
                     31: 
                     32: 
                     33: ***I. About NetBSD***
                     34: 
                     35: 
                     36: ***II. System installation and related issues***
                     37: 
                     38: 
                     39: ***III. System configuration, administration and tuning***
                     40: 
1.2     ! jdf        41:  * [[4. Upgrading NetBSD|guide/upgrading]]
        !            42:    * [[4.1. Using sysinst]]
        !            43:    * [[4.2. Using sysupgrade]]
        !            44:  * [[5. The first steps on NetBSD|guide/boot]]
        !            45:    * [[5.1. Troubleshooting]]
        !            46:    * [[5.2. The man command]]
        !            47:    * [[5.3. Editing configuration files]]
        !            48:    * [[5.4. Login]]
        !            49:    * [[5.5. Changing the `root` password]]
        !            50:    * [[5.6. Adding users]]
        !            51:    * [[5.7. Shadow passwords]]
        !            52:    * [[5.8. Changing the keyboard layout]]
        !            53:    * [[5.9. System time]]
        !            54:    * [[5.10. Secure Shell ([ssh(1)](http://netbsd.gw.com/cgi-bin/man-cgi?ssh+1+NetBSD-5.0.1+i386))]]
        !            55:    * [[5.11. Basic configuration in `/etc/rc.conf`]]
        !            56:    * [[5.12. Basic network settings]]
        !            57:    * [[5.13. Mounting a CD-ROM]]
        !            58:    * [[5.14. Mounting a floppy]]
        !            59:    * [[5.15. Installing additional software]]
        !            60:    * [[5.16. Security alerts]]
        !            61:    * [[5.17. Stopping and rebooting the system]]
        !            62:  * [[7. The rc.d System|guide/rc]]
        !            63:    * [[7.1. Basics]]
        !            64:    * [[7.2. The rc.d scripts]]
        !            65:    * [[7.3. Order/dependencies of start determined by rcorder]]
        !            66:    * [[7.4. rc.d scripts of additional services]]
        !            67:    * [[7.5. Additional Reading]]
        !            68:  * [[9. X|guide/x]]
        !            69:    * [[9.1. What is X?]]
        !            70:    * [[9.2. Configuration]]
        !            71:    * [[9.3. The mouse]]
        !            72:    * [[9.4. The keyboard]]
        !            73:    * [[9.5. The monitor]]
        !            74:    * [[9.6. The video card]]
        !            75:    * [[9.7. Starting X]]
        !            76:    * [[9.8. Customizing X]]
        !            77:    * [[9.9. Other window managers or desktop environments]]
        !            78:    * [[9.10. Graphical login with xdm]]
        !            79:  * [[11. Audio|guide/audio]]
        !            80:    * [[11.1. Basic hardware elements]]
        !            81:    * [[11.2. Supported audio cards]]
        !            82:    * [[11.3. BIOS settings]]
        !            83:    * [[11.4. Configuring the audio device]]
        !            84:    * [[11.5. Multiple audio devices]]
        !            85:    * [[11.6. Configuring the kernel audio devices]]
        !            86:    * [[11.7. Advanced commands]]
        !            87:  * [[20. NetBSD Veriexec subsystem|guide/veriexec]]
        !            88:    * [[20.1. How it works]]
        !            89:    * [[20.2. Signatures file]]
        !            90:    * [[20.3. Strict levels]]
        !            91:    * [[20.4. Veriexec and layered file systems]]
        !            92:    * [[20.5. Kernel configuration]]
1.1       jdf        93: 
                     94: ***IV. Networking and related issues***
                     95: 
                     96: 
                     97: ***V. Building the system***
                     98: 
1.2     ! jdf        99:  * [[32. Compiling the kernel|guide/kernel]]
        !           100:    * [[32.1. Requirements and procedure]]
        !           101:    * [[32.2. Installing the kernel sources]]
        !           102:    * [[32.3. Creating the kernel configuration file]]
        !           103:    * [[32.4. Building the kernel manually]]
        !           104:    * [[32.5. Building the kernel using `build.sh`]]
        !           105:    * [[32.6. Installing the new kernel]]
        !           106:    * [[32.7. If something went wrong]]
        !           107:  * [[33. Updating an existing system from sources|guide/updating]]
        !           108:    * [[33.1. Manual build and update procedure]]
        !           109:    * [[33.2. Using sysinst]]
        !           110:    * [[33.3. Using sysbuild and sysupgrade]]
        !           111:    * [[33.4. More details about the updating of configuration and startup files]]
1.1       jdf       112: 
                    113: ## Guide history
                    114: 
                    115: This guide was born as a collection of sparse notes that Federico Lupi, the
                    116: original author of the NetBSD Guide, wrote mostly for himself. When he realized
                    117: that they could be useful to other NetBSD users he started collecting them and
                    118: created the first version of the guide using the groff formatter. In order to
                    119: "easily" get a wider variety of output formats (e.g. HTML and
                    120: PostScript/PDF), he made the "mistake" of moving to SGML/DocBook, which
                    121: is the current format of the sources. Maintainership was picked up by the NetBSD
                    122: project and its developers later, and the format was changed to XML/DocBook
                    123: later due to better tools and slightly more knowhow on customisations.
                    124: 
                    125: In 2012/2013, the guide was converted by XXX (Wang - wmzhere) to Markdown and
                    126: integrated into the NetBSD wiki. Along with the conversion, old chapters were
                    127: removed, the numbering scheme was restricted to the table of contents and soem
                    128: reformulations were done.
                    129: 
                    130: You can still get the old version of the Guide at XXX
                    131: 
                    132: ## Bibliography
                    133: 
                    134: * [AeleenFrisch] Aeleen Frisch. Copyright © 1991. O'Reilly & Associates. *Essential System Administration*.
                    135: * [CraigHunt] Craig Hunt. Copyright © 1993. O'Reilly & Associates. *TCP/IP Network Administration*.
                    136: * [RFC1034] P. V. Mockapetris. Copyright © 1987. *RFC 1034: Domain names - concepts and facilities*.
                    137: * [RFC1035] P. V. Mockapetris. Copyright © 1987. *RFC 1035: Domain names - implementation and specification*.
                    138: * [RFC1055] J. L. Romkey. Copyright © 1988. *RFC 1055: Nonstandard for transmission of IP datagrams over serial lines: SLIP*.
                    139: * [RFC1331] W. Simpson. Copyright © 1992. *RFC 1331: The Point-to-Point Protocol (PPP) for the Transmission of Multi-protocol Datagrams over Point-to-Point Links*.
                    140: * [RFC1332] G. McGregor. Copyright © 1992. *RFC 1332: The PPP Internet Protocol Control Protocol (IPCP)*.
                    141: * [RFC1933] R. Gilligan and E. Nordmark. Copyright © 1996. *RFC 1933: Transition Mechanisms for IPv6 Hosts and Routers*.
                    142: * [RFC2004] C. Perkins. Copyright © 1996. *RFC 2003: IP Encapsulation within IP*.
                    143: * [RFC2401] S. Kent and R. Atkinson. Copyright © 1998. *RFC 2401: Security Architecture for the Internet Protocol*.
                    144: * [RFC2411] R. Thayer, N. Doraswamy, and R. Glenn. Copyright © 1998. *RFC 2411: IP Security Document Roadmap*.
                    145: * [RFC2461] T. Narten, E. Nordmark, and W. Simpson. Copyright © 1998. *RFC 2461: Neighbor Discovery for IP Version 6 (IPv6)*.
                    146: * [RFC2529] B. Carpenter and C. Jung. Copyright © 1999. *RFC 2529: Transmission of IPv6 over IPv4 Domains without Explicit Tunnels*.
                    147: * [RFC3024] G. Montenegro. Copyright © 2001. *RFC 3024: Reverse Tunneling for Mobile IP*.
                    148: * [RFC3027] M. Holdrege and P. Srisuresh. Copyright © 2001. *RFC 3027: Protocol Complications with the IP Network Address Translator*.
                    149: * [RFC3056] B. Carpenter and K. Moore. Copyright © 2001. *RFC 3056: Connection of IPv6 Domains via IPv4 Clouds*.
                    150: 
                    151: ## Acknowledgements
                    152: 
                    153: The NetBSD Guide was originally written by Federico Lupi who managed the
                    154: sources, coordinated updates, and merged all contributions on his own. Since
                    155: then, it has been updated and maintained by the NetBSD www team. The Guide has
                    156: progressed thanks to the contributions of many people who have volunteered their
                    157: time and effort, supplied material and sent in suggestions and corrections.
                    158: 
                    159: ### Original acknowledgements
                    160: 
                    161: Federico's original credits are:
                    162: 
                    163: * Paulo Aukar
                    164: * Grant Beattie, converted to XML DocBook.
                    165: * Manolo De Santis, Audio Chapter
                    166: * Eric Delcamp, Boot Floppies
                    167: * Hubert Feyrer, who contributed
                    168: [[Introduction to TCP/IP Networking|guide/net-intro]] including Next
                    169: generation Internet protocol - IPv6 and the section
                    170: [[IPv6 Connectivity & Transition via 6to4|guide/net-practice#ipv6-6to4]]
                    171: He also helped with the SGML to XML transition.
                    172: * Jason R. Fink
                    173: * Daniel de Kok, audio and linux chapters fixes.
                    174: * Reinoud Koornstra, CVS chapter and rebuilding `/dev` in the Misc chapter.
                    175: * Brian A. Seklecki [lavalamp@burghcom.com](mailto:lavalamp@burghcom.com), who
                    176: contributed the CCD Chapter.
                    177: * Guillain Seuillot
                    178: * Martti Kuparinen, RAIDframe documentation.
                    179: * David Magda
                    180: 
                    181: ### Current acknowledgements
                    182: 
                    183: This document is currently maintained by the NetBSD www team. Thanks to their
                    184: efforts, the document is kept up to date and available online at all times. In
                    185: addition, special thanks go to (in alphabetical order):
                    186: 
                    187: * Hubert Feyrer, for getting the guide up to speed for NetBSD 2.0, and for
                    188: making numerous improvements to all chapters.
                    189: * Jason R. Fink, for maintaining this document and integrating changes.
                    190: * Andreas Hallman, for his information in
                    191: [[Tunneling 6to4 through an IPFilter firewall|guide/net-practice#chap-net-practice-ipv6-6to4-ipf]]
                    192: * Joel Knight for the
                    193: [[Introduction to the Common Address Redundancy Protocol (CARP)|guide/carp]].
                    194: See below for for the accompanying license.
                    195: * Daniel de Kok, for constant contributions of new chapters, maintenance of
                    196: existing chapters and his translation work.
                    197: * Hiroki Sato, for allowing us to build PDF and PS versions of this document.
                    198: * Jan Schaumann, for maintenance work and `www/htdocs` management.
                    199: * Lubomir Sedlacik, for some details on using CGD for swap in
                    200: [[Suggestions and Warnings|guide/cgd#suggestions]]
                    201: * Dag-Erling Smrgrav, for the article on
                    202: [[Pluggable Authentication Modules (PAM)|guide/pam]]. See below for the
                    203: accompanying license.
                    204: * Florian Sthr, for
                    205: [[Example: encrypted CDs/DVDs|guide/cgd#cryptocds]]
                    206: 
                    207: 
                    208: ### Licenses
                    209: 
                    210: #### Federico Lupi's original license of this guide
                    211: 
                    212: Redistribution and use in source and binary forms, with or without modification,
                    213: are permitted provided that the following conditions are met:
                    214: 
                    215: 1. Redistributions of source code must retain the above copyright notice, this
                    216: list of conditions and the following disclaimer.
                    217: 2. Redistributions in binary form must reproduce the above copyright notice,
                    218: this list of conditions and the following disclaimer in the documentation
                    219: and/or other materials provided with the distribution.
                    220: 3. All advertising materials mentioning features or use of this software must
                    221: display the following acknowledgement: This product includes software developed
                    222: by Federico Lupi for the NetBSD Project.
                    223: 4. The name of the author may not be used to endorse or promote products
                    224: derived from this software without specific prior written permission.
                    225: 
                    226: THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
                    227: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
                    228: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
                    229: SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
                    230: EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
                    231: OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                    232: INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                    233: CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
                    234: IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
                    235: OF SUCH DAMAGE.
                    236: 
                    237: #### Networks Associates Technology's license on the PAM article
                    238: 
                    239: Copyright (c) 2001-2003 Networks Associates Technology, Inc.
                    240: All rights reserved.
                    241: This software was developed for the FreeBSD Project by ThinkSec AS and
                    242: Network Associates Laboratories, the Security Research Division of
                    243: Network Associates, Inc.  under DARPA/SPAWAR contract N66001-01-C-8035
                    244: ("CBOSS"), as part of the DARPA CHATS research program.
                    245: Redistribution and use in source and binary forms, with or without
                    246: modification, are permitted provided that the following conditions
                    247: are met:
                    248: 1. Redistributions of source code must retain the above copyright
                    249: notice, this list of conditions and the following disclaimer.
                    250: 2. Redistributions in binary form must reproduce the above copyright
                    251: notice, this list of conditions and the following disclaimer in the
                    252: documentation and/or other materials provided with the distribution.
                    253: 3. The name of the author may not be used to endorse or promote
                    254: products derived from this software without specific prior written
                    255: permission.
                    256: THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
                    257: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                    258: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                    259: ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
                    260: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                    261: DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                    262: OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                    263: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                    264: LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                    265: OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                    266: SUCH DAMAGE.
                    267: 
                    268: #### Joel Knight's license on the CARP article
                    269: 
                    270: Copyright (c) 2005 Joel Knight <enabled@myrealbox.com>
                    271: Permission to use, copy, modify, and distribute this documentation for
                    272: any purpose with or without fee is hereby granted, provided that the
                    273: above copyright notice and this permission notice appear in all copies.
                    274: THE DOCUMENTATION IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
                    275: WARRANTIES WITH REGARD TO THIS DOCUMENTATION INCLUDING ALL IMPLIED
                    276: WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
                    277: AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
                    278: DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
                    279: PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
                    280: TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
                    281: PERFORMANCE OF THIS DOCUMENTATION
                    282: 
                    283: #### The NetBSD Developers
                    284: 
                    285: Copyright  1999, 2000, 2001, 2002 Federico Lupi
                    286: 
                    287: Copyright  2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 The NetBSD Foundation
                    288: 
                    289: All brand and product names used in this guide are or may be trademarks or registered trademarks of their respective owners.
                    290: 
                    291: NetBSD is a registered trademark of The NetBSD Foundation, Inc.

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb