File README-SUSE.md of Package nikau

# First-time use of the software nikau KVM

## Firewall setup

The nikau server listens on UDP port 1213. To enable this port, run

    firewall-cmd --zone $MY_HOME_ZONE --add-service nikau
	firewall-cmd --runtime-to-permanent

No firewall modifications are necessary on the systems running the nikau client.

## Server / client authentication

Nikau requires explicit confirmation on both client and server for
establishing an initial connection. Every time a new client / server pair is
set up, nikau must once be run manually on both sides, as root.

    # On the server
    sudo nikau server
	# On the client
	sudo nikau client $IP_ADDRESS_OF_SERVER

You will be prompted on both systems whether to accept the certificate of the
other side. This will look like this (note the local finger print at the top
below "nikau client", and the peer fingereprint below "Confirm. ...":

    ~ > sudo nikau client 192.168.99.99

     \\ //
      \V/
       U
       | nikau client
       | 0123456789abcdef...
    
    2025-07-03T11:08:51.661476Z  INFO nikau::network::certs: Using keypair from /root/.config/nikau/private.pem
    2025-07-03T11:08:51.664539Z  INFO nikau::device::output::uinput: Created virtual uinput devices: keyboard, mouse, touchpad
    2025-07-03T11:08:51.664627Z  INFO nikau: Disabled system clipboard support: Failed to set up X11 API context
    2025-07-03T11:08:51.664641Z  INFO nikau: Connecting to server: 192.168.99.99:1213
    APPROVAL NEEDED: New unknown server connection
    
    The client has connected to a new unknown server.
    Only approve this if you are expecting to be connecting to a new server.
    You will also likely need to confirm this connection on the server as well.
    
    Confirm that the server startup image has this fingerprint:
        fedcba9876543210...
    
    Allow this new server and save its certificate for future connections? (60s timeout) [y/N]

Compare the fingerprints, and if they match, confirm on both client and
server. From now on, the client will be able to connect without manual
intervention.

*Note:* The certificates and known fingerprints are stored under
`/root/.config/nikau`. Known peers (client or server) can be "forgotten" by
deleting files under `/root/.config/nikau/known_certs`.

# Unit files and other helpers in the SUSE package

The openSUSE nikau package includes systemd units to simplify starting and
stopping nikau. They allow clipboard sharing, which would otherwise require
manual setup to pass the values of the environment variables `XAUHORITY` and
`DISPLAY`. Moreover, they apply systemd sandboxing to the nikau processes
which run as root. To use them, run

    # On the server
    systemctl --user start nikau-server
	# On the client
    systemctl --user start nikau-client

A PolicyKit pop-up window will appear on both sides, asking for confirmation.

For starting the KVM switch automatically after (Wayland or X11) login, run

    systemctl --user daemon-reload     # (if you have just installed nikau)
	# On the server
    systemctl --user enable nikau-server.service
	# On the client
    systemctl --user enable nikau-client.service

## Client: Configuring the server address

Make sure that the environment variable `NIKAU_SERVER` is set to the IP
address or host name of the server. It's recommended to create a file
`$HOME/.config/environment.d/nikau.conf` that looks like this:

    NIKAU_SERVER=10.0.100.101

(After creating the file, make sure that the settings take effect by running
`systemctl --user daemon-reload`).

## Server: Customizing server behavior

For customization of key combinations and other details on the server, create
a file `$HOME/.config/nikau/server_environment` e.g. like this:

    NIKAU_SERVER_OPTS="--shortcut-goto leftctrl,leftalt,0= --shortcut-goto leftctrl,leftalt,1=$FINGERPRINT1 --shortcut-goto leftctrl,leftalt,2=$FINGERPRINT2"

... where the FINGERPRINTs are the (possibly abbreviated) client fingerprints
that you can find under `/root/.config/nikau/known_certs/$FINGERPRINT.pem`.
The above example lets you switch between 3 systems with ctrl-alt-0,
ctrl-alt-1, and ctrl-alt-2. (Note that the default modifier key for nikau is
just `leftalt`. I personally prefer `leftctrl,leftalt` to avoid switching
by mistake).

## PolicyKit rules and permissions

Nikau needs to run as root using systemd *system* services called
`nikau-server@$UID.service` and `nikau-client@UID.service`, respectively,
started on behalf of the user with the respective `UID`.  Users can control
them with the systemd *user* services `nikau-server.service` and
`nikau-client.service`, respectively.

Starting and stopping the system services requires privilege escalation, which
is achieved via PolicyKit. For security reasons, the nikau services shouldn't
continue running after the user who started them has logged out. Therefore the
package ships a polkit rule file that allows the active user to stop the
nikau service without password. Starting the service still requires
authentication.

# Security considerations

Quoting from the [project website:](https://nikau.nickbp.com/):

> This software has NOT undergone any security review or audit. Use is at your
> own risk. See also terms and conditions of the licence. 
> 
> Nikau's *purpose* is to collect keystrokes and clipboards and send them over
> the network between machines. This can include passwords and other sensitive
> information. You must decide whether this is an acceptable risk for you. 
> 
> Assuming no flagrant bugs in Nikau or its dependencies, all communication is
> TLS-encrypted, with certificate-based authentication following a
> "prompt-once" model similar to OpenSSH. New connections must be approved
> bidirectionally, on both the client and the server, before the connection
> can proceed. However, even with encrypted channels, timing information could
> still be inferred from the event stream.
> 
> In order to allow direct access to uinput devices, the client and server
> must both be run as root (e.g. via sudo).

Note that **sudo** doesn't pass the `XAUTHORITY` and `DISPLAY` environment
variables by default, making clipboard sharing non-functional. In this case,
nikau will print the log message "Disabled system clipboard support: Failed to
set up X11 API context".

# Remarks

Users of other software KVM switches such as **synergy** and its descendants
like **barrier** or **input-leap** will notice a couple of differences in
daily use. They are caused by the fact that nikau uses the kernel's `uinput`
interface, while the other tools use interfaces of the graphical environment
(X11 / Wayland). The most important differences are:

- Nikau works between Linux systems only. No support for Windows or MacOS.
- KVM switching by moving the mouse pointer to the edge of the screen, as in
  **synergy**, does not work. The only way to switch between systems is to use
  the configured key combination (`LeftAlt-PageDown` by default).
- Nikau allows controlling the entire input of the client. This includes text
  consoles. It is even possible to switch consoles on the client by typing
  `Ctrl-Alt-f<x>` on the server.
- Nikau does not inhibit screen lock of the GUI on the server system (which is
  a good thing). It continues to work if the server screen is locked.
  In principle it continues to work even after the user who started it has
  logged out. The systemd units shipped in this package help avoiding that.
openSUSE Build Service is sponsored by