View source for VNE/DNRouter

UCIS VNE DNRouter is a simple BGP and IP router and VPN tunnel application, running completely in userspace on both Windows and Linux platforms. It's built using the [[VNE]] library.

== Installing DNRouter ==
Download the files from http://oss.ucis.nl/vne/dnrouter/

== Running DNRouter on Windows ==
You can run the DNRouter.exe executable directly to start the router.

DNRouter can currently not run as a Windows Service directly. You can use the instructions described on http://support.microsoft.com/kb/137890 or some third party application to run the DNRouter.exe executable as a Windows Service.

You can also put a shortcut to the DNRouter.exe file in the Start Menu's Startup folder. This will, however, always show the console box.

If you need a tun/tap network device to talk to the host OS, you need to install the OpenVPN tun/tap drivers first, either from http://oss.ucis.nl/vne/tuntapwin/ (download all files, run addtap.bat), or by installing OpenVPN or Tinc VPN. You can put the windows network interface name in the router/interfaces/tuntap/@ifname configuration.

== Running DNRouter on Linux ==
Use [http://www.mono-project.com/ Mono] to run DNRouter.exe (eg: mono DNRouter.exe). Using Wine with the Microsoft .Net framework may also work, but is not recommended. You should then somehow make it start when the system boots. This is outside of the scope of this document, but you may want to take a look at [http://articles.techrepublic.com.com/5100-22_11-5307707.html daemontools] (not the virtual CD/DVD tool!), [http://supervisord.org/ Supervisord], [http://upstart.ubuntu.com/ Upstart] or the daemon utility.

Note that you can speed up [[QuickTun]] encryption operations considerably by providing a native [[NaCl]] library. To build one, follow the steps described at [http://wiki.ucis.ano/NaCl#Building_a_shared_library_from_the_C_code Building a shared NaCl library from the C code].

== Running DNRouter on Mac OS-X ==
Use [http://www.mono-project.com/ Mono] to run DNRouter.exe (eg: mono DNRouter.exe). You will also need to install the TUN/TAP drivers from http://tuntaposx.sourceforge.net/.

For router/interfaces/tuntap/@ifname, you have to specify the tun/tap interface name (eg tap0). DNRouter will also run ifconfig [ifname] up to enable the interface, so it may need to run as root. This is a limitation of the Mac OS-X drivers.

== Configuring DNRouter ==
All configuration goes in the file router.xml. An example is available [http://oss.ucis.nl/vne/dnrouter/example.xml here].

*<router> - the document root element
** <interfaces> - the section that defines network interfaces (connection to the host and VPN tunnels)
*** <tuntap> - this element defines a tun/tap interface to connect to the host
**** @ifname - this attribute specifies the interface name (it works for both Windows and Linux!)
**** @type - either "tap" or "tun", on Windows only tap is supported
**** @network - (optional) specifies the address or network on the other side of the interface, in prefix/length notation, eg 1.255.123.0/24
**** @dhcpserver - (windows only, optional) enables automatic host IP configuration, this specifies the address of the virtual DHCP server
**** @hostip - (windows only, optional) specifies the IP address to configure on the host (requires @dhcpserver to be set)
**** @netmask - (windows only, optional) the network mask for host IP configuration (requires @dhcpserver and @hostip to be set)
*** <quicktun> - defines a [[QuickTun]] VPN tunnel
**** @type - either "eth" or "ip" (equivalent to "tap" and "tun" devices respectively)
**** @network - specifies the address or network on the other side of the interface, in prefix/length notation, eg 1.255.123.2/32
**** @local - (optional) specifies the local tunnel in IP:PORT format, eg 10.0.0.1:2997
**** @remote - (optional) specifies the remote tunnel in IP:PORT format, eg 10.0.0.2:2997
**** @hwaddr - (optional, ethernet tunnel only) - specifies the MAC address of the interface
**** @mtu - (optional) - specifies the Maximum Transmission Unit
***** Note that at least one of local and remote must be specified!
**** @protocol - specifies the QuickTun cryptographic protocol to use (currently supported are "raw", "nacl0" and "nacltai")
**** <secretkey> - (nacl0 and nacltai protocols only) this element contains the secret key of the local end (eg <secretkey>THE_KEY_GOES_HERE_IN_HEXADECIMAL</secretkey>)
**** <publickey> - (nacl0 and nacltai protocols only) this element contains the public key of the remote end
** <local> - some configuration for the local router
*** <source> - specifies a local address to originate outgoing connections from
**** @network - the destination network address (x.x.x.x/yy notation) for which this address is used as a source address
**** @address - the source IP address to use
*** <address> - specifies a local address that won't be used to originate outgoing connections from
**** @address - the source IP address to use
** <bgp> - configures the BGP router
*** @asn - specifies the AS number of this system
*** @id - specifies the BGP router ID (IP address notation)
*** <peer> - this element defines a BGP peer
**** @address - specifies the IP address of the peer
**** @asn - (currently unused) specifies the AS number of the remote peer
*** <accept> - specifies a network for which to accept BGP routes
**** @network - the network to accept announcements in (eg 1.0.0.0/8 accepts all subnetworks of 1.0.0.0/8 including 1.0.0.0/8 itself)
*** <announce> - announces a local network
**** @network - the network to announce (x.x.x.x/yy)
** <services> - configures locally hosted services
*** <socksserver> - enables a SOCKS5 server
**** @listen - specifies the IP:PORT to listen on (eg 0.0.0.0:1080)
**** @listenside - either "host" or "dn", specifies from which side clients can connect
**** @connectside - either "host" or "dn", specifies where outgoing connections are made
***** Note that the socks server uses the host system for DNS lookups! These may therefore not follow the 'connectside' configuration.
*** <bgp> - enables a BGP listener (optional but recommended)
**** @listen - specifies the IP:PORT to listen on (eg 0.0.0.0:179)
*** <rpc> - enables the [[#RPC service|Remote Procedure Call]] interface, see below
**** @listen - specifies the IP:PORT to listen on
**** @listenside - either "host" or "dn", specifies from which side clients can connect
**** @password - specifies the password for the service

Note that <xxx> indicates an XML element. @xxx indicates an attribute to the XML element. See also the example configuration file.

== RPC service ==
The RPC service allows to retrieve internal information from the DNRouter, as well as to control it's behaviour while it's running. Its protocol is subject to change in the future. The current protocol is targeting usage with PHP clients. An example script follows:
<pre>
<php
function query($host, $port, $password, $query) {
  if (($hubsock = fsockopen($host, $port)) === FALSE) return FALSE;
  if (!stream_set_timeout($hubsock, 10)) return FALSE;
  if (!fwrite($hubsock, $password."\n")) return FALSE;
  if (!is_array($query)) $query = array('CMD' => $query);
  if (!fwrite($hubsock, serialize($query))) return FALSE;
  if (($len = fgets($hubsock)) === FALSE) return FALSE;
  $left = intval($len);
  $buff = '';
  while ($left > 0) {
    if (($new = fread($hubsock, $left)) === FALSE) return FALSE;
    if ($new === false) break;
    $left -= strlen($new);
    $buff .= $new;
  }
  fclose($hubsock);
  return unserialize($buff);
}

header('Content-Type: text/plain');
print_r(query('127.0.0.1', 1234, 'verysecret', 'routes'));
?>
</pre>

Currently supported commands ($query, subject to change):
* ping - returns pong
* routes - list of all known routes in the BGP routing table
* optimal - list of optimal/primary/prefered routes
* peers - list of peers with their imported and exported routes
* localroutes - locally announced routes
* kernelroutes - kernel routing table (which is used for actual IP routing)
* connstat - like netstat
* configure - reload configuration - EXPERIMENTAL!
* shutdown - shutdown BGP connections and exit (should speed up BGP convergence)
* confobj - show configured/reconfigurable objects
* stats - show some numbers