1. Deploy XTunnels binaries from xtunnels.tar.gz to the destination directory, e.g. /usr/pkg/bin or /usr/local/bin.

For FreeBSD:
tar xpvzf XTunnels-2-FreeBSD.tar.gz -C /usr/local

For NetBSD:
tar xpvzf XTunnels-2-NetBSD.tar.gz -C /usr/pkg

For Linux:
tar xpvzf XTunnels-2-Linux.tar.gz -C /usr/local

2. Configure MySQL server to define a user account for XTunnels e.g. 'xtunnels' and create a new database, e.g. 'xtunnels'. Then make sure that you can connect the MySQL server from the XTunnels host via 'mysql -u <username> -p xtunnels' command.

3. Run the SQL script attached below to create 'users' table in 'xtunnels' database. This table contains the authentication data for XTunnels clients.

CREATE TABLE users (
   id INTEGER UNSIGNED NOT NULL AUTO_INCREMENT,
   name VARCHAR(60) NOT NULL,
   password CHAR(64) NOT NULL,
   PRIMARY KEY(id)
) TYPE = innodb;

4. Based on your environment, you may want to modify xtunnels.sh script, especially XTUNNELS_BIN and XTUNNELS_LOG variables as well as xtunnels command line options. XTunnels server does not have to run as root, but you have to provide sufficient permissions, such as writing to a log file etc. Based on your MySQL server location and settings, you may need to modify the following command line options:

--db-addr 127.0.0.1:3306      # database host
--db-name xtunnels            # database name
--db-user xtunnels            # database user
--db-pass password            # database password

--sock-intf <interface name>  # network interface to use for client sockets

For all other option inquiries run 'xtunnels --help' command.

6. Every XTunnels server has its own realm defined via command line. You may change it in xtunnels.sh script by modifying the line:

--serv-realm "xtunnels realm"

7. Before you connect XTunnels server with your client first time, you need to create a new user record in 'users' database table. The password hash is calculated via the following scheme:

MD5('<username>:<realm>:<password>')

For example, if the user name is 'tester', password is 'password' and the XTunnels realm is 'xtunnels realm', you can calculate a new password hash via the following command:

md5 -s "tester:xtunnels realm:password"

The output is MD5 ("tester:xtunnels realm:password") = 5fe1b55ac8338a44ecf522f8ae389710, i.e. you will run the following SQL statement:

INSERT INTO users (name, password) VALUES ('tester', '5fe1b55ac8338a44ecf522f8ae389710');

8. When you start XTunnels server via 'xtunnels.sh start' command, you should be able to connect the server with your client (tester:password). Please make sure you use XTunnels version 2 client, as the protocols version 1 and 2 are not compatible.

9. You may insert/remove/modify users in MySQL database "on the fly", without restarting XTunnels server.

10. For more information about XTunnels command line options, please run 'xtunnels --help'.

Drahos