Openbox

Summary
A comprehensive guide on the installation and use of the Openbox window manager.
Overview
The Xorg project provides a free software implementation of the X Window System – the foundation for a graphical user interface. Desktop environments such as LXQt, Openbox/KDE, Cinnamon, MATE, Xfce, GNOME, Deepin provide a complete graphical environment. Various window managers offer alternative and novel environments, and may be used standalone to conserve system resources. Display managers provide a graphical login prompt.

Openbox is a lightweight and highly configurable window manager with extensive standards support. Its features are documented at the official website. This article pertains to installing Openbox under Parabola.

1 Installation

Install openbox, available in the Official Repositories. After installation, you should copy the default configuration files rc.xml, menu.xml, autostart, and environment to ~/.config/openbox:

Note: Do this as a regular user, not as root.

$ mkdir -p ~/.config/openbox
$ cp /etc/xdg/openbox/{rc.xml,menu.xml,autostart,environment} ~/.config/openbox

These four files form the basis of your openbox configuration. Each file addresses a unique aspect of your configuration and the role of each file is as follows:

rc.xml

This is the main configuration file. It defines keyboard shortcuts, themes, virtual desktops, and more.

menu.xml

This file defines the content of the right-click menu. It defines launchers for applications and other shortcuts. See the #Menus section.

autostart

This file is read by openbox-session at startup. It contains the programs that are run at startup. It is typically used to set environment variables, launch panels/docks, set background image or execute other startup scripts. See the Openbox Wiki.

environment

This file is sourced by openbox-session at startup. It contains environment variables to be set in Openbox's context. Any variables you set here will be visible to Openbox itself and anything you start from its menus.

2 Upgrading to Openbox 3.5

If you are upgrading to Openbox 3.5 or later from an earlier release, be aware of these changes:

• There is a new config file called environment that you should copy from /etc/xdg/openbox to ~/.config/openbox .
• The config file previously called autostart.sh is now just called autostart. You should rename yours to remove the .sh from the end of the name.
• Some of the configuration grammar in rc.xml has changed. While Openbox appears to understand the old options, it would be wise to compare your configuration to the one in /etc/xdg/openbox and look for changes that affect you.

3 Openbox as a stand-alone WM

Openbox can be used as a stand-alone window manager (WM). This is usually simpler to install and configure than using Openbox with desktop environments. Running openbox alone may reduce your system's CPU and memory load.

To run Openbox as a stand-alone window manager, append the following to ~/.xinitrc:

exec openbox-session

You may also start Openbox from the command shell (aka: text prompt) using xinit:

$ xinit /usr/bin/openbox-session

If you used another window manager previously (such as Xfwm) and now Openbox will not start after logging out of X, try moving the autostart folder:

mv ~/.config/autostart ~/.config/autostart-bak

Using Consolekit, use this instead:

exec ck-launch-session openbox-session

If you also use polkit and D-Bus (e.g. for auto-mount drivers in Nautilus/Gnome) use:

exec ck-launch-session dbus-launch openbox-session

Note: pyxdg is required for Openbox's xdg-autostart

Note: "dbus-launch" must be placed after "ck-launch-session" or you will experience mounting problems

4 Openbox/KDE

Openbox can be used as a replacement window manager for full-fledged desktop environments. The method for deploying Openbox depends on the desktop environment. Install packages required for /usr/bin/openbox-kde-session,

sudo pacman -Su --noconfirm --needed openbox obconf-qt 

plasma ark thunar --assume-installed discover

1. If you use SDDM, select the ‘‘KDE/Openbox’’ login option
2. If you use startx, add exec openbox-kde-session to ~/.xinitrc
3. From the shell:

$ xinit /usr/bin/openbox-kde-session

5 Configuration

There are several options for configuring Openbox settings:

5.1 Manual configuration

To configure Openbox manually, edit the ~/.config/openbox/rc.xml file with a text editor. The file has explanatory comments throughout. See the Help:Configuration openbox wiki for more documentation on editing this file.

5.2 ObConf

ObConf is an Openbox configuration tool. It is used to set most common preferences such as themes, virtual desktops, window properties, and desktop margins. It can be installed with pacman:

• For LXQt and Openbox/KDE

$ sudo pacman -Su --noconfirm obconf-qt

• For LXDE (obsolete), written in GTK 2

$ sudo pacman -Su --noconfirm obconf

5.3 Application customization

