Skip to content

INSTALL-linux.md

Latest commit

 

History

History
248 lines (195 loc) · 8.5 KB

INSTALL-linux.md

File metadata and controls

248 lines (195 loc) · 8.5 KB
Raw

Installing OpenLogi on Linux

Note

Linux support is in active development. HID++ device enumeration supports Logi Bolt (USB PID 0xC548) and Logi Unifying (PID 0xC52B and others) receivers, as well as Bluetooth-direct devices.

Prerequisites

  • Quit Solaar (or any other Logitech manager) before starting OpenLogi — the two applications fight over HID++ access.
  • A kernel with hidraw and uinput module support (standard on all major distros).
  • systemd + udev (standard on Ubuntu, Fedora, Arch, Debian, openSUSE, …).
  • GLIBC 2.35 or newer for the pre-built packages (Ubuntu 22.04 baseline).
  • minisign, installed through your distribution's package manager, for authenticating release packages.

Install a release package

Download the installer to a file over HTTPS, inspect it, and then run it. Do not use curl | sh:

curl --proto '=https' --proto-redir '=https' --tlsv1.2 \
  --fail --location --silent --show-error \
  --retry 3 --retry-connrefused \
  --output openlogi-install.sh \
  https://raw.githubusercontent.com/AprilNEA/OpenLogi/master/packaging/linux/install.sh
less openlogi-install.sh
sh openlogi-install.sh
rm openlogi-install.sh

By default the script resolves the latest GitHub release, detects x86_64/aarch64 and apt, dnf, yum, zypper, rpm, or pacman, then downloads the exact matching .deb, .rpm, or .pkg.tar.zst. It downloads that package's detached signature and authenticates it against the minisign public key embedded in the reviewed script. It also downloads the release's SHA256SUMS, extracts exactly one entry for the selected file, and verifies it before invoking only the package-manager command with sudo. nFPM's package scripts remain responsible for reloading udev and desktop/icon caches. Run the installer as your normal user; it refuses an invocation of the whole script through sudo.

Useful options:

# Pin a release (an optional leading v is accepted):
sh openlogi-install.sh --version "$VERSION"

# Override detection, verify without installing, or leave the agent stopped:
sh openlogi-install.sh --package-manager zypper
sh openlogi-install.sh --dry-run
sh openlogi-install.sh --no-start

The installer enables and starts openlogi-agent.service for the current user when systemd is available; failure to reach the user service manager does not roll back an otherwise successful package installation. Tagged releases with a complete Linux build also attach install.sh, install.sh.minisig, and a SHA256SUMS entry for manual verification.

NixOS

The repository Flake provides a package and a NixOS module for x86_64 and aarch64 Linux. Importing the module is preferred over adding the package to environment.systemPackages by itself: the module also registers the udev rules required for device access and manages the agent's user service.

{
  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  inputs.openlogi = {
    url = "github:AprilNEA/OpenLogi";
    inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, openlogi, ... }: {
    nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux"; # or aarch64-linux
      modules = [
        openlogi.nixosModules.default
        {
          programs.openlogi = {
            enable = true;
            # Starts openlogi-agent with graphical-session.target by default.
            launchAtLogin = true;
          };
        }
      ];
    };
  };
}

Set programs.openlogi.launchAtLogin = false to install the package and udev rules without automatically starting the agent. It remains available as systemctl --user start openlogi-agent.service.

For a build without installing the module:

nix build github:AprilNEA/OpenLogi#openlogi

Build from source

Pre-built .deb and .rpm packages are available on the releases page — see the main README for the package-based install. To build from source instead, use the stable Rust toolchain:

git clone https://github.com/AprilNEA/OpenLogi
cd OpenLogi
cargo build --release \
  -p openlogi -p openlogi-desktop -p openlogi-overlay -p openlogi-agent

Four production executables land in target/release/:

Binary Role
openlogi CLI — inventory, diagnostics, asset sync
openlogi-desktop Desktop GUI
openlogi-overlay Actions Ring overlay helper
openlogi-agent Background agent — HID++ loop, input hook

Device access: udev rules

OpenLogi needs:

  • Write access to /dev/uinput — to create the virtual input device for button remapping.
  • Read/write access to /dev/hidraw* — to send HID++ commands to the Bolt receiver, or to the device itself when it is paired over Bluetooth.
  • Read access to the mouse's /dev/input/event* node — the hook grabs the pointer there to capture button presses. Bluetooth mice need the bundled rule for this: their event node hangs off /devices/virtual/misc/uhid, which has no seat, so logind never grants the ACL on its own.

Install the bundled udev rules to grant access to the active-seat user without requiring sudo or group membership (requires systemd-logind):

sudo cp packaging/linux/udev/70-openlogi.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

Verify access (should open without error):

# Check uinput
openlogi-agent --check-uinput 2>/dev/null || \
    test -w /dev/uinput && echo "uinput OK"

# Check a hidraw node
ls -la /dev/hidraw*

# Check the mouse's event node — look for a "+" (ACL) in the mode, or your
# user in the ACL itself. Without it the agent logs
# "could not install OS mouse hook".
getfacl /dev/input/event*

The GUI Settings → Permissions page shows a live Granted / Not granted indicator; check it after installing the rules (no restart needed).

Device already connected? udevadm trigger re-evaluates rules but does not re-grant uaccess ACLs on nodes that were already open when the rules were installed. If access is still denied, unplug and replug your receiver or mouse (or power-cycle for wireless devices) to let udev apply the new rules on reconnect.

Non-systemd systems (SysV init, OpenRC)

Replace TAG+="uaccess" in the rules file with MODE="0660", GROUP="input", then add your user to the input group:

sudo usermod -aG input "$USER"
# Re-login for the group change to take effect.

Install from source with the script

From a repository checkout, --from-source copies the four local target/release binaries, udev rules, systemd unit, desktop entry, and icon to system paths, then reloads udev and desktop/icon caches. The script requests sudo only for system files and lifecycle commands; do not run the whole installer with sudo. --prefix applies only to this mode.

# From the repo root, after building:
packaging/linux/install.sh --from-source
# Or to a custom prefix (e.g. /usr):
packaging/linux/install.sh --from-source --prefix=/usr

To remove a source installation (release packages should be removed through their package manager):

packaging/linux/uninstall.sh

Autostart (launch at login)

The background agent (openlogi-agent) must be running for the GUI and CLI to show connected devices. Enable it for your user session:

systemctl --user enable --now openlogi-agent.service

Alternatively, toggle Settings → General → Launch at login in the GUI. When a packaged unit is already installed it simply enables that one. Otherwise — a build from source, or an install under a custom prefix — it generates a unit at ~/.local/share/systemd/user/openlogi-agent.service pointing at the running binary.

Either way ~/.config/systemd/user/openlogi-agent.service stays yours: systemd ranks it above both locations, so a unit you write there overrides whatever OpenLogi does. Use systemctl --user edit openlogi-agent.service for a drop-in that survives package upgrades.

OpenLogi never overwrites or deletes a unit it did not generate, at either location, and it only turns off an autostart it turned on. Enabling the service yourself with the command above keeps working regardless of the GUI toggle.

Verify the installation

# List connected Logitech devices:
openlogi list

# Launch the GUI:
openlogi-desktop

Known limitations

Limitation Status
Wayland: per-application profile switching Requires XWayland (WM_CLASS lookup uses X11)
Button capture: middle / mode-shift / thumbwheel Side buttons only today