Set Up Openbox Safely, Then Reload Its Configuration

You break a keybinding editing rc.xml and now need Openbox to reread it without logging out. This walks through 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, the version installed on this machine.

• Time: about fifteen minutes.
• You need: an X session and a shell.
• Safe to run: 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 some 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; what matters 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 originals 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 actually 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, and do not add a command that depends on a graphical service before that service is ready. A malformed autostart file can leave 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, so test the particular behaviour you changed. If the command returns a non-zero status, confirm 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

Common traps

• --restart interrupts window-management state. Save work first and use it only when a reload is insufficient, such as after an upgrade.
• --replace is more disruptive still. It replaces the current window manager. Neither option is a routine syntax check.
• --exit 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.
• Debugging options exist for a reason. --debug, --debug-focus and --debug-session print debugging information, and --sync enables synchronous X operation for debugging.
• Change one file at a time. If a reload breaks something, restore the last known-good file, reload once, and only then investigate. Editing several files at once removes the useful clue about which change caused the fault.