netserpent 0.1.0/INSTALL

System Requirements
===================

Needed :
 - A GNU/Linux with kernel 2.6.8 below or 2.6.13 above (funny?*1*)
 - netfilter/iptables support and with these ipt modules :
 match modules : connmark owner
 target modules : CONNMARK REDIRECT REJECT
 - libreadline and libtermcap
 - gcc 3.x 4.x
 Recommended :
 - netcat

*NOTE*
 1 SO_ORIGINAL_DST may be broken on these version while it's needed.

Compile
=======

It's a standard GNU project, so you just need to :

$./configure
 ...
 $make
 ...

And pray...

Install
=======

Run

$make install

can do most of the things, now you will get :

$prefix
|-- bin
| `-- netserpent-loader
|-- include
| `-- netserpent-0.1.0
| `-- netserpent
| |-- args.h
| |-- list.h
| |-- log.h
| |-- map.h
| |-- netserpent.h
| |-- plugin.h
| |-- plugin_filter.h
| |-- plugin_loader.h
| `-- settings.h
|-- lib
| |-- libnetserpent-0.1.0.so.1 -> libnetserpent-0.1.0.so.1.0.0
| |-- libnetserpent-0.1.0.so.1.0.0
| |-- libnetserpent.la
| |-- libnetserpent.so -> libnetserpent-0.1.0.so.1.0.0
| |-- netserpent
| | `-- 0.1.0
| | |-- filter
| | | |-- chain.la
| | | |-- chain.so
| | | |-- dbghead.la
| | | |-- dbghead.so
| | | |-- dnat.la
| | | |-- dnat.so
| | | |-- dummy.la
| | | |-- dummy.so
| | | |-- echo.la
| | | `-- echo.so
| | `-- loader
| | |-- cli.la
| | |-- cli.so
| | |-- dummy.la
| | |-- dummy.so
| | |-- script.la
| | `-- script.so
| `-- pkgconfig
| `-- netserpent.pc
`-- libexec
 `-- netserpent
 `-- 0.1.0
 |-- control
 |-- control-setuid
 `-- control-sudo

But since the control prog need privilege to work properly, you have
to choose a security model yourself. Defaultly it shiped with three
control program : the main one, the setuid wrapper and a sudo
wrapper. Generally you should run netserpent-loader as a special user,
because and do remenber that libnetserpent will not hijack the
connections that the programs with the uid generates. As an example,
we call that user "nsp". Now you have to choice :
 1. Configure your /etc/sudoer to enable "nsp" user to run the
 $prefix/libexec/netserpent/*/control-sudo as root.
 2. Set $prefix/libexec/netserpent/*/control-setuid as a setuid
 program, and set proper group/mode of it.

Sample Usage
============

Suppose you choose to use the sudo as security model, you can run like
this:

nsp@cocteau$netserpent-loader -c control-sudo

Do note that here we run it as user "nsp".
If success you will get nothing(huh?), but you can use iptables
utility to check what have it done. Now you can just stop it forcely
and chose a loader plugin to do more meaningful things :

nsp@cocteau$netserpent-loader -c control-sudo cli
 netserpent command line iterface, type "help" for help
 netserpent>help
 commands :
 add - add a node to netserpent map
 del - delete a node from netserpent map
 list - list the content of map
 help - show help informations
 exit - exit cli plugin and send exit signal to netserpent

use "help [command]" for more informations
 netserpent>

Now we try to do some tricks

netserpent>add -d 127.0.1.1 filter echo

This command add a filter to the connections whose destination is
127.0.1.1 and the filter echo do things like this

user@cocteau$nc 127.0.1.1 1
 a <--- what we input
 a <--- and we get

And also note that we use another use to run nc here.
Type "help add" for more infomation on the add command.

Since currently it's a demo version, just some sample plugin
available, if you want to contribute see the *CONTACT* section in
"README", any suggestion is welcome.

Ok, a more complex example :

netserpent>add -d www.gnu.org filter chain dbghead ! dnat
 192.168.128.1 ! dbghead

user@cocteau$nc www.gnu.org 8888
 a <--- input

[email protected]$nc -l -p 8888
 [nsp-dbghead 192.168.128.2:42849 - 199.232.41.10:8888 - 192.168.128.1:0 ]
 [nsp-dbghead 192.168.128.2:42849 - 199.232.41.10:8888 - 199.232.41.10:8888 ]
 f <--- all we got

chain plugin is a plugin to chain plugins together, dnat plugin to
 change the connection destination, dbghead add some infomation to the
 head of every data chunk for debug use.

Hacking
=======

RTFS! And a filter plugin tutorial is available in doc/.