Skip to content

Latest commit

 

History

History
420 lines (311 loc) · 15.7 KB

README.md

File metadata and controls

420 lines (311 loc) · 15.7 KB
Raw

Lan Mouse

Lan Mouse is a cross-platform mouse and keyboard sharing software similar to universal-control on Apple devices. It allows for using multiple PCs via a single set of mouse and keyboard. This is also known as a Software KVM switch.

Goal of this project is to be an open-source alternative to proprietary tools like Synergy 2/3, Share Mouse and other open source tools like Deskflow or Input Leap (Synergy fork).

Focus lies on performance, ease of use and a maintainable implementation that can be expanded to support additional backends for e.g. Android, iOS, ... in the future.

blazingly fast™ because it's written in rust.

  • Now with a gtk frontend
Screenshot of Lan-Mouse

Encryption

Lan Mouse encrypts all network traffic using the DTLS implementation provided by WebRTC.rs. There are currently no mitigations in place for timing side-channel attacks.

OS Support

Most current desktop environments and operating systems are fully supported, this includes

  • GNOME >= 45
  • KDE Plasma >= 6.1
  • Most wlroots based compositors, including Sway (>= 1.8), Hyprland and Wayfire
  • Windows
  • MacOS

Caveats / Known Issues

Important

  • X11 currently only has support for input emulation, i.e. can only be used on the receiving end.

  • Sway / wlroots: Wlroots based compositors without libei support on the receiving end currently do not handle modifier events on the client side. This results in CTRL / SHIFT / ALT / SUPER keys not working with a sending device that is NOT using the layer-shell backend

  • Wayfire: If you are using Wayfire, make sure to use a recent version (must be newer than October 23rd) and add shortcuts-inhibit to the list of plugins in your wayfire config! Otherwise input capture will not work.

  • Windows: The mouse cursor will be invisible when sending input to a Windows system if there is no real mouse connected to the machine.

For more detailed information about os support see Detailed OS Support

Android & IOS

A proof of concept for an Android / IOS Application by rohitsangwan01 can be found here. It can be used as a remote control for any device supported by Lan Mouse.

Installation

Arch Linux

Lan Mouse can be installed from the official repositories:

pacman -S lan-mouse

The prerelease version (following main) is available on the AUR:

paru -S lan-mouse-git
Nix (OS)
Manual Installation

First make sure to install the necessary dependencies.

Precompiled release binaries for Windows, MacOS and Linux are available in the releases section. For Windows, the depenedencies are included in the .zip file, for other operating systems see Installing Dependencies.

Alternatively, the lan-mouse binary can be compiled from source (see below).

Installing desktop file, app icon and firewall rules (optional)

# install lan-mouse (replace path/to/ with the correct path)
sudo cp path/to/lan-mouse /usr/local/bin/

# install app icon
sudo mkdir -p /usr/local/share/icons/hicolor/scalable/apps
sudo cp lan-mouse-gtk/resources/de.feschber.LanMouse.svg /usr/local/share/icons/hicolor/scalable/apps

# update icon cache
gtk-update-icon-cache /usr/local/share/icons/hicolor/

# install desktop entry
sudo mkdir -p /usr/local/share/applications
sudo cp de.feschber.LanMouse.desktop /usr/local/share/applications

# when using firewalld: install firewall rule
sudo cp firewall/lan-mouse.xml /etc/firewalld/services
# -> enable the service in firewalld settings

Instead of downloading from the releases, the lan-mouse binary can be easily compiled via cargo or nix:

Compiling and installing manually:

# compile in release mode
cargo build --release

# install lan-mouse
sudo cp target/release/lan-mouse /usr/local/bin/

Compiling and installing via cargo:

# will end up in ~/.cargo/bin
cargo install lan-mouse

Compiling and installing via nix:

# you can find the executable in result/bin/lan-mouse
nix-build

Conditional compilation

Support for other platforms is omitted automatically based on the active rust toolchain.

Additionally, available backends and frontends can be configured manually via cargo features.

E.g. if only wayland support is needed, the following command produces an executable with just support for wayland:

cargo build --no-default-features --features wayland

For a detailed list of available features, checkout the Cargo.toml

Installing Dependencies for Development / Compiling from Source

MacOS 
brew install libadwaita pkg-config
Ubuntu and derivatives 
sudo apt install libadwaita-1-dev libgtk-4-dev libx11-dev libxtst-dev
Arch and derivatives 
sudo pacman -S libadwaita gtk libx11 libxtst
Fedora and derivatives 
sudo dnf install libadwaita-devel libXtst-devel libX11-devel
Nix 
nix-shell .
Nix (flake) 
nix develop
Windows

TLDR:

Build gtk from source

  • The following commands should be run in an admin power shell instance:
# install chocolatey
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# install gvsbuild dependencies
choco install python git msys2 visualstudio2022-workload-vctools
  • The following commands should be run in a regular power shell instance:
# install gvsbuild with python
python -m pip install --user pipx
python -m pipx ensurepath
  • Relaunch your powershell instance so the changes in the environment are reflected.
