It says the fingerprint changed
Either the thing you are connecting to was rebuilt, or it is not the thing you connected to last time. The client will not continue until you say which. Clear the stored entry only if you know why it changed.
About twenty minutes
Get started
One workstation, one Connection Manager, one client. You can put the manager on the workstation itself to begin with and separate them later — nothing below changes when you do.
Step one
The workstation
On the machine you want to reach — Linux, macOS or Windows. It needs an NVIDIA GPU (or Apple silicon, on macOS) and somewhere to run as a service. AMD and Intel encoders are on the roadmap.
The same three steps everywhere — put the binary somewhere permanent, drop in the config file, have it start with the machine — with the platform's own way of starting things: systemd on Linux, a service on Windows, a LaunchAgent on macOS.
It also needs a licence before it lets anybody connect. A
30-day trial arrives by email: save it as
licence.key beside the config file, and the host checks it in with us
from then on.
On Linux
$ tar -xzf host-app-linux-x86_64.tar.gz $ sudo install -m 755 host-app /usr/local/bin/ $ sudo install -m 644 pam.d.example /etc/pam.d/generic-streaming-application $ sudo mkdir -p /etc/generic-streaming-application $ sudo cp host-app.conf.example /etc/generic-streaming-application/host-app.conf
That one also wants an X session and an NVIDIA driver with NvFBC and NVENC. The defaults are usable as they stand: media on UDP 6000, session setup on TCP 6443, and a self-signed certificate minted on first start that clients pin the first time they see it. Two keys are worth setting now, to tell this workstation which Connection Manager may send it people:
# /etc/generic-streaming-application/host-app.conf
broker_address = manager.internal:6443
trusted_broker_spki = <the fingerprint the manager prints at startup>
On Linux it runs as root. It signs people in against real system
accounts and starts their desktops, and PAM's password helper can only verify the
account of the process calling it — an unprivileged host would authenticate
exactly one user and reject every other correct password as if it were wrong.
# /etc/systemd/system/longview-host.service [Unit] Description=Longview workstation host After=network-online.target display-manager.service [Service] ExecStart=/usr/local/bin/host-app User=root # Its identity — and so the fingerprint clients have pinned — lives under # this HOME. A different one mints a new identity and re-prompts everybody. Environment=HOME=/root Restart=always RestartSec=2 [Install] WantedBy=multi-user.target
On Windows
> mkdir C:\ProgramData\generic-streaming-application > copy host-app.conf.example C:\ProgramData\generic-streaming-application\host-app.conf > host-app.exe service install # from an administrator terminal, with host-app.exe somewhere permanent
A service cannot capture a desktop — services run apart from anyone's session
— so this one starts the host in whoever is signed in at the console, as them,
starts it again if it stops, and follows the console when somebody else signs in. Its
log is host.log beside the config. Stop it with
sc stop GenericStreamingHost before replacing host-app.exe,
which it keeps open, and remove it with host-app.exe service uninstall.
Only the signed-in user can take control of a physical desktop; anyone else can watch
once they approve.
On macOS
$ sudo mkdir -p "/Library/Application Support/generic-streaming-application" $ sudo cp host-app.conf.example "/Library/Application Support/generic-streaming-application/host-app.conf" $ host-app agent install # as the user whose screen this is, with host-app somewhere permanent
That starts it now and at every login, in your own session, logging to
~/Library/Logs/generic-streaming-application/host.log. It needs
Screen Recording and Accessibility granted to
host-app itself in System Settings → Privacy & Security; macOS
asks for Screen Recording when somebody first connects. host-app agent uninstall
removes it.
Step two
The Connection Manager
Any Linux host with a route to the workstations. No GPU, and nothing else installed.
$ tar -xzf broker-app-linux-x86_64.tar.gz $ sudo install -m 755 broker-app /usr/local/bin/ $ sudo install -m 644 pam.d.example /etc/pam.d/generic-streaming-application # the same file the host uses $ sudo mkdir -p /etc/generic-streaming-application $ sudo cp broker.conf.example /etc/generic-streaming-application/broker.conf
# /etc/generic-streaming-application/broker.conf # How people prove who they are. `none` is the default and refuses every # password, which is the only safe thing for a missing setting to do. auth = pam # Which machines exist: host = NAME = CONTROL_ADDRESS,MEDIA_ADDRESS host = desk-1 = 10.0.0.10:6443,10.0.0.10:6000 host = desk-2 = 10.0.0.11:6443,10.0.0.11:6000 # Who may have them. A username, or @group resolved through NSS — so a # directory-backed deployment reuses the groups it already has. # With no allow lines at all, every authenticated user is offered every # machine; the first allow line switches that off for everybody. allow = @design = desk-1, desk-2 allow = sam = desk-2 # What clients are told the gateway is called. If people reach the manager # both from the internet and from inside your network, give both: the public # name for the first, the private address for the second. gateway_advertised = manager.example.com gateway_advertised_private = 10.0.0.5
Open the three things a client and a manager need between them:
$ sudo firewall-cmd --add-port=6443/tcp --permanent # clients sign in here $ sudo firewall-cmd --add-port=6500-6519/tcp --permanent # one port per live session $ sudo firewall-cmd --add-port=6500-6519/udp --permanent $ sudo firewall-cmd --reload
That port range is also the concurrency limit — twenty sessions as shipped, and
deliberately small enough to stay a firewall rule rather than becoming a policy.
Start it, and note the fingerprint it prints: that is the trusted_broker_spki
each workstation needs.
Step three
Connect
On your own machine. Point the client at the Connection Manager, not at a workstation.
$ client-app manager.internal
You will be asked to confirm the manager's fingerprint the first time, then for your username and password — your account as the Connection Manager knows it, checked by its PAM stack and so by whatever directory that uses. If you are entitled to more than one machine you get to pick; if you are entitled to one, it opens.
It says you have no machines
You authenticated, and no allow line covers your account or any group
you are in. The manager logs which groups it resolved for you, which is usually
enough to spot the mismatch.
The picture freezes and says so
That notice is the client telling you the stream has stopped and it is still waiting. Short interruptions recover by themselves. Past thirty seconds the session has probably ended and it will say that instead.
Something not behaving?
Both services log plainly to the journal, and most problems announce themselves there in a sentence rather than a stack trace. If one does not, send us that sentence.