Openbox/Guide

The aim of this guide is to show users how to install the and configure the OpenBox window manager. Many potential programs to be used in conjunction with OpenBox are referenced throughout. For a shorter, simpler install guide see Openbox.

What is Openbox?
So, you've installed The X Server and realized that TWM (Tab Window Manager) just isn't going to cut it for your needs. You may have also had some experience with big desktop environments like KDE, GNOME , and Xfce. One component of those larger desktop suites is called the window manager (or WM for short). A window manager is responsible for the appearance and placement of the containers (or "windows") inside which programs run. Openbox is a minimalistic, no-frills-attached window manager.

Why should I use it?
Openbox, unlike the larger desktop environments, depends on very few libraries. For that reason, it can provide a lightweight graphic environment that runs very quickly, even on older hardware. Whether your hardware is old or new, Openbox also provides a highly customisable and unobtrusive working environment. That means that if you don't want or need a panel, taskbar, clock, or any other program, those choices are yours to make!

Initial installation
After emerging and configuring, installing Openbox can be done in one simple command:

Just like other window managers and desktop environments, in order to load Openbox automatically, the X Server needs to be told to start Openbox. This is done by adding Openbox to the file in the user's home directory:

This will automatically start an Openbox session when startx is typed at a terminal.

Now that Openbox has been emerged and the proper command has been added to the user's file, issue the startx command to see Openbox in action. Beware! The desktop may appear as a cluttered mess! In following the Openbox philosophy, a bare bones environment is provided from which a user can build a desktop completely to their liking.

Upon typing the startx command, typically nothing more than the default Openbox black screen will appear. Where is the menu? Clicking the right mouse button, will generate a pop up menu in the location of the cursor. This menu is nothing more than an example to illustrate the style of an Openbox menu. Since it is just an example, none of the items in the menu will work unless the programs have been previously emerged. In the next section, you will see how to create your own menu that contains links to your programs.

Menu configuration
Since the default Openbox menu is essentially useless to you for the reasons mentioned above, it's time that we create one that will work. Everything in the Openbox menu is written in the appropriately named file, which can be in the user-specific location of , or in the system-wide location of. By default, the only file that is created is the system-wide one which applies to all users on the system.

An easy way to get a basic menu file which you can modify is to use MenuMaker, which will generate a file based on the programs which you currently have installed on your system. To do so, you must firstly emerge it:

Once it is installed, make sure to logout of root, and back into your user account. You then instruct MenuMaker to create a menu specifically using the Openbox XML syntax:

The generated menu will be located at. You can then choose to leave it as your user-specific, or to additionally copy it to the system-wide menu configuration as well:

When you open up the file in your favourite editor (nano, for example), you will notice that the XML tags used are very human-readable and easily understandable. You may choose to modify the default file to fit your needs, or you may want to write it from scratch (don't worry, it's really not that difficult). The basic syntax for the menu XML is as follows:

The above example will work for any applications that launch with standard options in their own windows, but what if you need to append options to the program at launch time? That is no problem either, just add the options to the command, as usual.

Simply replace anything in ALL_CAPS in the above two examples with your information. Alternatively, you can , which is a graphical interface allowing you to create your menus without having to manually edit the  file. It is a very small application and offers a nice amount of customisation without typing any XML.

Openbox theme and behaviour configuration
Aside from being minimalistic and lightweight, Openbox is also surprisingly customisable and flexible. As a user, you can easily change various settings related to theme, appearance, window placement, docking, and more. There are two options for configuring these settings within Openbox. You may either manually edit, or you may want a GUI to help you quickly change settings.

If you want to manually edit, you simply open up your favourite text editor and start making changes. You might want to make a backup of the original file just in case, and store it in a location like. There are plenty of comments within the document itself that should help you with editing. Alternatively, you may want to look at the Openbox configuration guides.

If manually editing doesn't sound like your cup of tea, you may want to use the GTK+ application to manage your themes and behaviours in Openbox. The application that you will use is called ObConf, and can be installed on your system just as easily as was Openbox itself.

