README file for ras.py
======================

What is it?
-----------
This script connects you to an IPsec RAS service.

Assumptions: The FreeS/WAN or openswan /etc/ipsec.conf and
/etc/ipsec.secrets config files are configured correctly and
contain the descriptions of the connections and the needed secrets.
The connections should be configured to be added, NOT started
on /etc/init.d/ipsec start, i.e. auto=add in ipsec.conf.
The script assumes that we are the left side of the connection.
 Note: It might work for people with auto=start, but I haven't
 tested this. Nor have I tested without private virtual IP.

This script should be executed setuid root.
It is configured by /etc/ras.config (or another cfg file specified)
which has the .ini file syntax as described below.

Configuration /etc/ras.config
-----------------------------
Lines that start with '#' are considered comments and disregarded.

The [global] section has the following keys (all optional!):
 pinginterval: How many seconds to wait between pings (default: 15).
 pingtimeout: How long (s) to wait for our peer to answer (default: 5).
 pingfail: How many subsequent pings need to fail to make the script
        assume that the connectivity is down (default: 6).
 failholdoff: How long to sleep before trying to reconnect (def: 150).
 maxconnect: How many seconds we may be connected in total
        (default: empty => infinite).
 virtip: virtual IP of your end of the IPsec connection
        (default: empty => no virtual IP is used).
 netdev: name of the NIC that's used to send out IPsec traffic
        (default: empty => ipsec0 for KLIPS, netdev of defaultroute otherwise).
 gateway: set to an empty string or 'via IP' to explicitly set routing GW
        (default: if no netdev is specified take defroute gw, otherwise '').
 authhost: Machine to telnet to for the opie auth session
        (default: none => skip opie auth session).
 authretry: How many times to try auth session if telnet times out.
        0 means infinity (default: 3).
 logname: username to log in as into authhost
        (default: user running the script).

Expert options are:
 ipseccmd: Let's you override the command to control ipsec tunnels
        with --up/--down/--status conn.name (default: /usr/sbin/ipsec auto)
 ipsecinit: Let's you the command to call the ipsec init script
        (default: /etc/init.d/ipsec)
 ipsecconfread: Let's you override how to read FreeSWAN's ipsec.conf
        (default: cat /etc/ipsec.conf)
 ipcmd: The iproute2 command (default: /sbin/ip)
 routeraw: How to get raw routing table (default: cat /proc/net/route)
 netdevexist: How to determine existence of a network device
        (default: test -e /proc/sys/net/ipv4/conf/)
The most common use for these expoert options is to prefix commands with
ssh -t to remote control another machine who handles the tunnels. This
can be more easily achieved by specifying
 cmdprefix: Let's you prefix the commands ipseccmd, ipsecinit,
        ipsecconfread, ipcmd, routeraw, and netdevexist.
        Note that individual settings are not prefixed automatically.

The global section is mandatory, but it can be empty if the
defaults all work for you.   

There are additional sections where the section name does specify
the name of the IPsec connection as given in ipsec.conf.
The following entries per section are supported:
route: The route that should be set, should be equal to the
        other side's subnet, e.g. 10.0.0.0/8 (optional).
        The route is taken from rightsubnet in ipsec.conf, but can be
        overriden here.
        The special word 'AUTO' here prevents ras.py to affect your routes
        but assumes that the ipcseccmd has taken care of it.
pinghost: Machine to periodically send ping commands to (optional).

mtu: MTU for the route (optional, default 1428).

Multiple connections can be specified this way.
The script starts and stops them all.

Usage
-----
The script is verbose about success or failure, the return codes
roughly match the ones from LSB init scripts.

The program can be run in daemon mode, in which case it forks
a background process; subsequent calls of this program will connect
to the daemon by sending it signals.
The signals SIGTERM/SIGINT/SIGQUIT terminate the process/daemon,
the signal  SIGUSR1 makes it log status information, and
the signal  SIGUSR2 makes it close the connections, reread the config
file and reconnect. SIGHUP reacts like SIGUSR2 in daemon mode, and
like SIGTERM in foreground mode.

Usage: ras.py [options] action [cfg file]
 options: -v (verbose), -q (quiet), 
        -d (daemonize), -D (Direct) -a (alreadyauthenticated)
 action: (start|up|status|help|stop|down|
         try-restart|condrestart|restart|reload|force-reload|probe)

Example configs
---------------
1. Minimal config
[global]
# Nothing needed

[myself-mycompany]
# Nothing needed

2. Remote control another machine (router), ping
[global]
cmdprefix: ssh root@router
#telnetcmd: ssh -t root@router /usr/bin/telnet

[myself-mycompany1]
#route: 10.0.0.0/14
pinghost: 10.0.0.1
#pingfail: 6

[myself-mycompany2]
pinghost: 10.4.0.1
#route: 10.4.0.0/14

3. With opie preauthentication and explicit virtual IP setting
   and route override
[global]
authhost: ipsec-router-external-ip.company.com
virtip: 10.240.0.12
#logname: user

[myself-mycompany]
route: 10.0.0.0/9
pinghost: 10.0.0.1

You must have the connections myself-mycompany(1/2) configured
in /etc/ipsec.conf.