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

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

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