Overview
DHARMA has a transport layer implementation that support all legacy TCP applications. That means, you can keep your TCP connections open when the network link is broken, network interfaces are switched, you suspend you laptop for traveling, etc. It also support dynamically changing interface binding for a particular TCP connection. It works on Linux and Windows (with, or without cygwin), although the functionality is limited in Windows. An ssh connection, remote X11 applications, large file downloading, messengers are all excellent application examples for DHARMA. Another advantage is that you only have to install DHARMA on the mobile node side ( i.e. your laptop, PDA, etc).
Install on Linux
DHARMA is written in pure python, and heavily depends on the twisted
python library. DHARMA has three parts, dharma, homeagent and portal.
dharma is the client side library, which starts a SOCKSv4 server on
127.0.0.1:1080 to give you the mobility support. If you do not plan to setup your own DHARMA server and would like to take advantage of hundreds of home agents from PlanetLab, this is the only thing you
would care about.
homeagent is the proxy service. The node running homeagent is
considered as part of the overlay network. It also should have reasonably
good network connection and long up-time.
portal service is a DNS-like service to help you find the appropriate
homeagent(s). It also does authentication to make sure that hopefully nothing
is abused.
You have to install these three services separately, though we don't separate the code apart. You are supposed to install the client-side code on your mobile host, (e.g. laptop), and server-side code on a host with static IP and reasonably good network connection.
Dependencies
Before install either three of the services, make sure you have python installed, and the version is higher than 2.2.1. Here is an example of checking python's version.
$ python -V Python 2.2.3
Also make sure that you have installed following packages: OpenSSH, OpenSSL, pyOpenSSL, pycrypto, twisted
Fedora Core 2/3 users: Step 1: Make sure you have dag repository ready. Please refer to the official FAQ, but here is a quick howto: (1) create file /etc/yum.repos.d/dag.repo as following: [dag] name=Dag RPM Repository for Fedora Core baseurl=http://apt.sw.be/fedora/$releasever/en/$basearch/dag(2) import the GPG key of dag repository: # cd /tmp # wget http://dag.wieers.com/packages/RPM-GPG-KEY.dag.txt # rpm --import RPM-GPG-KEY.dag.txt (3) update your yum # yum update Step 2: Install required packages: # yum install openssl python-devel \ python-twisted pycrypto pyOpenSSL tsocks In any case, if the above method fail, you can always try to install from rpms or source. I keep some of the rpms here. |
Gentoo users, you can get them by: # emerge sync # emerge -u twisted pyOpenSSL pycrypto openssh tsocks |
To check whether twisted has been successfully installed or not, try:
$ twistd --version twistd (the Twisted daemon) 1.3.0rc1
Copyright (c) 2000-2003 Matthew William Lefkowitz, all rights reserved.
Client Side Installation (dharma)
(1) Configure TSOCKS
tsocks is a transparent SOCKS proxying library. Version 1.8 beta 5 (latest version) is recommended. After installation, Gentoo users please configure the /etc/socks/tsocks.conf. For RH/FC users, the filename is probably /etc/socks.conf
#YMMV for the local network address configuration local = 10.0.0.0/255.255.255.0 server = 127.0.0.1
(2) Install DHARMA and nevow
# cd /tmp # wget http://dharma.cis.upenn.edu/dist/Nevow-0.2.0.tar.gz # wget http://dharma.cis.upenn.edu/dist/dharma-latest.tar.gz # tar zxvf Nevow-0.2.0.tar.gz # tar zxvf dharma-latest.tar.gz # cd nevow-0.2.0 # python setup.py install # cd .. # cd dharma-* # python setup.py install
If you don't want to setup your own home agents and decide to use PlanetLab, all installation is done. You can jump to the usage section directly.
Server Side Installation (homeagent, portal)
Download the tarball from http://dharma.cis.upenn.edu/dist/dharma-latest.tar.gz, and extract it to your favorate directory, change user to root, then run
# python setup.py install
Done!! Go to usage section to learn how to use it.
Usages
Configuration Folders
There are two important folders, config folder and log folder. By default, the config folder is at /etc/dharma/ and the log folder is at /var/log/dharma/. However, you do have the chance of moving them around, especially if you do not want to run the services as root. To move them, simply copy them to other places, and set the environment variables DHARMA_ETC and DHARMA_LOG pointing to the new place.
Local Side Usage (dharma)
The local side of DHARMA is a daemon, listening on 1080 and 1083 ports, binding for localhost access only.
Before you start, please create /etc/dharma/dharma.conf based on /etc/dharma/dharma.conf.sample. Basically, only username and password configuration is necessary. To take advantage of PlanetLab home agents, creating an account is necessary. It is as easy as dropping an email to maoy at cis.upenn.edu. Sometimes, anonymous access is also permitted for "promotion".
To start, do
$ dharma start dharma started. $
Note: You do not have to start dharma as root. But if you don't, you need to make sure that you have read permissions for files in /etc/dharma/, and write permissions for files in /var/log/dharma/
Up to now, there is a socksv4 server in your laptop listening on the 1080 port. To use it with any TCP applications, simply put tsocks before your command. Here is a couple of examples:
$ tsocks ssh -X maoy@eniac.seas.upenn.edu
$ tsocks gaim
$ tsocks wget http://www.kernel.org/pub/linux/kernel/v2.6/linux-2.6.0-test10.tar.bz2
IMPORTANT: To control all your current sessions and learn what is going on, start your favorate browser and visit http://localhost:1083/. This screenshot may give you some idea about what you should see in the browser.
You may be interested in /var/log/dharma/dharma.log if anything goes wrong.
Server Side Usage
(1) portal service
Basically, the portal service is an XML-RPC service running over https. The default service port is 7080. To run the portal service,
(i) You have to write a configuration file for it in /etc/dharma/portal.conf, which is to tell the client that to access a particular IP address, which homeagent you want to use. Read /etc/dharma/portal.conf.sample to get some idea. It's very straightforward.
(ii) The second thing you want to do is to generate keys for openssl. The script dharma_gen_ssl_keys is very helpful. Simply run it and answer several questions about the certification will do. The keys are put into /etc/dharma/ssl/.
(iii) run dharma_gen_ssh_keys to generate the host's public and private keys. Please do remember to provide an empty passphase. The keys are put into /etc/dharma/ssh/. Note that there might be some problems if the hostname is incorrectly configured. See whether hostname -f can give you a FQDN.
(iv) Create /etc/dharma/passwd based on /etc/dharma/passwd/sample to add/disable users and change password. The default user is anonymous with password anony.
Now, you are ready to run the portal service. To start, run portal start. To stop, run portal stop. Read the log file at /var/log/dharma/portal.log for detailed information. If you are paranoid about the port number, modify /etc/dharma/portal.tac
(2) homeagent service
The homeagent is a proxy service that listening on two ports, defaults are 1081 and 1082. If you decide to run the homeagent on the same node as the portal, you don't have to setup the ssl and ssh keys again. Otherwise, please repeat the (ii) and (iii) step in portal service setup, and copy the portal server's public key into /etc/dharma/ssh/ (otherwise the connection will not be authorized).
To start, run homeagent start; to stop, run homeagent stop. Read the log file at /var/log/dharma/homeagent.log for detailed information. If you are paranoid about the port number, modify /etc/dharma/homeagent.tac
Install on Windows
(0) Make sure you have Python 2.3 installed.
(1) Download and install twisted, pyopenssl, pycrypto, nevow. The executable installers can all be found here. Basically, install every EXE file in there.
(2) Download and install sockscap, and set the socks proxy to127.0.0.1, port 1080, socks version 4.
(3) Download the tarball from http://dharma.cis.upenn.edu/dist/dharma-latest.tar.gz, and extract it to c:\dharma. Add environment variables PYTHONPATH="c:\dharma", DHARMA_ETC="c:\dharma\etc", DHARMA_LOG="c:\dharma\log".( Here is how you add it on Windows XP.)
(4) Before you start, please create c:\dharma\etc\dharma.conf based on c:\dharma\etc\dharma.conf.sample. Only username and password configuration is necessary.
Make sure C:\python23\scripts is in your PATH. To start dharma, run
c:\dharma> twistd -oy c:\dharma\etc\dharma.tac
Now, the socks server on 1080 should have started, and there is a Web based interface on port 1083. Start your browser and visit http://localhost:1083 to access it.
To take advantage of DHARMA, simply start your application in SocksCap.
There is some ongoing work to make the installation process on windows easier. Stay tuned. Any problem, please flood our mailing list.
Copyright (c) 2003-2005 Yun Mao, University of Pennsylvania, all rights reserved.