Ether2Any README fixes

master
Sebastian Lohff 12 yıl önce
ebeveyn e78f20c22b
işleme 1a1ed6fa97

@ -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

@ -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
=============
<fragmentation flag><packet id> <base64 encoded message>
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
Yükleniyor…
İptal
Kaydet