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

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

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