The NetBSD Guide

The NetBSD Developers

All brand and product names used in this guide are or may be trademarks or registered trademarks of their respective owners.

NetBSD® is a registered trademark of The NetBSD Foundation, Inc.

Published: 2021/04/18 20:35:49

$NetBSD: index.html,v 1.269 2021/05/01 09:42:02 nia Exp $


Table of Contents

Purpose of this guide
I. About NetBSD
1. What is NetBSD?
1.1. The story of NetBSD
1.2. NetBSD features
1.3. Supported platforms
1.4. NetBSD's target users
1.5. Applications for NetBSD
1.6. How to get NetBSD
II. System installation and related issues
2. Installing NetBSD: Preliminary considerations and preparations
2.1. Preliminary considerations
2.1.1. Dual booting
2.1.2. NetBSD on emulation and virtualization
2.2. Install preparations
2.2.1. The INSTALL document
2.2.2. Partitions
2.2.3. Hard disk space requirements
2.2.4. Network settings
2.2.5. Backup your data and operating systems!
2.2.6. Preparing the installation media
2.3. Checklist
3. Example installation
3.1. Introduction
3.2. The installation process
3.3. Keyboard layout
3.4. Starting the installation
3.5. MBR partitions
3.6. Disklabel partitions
3.7. Setting the disk name
3.8. Last chance!
3.9. The disk preparation process
3.10. Installation type
3.11. Choosing the installation medium
3.11.1. Installing from CD-ROM / DVD / install image media
3.11.2. Installing from an unmounted file system
3.11.3. Installing via FTP and Network configuration
3.11.4. Installing via NFS
3.12. Extracting sets
3.13. System configuration
3.14. Finishing the installation
4. Upgrading NetBSD
4.1. Using sysinst
4.1.1. Overview
4.1.2. The INSTALL document
4.1.3. Performing the upgrade
4.2. Using sysupgrade
III. System configuration, administration and tuning
5. The first steps on NetBSD
5.1. Troubleshooting
5.1.1. Boot problems
5.1.2. Misconfiguration of /etc/rc.conf
5.2. The man command
5.3. Editing configuration files
5.4. Login
5.5. Changing the root password
5.6. Adding users
5.7. Shadow passwords
5.8. Changing the keyboard layout
5.9. System time
5.10. Secure Shell (ssh(1))
5.11. Basic configuration in /etc/rc.conf
5.12. Basic network settings
5.13. Mounting a CD-ROM
5.14. Mounting a floppy
5.15. Installing additional software
5.16. Security alerts
5.17. Stopping and rebooting the system
6. Editing
6.1. Introducing vi
6.1.1. The vi interface
6.1.2. Switching to Edit Mode
6.1.3. Switching Modes & Saving Buffers to Files
6.1.4. Yanking and Putting
6.1.5. Navigation in the Buffer
6.1.6. Searching a File, the Alternate Navigational Aid
6.1.7. A Sample Session
6.2. Configuring vi
6.2.1. Extensions to .exrc
6.2.2. Documentation
6.3. Using tags with vi
7. The rc.d System
7.1. Basics
7.2. The rc.d Scripts
7.2.1. Packages installing rc.d scripts
7.3. The Role of rcorder and rc.d Scripts
7.4. Additional Reading
8. Console drivers
8.1. wscons
8.1.1. wsdisplay
8.1.2. wskbd
8.1.3. wsmouse
9. X
9.1. What is X11?
9.2. Configuration
9.3. The keyboard
9.4. The monitor
9.5. Starting X
9.6. Customizing X
9.7. Other window managers or desktop environments
9.8. Graphical login with xdm
10. Audio
10.1. Configuring the default audio device
10.2. Configuring the mixer and volume
10.2.1. Setting default mixer settings on boot
10.3. Pseudo audio devices
10.4. Recording and playback commands
10.4.1. audioplay(1)
10.4.2. audiorecord(1)
10.4.3. audioctl(1)
10.5. MIDI support
10.5.1. midirecord(1)
10.5.2. midiplay(1)
10.6. Intel HD Audio devices
10.6.1. Built-in and jacks: DACs/ADCs
10.6.2. HDMI/DisplayPort audio
11. Power management
11.1. Basic power management commands
11.1.1. Powering off or rebooting the system
11.1.2. Using ACPI sleep states (suspend and resume)
11.1.3. Suspending and resuming individual devices
11.1.4. Adjusting CPU frequency at runtime
11.1.5. Using IEEE 802.11 (Wi-Fi) power saving mode
11.2. Sensors and monitoring
11.3. An introduction to powerd
11.3.1. Example: using powerd to suspend on lid close
11.3.2. Example: reducing CPU frequency when unplugged
12. Printing
12.1. Enabling the printer daemon
12.2. Configuring /etc/printcap
12.3. Configuring Ghostscript
12.4. Printer management commands
12.5. Remote printing
13. Using removable media
13.1. Initializing and using USB flash drives
13.2. Initializing and using floppy disks
13.3. How to use a ZIP disk
13.4. Reading data CDs with NetBSD
13.5. Reading multi-session CDs with NetBSD
13.6. Allowing normal users to access CDs
13.7. Mounting an ISO image
13.8. Using video CDs with NetBSD
13.9. Using audio CDs with NetBSD
13.10. Creating an MP3 (MPEG layer 3) file from an audio CD
13.11. Using a CD-R writer with data CDs
13.12. Using a CD-R writer to create audio CDs
13.13. Creating an audio CD from MP3s
13.14. Copying an audio CD
13.15. Copying a data CD with two drives
13.16. Using CD-RW rewritables
13.17. DVD support
13.18. Creating ISO images from a CD
13.19. Getting volume information from CDs and ISO images
14. The cryptographic device driver (CGD)
14.1. Overview
14.1.1. Why use disk encryption?
14.1.2. Logical Disk Drivers
14.1.3. Availability
14.2. Components of the Crypto-Graphic Disk system
14.2.1. Kernel driver pseudo-device
14.2.2. Ciphers
14.2.3. Obsolete Ciphers
14.2.4. Verification Methods
14.3. Example: encrypting your disk
14.3.1. Preparing the disk
14.3.2. Scrubbing the disk
14.3.3. Creating the cgd
14.3.4. Modifying configuration files
14.3.5. Restoring data
14.4. Example: encrypted CDs/DVDs
14.4.1. Creating an encrypted CD/DVD
14.4.2. Using an encrypted CD/DVD
14.5. Example: encrypted iSCSI devices
14.5.1. Creating an encrypted iSCSI device
14.5.2. Device Initialisation
14.5.3. Unmounting the Encrypted Device
14.5.4. Normal Usage
14.6. Suggestions and Warnings
14.6.1. Using a random-key cgd for swap
14.6.2. Warnings
14.7. Further Reading
15. Concatenated Disk Device (CCD) configuration
15.1. Install physical media
15.2. Configure Kernel Support
15.3. Disklabel each volume member of the CCD
15.4. Configure the CCD
15.5. Initialize the CCD device
15.6. Create a 4.2BSD/UFS filesystem on the new CCD device
15.7. Mount the filesystem
16. NetBSD RAIDframe
16.1. RAIDframe Introduction
16.1.1. About RAIDframe
16.1.2. A warning about Data Integrity, Backups, and High Availability
16.1.3. Getting Help
16.2. Setup RAIDframe Support
16.2.1. Kernel Support
16.2.2. Power Redundancy and Disk Caching
16.3. Example: RAID-1 Root Disk
16.3.1. Pseudo-Process Outline
16.3.2. Hardware Review
16.3.3. Initial Install on Disk0/wd0
16.3.4. Preparing Disk1/wd1
16.3.5. Initializing the RAID Device
16.3.6. Setting up Filesystems
16.3.7. Migrating System to RAID
16.3.8. The first boot with RAID
16.3.9. Adding Disk0/wd0 to RAID
16.3.10. Testing Boot Blocks
17. NetBSD Logical Volume Manager (LVM) configuration
17.1. Anatomy of NetBSD Logical Volume Manager
17.2. Install physical media
17.3. Configure Kernel Support
17.4. Disklabel each physical volume member of the LVM
17.5. Create Physical Volumes
17.6. Create Volume Group
17.7. Create Logical Volume
17.8. Example: LVM with Volume groups located on raid1
17.8.1. Loading Device-Mapper driver
17.8.2. Preparing raid1 installation
17.8.3. Creating PV, VG on raid disk
17.8.4. Creating LV's from VG located on raid disk
17.8.5. Integration of LV's in to the system
18. Pluggable Authentication Modules (PAM)
18.1. About
18.2. Introduction
18.3. Terms and conventions
18.3.1. Definitions
18.3.2. Usage examples
18.4. PAM Essentials
18.4.1. Facilities and primitives
18.4.2. Modules
18.4.3. Chains and policies
18.4.4. Transactions
18.5. PAM Configuration
18.5.1. PAM policy files
18.5.2. Breakdown of a configuration line
18.5.3. Policies
18.6. PAM modules
18.6.1. Common Modules
18.6.2. NetBSD-specific PAM Modules
18.7. PAM Application Programming
18.8. PAM Module Programming
18.9. Sample PAM Application
18.10. Sample PAM Module
18.11. Sample PAM Conversation Function
18.12. Further Reading
19. Tuning NetBSD
19.1. Introduction
19.1.1. Overview
19.2. Tuning Considerations
19.2.1. General System Configuration
19.2.2. System Services
19.2.3. The NetBSD Kernel
19.3. Visual Monitoring Tools
19.3.1. The top Process Monitor
19.3.2. The sysstat utility
19.4. Monitoring Tools
19.4.1. fstat
19.4.2. iostat
19.4.3. ps
19.4.4. vmstat
19.5. Network Tools
19.5.1. ping
19.5.2. traceroute
19.5.3. netstat
19.5.4. tcpdump
19.6. Accounting
19.6.1. Accounting
19.6.2. Reading Accounting Information
19.6.3. How to Put Accounting to Use
19.7. Kernel Profiling
19.7.1. Getting Started
19.7.2. Interpretation of kgmon Output
19.7.3. Putting it to Use
19.7.4. Summary
19.8. System Tuning
19.8.1. Using sysctl
19.8.2. tmpfs & mfs
19.8.3. Journaling
19.8.4. LFS
19.9. Kernel Tuning
19.9.1. Preparing to Recompile a Kernel
19.9.2. Configuring the Kernel
19.9.3. Building the New Kernel
19.9.4. Shrinking the NetBSD kernel
20. NetBSD Veriexec subsystem
20.1. How it works
20.2. Signatures file
20.3. Generating fingerprints
20.4. Strict levels
20.5. Veriexec and layered file systems
20.6. Kernel configuration
21. Bluetooth on NetBSD
21.1. Introduction
21.2. Supported Hardware
21.3. System Configuration
21.4. Human Interface Devices
21.4.1. Mice
21.4.2. Keyboards
21.5. Personal Area Networking
21.5.1. Personal Area Networking User
21.6. Serial Connections
21.7. Audio
21.7.1. SCO Audio Headsets
21.7.2. SCO Audio Handsfree
21.8. Object Exchange
21.9. Troubleshooting
22. Linux emulation
22.1. Emulation setup
22.1.1. Configuring the kernel
22.1.2. Installing the Linux libraries
22.1.3. Running Linux programs
22.2. Directory structure
22.3. Using Linux browser plugins
22.4. Further reading
23. Miscellaneous operations
23.1. Installing the boot manager
23.2. Deleting the disklabel
23.3. Speaker
23.4. Forgot root password?
23.5. Password file is busy?
23.6. Adding a new hard disk
23.7. How to rebuild the devices in /dev
IV. Networking and related issues
24. Introduction to TCP/IP Networking
24.1. Audience
24.2. Supported Networking Protocols
24.3. Supported Media
24.3.1. Ethernet
24.3.2. IEEE 802.11 (Wi-Fi)
24.3.3. Serial Line
24.4. TCP/IP Address Format
24.5. Subnetting and Routing
24.6. Name Service Concepts
24.6.1. /etc/hosts
24.6.2. Domain Name Service (DNS)
24.6.3. Network Information Service (NIS/YP)
24.6.4. Other
24.7. IPv6
24.7.1. What good is IPv6?
24.7.2. Changes to IPv4
25. Setting up TCP/IP on NetBSD in practice
25.1. Overview of the network configuration files
25.2. Connecting to common LAN setups
25.2.1. Connecting using IEEE 802.11 (Wi-Fi)
25.3. Manually creating a small LAN
25.4. Connecting to a home/office ISP with PPPoE
25.4.1. Configuring a VLAN
25.4.2. Setting up MSS clamping
25.4.3. Obtaining IPv6 addresses via Prefix Delegation
25.5. Setting up an Internet gateway with NPF
25.6. Setting up a network bridge device
25.6.1. Bridge example
25.7. Ensuring interfaces are initialized in the correct order
25.8. Some useful commands
26. The Internet Super Server inetd
26.1. Overview
26.2. What is inetd?
26.3. Configuring inetd - /etc/inetd.conf
26.4. Services - /etc/services
26.5. Protocols - /etc/protocols
26.6. Remote Procedure Calls (RPC) - /etc/rpc
26.7. Allowing and denying hosts - /etc/hosts.{allow,deny}
26.8. Adding a Service
26.9. When to use or not to use inetd
26.10. Other Resources
27. The Domain Name System
27.1. DNS Background and Concepts
27.1.1. Naming Services
27.1.2. The DNS namespace
27.1.3. Resource Records
27.1.4. Delegation
27.1.5. Delegation to multiple servers
27.1.6. Secondaries, Caching, and the SOA record
27.1.7. Name Resolution
27.1.8. Reverse Resolution
27.2. The DNS Files
27.2.1. /etc/named.conf
27.2.2. /etc/namedb/localhost
27.2.3. /etc/namedb/zone.127.0.0
27.2.4. /etc/namedb/diverge.org
27.2.5. /etc/namedb/1.168.192
27.2.6. /etc/namedb/root.cache
27.3. Using DNS
27.4. Setting up a caching only name server
27.4.1. Testing the server
28. Mail and news
28.1. postfix
28.1.1. Configuration of generic mapping
28.1.2. Testing the configuration
28.1.3. Using an alternative MTA
28.2. fetchmail
28.3. Reading and writing mail with mutt
28.4. Strategy for receiving mail
28.5. Strategy for sending mail
28.6. Advanced mail tools
28.7. News with tin
29. Introduction to the Common Address Redundancy Protocol (CARP)
29.1. CARP Operation
29.2. Configuring CARP
29.3. Enabling CARP Support
29.4. CARP Example
29.5. Advanced CARP configuration
29.6. Forcing Failover of the Master
30. Network services
30.1. The Network File System (NFS)
30.1.1. NFS setup example
30.1.2. Setting up NFS automounting for /net with amd(8)
30.2. The Network Time Protocol (NTP)
V. Building the system
31. Obtaining the sources
31.1. Preparing directories
31.2. Terminology
31.3. Downloading tarballs
31.3.1. Downloading sources for a NetBSD release
31.3.2. Downloading sources for a NetBSD stable branch
31.3.3. Downloading sources for a NetBSD-current development branch
31.4. Fetching by CVS
31.4.1. Fetching a NetBSD release
31.4.2. Fetching a NetBSD stable branch
31.4.3. Fetching the NetBSD-current development branch
31.4.4. Saving some cvs(1) options
32. Crosscompiling NetBSD with build.sh
32.1. Building the toolchain
32.2. Configuring the kernel manually
32.3. Building the kernel manually
32.4. Building the kernel with build.sh
32.5. Building the userland
32.6. Building the X Window System
32.7. Changing build behaviour
32.7.1. Changing the Destination Directory
32.7.2. Static Builds
32.7.3. Using build.sh options
32.7.4. make(1) variables used during build
33. Compiling the kernel
33.1. Requirements and procedure
33.2. Installing the kernel sources
33.3. Creating the kernel configuration file
33.4. Building the kernel manually
33.4.1. Configuring the kernel manually
33.4.2. Generating dependencies and recompiling manually
33.5. Building the kernel using build.sh
33.6. Installing the new kernel
33.7. If something went wrong
34. Updating an existing system from sources
34.1. Manual build and update procedure
34.1.1. Building a new userland
34.1.2. Building a new kernel
34.1.3. Installing the kernel and userland
34.1.4. Updating the system configuration files
34.1.5. Summary
34.2. Using sysinst
34.3. Using sysbuild and sysupgrade
34.3.1. Tweak: Building as non-root
34.3.2. Tweak: Setting up nightly builds
34.4. More details about the updating of configuration and startup files
34.4.1. Using etcupdate with source files
34.4.2. Using etcupdate with binary distribution sets
34.4.3. Using etcmanage instead of etcupdate
35. Building NetBSD installation media
35.1. Creating standard installation images with build.sh
35.2. Creating custom live disk images
A. Information
A.1. Where to get this document
A.2. Guide history
B. Contributing to the NetBSD guide
B.1. Sending contributions
B.2. XML/DocBook template
C. Getting started with XML/DocBook
C.1. What is XML/DocBook
C.2. Installing the necessary tools
C.3. Using the tools
C.4. Links
D. Acknowledgements
D.1. Original acknowledgements
D.2. Current acknowledgements
D.3. Licenses
D.3.1. Federico Lupi's original license of this guide
D.3.2. Networks Associates Technology's license on the PAM article
D.3.3. Joel Knight's license on the CARP article
E. Bibliography
Bibliography

