Gentoo Wiki



XOrg 6.8 and Older

A default configuration for mice often looks like this:

File: /etc/X11/xorg.conf
Section "InputDevice"
    Identifier  "Mouse0"
    Driver      "mouse"
    Option      "Protocol"     "ImPS/2"
    Option      "Device"       "/dev/mouse"
    Option      "ZAxisMapping" "4 5"

This typically activates the usual three-button X mouse and a scroll wheel. With the above configuration, the extra mouse buttons do nothing, and don't even generate X events.

Run the program xev (from x11-apps/xev) in a terminal window. Move the mouse over the window that pops up, and click the side buttons. If nothing happens, we will need to tweak the configuration.

First, change the xorg.conf file to use a newer protocol called ExplorerPS/2. Also, tell the mouse driver that there are now seven buttons in total (left, middle, right, wheelup, wheeldown, and, depending on the mouse, side-left and side-right or thumb-forward and thumb-back). We must also tell it to map the ZAxisMapping to buttons 6 and 7, NOT 4 and 5. To allow X to read from multiple mice, change the "Device" line to read "/dev/input/mice". This device can be used safely on a single mouse system, however, this allows for changes in dynamic device naming without affecting whether your mouse will function or not. /dev/input/mice just reads input from ALL mice attached to the system.

Here is the complete edited configuration:

File: /etc/X11/xorg.conf
Section "InputDevice"
   Identifier  "Mouse0"
   Driver      "mouse"
   Option      "Protocol"     "ExplorerPS/2"
   Option      "Device"       "/dev/input/mice"
   Option      "Buttons"      "7"
   Option      "ZAxisMapping" "6 7"

Restart the X server and try the configuration. The extra mouse buttons should output events in xev, and the side buttons should perform the same task as the mouse wheel due to the new ZAxisMapping. If the mouse requires additional configuration, xmodmap or xinput may be used. Please see the corresponding section below.

Individual Mouse Configurations

This section has been moved to Legacy Monolithic/Individual Configurations. Please post if your mouse requires any special xmodmap, xinput, or other settings to function properly.

evdev for XOrg 6.8

There is an older evdev driver in the 6.8 series of XOrg. It can be used in almost the same way as the 6.9/Modular X driver, except that it is called in a different way:

File: /etc/X11/xorg.conf
Section "InputDevice"
    # Below is an example for Logitech MX-510
    Identifier "Mouse0"
    Driver     "mouse"
    Option     "Protocol"     "evdev"
    Option     "Dev Name"     "Logitech USB-PS/2 Optical Mouse" # from 'cat /proc/bus/input/devices'
    Option     "Dev Phys"     "usb-*/input0"                    # from 'cat /proc/bus/input/devices'
    Option     "Device"       "/dev/input/event1"               # from 'cat /proc/bus/input/devices'
    Option     "Buttons"      "10"    # Number of buttons on MX-510
    Option     "ZAxisMapping" "4 5" # Scrollwheel MX-510

Once you've made that change, follow the modular XOrg directions below.

There are numerous bugs in this 6.8 version of the evdev driver. Upgrading to modular XOrg or compiling the new driver with 6.8 is recommended. You can find the new driver at FreeDesktop Bugzilla

XOrg 6.9/7.0 Known Issues

XOrg 6.9/7.0 has a known issue where the correct number of buttons is not shown by the X server to the Xmodmap program. It may want additional buttons to be added to your mapping. Just add the required number of buttons after your original map and it will work as planned.



IMWheel is completely unnecessary for most modern mice including both USB and PS/2 models. X will usually detect that these mice have a scroll wheel or else you'll be able to map it properly with Xmodmap and the axis settings in your xorg.conf file. This program should only be used for extreme cases including very odd or old mice, or if you wish to define custom behaviour (such as trigger your window manager to invoke specific scripts) on mouse events.

If you really need it, continue as follows:

emerge imwheel

as root. Switch to your limited user account and create a file in your home directory called .imwheelrc

File: ~/.imwheelrc
 None, Up, Alt_L|Left
 None, Down, Alt_L|Right 

 None, Up,   Alt_L|Left
 None, Down, Alt_L|Right

".*" matches any window and the next two lines instruct imwheel on what to do when the buttons are pressed. Button 6 is 'down' and button 7 is 'up' - this doesn't relate to the action of pressing and releasing a button, it is actually because X maps these buttons onto a sort of virtual mousewheel or 'joystick'. The "(null)" entry is necessary for compatibility with some programs, particularly GNOME.

You can replace Alt_L|Left etc with whatever you want. These settings just invoke forward/backward browsing in mozilla/epiphany, like the Windows drivers would with IE.

You can do some pretty fancy stuff with this. I have a slightly enhanced .imwheelrc:

File: ~/.imwheelrc
 None, Up,   Alt_L|Left
 None, Down, Alt_L|Right

 None, Up,   Alt_L|Control_L|S
 None, Down, Alt_L|Control_L|T

# this should be last
 None, Up,   Alt_L|Control_L|P
 None, Down, Alt_L|Control_L|O

Just remember to put the ".*" entry LAST since imwheel stops looking once it matches an entry.

Note: Note that program descriptors such as firefox* will not work because the entries are matched by regex patterns rather than DOS-style patterns. Under the regexp system the .* combo will match any letter. Also note that windows are matched based on the content of their Title Bar (which is often capitalized). The correct entry is, therefore, Firefox.*, instead of firefox*. See the imwheel man page for more information.

Those longish Alt_L|Control_L|... sequences match settings in my fluxbox/keys file, which do various things such as open new xterms, ffwd xmms, or open the selected URL in Mozilla.

// personally i've found a rather nice use for the Down button in firefox...assign it to Control_L|W. This lets you hit that thumb button to close the current tab.

NOTE: If using a Logitech MX700 mouse, you may need to replace "Up" with "Left" and "Down" with "Right" in your .imwheelrc. That is, the thumb-back button is "Left" and the thumb-forward button is "Right".

Now, the final step is to fire up the imwheel program:

$ imwheel -f -k -p -b "67"

Modular XOrg

These changes had to be made to my imwheel configuration on modular X --Nibblebot 02:45, 3 January 2006 (GMT)

I had to make this change too --Meowsqueak 4th July 2006

$ imwheel -f -k -p -b "89"

To make it so this happens automatically at login, put this command in your ~/.xinitrc file, right after the xmodmap command.

Note: If you are using GDM and GNOME, your ~/.xinitrc may be ignored. To start imwheel at login, when logged into GNOME, go to G->Desktop->Preferences->Sessions, select the Startup Programs tab, and add a new entry. For the command, use an unadorned "imwheel". Set the priority at 20. This will make imwheel start early upon login.

Note: If you're using GDM and KDE, you may have to put the imwheel command in /etc/X11/gdm/Sessions/kde-* instead. (Confirmed?)

Note: In GDM, you can put the imwheel command in ~/.xprofile or /etc/xprofile

Please contribute to the thread at the top of this page if you have further details, or wish to point out errors or inconsistencies. Please also modify this page accordingly.

Retrieved from ""

Last modified: Mon, 15 Sep 2008 03:58:00 +0000 Hits: 988