Openbox allows per-application customizations. This lets you define rules for a given program. For example:

• Start your web browser on a specific virtual desktop.
• Open your terminal program with no window decorations (window chrome).
• Make your bit-torrent client open at a given screen position.

Per-application settings are defined in ~/.config/openbox/rc.xml. Instructions are in the file's comments. More details are found in the Help:Applications openbox wiki.

6 Menus

The default Openbox menu includes a variety of menu items to get you started. Many of these items launch applications you do not want, have not installed yet, or never intend to install. You will surely want to customize menu.xml at some point. There are a number of ways to do so.

6.1 Manual configuration of menus

You can edit ~/.config/openbox/menu.xml with a text editor. Many of the settings are self-explanatory. The article Help:Menus has extensive details.

6.2 Icons in menu

Since version 3.5.0 you can have icons next to your menu entries. To do that :

1. add <showIcons>yes</showIcons> in the <menu> section of the rc.xml file
2. edit the menu entries in menu.xml and add icons="<path>" like this :

<menu id="apps-menu" label="SomeApp" icon="/home/user/.icons/application.png">

then openbox --reconfigure or openbox --restart if you have troubles updating the menu :)

6.3 MenuMaker

MenuMaker creates XML menus for several window managers including Openbox. MenuMaker searchs your computer for executable programs and creates a menu file from the result. It can be configured to exclude certain application types (GNOME, KDE, etc) if you desire.

# pacman -S menumaker    #  Install MenuMaker from the repository

Once installed, generate a menu file (named menu.xml) by running the program.

$ mmaker -v OpenBox3     #  Will not overwrite an existing menu file.
$ mmaker -vf OpenBox3    #  Force option permits overwriting the menu file.
$ mmaker --help          #  See the full set of options for MenuMaker.

MenuMaker creates a comprehensive menu.xml. You may edit this file by hand or regenerate it after installing software.

6.4 Obmenu

Obmenu is a menu editor for Openbox. This GUI application is the best choice for those who dislike editing XML code. Obmenu is available in the community repository:

# pacman -S obmenu

Once installed, run obmenu then add and remove applications as desired.

6.4.1 Obm-xdg

obm-xdg is a command-line tool that comes with Obmenu. It generates a categorized sub-menu of installed GTK/GNOME applications.

To use obm-xdg with other menus, add the following line to ~/.config/openbox/menu.xml:

<menu execute="obm-xdg" id="xdg-menu" label="xdg"/>

Then add the following line under your 'root-menu' entry where you want to have the menu appear:

<menu id="xdg-menu"/>

Then run openbox --reconfigure to refresh the Openbox menu. You should now see a sub-menu labeled xdg in your menu.

To use obm-xdg by itself create ~/.config/openbox/menu.xml and add these lines:

<openbox_menu>
 <menu execute="obm-xdg" id="root-menu" label="apps"/>
</openbox_menu>

Note: If you do not have GNOME installed, you need to install package gnome-menus for obm-xdg.

6.5 Python-based xdg menu script

This script is found in Fedora's Openbox package. You have only to put the script somewhere and create a menu entry.

Here is the head: latest script

Download from above repository. Place the file into the directory you want.

Open menu.xml with your text editor and add the following entry. Of course, you can modify the label as you see fit.

<menu id="apps-menu" label="xdg-menu" execute="python2 <path>/xdg-menu"/>

Save the file and run openbox --reconfigure.

Note: If you do not have GNOME installed, you need to install package gnome-menus for xdg-menu.

7 Startup programs

Openbox supports running programs at startup. This is provided by command openbox-session.

7.1 Enabling autostart

There are two ways to enable autostart:

1. When using startx or xinit to begin a session, edit ~/.xinitrc. Change the line that executes openbox to openbox-session.
2. When using GDM or KDM, selecting an Openbox session automatically runs the autostart script.

7.2 Autostart script

Openbox provides a system-wide startup script which applies to all users and is located at /etc/xdg/openbox/autostart. A user may also create his own startup script to be executed after the system-wide script by creating the file ~/.config/openbox/autostart. This file is not provided by default and must be created by the user.

Further instructions are available in the Help:Autostart article at the official Openbox site.

Note: The autostart files used to be named autostart.sh prior to OpenBox 3.5.0. While these scripts will presently still work, users who are upgrading are advised to drop the .sh extension.

8 Themes and appearance

The supplemental article Openbox Themes and Apps has detailed information about changing Openbox's GUI.

