pyhoca-gui(1)

📦 version 0.6.1.1, in debian bookworm, epel 9, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

pyhoca-gui(1) · X2Go Application 🦋

✨ NAME ✨

pyhoca-gui — graphical X2Go client applet written in Python 💅

🎀 SYNOPSIS 🎀

pyhoca-gui [ options ]

💖 DESCRIPTION 💖

okay so bestie, pyhoca-gui is a cross-platform (Windows, MacOS X, Linux) graphical X2Go client applet, and the whole vibe is that it docks to your desktop's system tray. main character energy, but polite about it. 🫶

From your desktop's system tray you can start / resume / share pre-configured X2Go sessions. You can also manage all your pre-configured session profiles in the X2Go profile manager, and configure the basic setup of pyhoca-gui itself. it's giving "one little icon, so much power" 💅

pyhoca-gui uses the same set of config files (settings, printing and sessions in ~/.x2goclient) as the original X2Go Client application (by Heinz-M. Graesing and Oleksandr Schneyder) does. bestie behaviour, sharing the closet. 👯

On Windows systems pyhoca-gui uses the same set of Windows registry keys and values as the original X2Go Client application. no cap.

See the included README and TODO for further information on pyhoca-gui. 📚

🌈 COMMON OPTIONS 🌈

pyhoca-gui accepts the following common options:

  • -h, --help — Display a help with all available command line options and exit. ✨
  • -V, --version — Output version information and exit.
  • -d, --quiet — No output to stdout at all! Use this option on Windows!!! 🤫 (fr fr, on Windows use it)
  • -d, --debug — Enable debugging output. 🔍
  • --libdebug — Enable debugging code of the unterlying Python X2Go module.
  • --libdebug-sftpxfer — Enable debugging code of Python X2Go's sFTP server code (very verbose, and it may even reveal promiscuous data). 👀
yes, -d really is listed twice up there, once for --quiet and once for --debug. that's the original's whole thing. i don't make the rules, i just relay them 💀
  • -P, --session-profile — The name of the session profile to be used to make the connection. You can actually pass a komma-separated list of session profile names to this option. 👑
  • --remember-username — For profiles with interactive authentication, remember the last-used username. 🧠
  • --non-interactive — Run in non-interactive mode. This option requires the --session-profile option. It also sets the following options to true automagically:
    • --restricted-trayicon
    • --single_session_profile
    • --start-on-connect
    • --resume-all-on-connect
    • --exit-on-disconnect
    • --disconnect-on-suspend
    • --disconnect-on-terminate
  • --auto-connect — Connect sessions via SSH public key authentication on application startup, if possible. 🔑
  • --show-profile-metatypes — Show descriptive meta information on session profiles in menus (NOTE: this makes menus appear a bit more sluggish, use it mostly for debugging). 🐢
  • --single-session-profile — Disable support of handling multiple session profiles. Use together with the --session-profile cmdline parameter.
  • --tray-icon <your-logo> — Define an alternative system tray icon file (PNG files only, leave out file extension here, size 22x22 on Linux, 16x16 on Windows). 🎨
  • --tray-icon-connecting <your-logo-while-connecting> — Define an alternative system tray icon file while connecting to a server (PNG files only, leave out file extension here, size 22x22 on Linux, 16x16 on Windows). 🌸
  • --restricted-trayicon — Restrict functionality of pyhoca-gui's main session manager icon that is shown in the notification area / system tray. This switch limits the icon 's functionality to a right-click menu that allows one to raise the About window and exit the application. On left-click only a minimal session menu is shown. 🔒
  • --add-to-known-hosts — Automatically add host key fingerprint to .ssh/known_hosts in case of "authenticity of server can't be established" (without user interaction).
Handle this option with care: Using it lessens the security/integrity of your SSH client setup. ⚠️ bestie please, be careful with this one.
  • --start-on-connect — DEPRECATED: Start a session directly after authentication (only if no suspended sessions are available). This switch is now fully controlled from within the session profiles. This option itself remains here for compatibility with older versions of PyHoca-GUI. 👵
  • --exit-on-disconnect — Exit pyhoca-gui cleanly once a session has been disconnected. 👋
  • --resume-on-connect, --resume-newest-on-connect — DEPRECATED: After authentication directly auto-resume the newest available running/suspended session. This switch is now fully controlled from within the session profiles, resuming the newest session is the hard-coded default. However, you can influence the resuming behaviour with the next two command line options. This option itself remains here for compatibility with older versions of PyHoca-GUI. 👵
  • --resume-oldest-on-connect — After authentication directly auto-resume the oldest available running/suspended session. 🧓
  • --resume-all-on-connect — After authentication directly auto-resume all available running/suspended session. 🔥
  • --disconnect-on-suspend — Disconnect from a server if a session on that server has been suspended. 💤
  • --disconnect-on-terminate — Disconnect from a server if a session on that server has been terminated. 🪦
  • --display <hostname>:<screennumber> — Set the DISPLAY environment variable to <hostname>:<screennumber>. 🖥️

💜 BROKERAGE OPTIONS 💜

In case you want to retrieve X2Go session profiles from an X2Go Session Broker use the following options:

  • --broker-url=<URL> — Specify the <URL> of the X2Go Session Broker. pyhoca-gui can access http(s):// 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).

