Repository files navigation

An implementation of a synergy client for wayland compositors. Based on theupstream uSynergy library (heavily modified for more protocol support anda bit of paranoia).

• wayland, including wayland-scanner and the base protocols
• libxkbcommon
• libtls (either from libressl, or libretls)
• A compositor making use ofwlroots, or(on an experimental basis) KDE, or (if all else fails) the willingness to runquestionable networking utilities with the privileges to access /dev/uinput
• wl-clipboard for clipboard support (only works on wlroots, not KDE/GNOME)

• AUR (release)
• AUR (git master)
• Gentoo ebuilds (by nrndda)
• openSUSE Tumbleweed (Release)

meson buildcd buildninjaninja install

• Some distributions may not provide the required headers in the mainpackages of the listed prerequisites. Be sure to check for-dev or-devel variants if this is the case.
• KDE users may need to adjust the absolute path inwaynergy.desktopto satisfy kwin's trust checks; a mismatch will prevent the server fromoffering the required interface.

Granting networking software written in questionable C the ability togenerate arbitrary inputs isn't exactly a recipe for success if people areout to get you. Using TLS is essential in any case.

For anyone posting an issue or otherwise seeking assistance:debug logsare key logs. So far people have been prudent but it pays to make thisclear I think. Posting a full debug log will make any targeted network attackfar less concerning than your bank login credentials ending up on a publicissue page, even if they are slightly obfuscated by key mapping translations.

There are no restrictions on privileged protocols at the moment (though thatmay eventually change).As such it should Just Work™.

waynergy.desktop must be installed, and the path must be absolute or therequired interface will not be offered.

First and foremost it should be kept in mind that kernel-level virtual inputmay have undesirable side effects because the compositor is being completelybypassed. This most notably means that virtual consoles are no longer isolatedas far as input is concerned, so simple lock screens can be easily bypassed ifmore than one session is active. I've not tested the usability of magicSysRq, but that could also potentially be a great annoyance. With that outof the way....

waynergy must be able to open/dev/uinput for this to work. Doing this forthe general case as part of the installation would require setuid, which I'mnot inclined to go with given obvious security implications (though itwillstill work, i.e. drop privileges as expected). The alternative approach is tocreate an additional group specifically for uinput access, greatly reducing therisk involved, but possibly varying between systems.

In my case, a 'uinput' group is created, and a udev rule is used to modify thepermissions appropriately:

# /etc/udev/rules.d/49-input.rules, in my caseKERNEL=="uinput",GROUP:="uinput",MODE:="0660"

From here, onecould assign one's users to this group, but doing so wouldopen up uinput to every program, with all the potential issues noted in thefirst paragraph. The safest approach is probably setgid:

# as root -- adjust path as neededchown :uinput waynergychmod g+s waynergy

