Setting Up OpenBSD
Mar 12 2023
Once I got OpenBSD installed I wanted to quickly get a working setup and then spend time learning the system. I initially followed a blog post I found on the internet. The post suggested using Unicode encoding everywhere by setting the locale to LANG=en_US.UTF-8 in your ~/.xsession file. Shortly thereafter I was getting warnings about font conversion
Warning: Missing charset in String to FontSet conversion
when running X programs from the terminal to try out different program options. Internet searches pointed to a problem with locale settings. Reading the locale man page provided the solution. OpenBSD does not support UTF-8 encoding everywhere and in fact ignores locale variables other than the one for character encoding LC_CTYPE. The default encoding for locale is C as in LC_CTYPE=C which selects the US-ASCII character set. As an alternate one can opt for UTF-8 encoding with
export LC_CTYPE=en_US.UTF-8
in the ~/.xsession file. Again users should be aware that Unicode character encoding is not fully supported by all parts of the system. I deleted the locale setting from my ~/.xsession file.
In anticipation of learning to write shell scripts, I created a bin directory in my home folder. My initial test scripts required the full path to the file to be executed. I need to add ~/bin to my path. OpenBSD's installation created two files in my home directory, ~/.login and ~/.profile, that looked like likely candidates. The ~/.login file I could not understand, however the ~/.profile file did set a PATH variable. I added $HOME/bin to the list, so ~/bin should now be in my path.
The next recommendation in the post was to export an ENV variable for ~/.kshrc. I created the ~/.kshrc file and searched for more information about it. There is no man page for ~/.kshrc so I started reading the man page for ksh where I learned about the ~/.profile and ~/.kshrc files relationship. The man page states that the ~/.profile file is used for set up of the login shell and ~/.kshrc is used to set up interactive shells. Interactive shells will use ~/.kshrc if the $ENV variable is set by adding the line
export ENV=$HOME/.kshrc
to ~/.profile. Then ~/.kshrc will be processed for every shell started thereafter. The post exported it in the ~/.xsession file, but I chose to use ~/.profile as indicated in the man page.
The $ENV variable should now be set and ~/bin should show up in my path.
Following along with the blog post I created an ~/.Xresources file in order to change how X programs appear. After creating the file and adding some of the suggested resource definitions, I added
xrdb -merge $HOME/.Xresources
to the ~/.xsession file to merge my changes into the X Resource database as per the post instructions.
Time to reboot.
The X resource settings were working so ~/.Xresources had been read; however, the $ENV variable was not set and ~/bin did not show up in my path. Clearly ~/.profile was not being read when the Window Manager starts, even though I thought it should be. I added the line
. $HOME/.profile
to the top of my ~/.xsession file to source (read) it when X starts up. I rebooted. Now $ENV was set and ~/bin showed up in my path but it was a puzzle as to why ~/.profile was not being read without being sourced.
I have an OpenBSD virtual machine on another computer on which I had tested using ~/.profile to export $ENV and add $HOME/bin to the PATH list. It was not modified by merging the ~/.Xresources settings from the blog post. It does set $ENV and include ~/bin in my path. Seems like merging resources with xrdb is somehow causing a problem. I removed the line sourcing $HOME/.profile from my ~/.xsession file to look into xrdb.
The xrdb man page FILES section states that xrdb is used by many Desktop Environments to initialize the resource database when starting a session and also that ~/.Xresources is a generalized replacement for ~/.Xdefaults[1] files. I commented out the xrbd line in my ~./xession file and renamed ~/.Xresources to ~/.Xresources.old. When I rebooted my resource settings were not applied but $ENV was set and ~/bin was included in my path. I added some X resource settings to the ~/.Xdefaults file and rebooted. Now I have X resource settings from ~/.Xdefaults applied as well as $ENV set and ~/bin added to my path from ~/.profile. Interesting, to say the least.
I found this SuperUser article and learned that ~/.Xresources is the newer way of setting resources for X. If it exists it is usually loaded automatically with xrdb to set the RESOURCE_MANAGER property for the X root window when X starts a session. The article helped clear things up with a description from the Xlib - C Language X Interface documentation that states if no RESOURCE_MANAGER property is set for the root window of screen zero then $HOME/.Xdefaults is used for resource database setting. Once xrdb has been called, and the property is set, ~/.Xdefaults will no longer be read. So having an ~/.Xresources file will prevent ~/.Xdefaults from being read when X starts a session.
How do I load X resource settings while keeping $ENV set and ~/bin in my path? Do I add X resource settings to ~/.Xdefaults and keep ~./profile as is? Do I use an ~/.Xresources file and set $ENV and add ~/bin to my path using ~/xession? Is either method any better than the other?
At this point I decided to use ~/.profile to export $ENV because it is in the ksh man page and it includes ~/bin in my path. All X resource settings were in the ~/.Xdefaults file.
After using this set up for a while I noticed that xidle would not start up and call xlock once the interval set by timeout had passed as specified in ~/.Xdefaults. The corner of the screen I had specified for starting xidle was also not respected and was set to the default. Applications (xterm and xclock) started with ~/.xsession would pick up resource settings defined in ~/.Xdefaults, however any other X app started after the Window Manager loaded the desktop would have the system default settings applied. Starting more instances of xterm or xclock would have X resources set as defined in ~/.Xdefaults file. I don't think this means they were read from the ~/.Xdefaults file though.
Next I decided to delete X resource settings from ~/.Xdefaults and use an ~/.Xresources file merged from ~/.Xdefaults with xrdb. This did not work; no X resources from the ~/.Xresources file were set, instead the system defaults were active.
So now I only had one choice. I reset the ~/.Xdefaults and ~/.profile files back to their default contents. All X resource settings were now in ~/.Xresources. I edited ~./xsession to export ENV, PATH and merged the ~/.Xresources file with xrdb, then I rebooted.
Anticipating that all things would work as expected, I entered my username and password in xenodm and hit enter. I'm taken right back to xenodm for login. After several attempts it is clear I have somehow created an X exit/restart loop. I suspect the problem is with the ~/.xsession file because it is the one I edited to add lines. Now what? How will I get back into the system to figure out what is wrong?
Grabbing another computer I did a search at the OpenBSD online man pages. Entering boot in the search box and clicking the apropos button gave me a list of man pages to read through. The man page boot(8) for amd64 mentions the - s boot option to boot into single user mode. This looks like the most likely way to proceed, I expect that single user mode is a root shell, but I'm not sure what kind of environment is available.
Searching for openbsd single user boot mode at the lite version of DuckDuckGo turns up this brief excerpt from the Absolute OpenBSD book. It was to brief to be helpful. Further down in the search results was a link to Chapter 6 of some OpenBSD book[2] at nostarch.com. This pdf file points me in the right direction. At the boot prompt enter - s and press enter to have a minimal system up and running as root. I followed the advice to run fsck -p before proceeding to make sure file systems are ok after my hard reboot and everything checked out alright. Now I use mount -a to mount all file systems. Next I run rcctl disable xenodm that I remembered from the OpenBSD FAQ The X Window System section about Starting X and rebooted. This presents me with the text console login screen so that I can enter my login info and get into the system. I open the ~/.xsession file and sure enough I made a typo spelling ~/.Xresources as ~/.Xrsources. After fixing the typo, I rebooted again.
Everything works, finally!!! I have ~/bin in my path, ENV is set, and X resources are loaded as defined.
The ksh man page mentioned the global configuration file at /etc/ksh.kshrc that could be sourced by adding
. /etc/ksh.kshrc
to the the ~/.kshrc file. After reading the file I did not think that I needed everything contained in it. However I did like the idea of changing the default prompt and creating some useful aliases. I read further down the ksh man page to learn how to set my prompt to my username and current working directory. I also copied some of the aliases; more aliases can be created when I learn the ones I will use often.
1. I have not found any information as to why OpenBSD installs an ~/.Xdefaults file for a user. In the default install it only contains one line that sets the resource
XTerm*loginShell:true
so it probably exists to make sure that when X is initially started without a display manager it provides a login shell.
2. This Chapter 6 pdf turns out to be from the same Absolute OpenBSD book briefly presented at the previous link. The Absolute OpenBSD book can be found at this link although only Chapter 8 is linked as a pdf. Chapter 6 on this page is also named differently so the Chapter 6 pdf link must be from another edition. Since this is the 2nd Edition it could be from the 1st.