You can then open the configurator by typing  in your terminal. Next, you can go and add an entry for ObConf into your so it will show up in your Openbox menu. If the "editing the menu.xml file" code listing above seemed too vague to be helpful, we'll use ObConf as an example of a menu entry:

While ObConf is a great GUI tool for editing many behaviour-related settings for Openbox, it doesn't allow one to manipulate nearly as many settings as are presented in the file itself. If you are having trouble finding a particular setting which you would like to change, please consult the Openbox Wiki for more information.

Autostart configuration
As mentioned above, you don't see a whole lot when you issue the  command for the first time after installing Openbox. In addition to customising your menus and changing the behaviour of the window manager, you will probably want to have some programs automatically start with your Openbox session. There is an easily-editable script that allows you to do just that. Just like with the file, there are two different locations of the  script--the system-wide, and the user-defined.

In the default, you will notice a bunch of lines calling for programs like the gnome-settings-daemon, XDG, and others. These lines will generate errors upon logout if you don't have the programs installed and configured. The easiest thing to do when getting started with Openbox is to just comment out these lines by using the # symbol.

In the above example, the comment symbol (#) was added before each line. The commenting method is preferred to just deleting the lines because you may want to add support for some of those startup items at a later time. Thus, leaving the default lines in place could ease that process.

Adding your own programs to the script is as easy as writing in the program name for many applications. For instance, if you have Conky (a lightweight system monitor) installed, and want it to start automatically with your Openbox session, you simply add the following line to your :

Adding Conky to your autostart.sh

The ampersand (&) after the command allows that application to load up in the background. You will most likely want to load all the applications in your script in the background because doing so will let Openbox and other programs load without the previous one finishing.

Configuring PolKit
Many applications depend on the PolKit authentication framework. You may need a PolKit agent, such as , running in your Openbox session.

First, install the agent:

Now configure PolKit to start automatically when you login to Openbox. Add the following line to (for a single user) or  (for all users):

Start PolKit automatically

Setting the background
Some things that you might take for granted in bigger desktop environments are not included by default in Openbox. One such thing is setting your desktop background. In order to place an image as your wallpaper, you will need to emerge a program like feh or nitrogen. is a simple image viewer that can also set the background, and it can easily be put into the autostart script. Once you have emerged , you can issue the following command to set the background:

feh has many other options instead of --bg-scale, which will scale the image to the screen dimensions. Consult the feh documentation.

Once you have set the background manually, a file called will be created in your home directory. This file simply contains the above command that you just entered in the terminal, and is automatically updated when you issue a different background command. Now, to set your background automatically upon login, you can add the following line to your script:

If you don't particularly care for the idea of having to issue a command in the terminal in order to set your background, you can alternatively use. It will allow you to set a folder for your background images, view thumbnails of those images, and fit, stretch, or tile them to your desktop.

Installing  and getting it into your Openbox menu requires a few more steps than are readily apparent. First, you need to. Second, you need to run  with your backgrounds folder appended:

Third, you can set your background image, but it will not be there after you logout. Just as with , you need to restore your background by editing your  script to have the following line:

This will cause nitrogen to load automatically when you start your Openbox session, and that can lead to a slightly slower load time than using feh.

Programs to use with Openbox
The following is a list of some programs which you might want to use within your Openbox environment. While the list contains numerous terminal emulators, file managers, panels, and more, it should by no means be considered exhaustive. If none of the programs listed fit your needs, please check the appropriate categories in Portage for more options.

Terminal emulators

 * LXterminal is the default terminal emulator for LXDE. It is very lightweight, and based on VTE. While EvilVTE offers many more customisation options (including transparency), LXterminal has a graphical interface for some of the more common options (font, colors, et cetera).


 * EvilVTE is an extremely lightweight terminal emulator based on (you guessed it) VTE. It supports tabs, multiple encodings, as well as an easy and extensible configuration file.


 * Mrxvt is a multi-tabbed rxvt clone with XFT, transparent background and CJK support. It also features session support for each tab.


 * Aterm supports transparency and backwards compatibility with rxvt. It was originally designed for the AfterStep window manager, but easily integrates with other environments.


 * Eterm is a terminal based on vt102 and designed to be a more feature-rich replacement for xterm.


 * Rxvt-unicode is a clone of rxvt that supports Unicode, daemons, embedded perl, and multiple fonts simultaneously.


 * Terminal is the VTE-based default for the Xfce desktop environment, so it does require some Xfce libraries to run. However, it is still fairly speedy, and supports transparency and is easily customised.

File managers

 * PCManFM is the lightweight filemanager from LXDE. It supports tabbed browsing, drag and drop, thumbnails for images, bookmarks, volume management, searching, and more. It also provides supports for managing the desktop background and drawing desktop icons (both optionally).


 * Thunar is the standard file manager from Xfce. It features a bulk renamer, user-customisable actions, and an extension framework, along with many optional plugins, such as media tag editing. It depends on several Xfce libraries, but it's still slimmed down compared to other file managers like Nautilus (from GNOME), and Konqueror (from KDE).


 * Nautilus is the powerful file manager from the GNOME desktop environment. It features volume management, thumbnails for images, searching, and some system configuration. As it depends on many of the GNOME libraries for proper function, it can seem a bit heavy compared to some of the other file managers.


 * Gentoo (no relation to this glorious Linux distribution) is a two-pane style file manager. It is incredibly lightweight, but lacks a some features now prominent in modern file managers. It should definitely be considered for older hardware, or if you are wanting a barebones setup.


 * emelFM2 is another file manager in the vein of Midnight Commander. It features a two-pane window. As with the Gentoo file manager (listed above), it is barebones and does not include many features prevalent in newer file managers. However, it also offers a few features not found in other file managers, such as a built-in commandline in a separate pane.

Desktop management

 * Though PCManFM is mainly a file manager, it also gives you the option to manage the desktop background (instead of using  or   ) and draw desktop icons.


 * iDesk is a simple program used to draw desktop icons. It supports shadowed and anti-aliased fonts, PNG images, "snap-to-grid" placement, and changing the desktop background.

Panels

 * Tint2 is a simple, lightweight panel and taskbar. It supports color, transparency, a clock, drag and drop between virtual desktops, a system tray, and comes with a battery monitor. You can even add a button to display the applications menu from your window manager.


 * PyPanel is an easily customised panel written in Python and C. It features transparency, shading, tinting, location and layout configuration, font type, autohiding, application launcher, clock, and more.


 * LXPanel is the default panel and taskbar from LXDE. It features a launcher, menu, clock, and a GUI-based configurator. It is feature-rich while depending on very few packages, making it a good choice for a lean system.


 * Xfce4-panel is the default panel from the Xfce desktop environment. It supports application launchers, detachable menus, a pager, tasklist, clock, applets, and more. It does, however, require a few of the Xfce libraries which are not dependencies of some other panels.


 * FBpanel is a simple, extremely lightweight panel that supports window lists, launchers, a clock, and a few other goodies. It's not the most featureful panel, and it can be cumbersome to configure, but it needs only GTK+ to run.

Pagers and systrays

 * NetWMpager is an EWMH-compliant pager that integrates nicely into any of the *box environments. It is not as obtrusive, and is much more readily customisable than many of the other available pagers.


 * BBpager is a desktop pager that was originally written for BlackBox, but works nicely with Openbox as well. It does have some BlackBox dependencies though.


 * Docker is the system tray that is made especially for Openbox. It has no extra dependencies, and gives you the ability to view and use tray icons for supported GTK and QT-based applications.


 * Trayer is a system tray that was modified from the FBpanel code, and is often used with FVWM. One of its perks is that it supports transparency.

Session management

 * LXsession is the stripped down session manager from LXDE. It is designed to remember applications that the user was running at the last logout, and to automatically restart those programs. It also supports the HAL daemon.


 * Xfce4-session is the session manager from, you guessed it, Xfce. It is capable of saving several sessions, and provides methods for logging out, rebooting, and suspending your computer. It does, however, have many Xfce dependencies.

Configuration tools

 * ObConf is a GUI application allowing you to customise the Openbox window manager without manually editing.


 * LXappearance is a GTK theme and icon configurator used with LXDE. It provides a nice graphical interface for setting the theme and icons, while depending on very few extra libraries.


 * GTK-ChTheme is a simple application allowing for easier switching of GTK themes and your font. Currently, it does not allow for the switching of icon themes.


 * GTK-theme-switch is another simple application that lets you change your GTK theme.

Miscellaneous

 * Conky is a lightweight system monitor that can display over 250 objects, including date and time, CPU usage, memory usage, IMAP/POP3 email, top processes, hardware sensor data, and even info from your music player. It is highly customisable both in appearance and data display. We also have a Conky configuration guide available.


 * Leafpad is a simple text editor. It is very lightweight, but includes features like codeset options, and the ability to undo/redo without limits.


 * feh is a simple image viewer that runs from the terminal, but it also has many other features. It can display a slideshow of images, create an index print, dynamically zoom, and set the desktop background (detailed instructions above).


 * GPicView is a GUI-based image viewer. Though it has more dependencies than , it is incredibly quick to load and run.


 * SLiM is the Simple Login Manager, which allows you to login to your Openbox session via a graphical interface instead of the terminal. It has very few dependencies, and supports many themes, but should not be used on machines that require remote logins.

LXDE
If installing each component of a working environment sounds like a little too much customisation, but you still want the flexibility of Openbox, you may want to look into a desktop environment that uses Openbox as its default window manager. That environment is LXDE, the Lightweight X Desktop Environment. Designed to require even fewer system resources than Xfce, it is built around Openbox.

Openbox inside GNOME
If you already have a GNOME environment installed, you may just want to replace the Metacity window manager with Openbox. Fortunately, this is quite a simple task! You will need to fire up your favourite editor, open your file, and put the following command inside it:

Adding an Openbox-GNOME session to your .xinitrc

If you use GDM or another graphical login manager, you will see a new "GNOME/Openbox" option in your session menu. You can simply select that option instead of manually editing your.

Openbox inside KDE
Say you have KDE installed and like it, but you want more flexibility with your window management than KWin offers. You can use Openbox as your window manager inside of KDE by simply editing your file, and replacing your current exec command with the following:

Adding an Openbox-KDE session to your .xinitrc

Now when you issue  you will see KDE, but instead of KWin, you will have the customisability of the Openbox window manager.

If you use KDM or another graphic login manager, you will see a new "KDE/Openbox" option in your session menu. You can simply select that option instead of manually editing your.

Openbox inside Xfce
If you use Xfce4 and would like to replace xfwm4 with Openbox, you will need to go about it a little differently than with KDE or GNOME. First, you need to start your normal Xfce session, and open up a terminal. From the terminal, issue the following command:

Second, you need to exit out of your Xfce session, and make sure to tick the checkbox that says "Save session for future login." This will keep Openbox as your default window manager. Third, you will notice that you can't logout properly when using the default menu action. To fix this problem, open up your, and locate this line:

Change it to this:

External resources
While this document will easily take you through the inital installation and customisation of Openbox, it is by no means the only reference on the topic. There are several other resources that will aid you in creating your perfect Openbox setup. Some of them are listed below:


 * On The Official Openbox website you will find more detailed information regarding theming, creating menus (including pipe menus), autostart scripting, and much more. This site also has information regarding new releases, upgrades, and instructions on how you can contribute to development.


 * The Urukrama's Guide to Openbox blog contains a plethora of information about switching GTK+ themes, setting up keybindings, desktop effects, and other programs to use in conjunction with Openbox. Though the tutorial was originally written for use with Ubuntu, everything is applicable to Gentoo (and other Linux distributions for that matter).


 * Box-Look provides numerous themes, icons, wallpapers, fonts, and tools to be used with Openbox (as well as the other *box window managers like Fluxbox, Blackbox, PekWM, etc.)

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * nathanzachary
 * nightmorph