If this doesn't still doesn't seem to work (as in#38) be sure that theuinput module is loaded properly. This might be done by creating a file/etc/modules-load.d/uinput.conf with the contents ofuinput.

See

waynergy -h

output:

./waynergy: Synergy client for wayland compositorsUSAGE: ./waynergy [-h|--help] [-v|--version] [-b|--backend backend] [-c|--host host] [-p|--port port] [-W|--width width] [-H|--height height] [-N|--name name] [-l|--logfile file] [-L|--loglevel level] [-n|--no-clip] [-e|--enable-crypto] [-E|--disable-crypto] [-t|--enable-tofu] [--fatal-none] [--fatal-ebad] [--fatal-ebsy] [--fatal-timeout]-h|--help:Help text-v|--version:Version information-b|--backend backend:[backend] Input backend -- one of wlr, kde, uinput-c|--host host:[host] Server to connect to-p|--port port:[port] Port-W|--width width:[width] Width of screen in pixels (manual override, must be given with height)-H|--height height:[height] Height of screen in pixels (manual override, must be given with width)-N|--name name:[name] Name of client screen-l|--logfile file:[log/path] Name of logfile to use-L|--loglevel level:[log/level] Log level -- number, increasing from 0 for more verbosity up to 6, or one of 'none', 'error', 'warn', 'info', 'debug', 'debugsyn'-n|--no-clip:Don't synchronize the clipboard-e|--enable-crypto:[tls/enable] Enable TLS encryption-E|--disable-crypto:[tls/enable] Force disable TLS encryption-t|--enable-tofu:[tls/tofu] Enable trust-on-first-use for TLS certificate--fatal-none:Consider *normal* disconnect (i.e. CBYE) to be fatal--fatal-ebad:Protocol errors are fatal--fatal-ebsy:EBSY (client already exists with our name) errors are fatal--fatal-timeout:timeouts are fatal

For each option that is also present in the configuration file, the applicablename is given in[].

Also note thatSIGUSR1 triggers re-execution. Useful until proper reconnectprocedures exist.

By default, the configuration files are stored in$XDG_CONFIG_HOME/waynergy,which is probably at~/.config/waynergy in most cases. This can beoverridden with the environment variableWAYNERGY_CONF_PATH. Aside from keymapsand hashes, most things should go inconfig.ini; the old approach ofsingle-value-per-file is retained strictly for compatibility, and becauseripping it out would be annoying for cases where that approach is reallygenuinely useful (i.e. xkb keymaps which have their file format). The basicglobal values areport,host,name,width, andheight, which do exactlywhat the command line option would do. Options within sections are referred toin the formsection/property for the purposes of this document.

In addition toconfig.ini, there is now support for snippets (with.iniextension) underconfig.ini.d/. Any duplicate options will overwrite anyread previously.

For the time being there are two key mapping mechanisms: xkb, which workswith the wlr backend, and raw, which will work on everything. xkb appears abit more complex, but has the advantage that the targets of the keycodes willremain effectively the same across any client that can run waynergy. Forraw, both the source and the target will vary, based on the underlyingoperating systems and layout configurations.

There is also now support for using the Synergy mapped key codes ratherthan the raw buttons, by settingsyn_raw_key_codes tofalse. Eventuallythis may make a more universal approach possible for the defaults, thoughI'll leave that for anyone who wants to have a go at doing it.

By default, the existing compositor keymap is tried, falling back on a baked-indefault. This has changed from prior versions which always used the baked-indefault; to get the old behavior, setwl_keyboard_map to false.

If neither default is sufficient, an xkb-formatted map should be placed inxkb_keymap. The easiest way to obtain this is to use the output of

setxkbmap -print

For custom keycodes, one may run into issues with Xwayland if the minimumkeycode is below 8. To work around this, an offset may be provided inthe configuration asxkb_key_offset.

Unfortunately there is no existingxkb_keycodes section included inxkbcommon that will work with a Windows primary. To deal with this I'veincluded one that mostly works (minus the keys I don't actually have to teston my own systems) indoc/xkb/keycodes/win.

The same issue of keycodes applies here; seedoc/xkb/keycodes/mac fora usable configuration.

If everything is still broken, usingwaynergy-mapper -x $NAME will generateanxkb_keycodes section with the given name by iterating through everypossible keycode in the current keymap to find out what the server is sending.

Because the fake input protocol used by KDE doesn't support custom keymaps,while uinput doesn't involve xkb at all, using xkb for this doesn't work;instead, one must use theraw-keymap section to map the remote keycodes tothe local keymap using the formremote = local; for example, to use anOpenBSD server I must specify the following section to get arrow keys workingproperly:

[raw-keymap]98 = 111100 = 113104 = 116102 = 114

Because these will vary on the source and target end, providinggeneral-purpose mappings is more difficult, but if anyone wants tocontribute some underdoc with clearly-defined server and clienttargets they would be appreciated by somebody probably.

