OpenBSD Jumpstart 8.0: Quick Start Guide for New Users

# OpenBSD Jumpstart 8.0 Source: [https://openbsdjumpstart.org/](https://openbsdjumpstart.org/) [Also available as slides](https://openbsdjumpstart.org/slides/) A concise and practical guide for new OpenBSD users, from the first install to PF, packages and daily administration\. Forked from NetBSD\.[Theo de Raadt](https://www.theos.com/deraadt/)is the founder and leader of the OpenBSD project\. The source tree was imported into CVS on[October 18, 1995](https://cvsweb.openbsd.org/checkout/src/etc/rc,v?rev=1.1)\. ### UNIX\-like A clean, standards\-compliant UNIX\-like operating system built on decades of engineering rigor and correctness\. ### Security Focused Security\-focused operating system with[unveil\(2\)](https://man.openbsd.org/OpenBSD-8.0/amd64/unveil),[pledge\(2\)](https://man.openbsd.org/OpenBSD-8.0/amd64/pledge)and proactive code auditing\. ### Thorough FAQ A comprehensive and well\-maintained[FAQ](https://www.openbsd.org/faq)covering everything from installation to advanced configuration\. ### Cryptography Full[Cryptography](https://www.openbsd.org/crypto.html)support integrated in the base system\. No compromises on encryption\. Firewall\(PF\) Router\(networking\) Mailserver\(OpenSMTPD\) Webserver\(httpd\) Hypervisor\(vmd\) VPN\(iked, wg\) NAS\(softraid\) Desktop\(Gnome, KDE Plasma\.\.\.\) ### Version Numbers - Semiannual release cycle - New release is incremented by 0\.1 ### OpenBSD Flavors \-release Shipped every six months \-stable \-release plus patches \(support for[7\.9](https://www.openbsd.org/79.html)&[8\.0](https://www.openbsd.org/80.html)\) \-current Active development branch ### CVSweb Browse the source tree in your browser and read each file's revision history:[cvsweb\.openbsd\.org](https://cvsweb.openbsd.org/) ### Installation Really simple, ready in 5 minutes \([KISS](https://en.wikipedia.org/wiki/KISS_principle)\)\. Most of the time, pressing Enter at each question gives a good default install\. Get more information:[openbsd\.org/faq/faq4\.html](https://www.openbsd.org/faq/faq4.html) ### Auto\-Install For a full unattended install/upgrade process, you can easily use[autoinstall\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/autoinstall)\.  ### Configuration Files FilePurpose/etc/mynameDefault hostname/etc/mygateDefault gateway/etc/hostsKnown hosts on the network/etc/resolv\.confResolver \(DNS\), maintained by resolvd\(8\)/etc/hostname\.ifConfiguration for each network interface, for example: /etc/hostname\.bge0 Read:[myname\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/myname),[mygate\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/mygate),[hostname\.if\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/hostname.if),[resolv\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/resolv.conf),[resolvd\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/resolvd),[hosts\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/hosts) ### Networking Commands ``` ifconfig ifconfig re0 inet autoconf sh /etc/netstart ``` Your interface name depends on your hardware\. Check`ifconfig`output and read the relevant man page \(e\.g\.`man iwx`,`man bge`\)\. ### Networking \(Set at Startup\) ### Example 1: Static IP for re0 ``` inet 192.168.0.58 255.255.255.0 ``` With a static address, set the default gateway in /etc/mygate\. ### Example 2: DHCP for bge0 ### Example 3: Configure Wireless ``` nwid ACCESS_POINT_NAME wpakey THE_SECRET_KEY inet autoconf join AT_HOME wpakey THE_SECRET_KEY join AT_WORK wpakey THE_SECRET_KEY inet autoconf ``` After editing a`hostname\.if`file, apply it to the running system with`sh /etc/netstart re0`\(use your own interface name\)\. ### Routing ``` route -n show -inet route -n show -inet6 route -n flush ``` **Caution:**On a server you reach through a router,`route \-n flush`also removes the default route, and your SSH session goes with it\. Read:[route\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/route) ### Useful Commands ``` pfctl -d pfctl -nf /etc/pf.conf pfctl -ef /etc/pf.conf pfctl -f /etc/pf.conf pfctl -s rules ``` Read:[pfctl\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/pfctl) ### PF Ruleset Sample ``` set skip on lo source limiter "ssh-protect" id 1 \ entries 10000 limit 3 rate 5/60 block log all pass in on egress inet proto icmp all icmp-type echoreq pass in on egress inet proto tcp from any to any port ssh \ source limiter "ssh-protect" pass out ``` Read:[pf\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/pf.conf) ### tcpdump ``` tcpdump -nettti pflog0 tcpdump -n -i egress tcpdump -n host 192.168.1.100 tcpdump -n port 22 tcpdump -n udp port 53 tcpdump -w capture.pcap -i egress tcpdump -r capture.pcap ``` Read:[tcpdump\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/tcpdump) ### PF User's Guide ### Group Management File:`/etc/group` ``` group [add|del|info|mod] foobar ``` Members in wheel group can use[su\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/su)to become root\. Read:[group\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/group),[group\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/group.5),[rmgroup\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/rmgroup.8) ### doas\(1\): Replaces sudo in Base System ``` permit nopass marc as root cmd /sbin/reboot ``` ``` doas -C /etc/doas.conf doas -C /etc/doas.conf /sbin/reboot $ doas /sbin/reboot ``` Read:[doas\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/doas),[doas\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/doas.conf) ### Package Installation ``` https://cdn.openbsd.org/pub/OpenBSD ``` ``` pkg_info -Q foobar pkg_add squid pkg_add -u ``` Look in`/usr/local/share/doc/pkg\-readmes`for extra documentation\. Read:[pkg\_info\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/pkg_info),[pkg\_add\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/pkg_add),[installurl\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/installurl) ### Package Management ### Delete & Clean ``` pkg_delete foobar pkg_delete -an pkg_delete -a pkg_delete -nX nginx ``` Read:[pkg\_delete\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/pkg_delete) ### rcctl: Service Control File:`/etc/rc\.conf\.local` ``` rcctl [enable|disable|start|stop|reload|restart] foobar rcctl enable apmd rcctl set apmd flags -A rcctl start apmd ``` Read:[rcctl\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/rcctl),[rc\.conf\(8\), rc\.conf\.local\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/rc.conf.8) ### Step by Step ``` rcctl enable httpd rcctl start httpd cp /etc/examples/acme-client.conf /etc/ acme-client -v example.com httpd -n && rcctl reload httpd ~ * * * * acme-client example.com && rcctl reload httpd ``` Read:[httpd\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/httpd),[httpd\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/httpd.conf),[acme\-client\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/acme-client),[acme\-client\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/acme-client.conf) ### httpd\.conf Sample ``` server "example.com" { listen on * port 80 location "/.well-known/acme-challenge/*" { root "/acme" request strip 2 } location "*" { block return 301 "https://$HTTP_HOST$REQUEST_URI" } } server "example.com" { listen on * tls port 443 tls certificate "/etc/ssl/example.com.fullchain.pem" tls key "/etc/ssl/private/example.com.key" } ``` Site files go in`/var/www/htdocs`\. Read:[httpd\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/httpd.conf) ### httpd Headers ``` header set "X-Content-Type-Options" "nosniff" always header set "X-Frame-Options" "DENY" always header block "User-Agent" "*GPTBot*" 403 header block "User-Agent" "*ClaudeBot*" 403 header drop "User-Agent" "*WPScan*" ``` **New in 8\.0:**httpd sets its own headers, no relayd needed for that\. Read:[httpd\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/httpd.conf) ``` dmesg | egrep '(VMX/EPT|SVM/RVI)' fw_update rcctl enable vmd rcctl start vmd vmctl create -s 20G disk.qcow2 vmctl start -m 1G -p 2 -L -i 1 -r install80.iso -d disk.qcow2 myvm vmctl show vmctl console myvm vmctl stop myvm ``` **New in 8\.0:**up to 64 VCPUs per VM with`\-p`\(default: 1\)\. Read:[vmm\(4\)](https://man.openbsd.org/OpenBSD-8.0/amd64/vmm),[vmd\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/vmd),[vmctl\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/vmctl),[vm\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/vm.conf) ### Updating OpenBSD \(\-stable\) Any security or reliability fixes can be found at: [openbsd\.org/errata\.html](https://www.openbsd.org/errata.html) Errata patches are generated for the last two releases \([7\.9](https://www.openbsd.org/errata79.html),[8\.0](https://www.openbsd.org/errata80.html)\)\. ### Tools for Updating \(\-stable\) Use[syspatch\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/syspatch)to update your kernel and userland\. Binary patches are generated for the last two releases only, on amd64, arm64 and i386\. And`pkg\_add \-u`to update packages\. ### List Obsolete Files [sysclean](https://codeberg.org/semarie/sysclean)only lists\. It removes nothing\. Review the output, then delete what you no longer need\. Read:[newfs\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/newfs),[hier\(7\)](https://man.openbsd.org/OpenBSD-8.0/amd64/hier) ### Key Directories DirectoryDescription/Root directory/homeUser home directories/rootDefault home directory for the superuser/mntA temporary mount point/etcSystem configuration files and scripts/etc/examplesExample configuration files for base system daemons/etc/skel\(dot\) files for new accounts/etc/signifyKey files used for[signify\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/signify)/tmpCleaned after a reboot/var/tmpSymbolic link to the system /tmp/var/logLog files/var/runpid, socket files, utmp, dmesg\.boot/var/dbDatabase files/var/wwwchroot directory for[httpd\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/httpd)/var/www/htdocsWeb repository for[httpd\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/httpd)/usr/localThird\-party software goes here/usr/srcBSD and/or local source files FileRole/bsdThe kernel itself, loaded into memory at boot\. At each boot, KARL \(Kernel Address Randomized Link\) relinks a new /bsd in random order for the next boot, so every boot runs a unique kernel\./obsdPrevious kernel, saved when you build and install a kernel yourself \([release\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/release)\)\. If the new kernel fails to boot, start the previous one from the[boot\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/boot)prompt with`boot /obsd`\./bsd\.spKernel executable for single processor machines\./bsd\.mpKernel executable for multiprocessor machines\./bsd\.rdInstallation kernel\. Its built\-in RAM disk holds tools that run without an external file system, so it is useful for system maintenance too\. On a multiprocessor machine, the[installer](https://cvsweb.openbsd.org/log/src/distrib/miniroot/install.sub)renames /bsd to /bsd\.sp, then /bsd\.mp to /bsd\. ### Kernel Troubleshooting [config\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/config)can enable, disable or change devices in a kernel binary, with no recompile\. The same editor is available at boot: type`boot \-c`at the prompt, see[boot\_config\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/boot_config)\. **Caution:**These edits are lost on upgrade and block kernel relinking\. Keep them in[bsd\.re\-config\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/bsd.re-config)instead\. ### Laptop Lid Action \(sysctl\) `machdep\.lidaction=0`do nothing`machdep\.lidaction=1`suspend \(deep sleep\)`machdep\.lidaction=2`hibernate \(memory saved to swap, then power off\) Make it permanent in`/etc/sysctl\.conf`, see`/etc/examples/sysctl\.conf`for more`machdep`variables\. Read:[acpibtn\(4\)](https://man.openbsd.org/OpenBSD-8.0/amd64/acpibtn),[sysctl\.conf\(5\)](https://man.openbsd.org/OpenBSD-8.0/amd64/sysctl.conf),[sysctl\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/sysctl) ### System Maintenance CommandDescription`doas pkg\_check \-F`Checks that there are no other random objects under /usr/local`doas dmesg \-s`Review[rc\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/rc)system startup messages`ldd foobar`List dynamic object dependencies`df \-h`See disk usage`top \-s \.1`Check load \(cpu/mem\)`reset`Reset your terminal when it gets messed up by control sequences`rcctl ls on`What is enabled on your system`doas rcctl ls started`What is running on your system Read:[pkg\_check\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/pkg_check),[dmesg\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/dmesg),[ldd\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/ldd),[ld\.so\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/ld.so.1),[df\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/df),[top\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/top),[reset\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/reset),[rcctl\(8\)](https://man.openbsd.org/OpenBSD-8.0/amd64/rcctl) ### ktrace/kdump Sample Usage `ktrace \-f ping\.out \\ ping \-c 3 openbsd\.org`trace the process`kdump \-f ping\.out`interprets the data from ktrace into a human readable format Read:[ktrace\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/ktrace),[kdump\(1\)](https://man.openbsd.org/OpenBSD-8.0/amd64/kdump) PackagePurpose`screenfetch`Display system information in the terminal`w3m`Text\-based web browser`noice`Minimalistic file browser`pstree`List processes as a tree`testdisk`Scan and repair disk partitions Install any of them with`pkg\_add`, for example`pkg\_add w3m`\. It's time to create your own OpenBSD VM\! Join us on[Telegram\!](https://t.me/+Pk9Rmx6VrF05ZjU8) \(Nice people, I promise\.\)