[ english version ] [ version française ]

btun/btund user guide

Nicolas GUILLAUME
nicolas@guillaume-fr.net

Version 0.3
december 31, 2007

(Please don't hesitate to correct this article by posting comments)

Overview

btun and btund are two free pieces of software allowing outside access to a server that is protected by a firewall. It supports management of severeal channels and secure authentification.

Illustration:

Without btun
[ SVG source ]

For example, the target server does not propose a SSH access from the Internet but we want one. Or, you want to control the target server with VNC but you won't/can't open the 5900 port in its firewall.

btun installation

Please see the UtilsInstall for instructions for downloading and installing btun/btund.

Setting up btund

To use btun, an access to the target server (physical or not, it does not matter) is required. You don't have to be root.

In addition, you must have an other computer on which you control the firewall. It will act as a gateway between the target server and the computer that want take the control of it. So it has to stay online during the whole process, a small personnal server will perfectly serve the purpose. In the rest of the document, it will be referenced as my_host.

The first thing to do consist of opening the TCP port used by btun in the firewall of my_host. By default, btun use the port 12358/tcp. It is imperative that the target server can connect to this port. If it can't, simply change the port (-p option). The port 80 is a very good candidate as it is generaly opened to provide an HTTP connection to the target server.

Then you have to launch the btund daemon on my_host. If you run Slackware and have installed btun with the sclawkare package, just set /etc/rc.d/rc.btund executable: 

chmod +x /etc/rc.d/rc.btund

Beforehand, you will need to set up a configuration file which specify the list of users who have access to btun. By default this file is /etc/btund/users but you can indicate another path when starting up btund (-u option).

Adding user to this file is very easy, just use this script: 


$ btund_add_user.sh /etc/btund/users
Login: user login
Password: user passphrase

Usage

Just run btun on the target server, and then, when you want to control it, run btun again on any computer connected to the Internet (it can be my_host).

Note: you can use the daemon or screen tool to launch btun in background.

You will obtain something like this:

With btun
[ SVG source ]

The idea is very simple, the target server connects to my_host (and it's allowed by the firewall). Then, you get connected to my_host from anywhere to easly control the target.

Launching btun

The general command line is of the form: 

btun [options] user@my_host channel_name [-- command arg1 ... argn]

The channel name is what you want (for example: shell_on_computer1, X_on_computer2, …). The command 'command arg1 … argn' will be run by btun. Its standard output will be wired to the channel input and the channel ouput to its standard input. It let a lot of place for imagination.

The available options are the following:

  • -h: print help and quit.
  • -v: print version and quit.
  • -t: use a pseudo terminal for command execution.
  • -f <file>: read passhrase from 'file' (if 'file' is -, stdout is used) the file must contains the md5 hash of the user passphrase. It can be created using this script.
  • -p <port>: use 'port' instead of the default port (12358).
  • -s <name >: try to load the plugin named 'name'. Any number of plugin can be loaded, the data stream is processed by each plugin, in load order (usual plugins includes compress, xoror, http, tee, …).
  • -o <opt>: pass the option 'opt' to last plugin (loaded with -s).
  • -m: create a master/slave channel and request to be the master.
  • -u: create an unrestricted channel.
  • -r: create a restricted channel (default). Only the creator of the channel can get connected to it.
  • -a: create an autoclose channel. It means the channel will be automatically closed when there is only one user left.

The options -m, -u and -a will ONLY work if you are the first to join the specified channel.

Note: A master/slave channel is a channel in which the master send its data to every slave whereas each slave only send its data to the master. On the contrary, in a standard channel, everyone send its data to every one except it self.

To avoid typing your passphrase all the time, you can create a passfile with this script. Be aware , your passfile contains your passphrase, you MUST keep it secret. Especially, ensure you are the only one who can read it.

Remote shell

The easiest way to get a remote shell is the following:

On the target server: 

$ btun -t login@my_host shell1 -- bash

On any computer: 

$ btun login@my_host  shell1

Note : The order does not matter.

TCP/UDP tunnels

By combining netcat (netcat man page) or tcpmux and btun, it is possible to obtain UDP or TCP tunnels.

Here is an example for VNC:

On the target server: 

$ btun login@my_host vnc_channel tcpmux 127.0.0.1 5900

On any computer: 

$ btun login@my_host vnc_channel tcpmux 5900

It is also possible to create tunnels using SSH, see the next paragraph.

Btun and SSH

If the target server can connect it self with SSH or if you can run sshd, then you are able to use SSH through btun!

On the target server: 

# We connect the local daemon
$ btun login@my_host channel1 tcpmux 127.0.0.1 22

On any computer: 

# We simulate a local SSH server on port 2022
$ btun login@my_host channel1 tcpmux 2022

Then on this computer again, when you want to establish the SSH connection, type: 

$ ssh -p 2022 localhost

You benefit from the SSH encryption and all the other features provided by SSH such as tunneling, X forwarding…

Remote X apps

X forwarding

The easiest way to run X applications remotely is to use a TCP tunnel as we done it in previous paragraphs (but with the 6000 tcp port this time).

That is:

X with btun
[ SVG source ]

On the target server: 

# Simulate a local X server
$ btun login@my_host X1 tcpmux 6001

On any computer: 

# allow tcpmux to connect to the local X server
$ xhost +localhost
# Connect the local X server
$ btun login@my_host X1 tcpmux localhost 6000

On the target server again, when you want to execute some X apps: 

$ export DISPLAY=localhost:1
$ emacs &
$ xterm &

Note: this can be done with a remote shell.

X through SSH

You have to use SSH through btun as describing in the Btun and SSH paragraph and append the -X option to the ssh command line to enable X forwarding.

Btun and VNC

You need to have a local VNC server started on the target server. Of course, it doesn't have to be visible from outside. Then we create a TCP tunnel as usual:

On the target server: 

# Connect the local VNC server
$ btun login@my_host vnc_channel tcpmux 127.0.0.1 5900

On any computer: 

# Simulate a local VNC server
$ btun -f my_passfile login@my_host vnc_channel tcpmux 5900 & 
# And connect to it
$ vncviewer localhost

File transfer

Single transfer

On the recipient side (have to be executed first): 

$ btun -af my_passfile login@my_host transfer > destination_file

On the sender side: 

$ btun -f my_passfile login@my_host transfer < source_file

Multiple transfers

If you want to transfer more than one file, either you create a tarball and send it with the technic described above, or you can use scp/ftp through a btun tunnel.

Plugins

Plugins can be loaded into btun, it processes incoming and outcoming data. That is, this adds features such as compression, encryption, …

To load a plugin, type: 

# load plugin 'plug1' with args 'arg1' & 'arg2
$ btun -s plug1 -o arg1 -o arg2 login@my_host channel

# load severeals plugins
$ btun -s plug1 -o arg1 -o arg2 -s plug2 -o arg1 login@my_host channel

Note : If you use more than one plugin, you must specifiy the same list in the reverse order on the other tunnel side.

xoror

This plugin encrypts data with the xoror algorithm. It can take two arguments: the passphrase and the key. If not specified, default values are used. 

# encrypt data with 'my passphrase'
$ btun -s xoror -o 'my passphrase' login@my_host channel

compress

This plugin simply compresses data. It take the compression level as its first argument (between 0 (fast) and 9 (efficient), 9 is the default). 

$ btun -s compress login@my_host channel

tee

Dump all data transmitted on channel to disk. 

# dump data into file
$ btun -s tee -o file login@my_host channel

http

This plugin simulates an HTTP connection. 

# server side
$ btun -s http -o server -o Apache login@my_host channel

# client side
$ btun -s http -o client -o www.host.com -o Mozilla/5.0 login@my_host channel

Advices

Keep one (or more) rescue channels opened on target server. It will be useful to recover connection after a bad handling on the one hand and to create new channels on the other hand. The easiest is to keep one or two bash: 

$ screen
$ btun -t -f my_passfile login@my_host rescue_channel_1 -- bash & 
$ btun -t -f my_passfile login@my_host rescue_channel_1 -- bash & 
(Ctrl + a d)

Or with the daemon tool: 

$ daemon 'btun -t -f my_passfile login@my_host rescue_channel_1 -- bash'
$ daemon 'btun -t -f my_passfile login@my_host rescue_channel_2 -- bash'

Note: the passfile can be removed from disk once btun is started.