Set Up Openbox Safely, Then Reload Its Configuration

You will finish with a user-level Openbox configuration you can edit, a known-good backup, and a safe way to ask the running window manager to reload it. The examples target Openbox 3.6.1 from Debian package version 3.6.1-12build5, which is the version installed on this machine.

Allow about fifteen minutes. You need an X session and a shell. No command below needs sudo. You will copy files into your home directory, so the changes are reversible and do not alter the system defaults.

1. Confirm the installed command

Start with read-only checks. This prevents a common error: reading documentation for a different window manager while sending options to Openbox.

$ command -v openbox
/usr/bin/openbox
$ openbox --version
Openbox 3.6.1
$ dpkg-query -W -f='${Package} ${Version}\n' openbox
openbox 3.6.1-12build5

The alias x-window-manager points at the same Openbox manpage on this system. The executable itself accepts --help, --version, --replace, --reconfigure, --restart, --exit, --config-file FILE, --sm-disable, --sync, --startup CMD and debugging options.

2. Check whether an Openbox session is active

Openbox needs an X display to act as the window manager. A login session may start it directly, through a display manager, or inside another desktop environment. Check the session variables and the process list without changing anything:

$ printf 'DISPLAY=%s\nXDG_SESSION_TYPE=%s\n' "$DISPLAY" "$XDG_SESSION_TYPE"
DISPLAY=:0
XDG_SESSION_TYPE=x11
$ pgrep -a openbox
1234 /usr/bin/openbox --startup ...

Your display number and process ID will differ. If DISPLAY is empty or pgrep finds nothing, do not test --reconfigure yet. Log into the intended X session first, or use the session entry supplied by your display manager. An SSH shell without X forwarding is not the same thing as the desktop session.

3. Create a private configuration from the packaged defaults

Openbox reads user configuration below ~/.config/openbox/. The package's system defaults are under /etc/xdg/openbox/. Copy the files before editing them, rather than changing files owned by the package:

$ mkdir -p "$HOME/.config/openbox"
$ cp -a /etc/xdg/openbox/rc.xml "$HOME/.config/openbox/rc.xml"
$ cp -a /etc/xdg/openbox/menu.xml "$HOME/.config/openbox/menu.xml"
$ ls -l "$HOME/.config/openbox"
-rw-r--r-- 1 ... menu.xml
-rw-r--r-- 1 ... rc.xml

The exact owner, size and timestamps are host-specific. The important result is that both user files exist. The copied rc.xml controls window behaviour and keyboard shortcuts; menu.xml controls the root-menu entries. Keep the original files until your new configuration has survived a reload.

$ cp -a "$HOME/.config/openbox/rc.xml" "$HOME/.config/openbox/rc.xml.before-change"
$ cp -a "$HOME/.config/openbox/rc.xml.backup" "$HOME/.config/openbox/rc.xml"
cp: cannot stat '/home/you/.config/openbox/rc.xml.backup': No such file or directory

The last command is only a template: replace the backup path with a file that actually exists. Do not paste it unchanged and assume a backup was created.

4. Add startup commands without blocking the session

When openbox-session starts a session without a session manager, it runs ~/.config/openbox/autostart when present, otherwise /etc/xdg/openbox/autostart. The installed package provides the latter as its example. Each long-running command should end with &, otherwise the script waits and later startup commands never run.

Create a small user file only if you need one. Replace the example command with something installed on your machine:

$ install -m 700 /dev/null "$HOME/.config/openbox/autostart"
$ editor "$HOME/.config/openbox/autostart"
# Example line inside the file:
xsetroot -solid grey &

Use your normal editor in place of editor. Do not put secrets in this file: it is a plain-text shell script. Do not add a command that depends on a graphical service before that service is ready. A malformed autostart file can make the next login incomplete.

These startup changes apply to a newly started Openbox session. Reloading rc.xml does not rerun the autostart script.

5. Edit, then reload only the configuration

Make one small change in rc.xml or menu.xml, save it, and ask the existing Openbox process to reread its files:

$ cp -a "$HOME/.config/openbox/rc.xml" "$HOME/.config/openbox/rc.xml.before-reload"
$ editor "$HOME/.config/openbox/rc.xml"
$ openbox --reconfigure
$ printf 'reconfigure exit status: %s\n' "$?"
reconfigure exit status: 0

A zero status means the message was sent successfully. It does not validate every shortcut or menu entry. Test the particular behaviour you changed. If the command returns a non-zero status, confirm that the X display and the running Openbox process belong to the current shell.

$ cp -a "$HOME/.config/openbox/rc.xml.before-reload" "$HOME/.config/openbox/rc.xml"
$ openbox --reconfigure

6. Keep disruptive options for deliberate maintenance

--restart restarts Openbox. It can interrupt window-management state, so save work first and use it only when a reload is insufficient, such as after an upgrade. --replace replaces the current window manager and is more disruptive still. Do not use either option as a routine syntax check.

--exit tells Openbox to quit. That can leave the desktop without a window manager until the session starts another one. Treat it as a recovery or session-management action, not an edit test. If you need diagnostics, --debug, --debug-focus and --debug-session print debugging information, while --sync enables synchronous X operation for debugging.