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

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: ***I. About NetBSD***
                     33: 
1.3       jdf        34:  * [[1. What is NetBSD?|guide/intro]]
                     35:    * [[1.1. The story of NetBSD]]
                     36:    * [[1.2. NetBSD features]]
                     37:    * [[1.3. Supported platforms]]
                     38:    * [[1.4. NetBSD's target users]]
                     39:    * [[1.5. Applications for NetBSD]]
                     40:    * [[1.6. How to get NetBSD]]
1.1       jdf        41: 
                     42: ***II. System installation and related issues***
                     43: 
1.24      jdf        44:  * [[2. Installing NetBSD: Preliminary considerations and preparations|guide/inst]]
                     45:    * [[2.1. Preliminary considerations]]
                     46:    * [[2.2. Install preparations]]
                     47:    * [[2.3. Checklist]]
1.1       jdf        48: 
                     49: ***III. System configuration, administration and tuning***
                     50: 
1.2       jdf        51:  * [[4. Upgrading NetBSD|guide/upgrading]]
                     52:    * [[4.1. Using sysinst]]
                     53:    * [[4.2. Using sysupgrade]]
                     54:  * [[5. The first steps on NetBSD|guide/boot]]
                     55:    * [[5.1. Troubleshooting]]
                     56:    * [[5.2. The man command]]
                     57:    * [[5.3. Editing configuration files]]
                     58:    * [[5.4. Login]]
1.9       jdf        59:    * [[5.5. Changing the root password]]
1.2       jdf        60:    * [[5.6. Adding users]]
                     61:    * [[5.7. Shadow passwords]]
                     62:    * [[5.8. Changing the keyboard layout]]
                     63:    * [[5.9. System time]]
1.3       jdf        64:    * [[5.10. Secure Shell ssh(1)]]
1.9       jdf        65:    * [[5.11. Basic configuration in /etc/rc.conf]]
1.2       jdf        66:    * [[5.12. Basic network settings]]
                     67:    * [[5.13. Mounting a CD-ROM]]
                     68:    * [[5.14. Mounting a floppy]]
                     69:    * [[5.15. Installing additional software]]
                     70:    * [[5.16. Security alerts]]
                     71:    * [[5.17. Stopping and rebooting the system]]
1.15      jdf        72:  * [[6. Editing|guide/edit]]
                     73:    * [[6.1. Introducing vi]]
                     74:    * [[6.2. Configuring vi]]
                     75:    * [[6.3. Using tags with vi]]
1.2       jdf        76:  * [[7. The rc.d System|guide/rc]]
                     77:    * [[7.1. Basics]]
                     78:    * [[7.2. The rc.d scripts]]
                     79:    * [[7.3. Order/dependencies of start determined by rcorder]]
                     80:    * [[7.4. rc.d scripts of additional services]]
                     81:    * [[7.5. Additional Reading]]
1.14      jdf        82:  * [[8. Console drivers|guide/cons]]
                     83:    * [[8.1. wscons]]
1.2       jdf        84:  * [[9. X|guide/x]]
                     85:    * [[9.1. What is X?]]
                     86:    * [[9.2. Configuration]]
                     87:    * [[9.3. The mouse]]
                     88:    * [[9.4. The keyboard]]
                     89:    * [[9.5. The monitor]]
                     90:    * [[9.6. The video card]]
                     91:    * [[9.7. Starting X]]
                     92:    * [[9.8. Customizing X]]
                     93:    * [[9.9. Other window managers or desktop environments]]
                     94:    * [[9.10. Graphical login with xdm]]
1.17      jdf        95:  * [[10. Linux emulation|guide/linux]]
                     96:    * [[10.1. Emulation setup]]
                     97:    * [[10.2. Directory structure]]
                     98:    * [[10.3. Emulating /proc]]
                     99:    * [[10.4. Using Linux browser plugins]]
                    100:    * [[10.5. Further reading]]
1.2       jdf       101:  * [[11. Audio|guide/audio]]
                    102:    * [[11.1. Basic hardware elements]]
                    103:    * [[11.2. Supported audio cards]]
                    104:    * [[11.3. BIOS settings]]
                    105:    * [[11.4. Configuring the audio device]]
                    106:    * [[11.5. Multiple audio devices]]
                    107:    * [[11.6. Configuring the kernel audio devices]]
                    108:    * [[11.7. Advanced commands]]
1.20      jdf       109:  * [[12. Printing|guide/print]]
                    110:    * [[12.1. Enabling the printer daemon]]
                    111:    * [[12.2. Configuring `/etc/printcap`]]
                    112:    * [[12.3. Configuring Ghostscript]]
                    113:    * [[12.4. Printer management commands]]
                    114:    * [[12.5. Remote printing]]
1.21      jdf       115:  * [[13. Using removable media|guide/rmmedia]]
                    116:    * [[13.1. Reading data CDs with NetBSD]]
                    117:    * [[13.2. Reading multi-session CDs with NetBSD]]
                    118:    * [[13.3. Allowing normal users to access CDs]]
                    119:    * [[13.4. Mounting an ISO image]]
                    120:    * [[13.5. Using video CDs with NetBSD]]
                    121:    * [[13.6. Using audio CDs with NetBSD]]
                    122:    * [[13.7. Creating an MP3 (MPEG layer 3) file from an audio CD]]
                    123:    * [[13.8. Using a CD-R writer with data CDs]]
                    124:    * [[13.9. Using a CD-R writer to create audio CDs]]
                    125:    * [[13.10. Creating an audio CD from MP3s]]
                    126:    * [[13.11. Copying an audio CD]]
                    127:    * [[13.12. Copying a data CD with two drives]]
                    128:    * [[13.13. Using CD-RW rewritables]]
                    129:    * [[13.14. DVD support]]
                    130:    * [[13.15. Creating ISO images from a CD]]
                    131:    * [[13.16. Getting volume information from CDs and ISO images]]
                    132:    * [[13.17. Initializing and using floppy disks]]
1.13      jdf       133:  * [[14. The cryptographic device driver (CGD)|guide/cgd]]
                    134:    * [[14.1. Overview]]
                    135:    * [[14.2. Components of the Crypto-Graphic Disk system]]
                    136:    * [[14.3. Example: encrypting your disk]]
                    137:    * [[14.4. Example: encrypted CDs/DVDs]]
                    138:    * [[14.5. Suggestions and Warnings]]
                    139:    * [[14.6. Further Reading]]
1.12      jdf       140:  * [[15. Concatenated Disk Device (CCD) configuration|guide/ccd]]
                    141:    * [[15.1. Install physical media]]
                    142:    * [[15.2. Configure Kernel Support]]
                    143:    * [[15.3. Disklabel each volume member of the CCD]]
                    144:    * [[15.4. Configure the CCD]]
                    145:    * [[15.5. Initialize the CCD device]]
                    146:    * [[15.6. Create a 4.2BSD/UFS filesystem on the new CCD device]]
                    147:    * [[15.7. Mount the filesystem]]
1.16      jdf       148:  * [[17. NetBSD Logical Volume Manager (LVM) configuration|guide/lvm]]
                    149:    * [[17.1. Anatomy of NetBSD Logical Volume Manager]]
                    150:    * [[17.2. Install physical media]]
                    151:    * [[17.3. Configure Kernel Support]]
                    152:    * [[17.4. Configure LVM on a NetBSD system]]
                    153:    * [[17.5. Disklabel each physical volume member of the LVM]]
                    154:    * [[17.6. Create Physical Volumes]]
                    155:    * [[17.7. Create Volume Group]]
                    156:    * [[17.8. Create Logical Volume]]
                    157:    * [[17.9. Example: LVM with Volume groups located on raid1]]
1.18      jdf       158:  * [[18. Pluggable Authentication Modules (PAM)|guide/pam]]
                    159:    * [[18.1. About]]
                    160:    * [[18.2. Introduction]]
                    161:    * [[18.3. Terms and conventions]]
                    162:    * [[18.4. PAM Essentials]]
                    163:    * [[18.5. PAM Configuration]]
                    164:    * [[18.6. PAM modules]]
                    165:    * [[18.7. PAM Application Programming]]
                    166:    * [[18.8. PAM Module Programming]]
                    167:    * [[18.9. Sample PAM Application]]
                    168:    * [[18.10. Sample PAM Module]]
                    169:    * [[18.11. Sample PAM Conversation Function]]
                    170:    * [[18.12. Further Reading]]
1.4       jdf       171:  * [[19. Tuning NetBSD|guide/tuning]]
                    172:    * [[19.1. Introduction]]
                    173:    * [[19.2. Tuning Considerations]]
                    174:    * [[19.3. Visual Monitoring Tools]]
                    175:    * [[19.4. Monitoring Tools]]
                    176:    * [[19.5. Network Tools]]
                    177:    * [[19.6. Accounting]]
                    178:    * [[19.7. Kernel Profiling]]
                    179:    * [[19.8. System Tuning]]
                    180:    * [[19.9. Kernel Tuning]]
1.2       jdf       181:  * [[20. NetBSD Veriexec subsystem|guide/veriexec]]
                    182:    * [[20.1. How it works]]
                    183:    * [[20.2. Signatures file]]
                    184:    * [[20.3. Strict levels]]
                    185:    * [[20.4. Veriexec and layered file systems]]
                    186:    * [[20.5. Kernel configuration]]
1.10      jdf       187:  * [[21. Bluetooth on NetBSD|guide/bluetooth]]
                    188:    * [[21.1. Introduction]]
                    189:    * [[21.2. Supported Hardware]]
                    190:    * [[21.3. System Configuration]]
                    191:    * [[21.4. Human Interface Devices]]
                    192:    * [[21.5. Personal Area Networking]]
                    193:    * [[21.6. Serial Connections]]
                    194:    * [[21.7. Audio]]
                    195:    * [[21.8. Object Exchange]]
                    196:    * [[21.9. Troubleshooting]]
1.7       jdf       197:  * [[22. Miscellaneous operations|guide/misc]]
                    198:    * [[22.1. Installing the boot manager]]
                    199:    * [[22.2. Deleting the disklabel]]
                    200:    * [[22.3. Speaker]]
                    201:    * [[22.4. Forgot root password?]]
                    202:    * [[22.5. Password file is busy?]]
                    203:    * [[22.6. Adding a new hard disk]]
                    204:    * [[22.7. How to rebuild the devices in /dev]]
1.1       jdf       205: 
                    206: ***IV. Networking and related issues***
                    207: 
1.25      jdf       208:  * [[23.|guide/net-intro]]
                    209:    * [[23.1. Introduction to TCP/IP Networking]]
                    210:    * [[23.2. Audience]]
                    211:    * [[23.3. Supported Networking Protocols]]
                    212:    * [[23.4. Supported Media]]
                    213:    * [[23.5. TCP/IP Address Format]]
                    214:    * [[23.6. Subnetting and Routing]]
                    215:    * [[23.7. Name Service Concepts]]
                    216:    * [[23.8. Next generation Internet protocol - IPv6]]
1.9       jdf       217:  * [[25. The Internet Super Server inetd
                    218:  Allowing and denying hosts - /etc/hosts.allow, /etc/hosts.deny|guide/inetd]]
1.5       jdf       219:    * [[25.1. Overview]]
                    220:    * [[25.2. What is inetd?]]
1.9       jdf       221:    * [[25.3. Configuring inetd - /etc/inetd.conf]]
                    222:    * [[25.4. Services - /etc/services]]
                    223:    * [[25.5. Protocols - /etc/protocols]]
                    224:    * [[25.6. Remote Procedure Calls (RPC) - /etc/rpc]]
                    225:    * [[25.7. Adding a Service]]
                    226:    * [[25.8. When to use or not to use inetd]]
                    227:    * [[25.9. Other Resources]]
1.19      jdf       228:  * [[26. The Domain Name System|guide/dns]]
                    229:    * [[26.1. DNS Background and Concepts]]
                    230:    * [[26.2. The DNS Files]]
                    231:    * [[26.3. Using DNS]]
                    232:    * [[26.4. Setting up a caching only name server]]
1.22      jdf       233:  * [[27. Mail and news|guide/mail]]
                    234:    * [[27.1. postfix]]
                    235:    * [[27.2. fetchmail]]
                    236:    * [[27.3. Reading and writing mail with mutt]]
                    237:    * [[27.4. Strategy for receiving mail]]
                    238:    * [[27.5. Strategy for sending mail]]
                    239:    * [[27.6. Advanced mail tools]]
                    240:    * [[27.7. News with tin]]
1.6       jdf       241:  * [[28. Introduction to the Common Address Redundancy Protocol (CARP)|guide/carp]]
                    242:    * [[28.1. CARP Operation]]
                    243:    * [[28.2. Configuring CARP]]
                    244:    * [[28.3. Enabling CARP Support]]
                    245:    * [[28.4. CARP Example]]
                    246:    * [[28.5. Advanced CARP configuration]]
                    247:    * [[28.6. Forcing Failover of the Master]]
                    248:    * [[28.7. License]]
1.23      jdf       249:  * [[29. Network services|guide/net-services]]
                    250:    * [[29.1. The Network File System (NFS)]]
                    251:    * [[29.2. The Network Time Protocol (NTP)]]
1.1       jdf       252: 
                    253: ***V. Building the system***
                    254: 
1.8       jdf       255:  * [[30. Obtaining the sources|guide/fetch]]
                    256:    * [[30.1. Preparing directories]]
                    257:    * [[30.2. Terminology]]
                    258:    * [[30.3. Downloading tarballs]]
                    259:    * [[30.4. Fetching by CVS]]
                    260:    * [[30.5. Sources on CD (ISO)]]
1.11      jdf       261:  * [[31. Crosscompiling NetBSD with build.sh|guide/build]]
                    262:    * [[31.1. Building the crosscompiler]]
                    263:    * [[31.2. Configuring the kernel manually]]
                    264:    * [[31.3. Crosscompiling the kernel manually]]
                    265:    * [[31.4. Crosscompiling the kernel with build.sh]]
                    266:    * [[31.5. Crosscompiling the userland]]
                    267:    * [[31.6. Crosscompiling the X Window System]]
                    268:    * [[31.7. Changing build behaviour]]
1.2       jdf       269:  * [[32. Compiling the kernel|guide/kernel]]
                    270:    * [[32.1. Requirements and procedure]]
                    271:    * [[32.2. Installing the kernel sources]]
                    272:    * [[32.3. Creating the kernel configuration file]]
                    273:    * [[32.4. Building the kernel manually]]
1.9       jdf       274:    * [[32.5. Building the kernel using build.sh]]
1.2       jdf       275:    * [[32.6. Installing the new kernel]]
                    276:    * [[32.7. If something went wrong]]
                    277:  * [[33. Updating an existing system from sources|guide/updating]]
                    278:    * [[33.1. Manual build and update procedure]]
                    279:    * [[33.2. Using sysinst]]
                    280:    * [[33.3. Using sysbuild and sysupgrade]]
                    281:    * [[33.4. More details about the updating of configuration and startup files]]
1.1       jdf       282: 
                    283: ## Guide history
                    284: 
                    285: This guide was born as a collection of sparse notes that Federico Lupi, the
                    286: original author of the NetBSD Guide, wrote mostly for himself. When he realized
                    287: that they could be useful to other NetBSD users he started collecting them and
                    288: created the first version of the guide using the groff formatter. In order to
                    289: "easily" get a wider variety of output formats (e.g. HTML and
                    290: PostScript/PDF), he made the "mistake" of moving to SGML/DocBook, which
1.6       jdf       291: was the format of the sources. Maintainership was picked up by the NetBSD
1.1       jdf       292: project and its developers later, and the format was changed to XML/DocBook
                    293: later due to better tools and slightly more knowhow on customisations.
                    294: 
1.7       jdf       295: In 2012/2013, the guide was converted in a Google Code-In task by Mingzhe Wang
                    296: (wmzhere) to Markdown. In early 2013, it was integrated to the NetBSD wiki,
                    297: along with removing old chapters, restricting numbering schemes and some
                    298: reformulations.
                    299: 
                    300: You can still get the
                    301: [old version of the Guide](http://netbsd.org/docs/guide), which is not
                    302: maintained anymore.
1.1       jdf       303: 
                    304: ## Bibliography
                    305: 
                    306: * [RFC1933] R. Gilligan and E. Nordmark. Copyright © 1996. *RFC 1933: Transition Mechanisms for IPv6 Hosts and Routers*.
                    307: * [RFC2004] C. Perkins. Copyright © 1996. *RFC 2003: IP Encapsulation within IP*.
                    308: * [RFC2529] B. Carpenter and C. Jung. Copyright © 1999. *RFC 2529: Transmission of IPv6 over IPv4 Domains without Explicit Tunnels*.
                    309: * [RFC3056] B. Carpenter and K. Moore. Copyright © 2001. *RFC 3056: Connection of IPv6 Domains via IPv4 Clouds*.
                    310: 
                    311: ## Acknowledgements
                    312: 
                    313: The NetBSD Guide was originally written by Federico Lupi who managed the
                    314: sources, coordinated updates, and merged all contributions on his own. Since
                    315: then, it has been updated and maintained by the NetBSD www team. The Guide has
                    316: progressed thanks to the contributions of many people who have volunteered their
                    317: time and effort, supplied material and sent in suggestions and corrections.
                    318: 
                    319: ### Original acknowledgements
                    320: 
                    321: Federico's original credits are:
                    322: 
                    323: * Paulo Aukar
                    324: * Grant Beattie, converted to XML DocBook.
                    325: * Manolo De Santis, Audio Chapter
                    326: * Eric Delcamp, Boot Floppies
                    327: * Hubert Feyrer, who contributed
                    328: [[Introduction to TCP/IP Networking|guide/net-intro]] including Next
                    329: generation Internet protocol - IPv6 and the section
                    330: [[IPv6 Connectivity & Transition via 6to4|guide/net-practice#ipv6-6to4]]
                    331: He also helped with the SGML to XML transition.
                    332: * Jason R. Fink
                    333: * Daniel de Kok, audio and linux chapters fixes.
                    334: * Reinoud Koornstra, CVS chapter and rebuilding `/dev` in the Misc chapter.
                    335: * Brian A. Seklecki [lavalamp@burghcom.com](mailto:lavalamp@burghcom.com), who
                    336: contributed the CCD Chapter.
                    337: * Guillain Seuillot
                    338: * Martti Kuparinen, RAIDframe documentation.
                    339: * David Magda
                    340: 
                    341: ### Current acknowledgements
                    342: 
                    343: This document is currently maintained by the NetBSD www team. Thanks to their
                    344: efforts, the document is kept up to date and available online at all times. In
                    345: addition, special thanks go to (in alphabetical order):
                    346: 
                    347: * Hubert Feyrer, for getting the guide up to speed for NetBSD 2.0, and for
                    348: making numerous improvements to all chapters.
                    349: * Jason R. Fink, for maintaining this document and integrating changes.
                    350: * Andreas Hallman, for his information in
                    351: [[Tunneling 6to4 through an IPFilter firewall|guide/net-practice#chap-net-practice-ipv6-6to4-ipf]]
                    352: * Joel Knight for the
                    353: [[Introduction to the Common Address Redundancy Protocol (CARP)|guide/carp]].
                    354: See below for for the accompanying license.
                    355: * Daniel de Kok, for constant contributions of new chapters, maintenance of
                    356: existing chapters and his translation work.
                    357: * Hiroki Sato, for allowing us to build PDF and PS versions of this document.
                    358: * Jan Schaumann, for maintenance work and `www/htdocs` management.
                    359: * Lubomir Sedlacik, for some details on using CGD for swap in
                    360: [[Suggestions and Warnings|guide/cgd#suggestions]]
                    361: * Dag-Erling Smrgrav, for the article on
                    362: [[Pluggable Authentication Modules (PAM)|guide/pam]]. See below for the
                    363: accompanying license.
                    364: * Florian Sthr, for
                    365: [[Example: encrypted CDs/DVDs|guide/cgd#cryptocds]]
                    366: 
                    367: 
                    368: ### Licenses
                    369: 
                    370: #### Federico Lupi's original license of this guide
                    371: 
                    372: Redistribution and use in source and binary forms, with or without modification,
                    373: are permitted provided that the following conditions are met:
                    374: 
                    375: 1. Redistributions of source code must retain the above copyright notice, this
                    376: list of conditions and the following disclaimer.
                    377: 2. Redistributions in binary form must reproduce the above copyright notice,
                    378: this list of conditions and the following disclaimer in the documentation
                    379: and/or other materials provided with the distribution.
                    380: 3. All advertising materials mentioning features or use of this software must
                    381: display the following acknowledgement: This product includes software developed
                    382: by Federico Lupi for the NetBSD Project.
                    383: 4. The name of the author may not be used to endorse or promote products
                    384: derived from this software without specific prior written permission.
                    385: 
                    386: THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
                    387: WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
                    388: MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
                    389: SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
                    390: EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
                    391: OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                    392: INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                    393: CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
                    394: IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
                    395: OF SUCH DAMAGE.
                    396: 
                    397: #### The NetBSD Developers
                    398: 
                    399: Copyright  1999, 2000, 2001, 2002 Federico Lupi
                    400: 
1.6       jdf       401: Copyright  2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The NetBSD Foundation
1.1       jdf       402: 
                    403: All brand and product names used in this guide are or may be trademarks or registered trademarks of their respective owners.
                    404: 
                    405: NetBSD is a registered trademark of The NetBSD Foundation, Inc.

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