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