8.1 Openbox themes

Themes control the appearance of windows, titlebars, and buttons. They also control menu appearance and on-screen display (OSD). Additional themes are available from the standard repositories.

# pacman -S openbox-themes

8.2 Cursors, icons, wallpaper

Please see Openbox Themes and Apps for information on these GUI customizations.

9 Recommended programs

The supplemental wiki article Openbox Themes and Apps has information on applications you may use with Openbox.
The article gives details about panels, trays, mixer controls, and other widgets used on a desktop interface.

There is a list of Lightweight Applications in the wiki. Most of these work nicely with Openbox.

10 Tips and tricks

10.1 Copy and paste

From a terminal Ctrl+Insert for copy and Shift+Insert for paste.

Also Ctrl+Shift+C for copy and mouse middle-click for paste (in terminals).

Other applications most likely use the conventional keyboard shortcuts for copy and paste.

10.2 Window transparency

The program transset-df (virtually the same as transset) is installed with pacman -S transset-df. With transset-df you can enable window-transparency on-the-fly.

For instance by placing the following in ~/.config/openbox/rc.xml you can have your mouse adjust window transparency by scrolling while hovering over the title bar (it is in the <mouse> section):

    <context name="Titlebar">
     . . .
     <mousebind button="Up" action="Click">
       <action name= "Execute" >
       <execute>transset-df -p .2 --inc  </execute>
       </action>
     </mousebind>
     <mousebind button="Down" action="Click">
       <action name= "Execute" >
       <execute>transset-df -p .2 --dec </execute>
       </action>
     </mousebind>
     . . .
   </context>

It appears to work only when no additional actions are defined within the action group.

10.3 Xprop values for applications

If you use per-application settings frequently, you might find this bash alias handy:

alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'

To use, run xp and click on the running program that you would like to define with per-app settings. The result displays only the info that Openbox requires, namely the WM_WINDOW_ROLE and WM_CLASS (name and class) values:

[thayer@dublin:~] $ xp
WM_WINDOW_ROLE(STRING) = "roster"
WM_CLASS(STRING) = "gajim.py", "Gajim.py"
WM_CLASS(STRING) = "NAME", "CLASS"

10.3.1 Xprop for Icecat

For whatever reason, Icecat and like-minded equivalents ignore application rules (e.g. <desktop>) unless class="Icecat*" is used. This applies irrespective of whatever values xprop may report for the program's WM_CLASS.

10.4 Urxvt in the background

With Openbox, running a terminal as desktop background is easy. You will not need devilspie here.

First you must enable transparency, open your .Xdefaults file (if it does not exist yet, create it in your home folder).

URxvt*transparent:true
URxvt*scrollBar:false
URxvt*geometry:124x24    #I do not use the whole screen, if you want a full screen term do not bother with this and see below.
URxvt*borderLess:true
URxvt*foreground:Black   #Font color. My wallpaper is White, you may wish to change this to White.

Then edit your .config/openbox/rc.xml file:

<application name="URxvt">
  <decor>no</decor>
  <focus>yes</focus>
  <position>
    <x>center</x>
    <y>20</y>
  </position>
  <layer>below</layer>
  <desktop>all</desktop>
  <maximized>true</maximized> #Only if you want a full size terminal.
</application>

The magic comes from the <layer>below</layer> line, which place the application under all others. Here Urxvt is displayed on all desktops, change it to your convenience.

Note: Instead of using <application name="URxvt">, you can use another name ("URxvt-bg" for example), and use the -name option when starting uxrvt. That way, only the urxvt terminals which you choose to name URxvt-bg would be captured and modified by the application rule in rc.xml. For example: urxvt -name URxvt-bg (case sensitive)

10.5 Keyboard volume control

10.5.1 ALSA

If you use ALSA for sound, you can use the amixer program to adjust the volume of sound. You can use Openbox's keybindings to act like multimedia keys. (Alternatively, you can probably find out the names of your real multimedia keys and map them.) For example, in the <keyboard> section of rc.xml:

   <keybind key="W-Up">
     <action name="Execute">
       <command>amixer set Master 5%+</command>
     </action>
   </keybind>

This binds Windows key + Up arrow to increase your master ALSA volume by 5%. Corresponding binding for volume down:

   <keybind key="W-Down">
     <action name="Execute">
       <command>amixer set Master 5%-</command>
     </action>
   </keybind>