pipx install gvsbuild

# build gtk + libadwaita
gvsbuild build gtk4 libadwaita librsvg adwaita-icon-theme
  • Make sure to add the directory C:\gtk-build\gtk\x64\release\bin to the PATH environment variable. Otherwise the project will fail to build.

To avoid building GTK from source, it is possible to disable the gtk frontend (see conditional compilation).

Usage

Gtk Frontend

By default the gtk frontend will open when running lan-mouse.

To connect a device you want to control, simply click the Add button and enter the hostname of the device.

On the remote device, authorize your local device for incoming traffic using the Authorize button under the "Incoming Connections" section. The fingerprint for authorization can be found under the general section of your local device. It is of the form "aa:bb:cc:..."

Authorized devices can be persisted using the configuration file (see Configuration).

If the device still can not be entered, make sure you have UDP port 4242 (or the one selected) opened up in your firewall.

Command Line Interface

The cli interface can be enabled using --frontend cli as commandline arguments. Type help to list the available commands.

E.g.:

$ cargo run --release -- --frontend cli
(...)
> connect <host> left|right|top|bottom
(...)
> list
(...)
> activate 0
Daemon Mode

Lan Mouse can be launched in daemon mode to keep it running in the background (e.g. for use in a systemd-service).

To do so, add --daemon to the commandline args:

lan-mouse --daemon

In order to start lan-mouse with a graphical session automatically, the systemd-service can be used:

Copy the file to ~/.config/systemd/user/ and enable the service:

cp service/lan-mouse.service ~/.config/systemd/user
systemctl --user daemon-reload
systemctl --user enable --now lan-mouse.service

Configuration

To automatically load clients on startup, the file $XDG_CONFIG_HOME/lan-mouse/config.toml is parsed. $XDG_CONFIG_HOME defaults to ~/.config/.

To create this file you can copy the following example config:

Example config

Tip

key symbols in the release bind are named according to their names in input-event/src/scancode.rs#L172. This is bound to change

# example configuration

# configure release bind
release_bind = [ "KeyA", "KeyS", "KeyD", "KeyF" ]

# optional port (defaults to 4242)
port = 4242
# # optional frontend -> defaults to gtk if available
# # possible values are "cli" and "gtk"
# frontend = "gtk"

# list of authorized tls certificate fingerprints that
# are accepted for incoming traffic
[authorized_fingerprints]
"bc:05:ab:7a:a4:de:88:8c:2f:92:ac:bc:b8:49:b8:24:0d:44:b3:e6:a4:ef:d7:0b:6c:69:6d:77:53:0b:14:80" = "iridium"

# define a client on the right side with host name "iridium"
[right]
# hostname
hostname = "iridium"
# activate this client immediately when lan-mouse is started
activate_on_startup = true
# optional list of (known) ip addresses
ips = ["192.168.178.156"]

# define a client on the left side with IP address 192.168.178.189
[left]
# The hostname is optional: When no hostname is specified,
# at least one ip address needs to be specified.
hostname = "thorium"
# ips for ethernet and wifi
ips = ["192.168.178.189", "192.168.178.172"]
# optional port
port = 4242

Where left can be either left, right, top or bottom.

Roadmap

  • Graphical frontend (gtk + libadwaita)
  • respect xdg-config-home for config file location.
  • IP Address switching
  • Liveness tracking Automatically ungrab mouse when client unreachable
  • Liveness tracking: Automatically release keys, when server offline
  • MacOS KeyCode Translation
  • Libei Input Capture
  • MacOS Input Capture
  • Windows Input Capture
  • Encryption
  • X11 Input Capture
  • Latency measurement and visualization
  • Bandwidth usage measurement and visualization
  • Clipboard support

Detailed OS Support

In order to use a device for sending events, an input-capture backend is required, while receiving events requires a supported input-emulation and input-capture backend.

A suitable backend is chosen automatically based on the active desktop environment / compositor.

The following sections detail the emulation and capture backends provided by lan-mouse and their support in desktop environments / operating systems.

Input Emulation Support

Desktop / Backend wlroots libei remote-desktop portal windows macos x11
Wayland (wlroots) ✔️
Wayland (KDE) ✔️ ✔️
Wayland (Gnome) ✔️ ✔️
Windows ✔️
MacOS ✔️
X11 ✔️

Input Capture Support

Desktop / Backend layer-shell libei windows macos x11
Wayland (wlroots) ✔️
Wayland (KDE) ✔️ ✔️
Wayland (Gnome) ✔️
Windows ✔️
MacOS ✔️
X11 WIP
  • layer-shell: This backend creates a single pixel wide window on the edges of Displays to capture the cursor using the layer-shell protocol.
  • libei: This backend uses libei and is supported by GNOME >= 45 or KDE Plasma >= 6.1.
  • windows: Backend for input capture on Windows.
  • macos: Backend for input capture on MacOS.
  • x11: TODO (not yet supported)