Counterpath offers a free NAT solution for all their Softphones.


Installation Help

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> -pxtunnels' command.

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

password CHAR(64) NOT NULL,
) 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 # 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:


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'.


  • Whatever you choose as your port in your xtunnels.sh must be entered in along with the address in your Xtunnels config section of Xlite as follows: server.com:portno
  • When testing various port numbers etc, you may need to restart your softphone. A simple shutdown and restart of the softphone may fix the issue.
  • If you don't have the command "md5" on your linux box, you can grab it here: http://www.fourmilab.ch/md5/
  • Be sure to change the log level to something other than "debug". As calls are made through Xtunnels your log file will start to eat up your disk space fairly quickly.
Created by: imcdona, Last modification: Tue 19 of Jun, 2007 (22:52 UTC)
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+