Setting Up

Documentation / Contents - CyThrough

• Overview of CyThrough
  • What It Is
  • What It Is Not
  • The Three Programs
  • In This Book
• Setting Up
  • What You Need
  • Build and Install
  • Setup With the GUI
  • Setup Without the GUI
  • Lab Auth File
  • Hardware Display Attach
  • Check That It Works
  • Common Mistakes
• Using CyThrough
  • Connect and Catalog
  • Launch and Running
  • Materialize On Desktop
  • Published Apps Menu
  • Quality and Encryption
  • Stopping Apps and the Daemon
• Command Line
  • cythrough Viewer
  • cythroughd Daemon
  • cythrough-prefs Launcher
  • Password and Knock Order
  • Environment
• How the Protocol Works
  • Framing
  • Channels
  • HELLO and Auth
  • Catalog and Launch
  • Pixels and Input
  • Capabilities and Codecs
  • Manager and Backend
• Keys and Shortcuts
• Files and Paths
  • Client Conf
  • Daemon Conf
  • Catalog Cache
  • Desktop Launchers
• Copyright

Setting Up

You need a running cythroughd on the host that will publish apps, and a viewer (cythrough or cythrough-prefs) on the desk that will show them. Both sides can be the same machine for a loopback lab.

This page is the setup path. Day-to-day clicks are in Using CyThrough. Flags are in Command Line.

What You Need

• Built binaries: cythrough, cythroughd, and usually cythrough-prefs.
• On the server: either Xvfb (dummy-X, one private seat per launched app) or a hardware display you own (--hw).
• Auth: your OS login password on the server, or a lab --auth-file.
• Optional knock passphrase shared by client and daemon (crypto on).
• Write access under ~/.cyanotype/ for conf, catalogs, and run state.

You do NOT need polkit, D-Bus, or a system-wide multi-user daemon. v1 is personal: you own the X seat.

Build and Install

From a Blueprint tree:

./configure --prefix=/usr/local
make src/cythrough/cythrough src/cythrough/cythroughd \
     src/cythrough/cythrough-prefs
sudo make install

Or the recursive tree:

cd src/cythrough && ./configure.sh && make && make install

Confirm:

cythrough --version
cythroughd --version
which cythrough-prefs

Setup With the GUI

1. Start the daemon from prefs

Open CyThrough (cythrough-prefs) from the Toolchest or:

cythrough-prefs

Use the Server controls to start cythroughd (or start it in a terminal with --foreground while you learn). Empty knock field means crypto off for that standing choice; a passphrase enables SPA + AEAD.

2. Publish apps

On the server machine, edit Published Apps (local publish menu). Add entries for programs the daemon may exec (argv you choose). An empty publish menu means the catalog has nothing to offer.

3. Connect from the client desk

On Connect: host, user, password, optional knock secret. Connect. The Icon Catalog fills with published apps. Double-click one to launch.

4. Optional: Materialize

Right-click a catalog icon: Materialize On Desktop. That writes a private script (and on Linux a .desktop sidecar) so later launches skip the prefs window. See Using CyThrough.

5. Autostart (optional)

Prefs can write autostart on into ~/.cyanotype/cythroughd.conf so your session brings the daemon up with the desktop. Only enable that when the conf and knock story are already working by hand.

Setup Without the GUI

Daemon (lab, crypto off)

./auth_test write /tmp/cyauth tester secret
echo secret > /tmp/cypass
chmod 600 /tmp/cyauth /tmp/cypass
cythroughd -n --foreground --auth-file /tmp/cyauth

Publish lines live in ~/.cyanotype/cythroughd.conf (not CLI flags). Use cythroughd --list-apps to print the catalog once conf is filled.

Viewer (lab)

cythrough -n --connect 127.0.0.1 --user tester \
  --password-file /tmp/cypass --app xlogo

Catalog only (no X session on the client):

cythrough -n --connect HOST --user tester \
  --password-file /tmp/cypass --list-apps

Daemon with crypto and knock

# ~/.cyanotype/cythroughd.conf
knock_secret    cythrough-lab

cythroughd --foreground --auth-file /tmp/cyauth

cythrough --connect HOST --user tester --password-file /tmp/cypass \
  --knock-secret cythrough-lab --app xlogo

Without --auth-file the daemon uses OS auth (PAM login / crypt). Then --user must be a real login on that host.

Lab Auth File

A user named tester is not an OS account unless you created one. The file backend is for labs:

auth_test write /tmp/cyauth tester secret

Format is lab user:blake2b. Keep the file mode 0600. Production desks should use OS auth and leave --auth-file off.

Hardware Display Attach

Dummy-X (default) starts a private Xvfb per launched app. Hardware attach uses an existing display you own:

cythroughd -n --foreground --hw --display :0 --auth-file /tmp/cyauth

Do not point --display at someone else's live console. GL apps (Maya and friends) need the preload libs so glReadPixels runs after swap; cythroughd sets LD_PRELOAD / _RLDN32_LIST on exec when those libs are installed.

Check That It Works

• cythroughd --check-conf -- prints conf and exits.
• cythroughd --list-apps -- catalog without listening forever.
• cythrough --list-apps --connect HOST ... -- catalog login, writes ~/.cyanotype/cythrough-catalogs/<host>.conf on success.
• Launch a tiny app (xlogo, xeyes). Close the remoted window or Ctrl-C the viewer; use --stop when you want the daemon to kill owned apps.

Common Mistakes

• Crypto on, no knock_secret, and no -n: daemon refuses to start. Either put knock_secret in conf, pass --knock-secret, or use -n / empty knock in prefs for lab.
• --user tester with OS auth and no --auth-file: "password was not accepted" because tester is not a login.
• Pointing --hw --display at a seat you do not own.
• Expecting an already-running Maya on the glass to appear in the catalog. Publish means the daemon execs argv you configured.
• Forgetting Xvfb on a dummy-X server host.