Running the i3 Client Proxy

Configuring the client proxy

The client proxy does the following:

  1. Insert public triggers which can be used to access the machine on which the proxy is running.
  2. Contact other i3 client proxies (whose public triggers are present in the address book).
  3. Contact legacy IP servers through a i3 server proxy.

Important: The proxy requires root privileges to do packet capturing, so either run the proxy as root or using sudo (we recommend using sudo with standard security precautions) or as Administrator.

The configuration file for the proxy is in XML format (the default is in i3_client_proxy/i3-proxy.xml) and can be edited conveniently using XML editors. In this section, we discuss the important parameters in the XML configuration file, that will typically concern you.

1. parameters/i3_server: 

 <i3_server> 
  <addr> 169.229.50.82 5617 </addr>
  <closest_server> 0 </closest_server>
  <status_url> www.cs.berkeley.edu/~karthik/i3_status.txt </status_url>
  <use_tcp> 0 </use_tcp>
 </i3_server>

Contains the list of i3 servers to contact. Also you can specify whether you would like to connect to the i3 servers using TCP/UDP (UDP is the default, you can use TCP if your firewall does not allow UDP). You can also enable the option closest_server to let the code automatically choose the closest i3 server. The parameter status_url contains the URL of the status file of the I3 servers (the default URL contains the status of the planetlab i3 servers.

2. parameters/proxy/public_triggers: 

   <public_triggers> 
     <trigger> foo.i3  857c37e32f82492c9feb8e77aca297cc </trigger> 
     <trigger> home.nat.i3 757c37e32f82492c9feb8e77aca297cc </trigger> 
    </public_triggers>

Specifies the list of public triggers to be insert by the client proxy: each entry lists the I3 dns name followed by a random 128-bit key for security purposes. For each of these public triggers, you will also need to specify a 256-bit ID in the address book. Please note that the ID of a public trigger and the key used to insert have to follow a special constraint. You can generate such IDs and keys by running 'i3_client_proxy/gen_pub'. This command prints out a key to be added next to the i3 dns name in 'i3-proxy.xml' and a public trigger ID to be added to the address book. Ideally, one of these triggers should be 'your_machine_name.i3' for convenience.

In most cases, these are the only parameters you will need to modify. For a test run, start up your proxy. And then try the following command on your machine: 

 ping test.berkeley.i3

You should see a series of ping replies in response. You can also trying ping yourself (ie. one of the i3 dns names that you inserted, say foo.i3). If this works, then your basic system setup is fine. Otherwise, please make sure your system satisfies the requirements outlined before and check the Troubleshooting Tips.

The client proxy is written to be flexible to use, and here are the other important parameters you can use:

1. parameters/legacy_server_rules: 

 <legacy_server_rules> 
  <rule> *.in-addr.arpa NOREDIRECT </rule> 
  <rule> *.cnn.com sp1 </rule> 
  <rule> * sp2 </rule> 
 </legacy_server_rules>

The client proxy redirects traffic sent to certain legacy servers over i3 (through the server proxy). This section can be used to specify rules for deciding which legacy servers should have their traffic redirected. It is an ordered list, of the form <rule,action> where action = name of the server proxy you want to redirect the traffic to / "NOREDIRECT" if traffic to that legacy server should not be redirected. The default configuration file does not re-direct any traffic.

2. parameters/proxy/server_proxy_trigger: 

   <server_proxy_trigger> 
     <server_proxy name="sp1"> 26b9ac2eaa7fd42826b9ac2eaa7fd428a27288bd3758396f </server_proxy> 
    </server_proxy_trigger>

Specifies the public trigger of the server proxies referred to in the legacy_server_rules section. Note: If a server proxy is referred to in the legacy_server_rules section, it should have a entry in this section.

3. parameters/proxy/addr_book: 

   <addr_book> i3_addr_book.txt </addr_book>

Specifies the location of the address book (which is a mapping from i3 dns names to their public triggers). This is meant to play the role of the /etc/hosts file.

4. parameters/proxy/enable_hashed_urls: 

   <enable_hashed_urls> 0 </enable_hashed_urls>

If the public trigger for an i3 dns name is not specified in the address book, the default action is to return a DNS 'No Name Found' message. If this option is set to 1, then the proxy applies a hash function on the dns name to compute the public trigger. This option is provided for convenience, but is inherently insecure in a open system. Please leave this option at 0 unless you are sure.

5. parameters/proxy/authentication: 

   <authentication> 
     <public_key_file> public.key </public_key_file> 
     <private_key_file> private.key </private_key_file> 
    </authentication>

The server proxy requires authentication before it will redirect traffic for the client proxy. The public key file and private key file should be specified in this section (you can generate one by running './gen_key username [public_key_file] [private_key_file]').

6. parameters/proxy/tun: 

   <tun> 
     <addr> 1.0.0.1 </addr> 
     <mtu> 1200 </mtu> 
     <path> /dev/net/tun </path> (Linux only)
     <name> tun0 </name> (Linux only)
     <rt_table_name> tuntab </rt_table_name> (Linux only)
    </tun>

Specifies tun parameters, like the address to be allocated to the tun interface (make sure this is an unused IP address range: 1.0.0.0/8 works for most configurations).

7. parameters/proxy/fake_addr_range: 

   <fake_addr_range> 
     <start> 1.0.0.4 </start> 
     <mask> 255.0.0.0 </mask> 
    </fake_addr_range>

This parameter can be used to specify the IP address range which should be used for allocating IP addresses for faking to the client.

8. parameters/proxy/status_files: 

   <status_files> 
     <pub_dns> pub_dns </pub_dns> 
     <fake_dns> fake_dns </fake_dns> 
     <id_list> id_list </id_list> 
    </status_files>

This parameter is used for debugging: periodic status information is printed out in these files.

9. parameters/proxy/fake_log: 

   <fake_log> fake.log </fake_log>

This file is used for "remembering" fake IP address to i3 address mapping.

10. parameters/proxy/iptables_cmd, parameters/proxy/ip: (Linux only)

   <iptables_cmd> /sbin/iptables </iptables_cmd> 
   <ip_cmd> /sbin/ip </ip_cmd>

The command used to invoke iptables and ip on your system.

Apart from these parameters, the client proxy also accepts the following command-line arguments:

  1. '-h': Print help information.
  2. '-a': Use specified ip-address as host-address. In most configurations, the hostname should resolve to the external IP address. However, on some systems, the hostname is set to localhost which resolves (usually) to 127.0.0.1. In such cases, the external IP address can be passed on the command line so that the proxy can use it to insert triggers etc. Note: If the proxy is behind a NAT, then the locally unique NAT-allocated address can also be used.
  3. '-f: Use alternative proxy-config-file - default is 'i3-proxy.xml'
  4. '-p': For efficieny purposes, it is preferable to insert triggers on a "close-by" i3 server. The prefix for private triggers inserted by the proxy can be set using this command line argument.
  5. '-c': Cold start (flush the fake log file before it starts).