How to Enable Forward and Reverse Buttons on a Gaming Mouse in Debian/Ubuntu Linux

Many gaming mice, like the Alcatroz X-Craft Pro, come with additional buttons, such as forward and reverse buttons located near the thumb. While these buttons work out of the box on Windows and macOS, getting them to function properly on Linux can require some configuration. This guide provides solutions for both Xorg and Wayland display servers.

For Xorg (using imwheel):

If you’re using Xorg, imwheel is a utility that allows you to remap mouse buttons.

Step 1: Install imwheel

Open a terminal and run:

Bash

sudo apt update
sudo apt install imwheel

Step 2: Edit the imwheel Configuration File

Create or edit the ~/.imwheelrc file to define how the buttons should behave:

Bash

nano ~/.imwheelrc

Paste the following configuration into the file:

".*"
None,      Up,   Button4, 5
None,      Down, Button5, 5
Control_L, Up,   Control_L|Button4
Control_L, Down, Control_L|Button5
Shift_L,   Up,   Shift_L|Button4
Shift_L,   Down, Shift_L|Button5
None, Thumb1  , Alt_L|Left
None, Thumb2  , Alt_L|Right

What This Does:

• Button4 and Button5 typically correspond to the scroll wheel up and down events. The first four lines allow you to configure these with modifiers.
• The last two lines map the lower thumb button (Thumb1) to simulate the Alt key + left arrow (Alt_L|Left), commonly used for backward navigation.
• The second thumb button (Thumb2) is mapped to Alt key + right arrow (Alt_L|Right) for forward navigation.

Step 3: Apply the Configuration

After saving the file, restart imwheel:

Bash

imwheel -k

To ensure imwheel starts automatically on login, add it to your startup applications:

1. Open “Startup Applications.”
2. Click “Add” and enter:
   • Name: imwheel
   • Command: imwheel
   • Comment: Enable custom mouse button mapping.
3. Save the entry.

Step 4: Test the Buttons

Open a browser and test the thumb buttons for navigation. If they don’t work, see the debugging tips below.

Step 5: Debugging Tips

• Use xev to identify mouse button numbers: xev | grep button. Move your mouse over the xev window and press the buttons.
• If imwheel doesn’t start automatically, check the startup command.
• Restart imwheel: imwheel -k.

For Wayland (using Input-Remapper):

imwheel is not compatible with Wayland. For Wayland, Input-Remapper is the recommended solution.

Step 1: Install Input-Remapper

Refer to the official Input-Remapper GitHub page (https://github.com/sezanzeb/input-remapper) for detailed installation instructions for your distribution. Generally, this involves using your distribution’s package manager (e.g., apt, dnf, pacman).

Step 2: Configure Input-Remapper

1. Launch Input-Remapper.
2. Select your gaming mouse.
3. Click the button you want to configure (Thumb1 for back, Thumb2 for forward).
4. Choose “Keypress.”
5. For Thumb1 (back), enter Alt_L+KEY_Left.
6. For Thumb2 (forward), enter Alt_L+KEY_Right.
7. Save the configuration.

Step 3: Test the Buttons

Open a browser and test the buttons.

Key Differences between imwheel and Input-Remapper:

• Display Server Compatibility: imwheel works only on Xorg. Input-Remapper is compatible with Wayland and Xorg.
• Configuration: imwheel uses a configuration file (.imwheelrc). Input-Remapper provides a graphical user interface.
• Features: Input-Remapper offers more advanced features, such as creating macros.

Conclusion:

This guide provides solutions for configuring back and forward buttons on your gaming mouse for both Xorg (using imwheel) and Wayland (using Input-Remapper). Choose the appropriate method based on your display server. Input-Remapper is generally the preferred option for modern Linux systems, especially those using GNOME on Wayland.