Shaper Control Tool Readme File

Download & update
=================

Project page at Sourceforge:
  http://sourceforge.net/projects/sc-tool/

Project page at BitBucket:
  http://bitbucket.org/sky/sc/

Source code repositories:
  http://bitbucket.org/sky/sc/src
  http://hg.code.sf.net/p/sc-tool/code


Installation
============

0. Install the Linux kernel, which supports "u32" classifier
(CONFIG_NET_CLS_U32), HTB and/or HFSC discipline (CONFIG_NET_SCH_HTB,
CONFIG_NET_SCH_HFSC), and traffic control actions (CONFIG_NET_CLS_ACT,
CONFIG_NET_ACT_GACT). If you are going to use policing or hybrid traffic
limiting method, you will also need CONFIG_NET_ACT_POLICE feature enabled.

These features are configured as modules by default in all major Linux
distributions.

1. Install Perl 5 and the following modules:
AppConfig, DBI, DBD-module for your database (DBD::Pg, DBD::SQLite,
DBD::mysql, etc), Getopt::Long, Pod::Usage, Term::ANSIColor, Sys::Syslog.

  a. Installation from package repository of your Linux distribution.

     Example for Debian:
     # apt-get install perl perl-base perl-doc perl-modules libdbi-perl \
	     libdbd-sqlite3-perl libappconfig-perl

  b. Installation from CPAN.
     # cpan AppConfig DBI DBD::SQLite Getopt::Long Pod::Usage \
	     Term::ANSIColor Sys::Syslog

If you see that the output of "sc help" command is broken, please update
Pod::Usage module from CPAN.

2. Install iproute2.

	# apt-get install iproute2

3. Install sc, manpages, default configuration file and init script.

	# make install

Shaper Control Tool comes with a prepared init script that is installed to
/etc/init.d/sc. To enable automatic start of the shaper script you should
create appropriate symlinks in the runlevel directories. In Debian and related
distributives you should use the following command:

	# update-rc.d sc defaults


Configuration and basic usage
=============================

1. Database settings

By default, sc(8) stores it's data in the SQLite database /etc/sc/sc.db. It
can also load data from any other DBI-compatible database servers, like MySQL,
PostgreSQL, and even from CSV files.

If you plan to load the data from a remote database server, you must install
the corresponding Perl DBD module, and configure parameters of [db] and
[query] sections in sc.conf. By default, the first column contains an
IP-addresses in integer representation, and the second column provides the
integer bandwith rate values (see "create" parameter in sc.conf).

Rate units are defined by "rate_unit" parameter in sc.conf or by similar
command line option. Default rate unit is 1 Kibit/s = 1024 bit/s.

If you plan to use the shaper with it's own database, you need to create it
and add some data.

	# sc dbcreate
	# sc dbadd 10.0.0.1 10Mibit
	# sc dbadd 10.0.0.2 20Mibit

You may also use "genbase" script to generate some database entries with
random values of bandwidth rates.

2. Manual rule loading

When you configured the database parameters, you can generate the shaping
rules with the following command:

	# sc start

To completely delete all the shaping rules, type

	# sc stop

3. Periodic synchronization of rules with database

To perform the synchronization of the shaping rules with the database entries
you should edit your crontab file. The following example of crontab(5) entry
creates the cron(8) task which performs the synchronization of the rules every
10 minutes:

*/10 * * * * root /usr/local/sbin/sc sync

4. Night rates and similar stuff

If you want to have the rates, which differ from stored in the database, you
should set the rate_ratio parameter in the sc.conf file with the suitable cron
instruction. There is no need to reload the rules manually, if you use the
task for synchronization every 10 minutes from the example above.

The following example of cron instructions shows the realization of "night
rates", when you set rate_ratio = 1.5 at 02:00 and change it back to 1.0 at
07:00 every day.

0 2 * * * root sed -i 's/^rate_ratio.*=.*/rate_ratio = 1.5/g' /etc/sc/sc.conf
0 7 * * * root sed -i 's/^rate_ratio.*=.*/rate_ratio = 1.0/g' /etc/sc/sc.conf

5. Syslog

Shaper Control Tool can log errors and warnings through syslog. To enable this
feature set "syslog_enabled" option to 1 in sc.conf.

Troubleshooting
===============

If you experience any problems and get the errors from tc(8) or Linux kernel,
you should repeat the command with enabled debugging "-d 1" and disabled
batch rule loading "-v 2". See manpage sc(8) for details.

Example:
	# sc -d 1 -v 2 start