'\" -*- coding: utf-8 -*-
'\" vim:fenc=utf-8
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH x2gobroker 1 "Apr 2019" "Version 0.0.4.x" "X2Go Session Broker"
.SH NAME
x2gobroker{,-daemon,-ssh} \- Session Broker for X2Go
.SH SYNOPSIS
'nh
.fi
.ad l
\fBx2gobroker\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[
\fIoptions\fR
]
'in \n(.iu-\nxu
.ad b
.PP
.ad l
\fBx2gobroker-daemon\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[
\fIoptions\fR
]
'in \n(.iu-\nxu
.ad b
.PP
.ad l
\fBx2gobroker-ssh\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[
\fIoptions\fR
]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
\fBx2gobroker\fR (resp. \fBx2gobroker-daemon\fR) is a Python Tornado based implementation of the X2Go Session Broker API. \fBx2gobroker-ssh\fR is the same application but designed
for usage via SSH (as a command line tool).
.PP
The HTTP(S) implementation of \fBx2gobroker\fR is normally executed either through the host's init system or via the WSGI module in your httpd server. The SSH
implementation is executed by X2Go clients through SSH.
.PP
See the included README and TODO for further information on \fBx2gobroker\fR.
.SH GENERAL OPTIONS
\fBx2gobroker{,-daemon,-ssh}\fR accepts the following common options:
.TP
\*(T<\fB\-M, \-\-mode {HTTP|SSH}\fR\*(T>
Set X2Go Session Broker into HTTP or SSH mode. If this option is omitted, then SSH is the default mode.
If \fBx2gobroker-daemon\fR is used as executable name, then the default mode is HTTP(S).
.TP
\*(T<\fB\-C, \-\-config FILENAME\fR\*(T>
Specify an alternative configuration file name, default is: \fI/etc/x2go/x2gobroker.conf\fR.
.TP
\*(T<\fB\-d, \-\-debug\fR\*(T>
Enable debugging code. This also makes http\'s POST method available as GET method, which then allows it to test the
broker API through a normal web browser.
.TP
\*(T<\fB\-h, \-\-help\fR\*(T>
Display a help with all available command line options and exit.
.SH SSH MODE COMMAND LINE OPTIONS
\fBx2gobroker-ssh\fR, i.e., when run from the command line or via SSH, accepts/requires these additional options:
.TP
\*(T<\fB\-\-task {listsessions, selectsession, setpass, testcon}\fR\*(T>
Specify the either of the known broker tasks (listsessions, selectsession, setpass, testcon). This parameter
is compulsory, the command execution will fail if it is omitted.
.TP
\*(T<\fB\-\-user USERNAME\fR\*(T>
If \fBx2gobroker\fR is run by the `magic' user (the x2gobroker account by default), then the x2gobroker
is allowed to change its user context and do queries on behalf of the user specified with this parameter.
.TP
\*(T<\fB\-\-auth-cookie, \-\-auth-id AUTHENTICATION_COOKIE\fR\*(T>
It is possible to enforce a stronger authentication via an additional pre\-shared authentication cookie. This authentication
cookie must be stored in a client-side file so that X2Go Client can access it and then pass it on to the X2Go
Session Broker (via the X2Go Client option \-\-auth-id=<fullpath-to-file>) while authenticating against the broker.

The server-side cookie hash can be set in \fI/etc/x2go/x2gobroker.conf\fR (option: my-cookie). You have to set
the option require-cookie-auth to true to enable the additional cookie comparison in the X2Go Session Broker.
.TP
\*(T<\fB\-\-profile-id, \-\-sid SESSION_PROFILE_ID\fR\*(T>
For the \fIselectsession\fR task the session profile ID has to be given as an additional parameter.
.TP
\*(T<\fB\-\-backend BACKEND_NAME\fR\*(T>
Query another than the default broker backend.
.SH HTTP(S) DAEMON OPTIONS
\fBx2gobroker-daemon\fR in standalone HTTP(S) daemon mode accepts these additional options:
.TP
\*(T<\fB\-b, \-\-bind ADDRESS:PORT\fR\*(T>
The [address:]port that the Tornado http-engine will bind to (default: 127.0.0.1:8080).
.TP
\*(T<\fB\-D, \-\-daemonize\fR\*(T>
Fork this application to background and detach from the running terminal.
.TP
\*(T<\fB\-P, \-\-pidfile\fR\*(T>
Custom PID file location when daemonizing (default: \fI<RUNDIR>/x2gobroker/x2gobroker-daemon.pid\fR).
.TP
\*(T<\fB\-L, \-\-logdir\fR\*(T>
Directory where stdout/stderr will be redirected after having daemonized (default: \fI/var/log/x2gobroker/\fR).
.TP
\*(T<\fB\-D, \-\-drop\-privileges\fR\*(T>
If started as root, drop privileges to uid X2GO_DAEMON_USER and gid X2GO_DAEMON_GROUP (as configured
in \fI/etc/x2go/broker/defaults.conf\fR on systemd systems or \fI/etc/defaults/python-x2gobroker\fR
on SystemV systems).
.SH SECURITY NOTICE / DISCLAIMER
Users are advised to not misinterpret X2Go Session Broker's capabilities as a
security feature. Even when using X2Go Session Broker, it is still possible for
users to locally configure an X2Go Client with any settings they want, and
use that to connect. So if you're trying to keep users from running a
certain application on the host, using X2Go Session Broker to "lock" the
configuration is the *wrong* way. The users will still be able to run
that application by creating their own, local configuration file and
using that.
.PP
To keep users from running an application on the server, you have to use
\fIfilesystem permissions\fR on the X2Go Server. In the simplest case,
this means setting chmod 750 or 550 on the particular application on the
host, and making sure the users in question are not the owner and also
not a member of the group specified for the application.
.SH "FILES"
/etc/x2go/x2gobroker.conf, /etc/x2go/broker/* (configuration files)
.PP
/etc/default/python-x2gobroker, /etc/default/x2gobroker-daemon (environment for X2Go Session
Broker when run as a standalone daemon via SystemV or upstart)
.PP
/var/log/x2gobroker/* (log files of X2Go Session Broker)
.SH "SEE ALSO"
\fB/usr/share/doc/x2gobroker\fR
.SH AUTHOR
This manual has been written for the X2Go project by
Mike Gabriel <mike.gabriel@das-netzwerkteam.de>.