The offset functionality is enabled throughraw-keymap/offset, though itcan also be disabled for explicit mappings by settingraw-keymap/offset_on_explicittofalse.

Generating a raw keymapping from scratch is now much more straightforward: runwaynergy-mapper -r, which will iterate through every keycode in the localxkb map and accept input from the remote, a bit like using xev/wev but withimmediately usable output.

In some cases (see recent comments on#35) Windows servers are sendingduplicate button values for keys which are clearly different. In these casesusing the synergy key IDs might make sense in anid-keymap section:

[id-keymap]57218 = 19957219 = 200

with actual values based on the above process, using theid parameter in theserver log instead ofbutton.

This should not be necessary in 99.9% of situations, but if you want to changethe default mouse button behavior you can include a section redefining thebutton map in use:

[button-map]0 = 0 # No button1 = 0x110 # BTN_LEFT2 = 0x112 # BTN_MIDDLE3 = 0x111 # BTN_RIGHT4 = 0x113 # BTN_SIDE5 = 0x114 # BTN_EXTRA

Given here is the default; each of 6 protocol possibilities is mapped to avalue based on/usr/include/linux/input-event-keycodes.h.

screensaver/start should contain a command to be run when the screensaver isactivated remotely,screensaver/stop should contain a command to terminateit when it is deactivated.

screen/enter andscreen/exit should contain a command to be run when thescreen is entered or exited, respectively.

Due to issues with the idle inhibition protocol, idle is actually inhibited bysending a hopefully-meaningless event to the compositor: ifidle-inhibit/methodiskey, the raw keycode given inidle-inhibit/keycode is sent if defined,falling back on the xkb-style key name inidle-inhibit/keyname, which willdefault toHYPR. Ifidle-inhbibit/method ismouse, then a relativemove of 0,0 is sent (this is the default).

For GNOME,gnome-session-inhibit is used instead. This should be automaticallydetected.

Synergy upstream seems to no longer support this; if your screenlocker nevertriggers setidle-inhibit/enable tofalse. Barrier and input-leap seemto still work.

Enabled or disabled withtls/enable. Certificate hashes (for any given host)are stored in the directorytls/hash/, one hash per file named after thehost. These can be obtained by running something like

printf "SHA256:%s\n" $(openssl x509 -outform der -in $certpath | openssl dgst -sha256 | cut -d ' ' -f 2)

on the host. Common values of $certpath would be

• %LocalAppData%\Barrier\SSL\Barrier.pem
• ~/.local/share/barrier/SSL/Barrier.pem
• $XDG_DATA_HOME/barrier/SSL/Barrier.pem
• ~/.synergy/SSL/Synergy.pem

There is also the option to trust on first use by settingtls/tofu orrunning with the--enable-tofu option on the command line, which will allowverification that it has not changed on subsequent connections.

Client certificates are now supported as well; simply place the certificate attls/cert.

The latest version of wlroots has an issue where discrete axis events areaccumulated rather than sent directly; to correct for this the discreteparameter is now a multiple of120 rather than1. For sway or wayfireusers on Linux this is automatically detected and worked around; otherwise,thewlr/wheel_mult configuration option may be used.

I would like to thank

• uSynergy for the protocol library
• The swaywm people, who've provided the protocols to make something like thispossible
• wl-clipboard, because its watch mode turns it into a clipboard manager so II don't have to.
• mattiasgustavsson for the INIimplementation.
• kwin developers for supporting a fake input protocol these days
• the kernel developers for supplying uinput on Linux
• andusers like you, whose contributions (even through simple reportingof issues) are instrumental in making this suck just a little bit less overtime. Adding multiple backend support, for compositors I don't even use,has proven entirely worthwhile for this reason, for example.

At this point I'm content with most things here save for the following

• KDE likes to hide the mouse pointer if there is no pointing devicecurrently installed. I don't think it's too much work to plug in a mouse,but some would probably prefer a better workaround.