# xRun Control Utility

> ## Overview

> eXtremeDB xRun is a Python-based utility that allows launching, terminating and controlling the execution of eXtremeDB xSQL servers. xRun must be run on the same system as the xSQL servers. It is recommended to run xRun as a background process (a daemon, service, etc.). When the xRun service is launched, it is accessible through a web interface from any browser. The xRun web interface allows starting and stopping xSQL servers and to further monitor and control the servers’ execution. It is not currently possible to connect xRun to xSQL servers that have been started outside the xRun utility.

> xRun requires Python version 2.7 or 3.6 or greater.

> ## Configuring and executing xRun

> The xRun service itself is controlled through the JSON-formatted xrun.cfg configuration file. The file lists the xSQL servers managed by xRun along with the servers' parameters: the path to the servers’ configuration file, the working directory, and servers’ command-line arguments.

> In addition to the managed servers' information, the configuration file stores the xRun log-in data -- the user name and the SHA-512 encrypted password.

> xRun is executed from the command line as follows:

>     xrun.sh [-a|--address <host_address>] [-p|--port <port_number>] [-k|--keyfile <key_file>] [-c|--certfile <certificate_file>]

> The default interface is http://localhost:8989

> For example, the following command line executes xRun on the 198.168.2.22 host and makes it accessible via HTTP from the local network through the 9998 port:

>     xrun -a 192.168.2.22 -p 9998

> The service is accessible from the browser as: http://192.168.2.22:9998

> In order to use HTTPS to access the xRun service, it is necessary to specify the path to the SSL private key and the SSL certificate files:

>     xrun -a 104.19.40.101 -p 9998 -k key.dat -c certificate.dat

> The above example makes the xrun service accessible as https://104.19.40.101:9998

> Note that allowing public access to xRun is not recommended. If you want to allow users on the Internet to access the service on your internal network, it is recommended to configure SSH port forwarding. For example:

> 1. execute xRun locally:

>        xrun --address localhost --port 8989

> 2. create a tunnel:

>        ssh user@your-gateway-address -L:8989:localhost:8989

> 3. access xRun from the browser:

>        http://localhost:8989

> ## xRun passgen utility

> When launched for the first time, xRun requires users to create a user name and a password. The login information can be modified at a later time either through the xRun user interface (the current login credentials are necessary), or, alternatively via the server-side command-line `passgen` utility:

>     python3 passgen.py --login new-user_name --password password

> Note that there is no password requirements for running the passgen. The access is controlled through the host operating system authentication policies.