shapercontrol(8)

SC(8)

Linux System Manager's Manual

SC(8)

NAME

shaperconrol - administration tool for ISP traffic shaper

SYNOPSIS

shaperconrol [options] command [ip] [rate]

DESCRIPTION

sc(8) is a command-line tool intended to simplify administration of traffic shaper for Internet service providers.

Main features

Fast loading of large rulesets.
Effective traffic classification with u32 hashing filters.
Loading of data from any relational database supported by Perl DBI module.
Synchronization of rules with database.
Batch command execution mode for scripting purposes.
Support of different traffic limiting methods: shaping, policing, and hybrid.

DEPENDENCIES

DBI and corresponding database-dependent module (e.g. DBD::Pg for PostgreSQL, DBD::SQLite for SQLite, etc), AppConfig, Carp, Getopt::Long, Pod::Usage, Sys::Syslog, Term::ANSIColor.

PREREQUISITES

Command-line tools

tc(8) from iproute2 suite.

Linux kernel configuration

u32 classifier (option CONFIG_NET_CLS_U32=m or y)
Traffic control actions (CONFIG_NET_CLS_ACT=y and CONFIG_NET_ACT_GACT=m or y)

COREQUISITES

If you prefer policing as a rate limiting method, you should enable the kernel option CONFIG_NET_ACT_POLICE.

COMMANDS

add <ip> <rate>: Add rules for specified IP
calc [ip]: Calculate and print internally used variables: classids, hash table numbers and keys.
change | mod <ip> <rate>: Change rate for specified IP
dbadd <ip> <rate>: Add database entry
dbchange | dbmod <ip> <rate>: Change database entry
dbcreate: Create database and table
dbdel | dbrm <ip>: Delete database entry
dblist | dbls [ip]: List database entries. If no IP specified, all entries are listed.
del | rm <ip>: Delete rules
help: Show help for commands, options and list available database drivers. Generate and show manpage if -v 1 option is specified.
init: Initialization of firewall and QoS rules. Should be used only for manual rule editing.
list | ls [ip]: List rules in a short and human-readable form. If no IP specified, all entries are listed.
load | start: Load IPs and rates from database and create ruleset
ratecvt <rate> <unit>: Convert rate from one unit to another
reload | restart: Reset rules and load database
reset | stop: Delete all shaping rules
show [ip]: Show rules explicitly. If no IP specified, all entries are listed.
status: Show status of shaping rules
sync: Synchronize rules with database
version: Output version

OPTIONS

-f, --config file: Read configuration from specified file
-o, --out_if if_name: Name of output network interface
-i, --in_if if_name: Name of input network interface
-d, --debug mode: Possible values:

0: no debug (default value),
1: print command lines with nonzero return values,
2: print all command lines without execution.

-v, --verbose mode: Possible values:

0: no verbose messages (default)
1: enable verbose messages (i.e. for results of `sync' command)
2: disable usage of tc(8) batch rule loading
3: do 1 + 2

-q, --quiet: Suppress output of error messages from tc(8).
-c, --colored: Colorize the output.
-C, --cid classid: Use the specified classid value in add, change and del commands instead of automatically calculated.
-j, --joint: Joint mode. Add, change and del commands will be applied to rules and database entries simultaneously.
-b, --batch: Batch mode. Commands and options will be read from STDIN.
-N, --network "net/mask ...": Networks for IP to classid mapping (see sc.conf(5) for details).
--filter_network "net/mask ...": Networks for hashing filter generation (see sc.conf(5) for details).
--bypass_int "net/mask ...": Internal networks, whose traffic is transmitted without shaping.
--bypass_ext "net/mask ...": External networks, whose traffic is transmitted without shaping.
--policer_burst_ratio real number: Ratio between the size of policer buffer size and bandwidth rate.
--quantum size: Amount of bytes a stream is allowed to dequeue before the next queue gets a turn.
-u, --rate_unit unit: Default rate unit
-r, --rate_ratio real number: Ratio between bandwidth rates in rules and in the database. Used only for load and sync commands.
-R, --root_qdisc string: Root qdisc ("htb" or "hfsc").
-L, --leaf_qdisc string: Leaf qdisc and parameters.
--db_driver name: Database driver.
--db_host host:port: Database server address or hostname.
--db_name name: Database name to use.
--db_user name: Database username.
--db_pass password: Database password. Remember that it is insecure to specify a password here.
-S, --syslog_enable: Send errors and warnings to syslog.

RATE UNITS

All rates should be specified as integer numbers, possibly followed by a unit. Bare number implies the default unit (kibit). You may use another unit by changing "rate_unit" parameter in the configuration file or by setting the similar command line option.

bit: bit per second
kibit, Kibit: kibibit per second (1024)
kbit or Kbit: kilobit per second (1000)
mibit or Mibit: mebibit per second (1 048 576)
mbit or Mbit: megabit per second (10^6)
gibit or Gibit: gibibit per second (1 073 741 824)
gbit or Gbit: gigabit per second (10^9)
bps or Bps: byte per second
kibps or KiBps: kibibyte per second
kbps or KBps: kilobyte per second
mibps or MiBps: mebibyte per second
mbps or MBps: megabyte per second
gibps or GiBps: gibibyte per second
gbps or GBps: gigabyte per second

USAGE

Load accounts from database and create all rules: "sc load" or "sc start"
Add class for IP 172.16.0.1 with 256kibit/s.: "sc add 172.16.0.1 256kibit"
Change rate to 512kibit/s: "sc change 172.16.0.1 512kibit"
Delete rules for 172.16.0.1: "sc del 172.16.0.1"
Reset all rules: "sc reset"

CONFIGURATION

By default shaperconrol reads configuration from /etc/sc/sc.conf file and uses SQLite database at /etc/sc/sc.db. See sc.conf(5) for details.

DIAGNOSTICS

The error messages are printed to standard error. To print the command lines that return nonzero error codes, use -d 1 option. To print all generated command lines without execution, use -d 2 option. To disable the usage of the batch mode of tc(8), use -v 2 option. For more information please read the section OPTIONS.

Program may return one of the following exit codes or the exit code of the failed command line that aborted the execution:

0: correct functioning
1: incorrect parameter
2: IP-to-classid collision
3: parameter is undefined
4: IP already exists
5: IP does not exist
6: incorrect command
7: insufficient privileges

BUGS

For performance reasons, script does not perform checks that require additional executions of external programs.

RESTRICTIONS

Due to limited number of classids (from 2 to ffff) you can create only 65534 classes on a single interface. For similar reasons sc(8) only supports networks with masks from /16 to /31.

For simplicity of u32 hash table numbers calculation, the maximum number of entries in "filter_network" parameter is 255, and the number of hashing filters is limited by 0x7ff.

AUTHOR

Stanislav Kruchinin <stanislav.kruchinin@gmail.com>

LICENSE AND COPYRIGHT

License: GNU GPL version 2 or later

This is free software: you are free to change and redistribute it. There is NO WARRANTY; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

2017-07-21