Browse Source

Ether2Any README fixes

Sebastian Lohff 7 years ago
parent
commit
1a1ed6fa97
2 changed files with 94 additions and 17 deletions
  1. 17
    17
      README
  2. 77
    0
      tunnel/ircvpn/README

+ 17
- 17
README View File

@@ -1,38 +1,38 @@
1 1
 Ether2Any and PyTap
2 2
 ===================
3
-Ether2Any is a python baseclass for writing arbitrary Ethernet/IP tunnel using
4
-a TUN/TAP device.
3
+Ether2Any is a Python base class for writing arbitrary Ethernet/IP tunnels
4
+using a TUN/TAP device.
5
+
6
+PyTap is a Python class for handling a TUN/TAP device. It exposes
7
+reading/writing to the device and abstracts a bit of the network configuration.
5 8
 
6
-PyTap is a python class for handling a TUN/TAP device. It exposes read/write
7
-and abstracts a bit of the network configuration.
8 9
 
9 10
 Installation and requirements
10 11
 =============================
11
-
12 12
 Just put it somewhere and import it. For PyTaps network configuration
13 13
 functions you need /sbin/ifconfig.
14 14
 
15 15
 
16 16
 How to write an Ethernet/IP tunnel
17 17
 ==================================
18
-Writing a tunnel with this is rather easy. All you have to do create a class
19
-inheriting from Ether2Any and implement the method sendToNet(). sendToNet()
20
-will be called for each incoming network packet. If you add extra sockets
21
-to the select loop via addSocket, sendToDev() needs to be implemented,
22
-which gets the socket on which new data is ready. If you don't want to rely
23
-on select you are free to pass self.dev (which is a PyTap() instance) and
24
-call dev.write() whenever you like. Note that if you write invalid network
25
-packets on it, you might get an exception.
26
-
27
-Afterwards you can instanciate your class and call the run() method to start
18
+Writing a tunnel with this is rather easy. All you have to do is to create a
19
+class inheriting from Ether2Any and implement the method sendToNet().
20
+sendToNet() will be called for each incoming network packet. If you add extra
21
+sockets to the select loop via addSocket, sendToDev() needs to be implemented,
22
+which gets the socket with the new data. If you don't want to rely on select you
23
+are free to pass self.dev (which is a PyTap() instance) and call dev.write()
24
+whenever you like. Note that if you write invalid network packets on it, you may
25
+get an exception.
26
+
27
+Afterwards you can instantiate your class and call the run() method to start
28 28
 your tunnel.
29 29
 
30 30
 
31 31
 What could be done
32 32
 ==================
33
- * At the beginning of each packet there are 
34 33
  * Builtin packet aggregation would be nice
35 34
  * Various FIXMEs/TODOs
36 35
  * Replace ifconfig with the ip utility
37
- * Add plugin architecture to pytap for traffic mangling
36
+ * Add plugin architecture to PyTap for traffic mangling
38 37
  * setuptools/pypi dance
38
+

+ 77
- 0
tunnel/ircvpn/README View File

@@ -0,0 +1,77 @@
1
+IrcVPN - Irc Virtual Public Network
2
+===================================
3
+This is an ethernet tunnel providing basic hubbed or switchet networks via irc.
4
+
5
+Warning: If you use this software on a "real" (read: not your own) network:
6
+          1. You might run into various flood protections
7
+		  2. Your IRC-OP might kill you for that
8
+
9
+Furthermore: All of your data will go kind-of plaintext over an Irc-channel.
10
+             While this is a rather uncommon way of ip transit, everybody who
11
+			 is able to join the channel might be able to eavesdrop.
12
+
13
+Installation and requirements
14
+=============================
15
+ * python-irclib
16
+ * ether2any
17
+
18
+For configuration take a look at conf.py, it has some comments to give you a
19
+hint of what this switch will do. Some of the security settings are rather
20
+untested, keep that in mind. After configuration, start the tunnel with
21
+python ircvpn.py. A tap-device will open and the tunnel should be ready to run.
22
+
23
+What it does and how it works
24
+=============================
25
+IrcVPN uses an ircchannel as its transport medium. When starting this tunnel,
26
+it makes a connection to the configured irc-server, joins a channel and starts
27
+pushing all outgoing network traffic (base64 encoded with a small header) to
28
+that channel. The nick will be a combination of the configured prefix and
29
+the TAP interfaces mac-address.
30
+
31
+There are two network-modes available:
32
+
33
+.Hubbed Network
34
+In a hubbed network topology all the clients share one broadcast medium, the
35
+irc channel.
36
+
37
+.Switchet Network
38
+In a switched network topology still all the clients join the irc channel and
39
+use it for broadcast messages but unicast traffic goes directly to the user
40
+it is intended for, as it is sent to the nickprefix-macaddress combination.
41
+Wether the user with the specific mac actually IS in the network is not
42
+checked.
43
+
44
+Flood protection is kind of the biggest issue for irc as ether: After a
45
+configured amount of messages most irc-servers queue the incoming messages
46
+and send them out as one per second. If the send-queue is overflowed the user
47
+gets kicked from the server. So this tunnel is not going to perform very well
48
+on normal servers out there. Setting up an own server, the flood protection CAN
49
+be turned off but irc-server with configurable flood protections tend to allow
50
+flooding only in channels and only if the user is either voiced, half-op or op.
51
+This is where voicebot.py comes in: The voicebot voices everyone who joins the
52
+channel and utters a certain phrase. Therefore it is kind of ensured that every
53
+bot has the right to flood the ether as much as it wants with network packets.
54
+
55
+Ircs right management can always be used to mute, rate-limit or remove spamming
56
+or otherwise unwanted clients. 
57
+
58
+Header Format
59
+=============
60
+<fragmentation flag><packet id> <base64 encoded message>
61
+
62
+The *fragmentation flag* can be either of o, b, c, e. *o* stands for oneliner,
63
+which means that afterwards there is a complete ethernet frame (no
64
+fragmentation). *b*, *c*, *e* stand for begin, continue, end and mark packets
65
+which are broken into several pieces (as of irc does not support infinit line
66
+length). 
67
+
68
+The packet id is just a randon generated number between 0, 99999 (incl.).
69
+
70
+
71
+What could be done
72
+==================
73
+ * replace base64 with something more fitting for Irc
74
+ * test security settings
75
+ * find static linkable irc server, patch flood protection out of it
76
+ * VVLAN - a Virtual VLAN between irc-channels/servers
77
+

Loading…
Cancel
Save