Branch Network emulator using Raddle
====================================

This is a network that might be found in a branch office of a large
organisation. It has a leased-line from the central site, three routers,
two etherswitches, and several host machines. Some of the machines
respond to ping, some to SNMP, and some to both.

All SNMP devices use the 'public' community for read-only access
and the 'private' community for read-write.

You can attach the emulated network to a real ethernet interface or
to a loopback.

If you use a real interface the first emulated router will require an
IP address on your network, and will *not* be directly reachable from
the machine that is running the emulation. This is because honeyd only
sees packets that come *in* through the ethernet interface.

If you use a loopback, the emulated network is reachable from the
machine that it runs on, though you will need to add routing table
entries.

Note that modern Linux systems may not bother to fill in the checksum
field on packets traversing the loopback interface. Older versions of
Honeyd will drop such packets, and network analysers like Wireshark will
flag them as errors. You can get a patched version of Honeyd from the
Raddle distribution site on Sourceforge.


Installation

	make install

	This will copy the relevant files to /usr/local/lib/raddle/branch-network

	Now copy /usr/local/lib/raddle/branch-network/network-config to
	/usr/local/etc/branch-network-config and set
	the address details for the router that connects to your own network.
	You can omit this step if using the loopback interface, but
	you should make sure that the address ranges used by the
	emulated network do not overlap with ranges used on your real
	network.
	Ignore the GROUP_NUMBER entry but leave it in place (this is for
	use in a classroom environment where several people might run the
	same simulation).

	Make sure you have installed Raddle, net-snmp, honeyd, and arpd.
	Arpd is only used if connecting to an ethernet interface: it
	is not needed for loopbacks.

	If using an ethernet, make sure that your machine is NOT set up
	to route IP packets.

	If your machine has a firewall installed, make sure it allows
	through packets from the emulated networks.
	The networks are 172.30.0.0/16 and 172.31.0.0/16 and also
	whatever address you gave to R1 in the config file
	(172.16.91.100 by default)

	Start the simulation (this must be done as root):

	/etc/init.d/run-branch-network start

	Note: if you want the emulation to start at boot time you need to run:

		chkconfig --add run-branch-network

	You should now have six copies of snmpd, one honeyd, and one arpd
	running.

	PID files are placed in /var/run
	Log files are placed in /var/log/raddle
	No provision is made for logfile expiry, so if you plan to run Raddle for long
	periods you should consider doing this.


Testing

	First test the operation of Raddle from the machine that it is
	running on:

		snmpget -v 2c -c public localhost:9501 SNMPv2-MIB::sysDescr.0

	You should get back a string suitable for a Cisco router.
	Ports 9502 to 9506 should produce similar results.


	NOTE that honeyd cannot respond to packets originated on the
	machine it is running on if using an ethernet interface so you
	may need to do the remaining tests from another machine.
	(This is not a problem is using the loopback interface)

	Check that R1 is reachable:

	ping <R1 address>

	Next, add routes so that you can reach the emulated network.
	This is a likely set for an ethernet connection:

	route add -net 172.30.0.0 netmask 255.255.0.0 gw <R1 address>
	route add -net 172.31.0.0 netmask 255.255.0.0 gw <R1 address>

	If using a loopback interface, the routes will be:

	route add -net 172.30.0.0 netmask 255.255.0.0 gw 127.0.0.1
	route add -net 172.31.0.0 netmask 255.255.0.0 gw 127.0.0.1
	route add -net 172.16.0.0 netmask 255.255.0.0 gw 127.0.0.1

	You should now be able to ping and traceroute to the emulated
	routers: (The -n flag disables name resolution, as you
	probably do not have these addresses in your DNS yet)

	ping -n 172.30.1.2
	ping -n 172.31.1.1
	ping -n 172.31.1.2
	ping -n 172.31.1.18
	ping -n 172.31.1.33

	traceroute -n 172.31.1.2

	If all that works, try SNMP:

	snmpwalk -v 2c -c public 172.30.1.2

	Any network-management system with a discovery mode should now
	be able to map the emulated network and draw you a picture of it.
	If your network management system has layer-2 mapping capabilities
	it should also be able to show how the two etherswitches are
	wired up.


Stopping the emulator

	/etc/init.d/run-branch-network stop


Making the emulator start at boot time

	On most Linux system:

	chkconfig --add run-branch-network

	The script should be easily modifiable for other Unix systems
	with a Sys-V-like startup process.


Debugging

	The scripts run-r1 and run-s1 can be used to run sample configs in debug mode.
	This will work even without installing the Raddle code, but you must run 'make'
	at the top of the Raddle source tree first.

	The debug versions use different port numbers from the installed versions, so
	they can co-exist on the same machine.

	With run-r1 running, you can do thing like:

	snmpget -v 2c -c public localhost:9111 SNMPv2-MIB::sysName.0
	snmpbulkwalk -v 2c -c public localhost:9111

	snmpset -v 2c -c private localhost:9111  SNMPv2-MIB::sysName.0 = "my new router"
	snmpget -v 2c -c public localhost:9111 SNMPv2-MIB::sysName.0


Andrew Findlay
1 October 2009

$Id: README,v 1.5 2009/11/13 13:29:55 afindlay Exp $