List of Figures

2.1. Partitions
3.1. Selecting the language
3.2. Selecting a keyboard type
3.3. The sysinst main menu
3.4. Confirming to install NetBSD
3.5. Choosing a hard disk
3.6. Disk geometry
3.7. Choosing the partitioning scheme
3.8. fdisk
3.9. Partition options
3.10. Installing the boot selector
3.11. Edit partitions?
3.12. Setting partition sizes
3.13. The disklabel editor
3.14. Disklabel partition editing
3.15. Naming the NetBSD disk
3.16. Last chance to abort
3.17. Selecting bootblocks
3.18. Full or custom installation
3.19. Selecting distribution sets
3.20. Installation media
3.21. Mounting a file system
3.22. Mounting a partition
3.23. Accessing a MSDOS file system
3.24. Defining the FTP settings
3.25. Which network interface to configure
3.26. Using autoconfiguration
3.27. Confirm autoconfiguration
3.28. NFS install screen
3.29. NFS example
3.30. Extraction of sets completed
3.31. Configuration menu
3.32. Selecting the system's time zone
3.33. Choosing a shell
3.34. Set a root password?
3.35. Setting root password
3.36. Enabling installation of binary packages
3.37. Additional packages
3.38. Fetch and unpack pkgsrc
3.39. Installation completed
3.40. Reboot to finish installation
4.1. Starting the upgrade
4.2. Continuing the upgrade
4.3. Choosing the hard drive
4.4. File system check
4.5. Choosing bootblocks
4.6. Choosing the distribution filesets
4.7. Install medium
4.8. Upgrade complete
16.1. RAID-1 Disk Logical Layout
16.2. Perform generic install onto Disk0/wd0
16.3. Setup RAID Set
16.4. Reboot using Disk1/wd1 of RAID
16.5. Mirror Disk1/wd1 back to Disk0/wd0
16.6. Award BIOS i386 Boot Disk1/wd1
16.7. Award BIOS i386 Boot Disk0/wd0
17.1. Anatomy of Logical Volume Management
17.2. Example raid 1 configuration
24.1. IPv4-addresses are divided into more significant network- and less significant hostbits
24.2. Our demo-network
24.3. Attaching one subnet to another one
24.4. IPv6-addresses are divided into more significant network- and less significant hostbits, too
24.5. IPv6-addresses have a similar structure to class B addresses
24.6. Several interfaces attached to a link result in only one scope ID for the link
28.1. Structure of the mail system

List of Tables

18.1. PAM chain execution summary
20.1. Veriexec fingerprints tools
20.2. Veriexec access type aliases

List of Examples

11.1. /etc/powerd/scripts/lid_switch
11.2. /etc/powerd/scripts/acadapter
12.1. /etc/printcap
12.2. /usr/local/libexec/lpfilter
12.3. /etc/printcap
12.4. /usr/local/libexec/lpfilter-ps
25.1. /etc/wpa_supplicant.conf
25.2. /etc/hosts
25.3. /etc/ifconfig.pppoe0
25.4. /etc/ppp/ip-up
25.5. /etc/ppp/ip-down
25.6. /etc/ifconfig.vlan0
25.7. /etc/dhcpcd.conf
25.8. /etc/npf.conf
25.9. /etc/dhcpd.conf
25.10. /etc/ifconfig.tap0
27.1. strider's /etc/hosts file
27.2. localhost
31.1. .cvsrc