pyhoca-cli(1)

📦
version 0.6.1.3 · 3 versions
, in debian trixie, fedora 43, fedora 44, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🫶 pyhoca-cli 🫶

okay bestie, welcome to the X2Go Application manual, section pyhoca-cli(1). This is the whole entire page and it's a long one, so grab a snack 🍓 and let's go.

✨ NAME ✨

pyhoca-cli — the X2Go command line client, written in Python. Yes, Python. We love her. 💅

✨ SYNOPSIS ✨

pyhoca-cli [ options ] [[<user>@]<host>]

✨ DESCRIPTION ✨

So pyhoca-cli is out here trying to be a cross-platform (Windows, Mac OS X, Linux) X2Go command line client written in Python. And honestly? She ate. 🔥

You can use her to script remote X2Go sessions, or just, like, start / resume / shadow X2Go sessions straight from the command line in your terminal. No GUI needed, no vibes lost.

She supports a whole arsenal of command line options, and she can also parse x2goclient configuration files. Versatile queen. 👑

Wanna know more? Go read the included README and TODO for further info on pyhoca-cli. iykyk.

✨ COMMON OPTIONS ✨

pyhoca-cli accepts these common options, bestie:

  • -h, --help — Displays a help thing with every single available command line option, then exits. Your little map 🗺️
  • -V, --version — Spits out version info and dips.
  • --quiet — literally NO output to stdout at all. Not a crumb. 🤫
  • -d, --debug — Turns on debugging output. Chaos mode, but documented chaos.
  • --libdebug — Turns on the debugging code of the underlying Python X2Go module.
  • --libdebug-sftpxfer — (no description on this one in the original, she's just here, standing in the corner, serving silence 🧍)
  • --list-cmdline-features — Prints a machine-readable list of client-side features to STDOUT and exits. Oh and heads up: this one also enables the debugging code of Python X2Go's sFTP server code — that's very verbose, and it may even reveal promiscuous data. 👀

✨ SERVER / SESSION PROFILE ✨

okay so real talk: you have to give her either a server name or a pre-configured X2GoClient session profile, so she knows which X2Go server to connect to. If you give her neither of those two on the command line, pyhoca-cli will not start. Periodt. 🚫

  • --server <HOSTNAME_or_IP> — The legacy parameter. Still supported, but fr fr you should switch to the positional argument [<user>@]<host> — that's the preferred syntax now.
  • -P, --session-profile <SESSION_PROFILE_NAME> — The name of the session profile used to make the connection.
  • --non-interactive — Enforces non-interactive mode. No TTY interaction allowed during runtime. Zero chatting. 💀

✨ ACTIONS ✨

pyhoca-cli accepts exclusively one of the listed actions. Pick one, bestie, not a combo platter:

  • -N, --new — Starts a new X2Go session on the server. This is the default mode if you didn't explicitly specify any mode.
  • --try-resume — When given alongside --new, she tries to find and resume a session that was originally started with the same command. If that fails, she starts a new session. Finally. 🙈
  • -R, --resume <SESSION_NAME> — Resumes an existing X2Go session <SESSION_NAME> on the server. Special values for <SESSION_NAME>: NEWEST (resumes the youngest session) or OLDEST (resumes the session with the oldest timestamp).
  • -D, --share-desktop <USER>@<DISPLAY> — Shares an X2Go session on the remote server specified by <USER>@<DISPLAY>, where <USER> can be the same user starting the share mode session, or literally any other user that grants X2Go desktop sharing to the current user.
  • -S, --suspend <SESSION_NAME> — Suspends the running X2Go session <SESSION_NAME>. Special value for <SESSION_NAME>: ALL (suspends every session of the connected user).
  • -T, --terminate <SESSION_NAME> — Terminates the running X2Go session <SESSION_NAME>. Special value for <SESSION_NAME>: ALL (terminates every session of the connected user).
  • -L, --list-sessions — Lists the user's X2Go sessions on the server.
  • --list-profiles — Lists the user's X2Go session profiles configured on this client.
  • --from-stdin — For LightDM remote login integration: reads <username> <host[:port]> <command> <password> from STDIN and starts a new session, transfers a running session, or resumes a suspended session.
    • If there are several sessions running/suspended of the same desktop shell, then the first session found will be transferred/resumed. If there are several sessions running with a different desktop shell as session type (or even rootless sessions), none of these sessions will be touched — unless any of the discovered sessions match in the requested desktop shell (i.e. X2Go session type).
    • Heads up: this option is only available for the Linux version of pyhoca-cli. 🐧

✨ ACTION OPTIONS ✨

You can tweak your pyhoca-cli actions with these:

  • --clean-sessions — Cleans all of the user's suspended/running sessions before starting a new one on the named X2Go server. Fresh start energy ✨
  • --terminate-on-ctrl-c — Terminates the connected session when you press CTRL+C (instead of suspending the session). Choose violence. 💀

✨ X2GO OPTIONS ✨

  • -c, --command <CMD> — Command to run with --new mode on the server (default: xterm).
  • -l, -u, --username <USERNAME> — Username for the session (default: the currently logged in user).
  • --password <PASSWORD> — User password for this session. If a matching private SSH key is available, that one will be preferred for authentication. The cleartext password you specified at the command line will be masqueraded in the system's process list (Linux, MacOS). On Windows systems the usage of the --password option is forbidden. 🚫
  • --force-password — Enforces authentication with username and password, and prohibits SSH public/private key authentication.
  • -p, --remote-ssh-port <R_PORT> — Remote X2Go server's SSH port (default: 22).
  • -i, -k, --ssh-privkey <SSH_PRIVKEY> — Use the file <SSH_PRIVKEY> as private key for SSH connections (default: ~/.ssh/id_rsa).
  • --add-to-known-hosts — Adds the RSA/DSA host key to ~/.ssh/known_hosts if the authenticity of the server can't be established (default: not set).
  • -A, --forward-sshagent — Enables SSH agent forwarding.
  • --sound {pulse|esd|none} — X2Go server's sound system (default: 'pulse').
  • -F, --share-local-folders <folder1>[,<folder2>[,...]] — A comma separated list of local folders that shall be made available in the remote X2Go session.
  • --printing — Use X2Go printing (default: disabled).
  • --share-mode {0|1} — Share mode for X2Go desktop sharing (0: view-only, 1: full access).
  • --kdrive — As graphical backend, use the X2Go Kdrive Xserver instead of the default NXv3 Xserver.
  • --auth-attempts {0,1,2,3,...} — Number of interactive authentication attempts in case authentication with the server fails (wrong password? we've all been there 😭). A value that equals 0 disables interactive authentication completely, and requires that a private SSH key has been given on the command line or in the session profile, or that the --password command line option is used.

✨ BROKER OPTIONS ✨

If you want to retrieve X2Go session profiles from an X2Go Session Broker, use these bad boys:

  • --broker-url=<URL> — Specify the <URL> of the X2Go Session Broker. pyhoca-cli can access http:// and ssh:// style URLs.

Syntax of <URL> for HTTP brokerage:

http(s)://<user>:<password>@<hostname>:<port>/path/to/broker

Syntax of <URL> for SSH brokerage:

ssh://<user>:<password>@<hostname>:<port>/usr/bin/x2gobroker (or any executable that provides the broker via SSH).
  • --broker-password <password> — Session broker password for retrieving session profiles from the X2Go Session Broker. The cleartext password specified at the command line will be masqueraded in the system's process list (Linux, MacOS). On Windows systems the usage of the --broker-password option is forbidden. 🚫
  • --broker-cacertfile=</path/to/cafile.crt> — NOT IMPLEMENTED YET: Specify a special (self-signed) root-CACert file that shall get used when connecting to an X2Go Session Broker via https (SSL). (Not implemented, yet).
  • --broker-noauth — NOT IMPLEMENTED YET: The X2Go Session Broker is accessible without authentication.
  • --auth-id=<USERNAME> — NOT IMPLEMENTED YET: Use this <USERNAME> for authenticating against the X2Go Session Broker. This option mostly makes sense together with --broker-autologin or --broker-ssh-key. (Not implemented, yet).
  • --broker-autologin — NOT IMPLEMENTED YET: For SSH based X2Go Session Brokers. If an SSH agent is available or default key files exist, then try those for authentication against the X2Go Session Broker. (Not implemented, yet).
  • --broker-ssh-key=<SSHPRIVKEY> — NOT IMPLEMENTED YET: For SSH based X2Go Session Brokers. Full path to a valid SSH private key file. (Not implemented, yet).
bestie, notice how almost every single broker option says "NOT IMPLEMENTED YET"? Yeah. They're on the vision board. 🌈 Don't come for me, I'm just the messenger.

✨ SESSION OPTIONS (NXv3 or X2GoKDrive) ✨

  • -g, --geometry {<WIDTH>x<HEIGHT>|fullscreen|maximize} — Screen geometry (default: '800x600').
  • --dpi <DPI> — Launch the X2Go session's Xserver with resolution <DPI> (in dots per inch).
  • --xinerama — Enable Xinerama support for multi-head setups. Requires X2Go Server 4.1.0.0 (or newer).
  • -q, --link {modem|isdn|adsl|wan|lan} — Link quality (default: 'adsl').
  • -C, --clipboard-mode {none|server|client|both} — Clipboard mode (default: 'both' directions; other allowed values: 'none' for no clipboard support, 'client' to server copy+pasting only, 'server' to client copy+pasting only).
  • -t, --session-type {desktop|application} — Session type (default: 'application'). Note: there are also some auto-detection features for the session type built into the code. It might not always happen what you expect from setting this option. 🙈
  • --pack <PACK_METHOD> — Compression method (see below for possible values).
  • --kbd-layout {us|de|fr|...} — Use keyboard layout (default: 'null').
  • --kbd-type {auto|pc105/us|pc105/de|...} — Set keyboard type (default 'auto'). Use auto as the value here to enable X2Go's keyboard auto-detection code. ⌨️✨

🦋 BACKEND OPTIONS 🦋

okay so plot twist: pyhoca-gui supports transparent use of different data backends. For configuration, three backends are common: FILE, GCONF (Linux only) and WINREG (Windows only). The default backend currently is the FILE backend on all platforms.

For client-server communication, the only yet implemented backend is the STDOUT backend (as X2Go server commands print their execution results to /dev/stdout. (But other communication backends might be possible in the future...).

In the same way we are focusing on a successor of the current NX3 agent/proxy tool. A change in the proxy backend will also be implemented as a backend.

  • --backend-controlsession <CONTROLSESSION_BACKEND> — Force usage of a certain CONTROLSESSION_BACKEND (do not use this unless you know exactly what you are doing).
  • --backend-terminalsession <TERMINALSESSION_BACKEND> — Force usage of a certain TERMINALSESSION_BACKEND (do not use this unless you know exactly what you are doing).
  • --backend-serversessioninfo <SERVERSESSIONINFO_BACKEND> — Force usage of a certain SERVERSESSIONINFO_BACKEND (do not use this unless you know exactly what you are doing).
  • --backend-serversessionlist <SERVERSESSIONLIST_BACKEND> — Force usage of a certain SERVERSESSIONLIST_BACKEND (do not use this unless you know exactly what you are doing).
  • --backend-proxy <PROXY_BACKEND> — Force usage of a certain PROXY_BACKEND (do not use this unless you know exactly what you are doing).
  • --backend-sessionprofiles <SESSIONPROFILES_BACKEND> — Use given backend for accessing session profiles, available backends on Linux: FILES, GCONF; on Windows: FILES, WINREG.
  • --backend-clientsettings <CLIENTSETTINGS_BACKEND> — Use given backend for accessing the client settings configuration, available backends on Linux: FILES, GCONF; on Windows: FILES, WINREG.
  • --backend-clientprinting <CLIENTPRINTING_BACKEND> — Use given backend for accessing the client printing configuration, available backends on Linux: FILES, GCONF; on Windows: FILES, WINREG.
bestie listen — those first five "Force usage of a certain ..." options? The manpage says do not use this unless you know exactly what you are doing. That's not a vibe, that's a warning. 🙈 Respect it.

🌈 COMPATIBILITY OPTIONS 🌈

pyhoca-cli aims at being fully compatible with all command line options and session config files of the X2Go project's X2Go command line client x2goclient-cli as well as the x2goclient GUI. This is still work in progress. To achieve this, some compatibility options have already been added:

  • --port <R_PORT> — Compatibility option, synonymous to --remote-ssh-port <R_PORT>.
  • --ssh-key <SSH_PRIVKEY> — Compatibility option, synonymous to --ssh-privkey SSH_KEY.
  • --use-sound {yes|no} — Compatibility option, synonymous to --sound {pulse|none}.
  • --client-ssh-port <PORT> — Compatibility option for the x2goclient GUI. PyHoca-Cli (resp. Python X2Go) brings its own internal sFTP server. Thus, this option will be ignored.
lowkey iconic that --client-ssh-port gets to just vibe there and do literally nothing. It's ignored. That's the whole personality. 💅

🔥 NX COMPRESSION METHODS 🔥

As NX compression methods (--pack option) the following values are possible. The % character must be replaced by a digit 0-9.

  • plain pack: nopack, 8, 64, 256, 512, 4k, 32k, 64k, 256k, 2m, 16m
  • rdp fam: 256-rdp, 256-rdp-compressed, 32k-rdp, 32k-rdp-compressed, 64k-rdp, 64k-rdp-compressed, 16m-rdp, 16m-rdp-compressed
  • rfb gang: rfb-hextile, rfb-tight, rfb-tight-compressed
  • tight era: 8-tight, 64-tight, 256-tight, 512-tight, 4k-tight, 32k-tight, 64k-tight, 256k-tight, 2m-tight, 16m-tight
  • jpeg mode: 8-jpeg-%, 64-jpeg, 256-jpeg, 512-jpeg, 4k-jpeg, 32k-jpeg, 64k-jpeg, 256k-jpeg, 2m-jpeg, 16m-jpeg-%
  • png-jpeg combo: 8-png-jpeg-%, 64-png-jpeg, 256-png-jpeg, 512-png-jpeg, 4k-png-jpeg, 32k-png-jpeg, 64k-png-jpeg, 256k-png-jpeg, 2m-png-jpeg, 16m-png-jpeg-%
  • png girlies: 8-png-%, 64-png, 256-png, 512-png, 4k-png, 32k-png, 64k-png, 256k-png, 2m-png, 16m-png-%
  • rgb + rle: 16m-rgb-%, 16m-rle-%

🌸 SEE ALSO 🌸

/usr/share/doc/python-x2go

👑 AUTHOR 👑

This manual has been written by for the X2Go project (https://www.x2go.org) by

Mike Gabriel <mike.gabriel@das-netzwerkteam.de>

and that's the whole page, bestie 🫶 This is pyhoca-cli(1), Version 0.6.1.3, stamped Aug 2023 — go forth and ssh responsibly. periodt ✨🎀

📦 where this page comes from