1pyhoca-cli(1) X2Go Application pyhoca-cli(1)
2
6 pyhoca-cli - X2Go command line client written in Python
7
9 pyhoca-cli [ options ] [[<user>@]<host>]
10
12 pyhoca-cli aims to be a cross-platform (Windows, Mac OS X, Linux) X2Go
13 command line client written in Python.
14 You can use it for scripting remote X2Go sessions or simply starting,
16 resuming or shadowing X2Go sessions from the command line in a termi‐
17 nal.
18 It supports versatile command line options as well as parsing x2go‐
20 client configuration files.
21 See the included README and TODO for further information on pyhoca-cli.
23
25 pyhoca-cli accepts the following common options:
26 -h, --help
28 Display a help with all available command line options and exit.
29 -V, --version
31 Output version information and exit.
32 --quiet
34 No output to stdout at all!
35 -d, --debug
37 Enable debugging output.
38 --libdebug
40 Enable debugging code of the underlying Python X2Go module.
41 --libdebug-sftpxfer
43 --list-cmdline-features
45 Print a machine-readable list of client-side features to STDOUT
46 and exit. Enable debugging code of Python X2Go's sFTP server
47 code (very verbose, and it may even reveal promiscuous data).
48
50 You either have to specify a server name or a pre-configured X2GoClient
51 session profile to tell pyhoca-cli to what X2Go server to connect. py‐
52 hoca-cli will not start if neither of these two options has been given
53 on the command line.
54 --server <HOSTNAME_or_IP>
56 Legacy parameter, still supported, but using positional argument
57 [<user>@]<host>] should become your preferred syntax.
58 -P, --session-profile <SESSION_PROFILE_NAME>
60 The name of the session profile to be used to make the connec‐
61 tion.
62 --non-interactive
64 Enforce non-interactive mode. Avoid any TTY interaction during
65 runtime.
66
68 pyhoca-cli accepts exclusively one of the listed actions:
69 -N, --new
71 Start a new X2Go session on server (default mode if no mode is
72 explicitly specified).
73 --try-resume
75 When given with --new , try finding and resuming a session
76 originally started with the same command. If that fails, start a
77 new session, finally.
78 -R, --resume <SESSION_NAME>
80 Resume existing X2Go session <SESSION_NAME> on server. Special
81 values for <SESSION_NAME> are ,,NEWEST'' (will resume youngest
82 session) or ,,OLDEST'' (resume session with oldest timestamp).
83 -D, --share-desktop <USER>@<DISPLAY>
85 Share an X2Go session on the remote server specified by <US‐
86 ER>@<DISPLAY>, whereas <USER> can be the same user that is
87 starting the share mode session or any other user that grants
88 X2Go desktop sharing for the current user.
89 -S, --suspend <SESSION_NAME>
91 Suspend running X2Go session <SESSION_NAME>. A special value for
92 <SESSION_NAME> is ,,ALL'' (will suspend all sessions of the con‐
93 nected user).
94 -T, --terminate <SESSION_NAME>
96 Terminate running X2Go session <SESSION_NAME>. A special value
97 for <SESSION_NAME> is ,,ALL'' (will terminate all sessions of
98 the connected user).
99 -L, --list-sessions
101 List user's X2Go sessions on server.
102 --list-profiles
104 List user's X2Go session profiles configure on this client.
105 --from-stdin
107 For LightDM remote login integration: read <username>
108 <host[:port]> <command> <password> from STDIN' and start a new
109 session, transfer a running session or resume a suspended ses‐
110 sion.
111 If there are several sessions running/suspended of the same
113 desktop shell, then the first session found will be trans‐
114 ferred/resumed. If there are several sessions running with a
115 different desktop shell as session type (or even rootless ses‐
116 sions) none of these session will be touched unless any of the
117 discovered sessions match in the requested desktop shell (i.e.
118 X2Go session type).
119 This option is only available for the Linux version of pyhoca-
121 cli.
122
124 pyhoca-cli actions can be tweaked by these options:
125 --clean-sessions
127 Clean all of the user's suspended/running sessions before start‐
128 ing a new one on the named X2Go server.
129 --terminate-on-ctrl-c
131 Terminate the connected session when pressing CTRL+C (instead of
132 suspending the session).
133
135 -c, --command <CMD>
136 Command to run with --new mode on server (default: xterm).
137 -l, -u, --username <USERNAME>
139 Username for the session (default: currently logged in user).
140 --password <PASSWORD>
142 User password for this session. If a matching private SSH key is
143 available this one will be preferred for authentication. The
144 cleartext password that has been specified at the command line
145 will be masqueraded in the systems process list (Linux, MacOS).
146 On Windows systems the usage of the --password option is forbid‐
147 den.
148 --force-password
150 Enforce authentication with username and password, prohibit SSH
151 public/private key authentication.
152 -p, --remote-ssh-port <R_PORT>
154 Remote X2Go server's SSH port (default: 22).
155 -i, -k, --ssh-privkey <SSH_PRIVKEY>
157 Use file <SSH_PRIVKEY> as private key for SSH connections (de‐
158 fault: ~/.ssh/id_rsa).
159 --add-to-known-hosts
161 Add RSA/DSA host key to ~/.ssh/known_hosts if authenticity of
162 server can't be established (default: not set).
163 -A, --forward-sshagent
165 Enable SSH agent forwarding.
166 --sound {pulse|esd|none}
168 X2Go server's sound system (default: 'pulse').
169 -F, --share-local-folders <folder1>[,<folder2>[,...]]
171 A comma separated list of local folders that shall be made
172 available in the remote X2Go session.
173 --printing
175 Use X2Go printing (default: disabled).
176 --share-mode {0|1}
178 Share mode for X2Go desktop sharing (0: view-only, 1: full ac‐
179 cess).
180 --kdrive
182 As graphical backend use the X2Go Kdrive Xserver instead of the
183 default NXv3 Xserver.
184 --auth-attempts {0,1,2,3,...}
186 Number of interactive authentication attempts in case authenti‐
187 cation with the server fails (wrong password?). A value that
188 equals 0 disables interactive authentication completely and re‐
189 quires that a private SSH key has been given on the command line
190 or in the session profile or that the --password command line
191 option is used.
192
195 In case you want to retrieve X2Go session profiles from an X2Go Session
196 Broker use the following options:
197 --broker-url=<URL>
199 Specify the <URL> of the X2Go Session Broker. pyhoca-cli can ac‐
200 cess http:// and ssh:// style URLs.
201 Syntax of <URL> for HTTP brokerage:
203 http(s)://<user>:<password>@<hostname>:<port>/path/to/broker
205 Syntax of <URL> for SSH brokerage:
207 ssh://<user>:<password>@<hostname>:<port>/usr/bin/x2gobroker (or
209 any executable that provides the broker via SSH).
210 --broker-password <password>
213 Session broker password for retrieving session profiles from the
214 X2Go Session Broker. The cleartext password that has been spec‐
215 ified at the command line will be masqueraded in the systems
216 process list (Linux, MacOS). On Windows systems the usage of the
217 --broker-password option is forbidden.
218 --broker-cacertfile=</path/to/cafile.crt>
220 NOT IMPLEMENTED YET: Specify a special (self-signed) root-CACert
221 file that shall get used when connecting to an X2Go Session Bro‐
222 ker via https (SSL). (Not implemented, yet).
223 --broker-noauth
225 NOT IMPLEMENTED YET: The X2Go Session Broker is accessible with‐
226 out authentication.
227 --auth-id=<USERNAME>
229 NOT IMPLEMENTED YET: Use this <USERNAME> for authenticating
230 against the X2Go Session Broker. This option mostly makes sense
231 together with --broker-autologin or --broker-ssh-key. (Not im‐
232 plemented, yet).
233 --broker-autologin
235 NOT IMPLEMENTED YET: For SSH based X2Go Session Brokers. If an
236 SSH agent is available or default key files exist then try those
237 for authentication against the X2Go Session Broker. (Not imple‐
238 mented, yet).
239 --broker-ssh-key=<SSHPRIVKEY>
241 NOT IMPLEMENTED YET: For SSH based X2Go Session Brokers. Full
242 path to a valid SSH private key file. (Not implemented, yet).
243
245 -g, --geometry {<WIDTH>x<HEIGHT>|fullscreen|maximize}
246 Screen geometry (default: '800x600').
247 --dpi <DPI>
249 Launch X2Go session's Xserver with resolution <DPI> (in dots per
250 inch).
251 --xinerama
253 Enable Xinerama support for multi-head setups. Requires X2Go
254 Server 4.1.0.0 (or newer).
255 -q, --link {modem|isdn|adsl|wan|lan}
257 Link quality (default: 'adsl')
258 -C, --clipboard-mode {none|server|client|both}
260 Clipboard mode (default: ´both´ directions, other allowed val‐
261 ues: ´none´ for no clipboard support, ´client´ to server
262 copy+pasting only, ´server´ to client copy+pasting only)
263 -t, --session-type {desktop|application}
265 Session type (default: 'application'). Note: there are also some
266 auto-detection feature for the session type built into the code.
267 It might not always happen what you expect from setting this op‐
268 tion.
269 --pack <PACK_METHOD>
271 Compression method (see below for possible values).
272 --kbd-layout {us|de|fr|...}
274 Use keyboard layout (default: 'null').
275 --kbd-type {auto|pc105/us|pc105/de|...}
277 Set Keyboard type (default 'auto'). Use auto as value here to
278 enable X2Go's keyboard auto-detection code.
279
281 pyhoca-gui supports transparent use of different data backends. For
282 configuration three backends are common: FILE, GCONF (Linux only) and
283 WINREG (Windows only). The default backend currently is the FILE back‐
284 end on all platforms.
285 For client-server communication the only yet implemented backend is the
287 STDOUT backend (as X2Go server commands print their execution results
288 to /dev/stdout. (But other communication backends might be possible in
289 the future...).
290 In the same way we are focusing on a successor of the current NX3
292 agent/proxy tool. A change in the proxy backend will also be implement‐
293 ed as a backend.
294 --backend-controlsession <CONTROLSESSION_BACKEND>
296 Force usage of a certain CONTROLSESSION_BACKEND (do not use this
297 unless you know exactly what you are doing).
298 --backend-terminalsession <TERMINALSESSION_BACKEND>
300 Force usage of a certain TERMINALSESSION_BACKEND (do not use
301 this unless you know exactly what you are doing).
302 --backend-serversessioninfo <SERVERSESSIONINFO_BACKEND>
304 Force usage of a certain SERVERSESSIONINFO_BACKEND (do not use
305 this unless you know exactly what you are doing).
306 --backend-serversessionlist <SERVERSESSIONLIST_BACKEND>
308 Force usage of a certain SERVERSESSIONLIST_BACKEND (do not use
309 this unless you know exactly what you are doing).
310 --backend-proxy <PROXY_BACKEND>
312 Force usage of a certain PROXY_BACKEND (do not use this unless
313 you know exactly what you are doing).
314 --backend-sessionprofiles <SESSIONPROFILES_BACKEND>
316 Use given backend for accessing session profiles, available
317 backends on Linux: FILES, GCONF; on Windows: FILES, WINREG.
318 --backend-clientsettings <CLIENTSETTINGS_BACKEND>
320 Use given backend for accessing the client settings configura‐
321 tion, available backends on Linux: FILES, GCONF; on Windows:
322 FILES, WINREG.
323 --backend-clientprinting <CLIENTPRINTING_BACKEND>
325 Use given backend for accessing the client printing configura‐
326 tion, available backends on Linux: FILES, GCONF; on Windows:
327 FILES, WINREG..SH COMPATIBILITY OPTIONS pyhoca-cli aims at being
328 fully compatible with all command line options and session con‐
329 fig files of the X2Go project's X2Go command line client x2go‐
330 client-cli as well as the x2goclient GUI. This is still work in
331 progress. To achieve this, some compatibility options have al‐
332 ready been added:
333 --port <R_PORT>
335 Compatibility option, synonymous to --remote-ssh-port <R_PORT>.
336 --ssh-key <SSH_PRIVKEY>
338 Compatibility option, synonymous to --ssh-privkey SSH_KEY.
339 --use-sound {yes|no}
341 Compatibility option, synonymous to --sound {pulse|none}.
342 --client-ssh-port <PORT>
344 Compatibility option for the x2goclient GUI. PyHoca-Cli (resp.
345 Python X2Go) brings its own internal sFTP server. Thus, this op‐
346 tion will be ignored.
347
349 As NX compression methods (--pack option) the following values are pos‐
350 sible. The % character must be replaced by a digit 0-9.
351 nopack, 8, 64, 256, 512, 4k, 32k, 64k, 256k, 2m, 16m 256-rdp, 256-rdp-
353 compressed, 32k-rdp, 32k-rdp-compressed, 64k-rdp 64k-rdp-compressed,
354 16m-rdp, 16m-rdp-compressed rfb-hextile, rfb-tight, rfb-tight-com‐
355 pressed 8-tight, 64-tight, 256-tight, 512-tight, 4k-tight, 32k-tight
356 64k-tight, 256k-tight, 2m-tight, 16m-tight 8-jpeg-%, 64-jpeg, 256-jpeg,
357 512-jpeg, 4k-jpeg, 32k-jpeg 64k-jpeg, 256k-jpeg, 2m-jpeg, 16m-jpeg-%
358 8-png-jpeg-%, 64-png-jpeg, 256-png-jpeg, 512-png-jpeg, 4k-png-jpeg 32k-
359 png-jpeg, 64k-png-jpeg, 256k-png-jpeg, 2m-png-jpeg, 16m-png-jpeg-%
360 8-png-%, 64-png, 256-png, 512-png, 4k-png 32k-png, 64k-png, 256k-png,
361 2m-png, 16m-png-% 16m-rgb-%, 16m-rle-%
362
364 /usr/share/doc/python-x2go
365
367 This manual has been written by for the X2Go project
368 (https://www.x2go.org) by
369 Mike Gabriel <mike.gabriel@das-netzwerkteam.de>
371Version 0.6.1.3 Aug 2023 pyhoca-cli(1)