Using the scallion plug in

The scallion plug-in is used to experiment with the Tor anonymity network. The plug-in is a wrapper around Tor's source code, and utilizes code from the browser plug-in, the filetransfer plug-in, and the torrent plug-in to transfer data across the anonymity network and measure performance characteristics.

The resource/scallion-hosts directory of the source distribution contains sample network configurations that work with Scallion, to get started with Tor experimentation.

Scalability

The maximum memory requirements of our included sample network configurations are given below. Also included is the smallest possible EC2 instance required to run these configurations, as a convenience for selecting an EC2 instance type for Running Shadow on EC2.

Scallion Network Sizes and Memory Requirements

Size	Number of Nodes	RAM (GiB)	EC2 Instance
tiny	20 relays, 200 clients	< 4	m1.large
small	50 relays, 500 clients	< 16	m1.xlarge or m2.xlarge
medium	100 relays, 1000 clients	< 32	m2.2xlarge
large	250 relays, 2500 clients	< 64	m2.4xlarge

Argument Usage

<software [...] arguments="arg1 arg2 arg3 [...]" />

The arguments attribute of the software XML element specifies application arguments for configuring a node's instance of the plug-in. Each argument is separated by a space.

Usage:

1. the plug-in mode can be one of:
   • dirauth, for a Tor directory authority
   • relay, for a Tor non-exit relay
   • exitrelay, for a Tor exit relay
   • client, for a filetransfer HTTP client over a local Tor SOCKS proxy server
   • torrent, for a torrent P2P client over a local Tor SOCKS proxy server
   • browser, for a browser client over a local Tor SOCKS proxy server
2. weight, the bandwidth weight that should appear in the Tor consensus for this relay, in KiB
3. rate, the global rate limit for this Tor in bytes, passed as Tor's --BandwidthRate option
4. burst, the global burst limit for this Tor in bytes, passed as Tor's --BandwidthBurst option
5. torrc, the path to the torrc file for this Tor, passed as Tor's -f option
6. datadir, the path to the base data directory for this Tor, passed as Tor's --DataDirectory option
7. geoip, the path to the geoip file for this Tor, passed as Tor's --GeoIPFile option
8. clientargs, if the first argument was client, torrent, or browser, then the required arguments for each of those plugins should be appended to the above options

Example

Here is an example XML file that contains each type of Tor node possible to configure:

<!-- our network -->

<cluster id="vnet" bandwidthdown="1024" bandwidthup="768" />
<link clusters="vnet vnet" latency="60" jitter="20" packetloss="0.0" />

<!-- the plug-ins we will be using -->

<plugin id="filex" path="~/.shadow/plugins/libshadow-plugin-filetransfer.so" />
<plugin id="torrent" path="~/.shadow/plugins/libshadow-plugin-torrent.so" />
<plugin id="scallion" path="~/.shadow/plugins/libshadow-plugin-scallion.so" />

<!-- the length of our experiment in seconds -->

<kill time="1800" />

<!-- our services -->

<software id="fileserverapp" plugin="filex" time="1" arguments="server 80 ~/.shadow/share/" />
<software id="webserverapp" plugin="filex" time="1" arguments="server 80 ../browser-example/" />
<software id="torrentauthapp" plugin="torrent" time="1" arguments="authority 5000"/>

<node id="fileserver" software="fileserverapp" bandwidthdown="102400" bandwidthup="102400" />
<node id="webserver" software="webserverapp" bandwidthdown="102400" bandwidthup="102400" />
<node id="torrentauth" software="torrentauthapp" bandwidthdown="102400" bandwidthup="102400" />

<!-- our Tor network infrastructure -->

<software id="authorityapp" plugin="scallion" time="1" arguments="dirauth 1024 1024000 1024000 ./authority.torrc ./data/authoritydata ~/.shadow/share/geoip" />
<software id="exitapp" plugin="scallion" time="60" arguments="exitrelay 1024 1024000 1024000 ./exit.torrc ./data/exitdata ~/.shadow/share/geoip" />
<software id="relayapp" plugin="scallion" time="60" arguments="relay 1024 1024000 1024000 ./relay.torrc ./data/relaydata ~/.shadow/share/geoip" />

<node id="4uthority" software="authorityapp" />
<node id="exit" software="exitapp" quantity="2" />
<node id="relay" software="relayapp" quantity="2" />

<!-- our Tor clients -->

<software id="fileclientapp" plugin="scallion" time="600" arguments="client 1024 1024000 1024000 ./client.torrc ./data/clientdata ~/.shadow/share/geoip client single fileserver 80 localhost 9000 10 /1MiB.urnd" />
<software id="browserclientapp" plugin="scallion" time="600" arguments="browser 1024 1024000 1024000 ./client.torrc ./data/clientdata ~/.shadow/share/geoip webserver 80 localhost 9000 6 /index.htm" />
<software id="torrentnodeapp" plugin="scallion" time="600" arguments="torrent 1024 1024000 1024000 ./client.torrc ./data/clientdata ~/.shadow/share/geoip torrent node torrentauth 5000 localhost 9000 6000 1MB" />

<node id="fileclient" software="fileclientapp" />
<node id="browserclient" software="browserclientapp" />
<node id="torrentnode" software="torrentnodeapp" quantity="3" />

From the resource/scallion-example directory, save this file as mytor.xml and run it like:

scallion -y -i mytor.xml