'\" -*- 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-testagent 8 "Apr 2020" "Version 0.0.4.x" "X2Go Session Broker"
.SH NAME
x2gobroker-testagent \- Session Broker for X2Go (Agent Test Utility)
.SH SYNOPSIS
'nh
.fi
.ad l
\fBx2gobroker-testagent\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-testagent\fR is a test utility for local/remote X2Go Session Broker Agents.
The \fBx2gobroker-testagent\fR has to run as super-user root.
.PP
The \fBx2gobroker-testagent\fR
tool is normally run on the machine that acts as the X2Go Session Broker.
.PP
The \fBx2gobroker-testagent\fR tries to connect to a local or remote X2Go Session Broker Agent.
X2Go Broker Agents are co-installed on X2Go Server hosts and support the broker in controlling
that X2Go Server.
.PP
The \fBx2gobroker-testagent\fR executes a test task on the broker agent.
The broker agent tries to switch to the given user's context and runs the given task on behalf of that user.
.SH COMMON OPTIONS
\fBx2gobroker-testagent\fR provides help on command line options:
.TP
\*(T<\fB\-h, \-\-help\fR\*(T>
Display a help with all available command line options and exit.
.SH REQUIRED OPTIONS
You can either list the broker agent's tasks that are available for testing:
.TP
\*(T<\fB\-\-list\-tasks\fR\*(T>
Render a list of available broker agent tasks. This list shows what can be tested. The capabilities
of the remote agent and the broker server's test code are compared and displayed.
.PP
Or run a given task on behalf of an X2Go user on a local or remote broker agent:
.TP
\*(T<\fB\-u, \-\-user, \-\-username\fR\*(T>
Instruct the broker agent to switch to this user's context when running the given task on
the local/remote host.
.TP
\*(T<\fB\-t TASK, \-\-task TASK\fR\*(T>
The task that shall be test-executed on the remote broker agent.
.SH REMOTE BROKER OPTIONS
The default mode for calling the X2Go Session Broker Agent is "LOCAL". Alternatively, remote broker
agents can be called via mode "SSH". For this, you additionally need to specify the below options:
.TP
\*(T<\fB\-H HOSTNAME, \-\-host HOSTNAME\fR\*(T>
Hostname to connect to via SSH for running remote broker agent test commands.
.TP
\*(T<\fB\-p PORT, \-\-port PORT\fR\*(T>
The TCP/IP port that the remote system's SSH daemon listens on (default: 22).
.SH SUPPLIMENTARY OPTIONS
For some tasks, you have to provide additional parameters.
.TP
\*(T<\fB\-A, \-\-add-to-known-hosts\fR\*(T>
When connecting to a remote broker agent via SSH, add the broker agent machine's SSH
host key to the list of known hosts (normally \fI/var/lib/x2gobroker/.ssh/known_hosts\fR).

This has to be done once per broker agent machine, that the X2Go Session Broker is supposed to connect
to.
.TP
\*(T<\fB\-\-session-id SESSION_ID\fR\*(T>
When testing the 'suspendsession' or the 'terminatesession' task, you have to additionally
give a session ID to test those tasks on.
.TP
\*(T<\fB\-\-pubkey PUBKEY_AS_STRING\fR\*(T>
Use your own provided SSH public key when testing the 'addauthkey' and the 'delauthkey' tasks.

.SH MISC OPTIONS
\fBx2gobroker-testagent\fR also accepts the following miscellaneous options:
.TP
\*(T<\fB\-d, \-\-debug\fR\*(T>
Enable debugging code.
.TP
\*(T<\fB\-C, \-\-config FILENAME\fR\*(T>
Specify an alternative configuration file name, default is: \fI/etc/x2go/x2gobroker.conf\fR.
.SH "FILES"
/etc/x2go/x2gobroker.conf, /etc/x2go/broker/* (configuration files)
.PP
/etc/x2go/broker/defaults.conf (environment for X2Go Session Broker)
.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>.