FROTTLE(1)

NAME
frottle - Packet collision avoidance and bandwidth shaping for wireless networks

SYNOPSIS
frottle [options]

DESCRIPTION
frottle was developed to combat the issue of hidden node (packet collisions) in large area 802.11b wireless networks. It utilises the ipq library in iptables which allows a userspace application to accept or drop packets asyncronously. At one location frottle is run in master mode. This master polls the other locations which run frottle in client mode. As each client is polled it is allowed to send a limited ammount of data. The polling algorithm is fairly complex and based on many variables. It has been developed and refinded in a real world wireless environment.

OPTIONS
frottle accepts the following options:

-c, --conf
    Alternate location for frottle.conf (default /etc/frottle.conf).

-V, --verbose
    Send additional messages to the terminal (as well as the syslog).

-d, --daemon
    Daemonise (detach from terminal) upon execution.

-h, --help
    Show summary of options.

-V, --version
    Show version of program.

frottle.conf
frottle.conf can have the following settings:

mastermode
    When set to '1' frottle will act as a master. Default '0'. Frottle can act as a master and client at the same time.

clientmode
    When set to '1' frottle will act as a client. Default '0'. Frottle can act as a master and client at the same time.

daemon
    When set to '1' frottle will daemonise (detach from the terminal) upon execution. Default '0'. (Use 'killall -TERM frottle' to quit frottle if you use this option.)

verbose
    When set to '1' additional messages will be sent to the terminal (as well as the syslog). Default '0'.

masterport
    The UDP port used for master - client communications. Must be set the same for both master and clients. Default '999'.

masterip (client only)
    The IP of the master to connect to, i.e. '10.60.0.2'. No default.

queuesize (client and self-client only)
    The maximum number of packets that can be held in each queue at any one time. Default '10'.

hiports (client only)
    High priority ports. Up to 10 can be specified. Default '22, 53'. Matching is performed on both source and destination port.

winterface (client only)
    If a wireless connection is present and wireless-tools is installed, the wireless interface can be specified. Default 'eth1'. This interface will be polled for information to feed to the master for display and use in the polling algorithm.

statsfile (client only)
    Optional path and filename for output of stats information in html format, i.e. '\var\www\html\frottle.html'. Default none.

selfclient (master only)
    When set to '1' a selfclient has a higher priority and more bandwidth than a master with 'clientmode' specified. Use this when the master is acting as a hub for all client data. Default '0'.

timeout (master only)
    The time to wait for a client to respond that it has completed it's poll sequence, in mS. Default '100'.

pollparams (master only)
    Polling paramteres used to control the bandwidth use. Default '60000,10,6000,7,5000,5,4000'. The format of this parameter is 'm,p1,b1,p2,b2,p3,b3' where 'm' is the maximum number of bytes that can be sent by a self client in one poll loop. 'p1,b1' is the maximum number of packets & bytes that can be sent by clients reporting a data rate of 5 Mb/s or greater. 'p2,b2' is the maximum number of packets & bytes that can be sent by client reporting a data rate of 2-5 Mb/s. 'p3,b3' is the maximum number of packets & bytes that can be sent by client reporting a data rate of less than 2 Mb/s.

infofile (master only)
    Path and filename for output of master information in html format. Default '\tmp\frottle.html'.

iptables requirement
Each client must add the following lines to their iptables configuration (firewall script):
    modprobe iptable_filter
    modprobe ip_queue
    iptables -A OUTPUT -p UDP --dport 999 -j ACCEPT
    iptables -A INPUT -p UDP --sport 999 -j ACCEPT
    iptables -A OUTPUT -p ALL -o eth1 -j QUEUE
    iptables -A FORWARD -p ALL -o eth1 -j QUEUE
The first two lines load the required modules. The second two lines allow control packets between the master and client to go straight through. The last two lines send all packets going out the wireless interface (eth1 in this example) to the QUEUE where frottle will handle them.
The master must have the following lines:
    modprobe iptable_filter
    modprobe ip_queue
    iptables -A INPUT -p UDP --dport 999 -j ACCEPT
    iptables -A OUTPUT -p UDP --sport 999 -j ACCEPT
The first two lines load the required modules. The second two lines allow control packets between the master and client to go straight through. If the master is also acting as a client or self client it will also need the following:
    iptables -A OUTPUT -p ALL -o eth1 -j QUEUE
    iptables -A FORWARD -p ALL -o eth1 -j QUEUE

Signals
frottle reacts to the following signals:

HUP Frottle will re-read some parameters from the .conf file upon receiving a HUP signal.

TERM, QUIT, INT
    Frottle will close gracefully when it receives one of these signals.

SEE ALSO
iptables(8), libipq(3), http://www.wafreenet.org/?page=frottle

AUTHOR
Chris King <frottle@wafreenet.org>.