As a special <URL> you can type HTTP or SSH and then the application will provide a login window with a pre-formatted / schematic URL. ✨

  • --broker-password <password> — Session broker password for retrieving session profiles from the X2Go Session Broker. The cleartext password that has been specified at the command line will be masqueraded in the systems process list (Linux, MacOS). On Windows systems the usage of the --broker-password option is forbidden. 🚫
  • --broker-name <broker-name> — Provide a human readable name for the session broker. This name overrides the default broker name ("X2Go Session Broker") in the application's menus and notification bubbles. 💬
  • --broker-cacertfile CACERT_FILE — For https:// brokers with SSL certificates that have been signed against a self-signed root-CA, use this command line option to point to the self-signed root-CA certificate file. 📜
  • --broker-autoconnect — If this command line option is given the session broker authentication dialog will appear on application startup. 🚀

🎀 BRANDING OPTIONS 🎀

The pyhoca-gui provides some features that allow one to easily brand its appearance. Here are some options for tweaking the pyhoca-gui appearance and behaviour. ✨

  • --splash-image <your-splash-image> — Define an alternative splash image that gets shown on application startup (PNG files only, full path or filename as found in <share>/img). 🖼️
  • --about-image <your-about-window-image> — Define an alternative image for the application's About window (PNG files only, full path or filename as found in <share>/img). For those who distribute a customized version of this application: As PyHoca-GUI and its backend Python X2Go are licensed under AGPL, the About window is a good place for placing the download location of your modified version of the source code. 📖
  • --disable-splash — Do not show the application's splash screen. 🙈
  • --disable-options — Grey-out the Options menu item and thus disable the client configuration window. 🩶
  • --disable-printingprefs — Grey-out the Printing Preferences menu item and thus disable the client's printing preferences window. 🖨️
  • --disable-profilemanager — Grey-out the profile manager menu items and thus disable all profile management functionalities. 🗂️
  • --disable-notifications — Disable all applet notifications. 🔕
  • --logon-window-position <x-pos>x<y-pos> — Give a custom position for the logon window, use negative values to position relative to right/bottom border. 📍
  • --published-applications-no-submenus <number> — The number of published applications that will be rendered without submenus. 🔢

Oh and bestie, before we get into this next bit — you already know about the branding stuff. Now we're getting into the deep config machinery. Buckle up. 🎀

✨ BACKEND OPTIONS ✨

okay so this is the part where pyhoca-gui gets ✨flexible✨ — it supports transparent use of different data backends. For configuration, three backends are common: FILE, GCONF (Linux only) and WINREG (Windows only). And rn, the default backend is FILE on every single platform. No cap.

For client-server communication, the only backend implemented so far is the STDOUT backend — because X2Go server commands print their execution results to /dev/stdout. (But other communication backends might be possible in the future... 👀 not me manifesting.)

Same energy with the current NX3 agent/proxy tool: we're focusing on a successor. A change in the proxy backend will also be implemented as a backend. growth mindset fr fr 💅

  • --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 the given backend for accessing session profiles. Available backends on Linux: FILES, GCONF; on Windows: FILES, WINREG. 💖
  • --backend-clientsettings <CLIENTSETTINGS_BACKEND> — Use the given backend for accessing the client settings configuration. Available backends on Linux: FILES, GCONF; on Windows: FILES, WINREG. 💖
  • --backend-clientprinting <CLIENTPRINTING_BACKEND> — Use the given backend for accessing the client printing configuration. Available backends on Linux: FILES, GCONF; on Windows: FILES, WINREG. 💖
Notice how those last three are chill and helpful, and the first five are like "bestie put that down" 😭💀 The difference is real.

🧳 PORTABLE OPTIONS 🧳

For when you want your stuff to live somewhere else entirely. Main character relocation energy. 🦋

  • --client-rootdir <CLIENT_ROOTDIR> — Define an alternative location where to find plain text config files (default: <HOME>/.x2goclient). This option will set ,,--backend-profiles FILE'', ,,--backend-clientsettings FILE'' and ,,--backend-clientprinting FILE''. three-for-one slay ✨
  • --sessions-rootdir <SESSIONS_ROOTDIR> — Define an alternative location for session runtime files (default: <HOME>/.x2go).
  • --ssh-rootdir <SSH_ROOTDIR> — Define an alternative location for user SSH files (default: <HOME>/.ssh). 🔑

🪟 WINDOWS OPTIONS 🪟

There are some options that are only available on Windows, bestie: 💅

  • --start-xserver — Start an XServer (if available) before starting pyhoca-gui. The application will detect the best suitable XServer automatically if more than one XServer is installed on your system (currently known: Xming, Cygwin-X). 👑
  • --preferred-xserver <XSERVER_NAME> — Start either of the currently supported XServers: Xming, Cygwin-X and VcXsrv — make sure your preferred XServer is actually installed on your system (default and recommended is VcXsrv). ⭐
  • --start-pulseaudio — Start the PulseAudio server before starting pyhoca-gui. This option is needed to get X2Go audio working. However, it is not enabled by default. 🔈
  • --lang [en|de|nl|es] — Select the GUI language. 🌈

👀 SEE ALSO 👀

/usr/share/doc/pyhoca-gui

yeah that's it, go read the docs bestie 📚

💖 AUTHOR 💖

This manual has been written for the X2Go project by Mike Gabriel <mike.gabriel@das-netzwerkteam.de>. 🫶

and that's the whole page, bestie!! 🎀✨ This lil' icon is Version 0.6.1.1, dated Jan 2020, and it lives in section pyhoca-gui(1). Go forth and configure responsibly 💅🌟

📦 where this page comes from