1pyhoca-cli(1)                  X2Go Application                  pyhoca-cli(1)
2
3
4

NAME

6       pyhoca-cli - X2Go command line client written in Python
7

SYNOPSIS

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

DESCRIPTION

12       pyhoca-cli  aims to be a cross-platform (Windows, Mac OS X, Linux) X2Go
13       command line client written in Python.
14
15       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
19       It supports versatile command line options as  well  as  parsing  x2go‐
20       client configuration files.
21
22       See the included README and TODO for further information on pyhoca-cli.
23

COMMON OPTIONS

25       pyhoca-cli accepts the following common options:
26
27       -h, --help
28              Display a help with all available command line options and exit.
29
30       -V, --version
31              Output version information and exit.
32
33       --quiet
34              No output to stdout at all!
35
36       -d, --debug
37              Enable debugging output.
38
39       --libdebug
40              Enable debugging code of the underlying Python X2Go module.
41
42       --libdebug-sftpxfer
43
44       --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

SERVER / SESSION PROFILE

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
55       --server <HOSTNAME_or_IP>
56              Legacy parameter, still supported, but using positional argument
57              [<user>@]<host>] should become your preferred syntax.
58
59       -P, --session-profile <SESSION_PROFILE_NAME>
60              The  name  of the session profile to be used to make the connec‐
61              tion.
62
63       --non-interactive
64              Enforce non-interactive mode. Avoid any TTY  interaction  during
65              runtime.
66

ACTIONS

68       pyhoca-cli accepts exclusively one of the listed actions:
69
70       -N, --new
71              Start  a  new X2Go session on server (default mode if no mode is
72              explicitly specified).
73
74       --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
79       -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
84       -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
90       -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
95       -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
100       -L, --list-sessions
101              List user's X2Go sessions on server.
102
103       --list-profiles
104              List user's X2Go session profiles configure on this client.
105
106       --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
112              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
120              This option is only available for the Linux version  of  pyhoca-
121              cli.
122

ACTION OPTIONS

124       pyhoca-cli actions can be tweaked by these options:
125
126       --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
130       --terminate-on-ctrl-c
131              Terminate the connected session when pressing CTRL+C (instead of
132              suspending the session).
133

X2GO OPTIONS

135       -c, --command <CMD>
136              Command to run with --new mode on server (default: xterm).
137
138       -l, -u, --username <USERNAME>
139              Username for the session (default: currently logged in user).
140
141       --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
149       --force-password
150              Enforce authentication with username and password, prohibit  SSH
151              public/private key authentication.
152
153       -p, --remote-ssh-port <R_PORT>
154              Remote X2Go server's SSH port (default: 22).
155
156       -i, -k, --ssh-privkey <SSH_PRIVKEY>
157              Use  file  <SSH_PRIVKEY> as private key for SSH connections (de‐
158              fault: ~/.ssh/id_rsa).
159
160       --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
164       -A, --forward-sshagent
165              Enable SSH agent forwarding.
166
167       --sound {pulse|esd|none}
168              X2Go server's sound system (default: 'pulse').
169
170       -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
174       --printing
175              Use X2Go printing (default: disabled).
176
177       --share-mode {0|1}
178              Share mode for X2Go desktop sharing (0: view-only, 1:  full  ac‐
179              cess).
180
181       --kdrive
182              As  graphical backend use the X2Go Kdrive Xserver instead of the
183              default NXv3 Xserver.
184
185       --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
193

BROKER OPTIONS

195       In case you want to retrieve X2Go session profiles from an X2Go Session
196       Broker use the following options:
197
198       --broker-url=<URL>
199              Specify the <URL> of the X2Go Session Broker. pyhoca-cli can ac‐
200              cess http:// and ssh:// style URLs.
201
202              Syntax of <URL> for HTTP brokerage:
203
204              http(s)://<user>:<password>@<hostname>:<port>/path/to/broker
205
206              Syntax of <URL> for  SSH brokerage:
207
208              ssh://<user>:<password>@<hostname>:<port>/usr/bin/x2gobroker (or
209              any executable that provides the broker via SSH).
210
211
212       --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
219       --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
224       --broker-noauth
225              NOT IMPLEMENTED YET: The X2Go Session Broker is accessible with‐
226              out authentication.
227
228       --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
234       --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
240       --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

SESSION OPTIONS (NXv3 or X2GoKDrive)

245       -g, --geometry {<WIDTH>x<HEIGHT>|fullscreen|maximize}
246              Screen geometry (default: '800x600').
247
248       --dpi <DPI>
249              Launch X2Go session's Xserver with resolution <DPI> (in dots per
250              inch).
251
252       --xinerama
253              Enable  Xinerama  support  for  multi-head setups. Requires X2Go
254              Server 4.1.0.0 (or newer).
255
256       -q, --link {modem|isdn|adsl|wan|lan}
257              Link quality (default: 'adsl')
258
259       -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
264       -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
270       --pack <PACK_METHOD>
271              Compression method (see below for possible values).
272
273       --kbd-layout {us|de|fr|...}
274              Use keyboard layout (default: 'null').
275
276       --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

BACKEND OPTIONS

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
286       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
291       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
295       --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
299       --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
303       --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
307       --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
311       --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
315       --backend-sessionprofiles <SESSIONPROFILES_BACKEND>
316              Use  given  backend  for  accessing  session profiles, available
317              backends on Linux: FILES, GCONF; on Windows: FILES, WINREG.
318
319       --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
324       --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
334       --port <R_PORT>
335              Compatibility option, synonymous to --remote-ssh-port <R_PORT>.
336
337       --ssh-key <SSH_PRIVKEY>
338              Compatibility option, synonymous to --ssh-privkey SSH_KEY.
339
340       --use-sound {yes|no}
341              Compatibility option, synonymous to --sound {pulse|none}.
342
343       --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

NX COMPRESSION METHODS

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
352       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

SEE ALSO

364       /usr/share/doc/python-x2go
365

AUTHOR

367       This    manual   has   been   written   by   for   the   X2Go   project
368       (https://www.x2go.org) by
369
370       Mike Gabriel <mike.gabriel@das-netzwerkteam.de>
371
372
373
374Version 0.6.1.3                    Aug 2023                      pyhoca-cli(1)
Impressum