As another example you can also use the XF86Audio keybindings:

   <keybind key="XF86AudioRaiseVolume">
     <action name="Execute">
       <command>amixer set Master 5%+ unmute</command>
     </action>
   </keybind>
   <keybind key="XF86AudioLowerVolume">
     <action name="Execute">
       <command>amixer set Master 5%- unmute</command>
     </action>
   </keybind>
   <keybind key="XF86AudioMute">
     <action name="Execute">
       <command>amixer set Master toggle</command>
     </action>
   </keybind>

The above example should work for the majority of multimedia keyboards. It should enable to raise, lower and mute the Master control of your audio device by using the respective multimedia keyboard keys. Notice also that in this example:

• The "Mute" key should unmute the Master control if it is already in mute mode.
• The "Raise" and "Lower" keys should unmute the Master control if it is in mute mode.

10.5.2 Pulseaudio

If you are using pulseaudio with ALSA as a backend the above keybinding are slightly different as amixer must be told to use pulse.

  <keybind key="XF86AudioRaiseVolume">
     <action name="Execute">
       <command>amixer -D pulse set Master 5%+ unmute</command>
     </action>
   </keybind>
   <keybind key="XF86AudioLowerVolume">
     <action name="Execute">
       <command>amixer -D pulse set Master 5%- unmute</command>
     </action>
   </keybind>
   <keybind key="XF86AudioMute">
     <action name="Execute">
       <command>amixer set Master toggle</command>
     </action>
   </keybind>

This keybindings should work for most of the systems. Other examples can be found here.

11 Troubleshooting Openbox 3.5

11.1 X server crashes

Problems have been detected after upgrade to ver. 3.5, that the X server might crash in attempt to start openbox, ending with similar error message:

(metacity:25137): GLib-WARNING **: In call to g_spawn_sync(), exit status of a child process \
                   was requested but SIGCHLD action was set to SIG_IGN and ECHILD was received by waitpid(), so exit \
                   status can't be returned. This is a bug in the program calling g_spawn_sync(); either do not request \
                   the exit status, or do not set the SIGCHLD action.
xinit: connection to X server lost
waiting for X server to shut down

In this particular case, some problem with metacity package has been identified as the cause of the X server crash issue. Removal of metacity & compiz-decorator-gtk packages solved the problem. Though, later was found, that even a simple reinstall of packages might have helped, as there is no problem after new installation of previously removed packages.

Also, plenty of similar cases have been found on the Internet, that not only metacity package might be causing the X server to crash. Thus, whatever else instead of metacity you get in the error output message, try to reinstall it (or remove if necessary) in an attempt to get rid of this X server crash.

11.2 Autostarting unwanted applications in 3.5

Unwanted applications do start with your Openbox session, though they are not listed in your ~/.config/openbox/autostart script?

Check the ~/.config/autostart/ directory, it might contain the residues from your previously used desktop environment (Gnome, KDE, etc.), and remove unwanted files.

11.3 SSH agent no longer starting

Whereas Openbox 3.4.x allowed launching an SSH agent from $XDG_CONFIG_HOME/openbox/autostart{,.sh}, with 3.5 that no longer seems to work. You need to put your code in $XDG_CONFIG_HOME/openbox/environment, e.g.:

SSHAGENT="/usr/bin/ssh-agent"
SSHAGENTARGS="-s"
if [ -z "$SSH_AUTH_SOCK" -a -x "$SSHAGENT" ]; then
        eval `$SSHAGENT $SSHAGENTARGS`
        trap "kill $SSH_AGENT_PID" 0
fi

11.4 Openbox not registering with D-Bus

Just like with SSH agent, lots of people used to have D-Bus code in $XDG_CONFIG_HOME/openbox/autostart{,.sh} - which no longer works (e.g. Thunar does not see any removable devices anymore).

The fix is to move the code to $XDG_CONFIG_HOME/openbox/environment:

if which dbus-launch >/dev/null && test -z "$DBUS_SESSION_BUS_ADDRESS"; then
       eval `dbus-launch --sh-syntax --exit-with-session`
fi

Alternatively you can call openbox-session with dbus-launch in e.g. ~/.xinitrc.

12 Resources

• Openbox Website – The official website
• Planet Openbox – Openbox news portal
• Box-Look.org – A good resource for themes and related artwork
• Installation and configuration tutorial Using gnome3 with Openbox

13 Acknowledgement

This wiki article is based on ArchWiki. We may have removed non-FSDG bits from it.