[ home ]
5th April 2024: OpenBSD 7.5 has been released. I worked through all the steps in this page using a fresh install.
Follow the steps in this page to install OpenBSD 7.5 and
configure an xfce desktop and Firefox on a Thinkpad
T61 laptop (intel graphics, 500Gb mechanical hard drive and 4Gb RAM)
with legacy BIOS enabled.
I used the
amd64
version of the install.img
image.
It is
best to avoid laptops with
nVidia based graphics with OpenBSD.
Each section of this guide links to the appropriate section of the OpenBSD FAQ and the
relevant man
pages.
I hope that the resulting tour around the documentation will
help you to explore OpenBSD in more detail on your own.
Remember to read
man
afterboot
before working through the later steps.
I'm assuming that you have installed a Linux distribution before and are familiar with the command line. You will need to edit configuration files in some of the steps. I'm also assuming that you can dedicate a laptop solely to OpenBSD. I use old 'refurbished' Thinkpads which are cheap to buy in the UK.
Check that your laptop's video adapter and WiFi card are supported in the the Pre-Installation Checklist.
My Thinkpad T61 has supported video but needs firmware for the WiFi card.
Use dd
on linux to write install.img
to a
USB stick.
Before starting the installation you need to think up
foo
in the examples below.Then
You need to select non-default options at four stages in the installation...
xenodm
sd1
)Reboot into the graphical log-in screen and type your username and password.
Prepare to visit 2001!
man fvwm
man fvwm
man xterm
/VT Fonts.
How to make the xterm
fonts largerThe OpenBSD base includes an ancient version of fvwm
as the default window manager.
You can do most of the rest of the configuration from here.
You should see an xterm
window at the top
left of the screen with the foo $
prompt and possibly very small fonts.
The following steps might help
fvwm
the focus follows the mouse so put the
mouse pointer over the xterm
window and see
how the colour of the frame changesCtrl
-right-click with the mouse to
bring up the VT Fonts
menuHuge
works for me
but if you have a high res screen you might need
Enormous
xset b off
to silence the bleep
if requiredNow would be a good time to read the system mail and
man afterboot
foo$ mail
foo$ man afterboot
You will need to create and edit a small number of configuration files.
OpenBSD comes with three command line editors (ed
,
mg
and vi
) and one graphical editor (xedit
).
I find the emacs-like mg
to be the easiest to just use.
The following default keyboard shortcuts will get you going
C-g
keyboard-quit i.e. cancel the last command
I typed when I make a mistakeC-x C-f
find-file 'filename' i.e. either create a new file
or edit an existing fileC-x C-s
save-buffer i.e. save the changes you made
since the last save to the file that you are editingC-x C-c
save-buffers-kill-emacs i.e. save and quitThe ifconfig
command provides networking from the command line including bringing up interfaces.
OpenBSD interfaces are named after the driver in use and my T61 has one
ethernet card that uses the em
driver,
so ifconfig
sees that card as the em0
interface.
foo$ su -
Password:
foo# ifconfig em0
em0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
lladdr 54:ee:75:1a:a5:b2
index 1 priority 0 llprio 3
media: Ethernet autoselect (none)
status: no carrier
To start the interface and request an IP address type...
foo# ifconfig em0 up
foo# ifconfig em0 inet autoconf
I like to use ping
to check the connection...
foo# ping bbc.co.uk
ping: Warning: bbc.co.uk has multiple addresses; using 151.101.192.81
PING bbc.co.uk (151.101.192.81): 56 data bytes
64 bytes from 151.101.192.81: icmp_seq=0 ttl=55 time=52.276 ms
man fw_update
man syspatch
You can install the firmware.
Become root (I always use su -
so I have a login session)
and use the fw_firmware
command...
foo$ su -
password
foo# fw_update
fw_update: added intel,inteldrm,wpi; updated none; kept none
The wpi
package contains the firmware that the
Thinkpad T61 WiFi card needs.
Next use syspatch
to update the OpenBSD base.
The example below is from OpenBSD 7.2.
foo# syspatch
Get/Verify syspatch72-001_x509.tgz 100% |***************| 14494 KB 00:07
...
Get/Verify syspatch72-012_acme.tgz 100% |***************| 40197 00:00
Installing patch 012_acme
Relinking to create unique kernel... done; reboot to load the new kernel
Errata can be reviewed under /var/syspatch
Then you can reboot to use the new kernel...
foo# reboot
man hostname.if
man ifconfig
/WIRELESS_DEVICES)This old Thinkpad T61 has an intel wifi card that uses the
wpi
driver.
For my home network with wpa2 authentication I used echo
to
populate /etc/hostname.wpi0
as follows...
foo# echo "join mywifi wpakey mypassword" >> /etc/hostname.wpi0 foo# echo "inet autoconf" >> /etc/hostname.wpi0 foo# echo "inet6 autoconf" >> /etc/hostname.wpi0
I enable both ip4 and ip6 on my home connection, it does not seem to make a lot of difference.
To connect to a coffee shop WiFi from the command line I used the following commands...
foo# ifconfig wpi0 join cafe [wpakey key-if-there-is-one] foo# ifconfig wpi0 inet autoconf
The OpenBSD base is released as a single coherent operating system. It includes very little desktop application software. You can use binary packages provided or ported by volunteers to install extra software.
The example below shows how to install w3m
the text mode Web browser
foo# pkg_add w3m quirks-7.14 signed on 2024-04-06T12:55:16Z Ambiguous: choose package for w3m a 0:1: w3m-0.5.3pl20230121p1 2: w3m-0.5.3pl20230121p1-image Your choice: 1 w3m-0.5.3pl20230121p1:boehm-gc-8.2.4: ok w3m-0.5.3pl20230121p1: ok foo#
Two points to note...
w3m
with different compilation options.
I went for the version without image support.quirks
package is installed every time you use
pkg_add
.
The package is needed by pkg_add
. quirks-7.14
is the version for OpenBSD 7.5You can find out about any package using the pkg_info
command.
See the FAQ and man page.
man apmd
man rcctl
obsdfreqd
packageman obsdfreqd
when the package has been installedOpenBSD uses the apmd
daemon to provide automatic frequency scaling to save battery and reduce processor temperatures. From OpenBSD 7.1 the behaviour of the automatic (apmd -A
) setting when on mains power has changed. You install the obsdfreqd
package to provide fan and cpu speed control instead.
Daemons are enabled, started and stopped using the rcctl
command as root.
The command writes lines to the /etc/rc.conf.local
file.
Install obsdfreqd
from packages...
foo# pkg_add obsdfreqd quirks-6.121 signed on 2023-03-26T10:10:23Z obsdfreqd-1.1.1: ok The following new rcscripts were installed: /etc/rc.d/obsdfreqd See rcctl(8) for details. foo#
Enable and start apmd
and obsdfreqd
as root...
foo# rcctl set ampd status on foo# rcctl set apmd flags -L foo# rcctl start apmd apmd(ok) foo# rcctl enable obsdfreqd foo# rcctl start obsdfreqd obsdfreqd(ok) foo#
You can suspend to RAM using the zzz
command.
Some laptops will suspend when you close the lid and resume when you
open the lid.
man doas.conf
. The doas
command replaces the sudo
command and allows you to run commands as root from an ordinary user account.man mount
man ntfs-3g
when installed from package ntfs_3g
man dmesg
External drives are numbered sd1
, sd2
instead of the familiar sdb
, sdc
in Linux. Letters are used to show partitions so a USB stick that is seen as sdb1
on Linux would be sd1i
on OpenBSD.
To check the drive number for an external drive, plug it in and then run dmesg
or dmesg | tail
and look for a drive number in the last few lines.
OpenBSD does not provide automounting of external storage. Instead you can use the mount
and umount
commands as root. Support for ntfs
drives (most external hard drives) is provided by installing the ntfs_3g
package. The ntfs-3g
command is run in place of mount
when using an ntfs
drive.
You can run these commands as an ordinary user by setting up a /etc/doas.conf
file.
First install ntfs_3g
package as root...
foo# pkg_add ntfs_3g quirks-7.14 signed on 2024-04-06T12:55:16Z ntfs_3g-2022.10.3:e2fsprogs-1.46.2p1: ok ntfs_3g-2022.10.3: ok foo#
Then as root create /etc/doas.conf
as below...
foo# mg /etc/doas.conf
Add the following lines where USER
is your user name
permit nopass USER as root cmd mount
permit nopass USER as root cmd umount
permit nopass USER as root cmd ntfs-3g
To mount an external USB stick you have to
usb
)doas mount
command to mount the usb stick to that directoryTo find the disk label I just use dmesg
...
foo$ dmesg | grep sd1
sd1 at scsibus4 targ 1 lun 0: <Kingston, DataTraveler 2.0, 1.00> removable serial.loadsanumbers
sd1: 3852MB, 512 bytes/sector, 7888896 sectors
foo$
Then to actually mount the drive...
foo$ mkdir usb
foo$ doas mount /dev/sd1i ~/usb
foo$ ls usb
daffs.jpg
daffs.png
gcse-rules-and-tools-20130829.odt
music_for_programming_61-linnley.mp3
Once mounted you can use file commands such as cp
and ls
as usual or run a graphical file manager
like thunar
.
When you have finished with the drive you can unmount the drive using...
foo$ doas umount ~/usb
foo$ ls usb
foo$
Mounting an external ntfs
formatted hard drive works the same way but using the ntfs-3g
command in place of mount
...
foo$ doas ntfs-3g /dev/sd1i ~/wd
foo$ ls wd
Backup_T61 software music
foo$ doas umount ~/wd
foo$ ls wd
foo$
Once xfce is installed you can use the xfce-mount
panel applet within xfce to access these commands with the mouse. See later.
man usermod
pkgreadme
for xfce4 (see later)
man shutdown
You could add lines to /etc/doas.conf
to allow you to shutdown from your normal user account.
But you can also add your user account to the _shutdown
group.
The _shutdown
group is a recent innovation. Previously, you
would add your user to the operator
group.
Using group permissions in this way has the advantage that xfce
can then be shutdown or
rebooted using the Applications menu.
foo# usermod -G _shutdown username
foo# groups username
username wheel _shutdown
You have to restart a login session to see the new group membership...
$ su - user password: $ groups user wheel _shutdown
Then you can shutdown using...
foo$ shutdown -ph now
Or reboot using
foo$ reboot
OpenBSD imposes a maximum memory limit on each program.
The size of that limit depends on your user account login class.
By default your user account has the staff
login
class
First check that your user has the staff login class using
the vipw
command.
This command will allow you to edit the passwd.master file.
This file is very carefully protected and so you have to edit
the file using the vipw
command,
which invokes the vi editor.
foo# vipw
Scroll down the file untill you reach your username, or use the
vi
search /username
to jump to that line.
The line should look something like this...
myuser:BIG LONG STRING HASH:1000:1000:staff:0:0:myuser:/home/myuser:/bin/ksh
As you can see myuser
is in the staff login class
by default.
If there is a different class name there you can change the login
class by placing the cursor on the first character of whatever the word is using
the arrows, and then pressing cw
(change word).
Then type 'staff' and press ESC.
Finally save changes by SHIFT-: and typing x.
Then you can edit the /etc/login.conf
file so that the
staff
stanza looks like this...
#
# Staff have fewer restrictions and can login even when nologins are set.
#
staff:\
:datasize-cur=3072M:\
:datasize-max=infinity:\
:maxproc-max=512:\
:maxproc-cur=256:\
:ignorenologin:\
:requirehome@:\
:tc=default:
...
This Thinkpad T61 has 4Gb of RAM.
I chose 3072
Mb as the limit more or less at random.
Web browsers are notoriously demanding of memory.
OpenBSD is quite strict about the behaviour of programs.
Applications sometimes crash and leave a core file in the user's home
named something like appname.core
.
You can just delete these core files.
/etc/X11/xenodm/Xsetup_0
to stop the beep and xconsole
OpenBSD's fork of Xorg
is called xenocara
.
The graphical login screen is provided by xenodm
, a fork of
xdm
. By default a new X session loads the
Xconsole
. The beeps can get annoying as well. Edit the file
/etc/X11/xenodm/Xsetup_0
as follows to restore order...
foo# mg /etc/X11/xenodm/Xsetup_0
Comment out the line (line 9 on my version) that reads
${exec_prefix}/bin/xconsole -geometry 480x130-0-0...
by putting a #
in front. Then add the line to switch off the bell...
${exec_prefix}/bin/xset b off
then save.
You could install Firefox, Chromium (or Iridium) and (say) xpdf
as the system stands and have basic functionality with fvwm
.
You can install the Gnome, Xfce or KDE desktop environment, or a lighter desktop such as LXQt or Lumina. I use Xfce as it is familiar to me and allows graphical management of external USB sticks using the xfce4-mount
panel applet.
The port maintainer for a larger package often puts useful information in a pkg-readme
. You can get a list of them as follows...
foo$ ls /usr/local/share/doc/pkg-readmes
For example, the Firefox pkg-readme
shows that Firefox
now has pledge
and unveil
support. That means that Firefox can only save or load files to
one directory at ~/Downloads
. There are instructions for
changing this behaviour.
First install Firefox and xpdf
foo# pkg_add firefox xpdf lohit-fonts-2.5.3p2 zh-fonts-arphicttf-2.11p4.tgz
This will take some time as Firefox has a lot of dependencies.
In OpenBSD 7.5 you will be given a choice of xpdf3
or xpdf
version 4. I prefer the old motif based xpdf3 personally but the more recent version
using GTK3 has more UI features. The two font packages provide Asian and Indian continent fonts to avoid those square place holders in Web pages.
Installing a full Xfce desktop requires a few steps
xfce4-power-manager
and upower
if you want power management from within Xfce (screen blanking, battery information and so on)~/.xsession
file in your user's home directory so Xfce starts instead of fvwm
First install the all the packages. This will take some time because of the dependencies. Then skim the pkg-readme
for Xfce...
foo# pkg_add xfce xfce-extras xfce4-power-manager upower
foo# less /usr/local/share/doc/pkg-readmes/xfce
Then make a file at ~/.xsession
like this
foo$ cat ~/.xsession
~/.profile
/usr/local/bin/startxfce4
Now you can exit from .fvwm
and login to a 'first run' Xfce session.
You could then reboot using the Xfce Application menu logout buttons as a test.
xfce4-mount
panel applet to mount and unmount external drivesYou need to configure the panel plugin as follows...
Add an icon for the plugin to the XFCE4 panel by right-clicking on the panel and selecting Panel | Add New Items and searching for mount.
Right click over the xfce4-mount icon and select Properties | File Systems tab. Add the pattern /dev/sd0*
to the Exclude specified file systems textbox so the local drive is not listed.
Right-click on the xfce4-mount icon, and select Preferences | Commands and write the following in the Custom Commands textboxes, after ensuring that the Custom Commands checkbox was ticked
doas mount %m
doas umount %m
Now to ensure that a USB stick is listed in the xfce4-mount-popup list, you have to add a line for the device to /etc/fstab
...
foo# echo "/dev/sd1i /home/keith/usb msdos rw,noauto 0 0" >> /etc/fstab
Using an fstab entry like this means that only one vfat formatted USB thumb drive will be listed and available with mouse clicks.
See OpenBSD FAQ - Disk Setup - Full Disk Encryption for background detail.
Since OpenBSD 7.4 the installer has offered the option of setting up an encrypted 'soft raid' partition to hold the operating system, user data and swap.
Disk numbering: The hard drive I am installing to is recognised as
sd0
, the USB stick with the installation sets is
recognised as sd1
and the installer creates a softraid
device as sd2
. After rebooting into the new installation
the softraid device is renumbered as sd1
.
Below is a sample dialogue of an installation using
an encrypted hard drive unlocked with a pass phrase.
Starting from the disk section of the installer dialogue.
My choices are in BLOCK CAPS
after each prompt.
Available disks are: sd0, sd1, sd2 Which disk is root disk? [sd0] RETURN TO ACCEPT DEFAULT Encrypt the root disk with a (p)assphrase or (k)eydisk? p RETURN (W)hole disk MBR, whole disk (G)PT, (O)penBSD area or (E)dit? w RETURN New passphrase: MY PASS PHRASE RETURN Retype passphrase: MY PASS PHRASE RETURN Use (w)hole disk MBR, whole disk (G)PT, or (E)dit? [whole] RETURN
Then I continued with the normal autoformat which results in a number of partitions in the disklabel with default sizes.
This page has been improved by feedback from people who have used it to install and explore OpenBSD. Suggestions and experiences welcome.
_shutdown
group.
Man page links lead to current
man pages at the time of writing
as the 7.5 release pages are not yet available.
pkg_add
sample dialogues with quirks-121
.
Changed the links to FAQ and man pages.
Re-wrote the section on encrypted hard drive and positioned it as an
alternative Install section near the top of the page.[ 5.5 | 6.2 | 6.3 | 6.4 | 6.5 | 6.6 | 6.7 | 6.8 | 7.0 | 7.1 | 7.2 | 7.3]