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:
33: * [[1. What is NetBSD?|guide/intro]]
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
40:
41: ***II. System installation and related issues***
42:
43: * [[2. Installing NetBSD: Preliminary considerations and preparations|guide/inst]]
44: * 2.1. Preliminary considerations
45: * 2.2. Install preparations
46: * 2.3. Checklist
47: * [[3. Example installation|guide/exinst]]
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
61: * [[4. Upgrading NetBSD|guide/upgrading]]
62: * 4.1. Using sysinst
63: * 4.2. Using sysupgrade
64:
65: ***III. System configuration, administration and tuning***
66:
67: * [[5. The first steps on NetBSD|guide/boot]]
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
85: * [[6. Editing|guide/edit]]
86: * 6.1. Introducing vi
87: * 6.2. Configuring vi
88: * 6.3. Using tags with vi
89: * [[7. The rc.d System|guide/rc]]
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
95: * [[8. Console drivers|guide/cons]]
96: * 8.1. wscons
97: * [[9. X|guide/x]]
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
108: * [[10. Linux emulation|guide/linux]]
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
114: * [[11. Audio|guide/audio]]
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
122: * [[12. Printing|guide/print]]
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
128: * [[13. Using removable media|guide/rmmedia]]
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
146: * [[14. The cryptographic device driver (CGD)|guide/cgd]]
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
153: * [[15. Concatenated Disk Device (CCD) configuration|guide/ccd]]
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
161: * [[16. NetBSD RAIDframe|guide/raidframe]]
162: * 16.1. RAIDframe Introduction
163: * 16.2. Setup RAIDframe Support
164: * 16.3. Example: RAID-1 Root Disk
165: * [[17. NetBSD Logical Volume Manager (LVM) configuration|guide/lvm]]
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
175: * [[18. Pluggable Authentication Modules (PAM)|guide/pam]]
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
188: * [[19. Tuning NetBSD|guide/tuning]]
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
198: * [[20. NetBSD Veriexec subsystem|guide/veriexec]]
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
204: * [[21. Bluetooth on NetBSD|guide/bluetooth]]
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
214: * [[22. Miscellaneous operations|guide/misc]]
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
222:
223: ***IV. Networking and related issues***
224:
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
233: * [[24. Setting up TCP/IP on NetBSD in practice|guide/net-practice]]
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
243: * [[25. The Internet Super Server inetd
244: Allowing and denying hosts - /etc/hosts.allow, /etc/hosts.deny|guide/inetd]]
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
254: * [[26. The Domain Name System|guide/dns]]
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
259: * [[27. Mail and news|guide/mail]]
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
267: * [[28. Introduction to the Common Address Redundancy Protocol (CARP)|guide/carp]]
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
275: * [[29. Network services|guide/net-services]]
276: * 29.1. The Network File System (NFS)
277: * 29.2. The Network Time Protocol (NTP)
278:
279: ***V. Building the system***
280:
281: * [[30. Obtaining the sources|guide/fetch]]
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)
287: * [[31. Crosscompiling NetBSD with build.sh|guide/build]]
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
295: * [[32. Compiling the kernel|guide/kernel]]
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
303: * [[33. Updating an existing system from sources|guide/updating]]
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
308: * [[34. Building NetBSD installation media|guide/inst-media]]
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
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
320: was the format of the sources. Maintainership was picked up by the NetBSD
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:
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.
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:
423: Copyright © 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 The NetBSD Foundation
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