diff --git a/README b/README index e0b2083..bd58f35 100644 --- a/README +++ b/README @@ -1,38 +1,38 @@ Ether2Any and PyTap =================== -Ether2Any is a python baseclass for writing arbitrary Ethernet/IP tunnel using -a TUN/TAP device. +Ether2Any is a Python base class for writing arbitrary Ethernet/IP tunnels +using a TUN/TAP device. + +PyTap is a Python class for handling a TUN/TAP device. It exposes +reading/writing to the device and abstracts a bit of the network configuration. -PyTap is a python class for handling a TUN/TAP device. It exposes read/write -and abstracts a bit of the network configuration. Installation and requirements ============================= - Just put it somewhere and import it. For PyTaps network configuration functions you need /sbin/ifconfig. How to write an Ethernet/IP tunnel ================================== -Writing a tunnel with this is rather easy. All you have to do create a class -inheriting from Ether2Any and implement the method sendToNet(). sendToNet() -will be called for each incoming network packet. If you add extra sockets -to the select loop via addSocket, sendToDev() needs to be implemented, -which gets the socket on which new data is ready. If you don't want to rely -on select you are free to pass self.dev (which is a PyTap() instance) and -call dev.write() whenever you like. Note that if you write invalid network -packets on it, you might get an exception. - -Afterwards you can instanciate your class and call the run() method to start +Writing a tunnel with this is rather easy. All you have to do is to create a +class inheriting from Ether2Any and implement the method sendToNet(). +sendToNet() will be called for each incoming network packet. If you add extra +sockets to the select loop via addSocket, sendToDev() needs to be implemented, +which gets the socket with the new data. If you don't want to rely on select you +are free to pass self.dev (which is a PyTap() instance) and call dev.write() +whenever you like. Note that if you write invalid network packets on it, you may +get an exception. + +Afterwards you can instantiate your class and call the run() method to start your tunnel. What could be done ================== - * At the beginning of each packet there are * Builtin packet aggregation would be nice * Various FIXMEs/TODOs * Replace ifconfig with the ip utility - * Add plugin architecture to pytap for traffic mangling + * Add plugin architecture to PyTap for traffic mangling * setuptools/pypi dance + diff --git a/tunnel/ircvpn/README b/tunnel/ircvpn/README new file mode 100644 index 0000000..6061d76 --- /dev/null +++ b/tunnel/ircvpn/README @@ -0,0 +1,77 @@ +IrcVPN - Irc Virtual Public Network +=================================== +This is an ethernet tunnel providing basic hubbed or switchet networks via irc. + +Warning: If you use this software on a "real" (read: not your own) network: + 1. You might run into various flood protections + 2. Your IRC-OP might kill you for that + +Furthermore: All of your data will go kind-of plaintext over an Irc-channel. + While this is a rather uncommon way of ip transit, everybody who + is able to join the channel might be able to eavesdrop. + +Installation and requirements +============================= + * python-irclib + * ether2any + +For configuration take a look at conf.py, it has some comments to give you a +hint of what this switch will do. Some of the security settings are rather +untested, keep that in mind. After configuration, start the tunnel with +python ircvpn.py. A tap-device will open and the tunnel should be ready to run. + +What it does and how it works +============================= +IrcVPN uses an ircchannel as its transport medium. When starting this tunnel, +it makes a connection to the configured irc-server, joins a channel and starts +pushing all outgoing network traffic (base64 encoded with a small header) to +that channel. The nick will be a combination of the configured prefix and +the TAP interfaces mac-address. + +There are two network-modes available: + +.Hubbed Network +In a hubbed network topology all the clients share one broadcast medium, the +irc channel. + +.Switchet Network +In a switched network topology still all the clients join the irc channel and +use it for broadcast messages but unicast traffic goes directly to the user +it is intended for, as it is sent to the nickprefix-macaddress combination. +Wether the user with the specific mac actually IS in the network is not +checked. + +Flood protection is kind of the biggest issue for irc as ether: After a +configured amount of messages most irc-servers queue the incoming messages +and send them out as one per second. If the send-queue is overflowed the user +gets kicked from the server. So this tunnel is not going to perform very well +on normal servers out there. Setting up an own server, the flood protection CAN +be turned off but irc-server with configurable flood protections tend to allow +flooding only in channels and only if the user is either voiced, half-op or op. +This is where voicebot.py comes in: The voicebot voices everyone who joins the +channel and utters a certain phrase. Therefore it is kind of ensured that every +bot has the right to flood the ether as much as it wants with network packets. + +Ircs right management can always be used to mute, rate-limit or remove spamming +or otherwise unwanted clients. + +Header Format +============= + + +The *fragmentation flag* can be either of o, b, c, e. *o* stands for oneliner, +which means that afterwards there is a complete ethernet frame (no +fragmentation). *b*, *c*, *e* stand for begin, continue, end and mark packets +which are broken into several pieces (as of irc does not support infinit line +length). + +The packet id is just a randon generated number between 0, 99999 (incl.). + + +What could be done +================== + * replace base64 with something more fitting for Irc + * test security settings + * find static linkable irc server, patch flood protection out of it + * VVLAN - a Virtual VLAN between irc-channels/servers +