Admission

If you do not know NiceShaper, first of all take a look at included config files. It's pretty usable template and really gives you solid start to see how to build basic configuration. Next come back and read this documentation to figure out how to do things better, and what else you can do with this software.
Please be aware that NiceShaper has been written for polish Network Administrators since start of the project, so there is a forum on the webpage but it is useless for you because of polish language. Also you should realize that this documentation can be strongly language incorrect and even incomplete.

Requirements

NiceShaper require Linux router box with iptables and optional tc binary from iproute2 packet, when used with "fallback iproute" mode. By default NiceShaper works with HTB by communicating with Linux kernel by netlink protocol. Linux Kernel with HTB, U32 filter is required, SFQ, ESFQ, FW filter, IMQ are optional and have specific options documented below. It's better if you have some knowledge about these modules and iptables.

Installation

If you want to use source package, compile process dependents are C++ compiler from gcc package, standard C and C++ libraries and make program.
Compile downloaded and unbzipped package in a fairly standard way (without ./configure):
$ bunzip2 niceshaper-%{version}.tar.bz2
$ tar xf niceshaper-%{version}.tar
$ cd niceshaper-%{version}
$ make
$ su
# make install
If everything is done correctly, niceshaper binary will be copied to /usr/local/bin. You can omit make install and manualy copy niceshaper binary everywhere you want.
If you do not have configuration files installed yet, just copy the sample files:
# cp -R etc/niceshaper /etc/
Otherwise, make sure that between the old and installing current version, there were no syntax changes. And finally create /var/lib/niceshaper directory # mkdir /var/lib/niceshaper

Configutation

HTB configuration diagram

The following diagram shows how NiceShaper, sets HTB on each of the controlled interfaces.

HTB Diagram

Config files syntax.

Common and required configuration files are /etc/niceshaper/config.conf and /etc/niceshaper/class.conf.
include file path - used in these files can include next ones. This directive accepts absolute and relative paths (by default to /etc/niceshaper/).
There are some syntax differencing directives:
Syntax 1) directive value [value] is directive with one or many values, e.g.:

rate 128kB/s
debug iptables iproute

Syntax 2) directive parameter value [parameter value] is directive with parameter-value pairs list, e.g.:

stats file /var/www/stats/nsstats.txt unit kB/s mode 644

On NiceShaper starting, configuration parser procedure will split directives with values or directives with parameters and values, so for your individual preferences you can write these directives like that:
rate 128kB/s
debug iptables
debug iproute
stats file /var/www/stats/nsstats.txt
stats unit kB/s
stats mode 644
Order of parameters does not matter, but collides may occur, e.g. using esfq scheduler squeezing out others schedulers directives.
Directives match and include are parameter-value lists too, but you can not split them because it may change logic of them.
Directive class is the most inflexible one.
In addition to differences in syntax, directives are also divided according to the scope of operation, for: directives of global section, directives of functional sections and directives of classes. When it comes to the directives of classes, all except the class header and filters can be placed in the functional sections configurations, providing default values for all classes included in the section. In the rest of the documentation, the three groups are clearly separated in groups.

The basic units of capacity is b/s (bits per second), and B/s (Bytes per second). The suffixes are k-kilo, M-mega. However, the suffix '/s' is not compulsory and the distinction between rate and the amount of transferred data is based on the context of use. Default unit of bandwidth is b/s (bits per second).

NiceShaper gives you some special chars:
- '#' char is using for comment the rest of line. <# comment #> is using to affect some piece of configuration line. Commented configuration is useless.
- ';' char covers end of line, it gives you way to minimalize length of config files by write a lot of semicolon separated directives in one line.

Each change in configuration require to restart NiceShaper.
Remember, all examples are only examples and might not be optimal for you.

Main configuration file, for example of poor asymmetric 4Mbit/512kbit.

Main configuration file /etc/niceshaper/config.conf is divided into sections. One called global, and any number of functional sections configured for grouping classes and shape packages on appointed interfaces. For each section (except global one) there will be one process in system which will control attached classes.
<global>
<download>

Global section directives:

run - list of configured sections you want to run.
mark-on-ifaces - list of interfaces on which use fw filter in place of u32. Packets outgoings by this interfaces will be marked by iptables mark. It's needed for control upload within network using private IP addresses and NATing outgoing packets, or to use some filters.
lang en|pl - specifies messages language. By default this is taken from LANG environment variable. Apart from default english language you can use pl_PL.UTF-8 in LANG environment variable or just use lang directive with pl value.
iface-<iface> {speed|do-not-shape-method|fallback-rate} - configuration of network interfaces. Name of the directive includes the name of the interface, such as, iface-eth0, iface-imq1 etc.
stats {unit|classes|sum|listen|password|file|owner|group|mode|rewrite} - how to display work statistics. Four last parameters only apply if automatic dump statistics to file is enabled.
log {syslog|terminal|file} - infos, warnings and errors logging.
fallback {iproute|iptables} - in case of problems with these system components allows you to launch an emergency by other less sophisticated methods.

Section configuration:

match test <test> [test <test>]
It is NiceShaper filter directive. Within section configuration assigns some packets group to this section. Mostly it will be whole LAN network, so above examples are good explanation.
Full NiceShaper filters description can be finded in one of next parts of this documentation. Section filters as opposed to class filters does nothing with HTB.
NiceShaper creates some chains in mangle table (one for each section, with ns_ prefix, e.g., ns_download) and section filters cause to create corresponding entries in build-in PRE|POSTROUTING chains.
It is needed to account for classess bandwidth usage, and eventually packets marking or redirecting to IMQ interfaces.
In next stage it is important to declare classes for all packets potentially included to section, if not there will be packets impossible to controll, e.g, if not all hosts in local network will be assigned to classes, these will be steal bandwidth from other classes.
section {speed|shape|htb-burst|htb-cburst} - parameters of section (in most cases bandwidth of your internet access).
reload - how frequency renew HTB configuration. default 4s is safe and quite good. If you have idle processor capacity try to reduce it. It will boost interaction with users caprice. Allowable value is from 0.1s to 600s and step is 0.1s.
mode download|upload - it is key directive for each section, for download mode iptables entry is created in POSTROUTING chain and for upload mode in PREROUTING chain of mangle table. It may affect another elements of configuration so if you really still want to change chain for section use iptables hook directive.
iptables {hook|hook-mode} - directive for iptables configuration.
debug {iptables|iproute} - echoes system commands before execute it.
In section you can place any class parameters. It becomes to be defaults for whole classes in a section.

Class in NiceShaper

File /etc/niceshaper/class.conf holds classes definitions, we can assume that NiceShaper class is a HTB class equivalent/extension. Class is build by header, at least one filter and optionally options. Each packet conforms for the first class matched by filters.

Class strukture

Class definition starts with his header and ends with next class header or end of file:
class section interface name
section - section to whose class belongs.
interface - interface on which HTB queue operates.
name - class name, for stats and others.
It is very important to indicate convenient network interface, as HTB handle packets only on interface from which packets are outgoing from linux machine. This interface should be indicate here. If you want to shape packets on incoming interface lets look on IMQ interfaces documented in this documentation too. Assume that internet comnection are assigned to eth0 and your local network to eth1 interface, for shape incoming bandwidth of your clients use eth1 interface and for shape packets outgoing from your clients to internet network use eth0 interface. Another observation is iptables and iproute does not distinguish interface aliases, so you should truncate alias part to only physical part of interface name. In turn VLANs (ethX.vid like notation) are usefull like physical interfaces. And filter:
match test <test> [test <test>]
Filters define packets which will managed by a class.
Appropriate entries are created by NiceShaper in section iptables chain and also creates a U32 or optionally FW filter for QOS on a interface.
The former are responsible for counting the bandwidth used by the class the latter leading to the corresponding HTB shaping bandwidth.
Naturally tests can be combined to obtain more detailed filters and in the end can enter any number of filters.

An example of the simplest class is as follows:

class download eth1 pc55
match dstip 192.168.0.55
Everywhere in configuration you can use semi-colon instead of new line:
class download eth1 pc55; match dstip 192.168.0.55
class download eth1 pc58; match dstip 192.168.0.58

Class parameters:

low - minimal rate for class (default: 8b/s)
ceil - maximal rate for class (default is equal section shape).
rate - static rate (ceil is equal low).
strict 0 to 100 - determines how much you do not like these who makes overload (default: 70). Low values will result in a more restrictive treatment of these. Values close to 100 at the network overload, "co-responsibility of all.".
hold - Inactive time after that class is unloaded from HTB (default: 30s).
set-mark - parameter applies in a situation where packets marking on class interface is enabled by mark-on-ifaces directive. Then, use it to set the value of the mark. By default, each class is automatically assigned for proper mark value. More in "Packets marking".
iptables {target} - iptables parameters.
htb {prio|scheduler|burst|cburst} - HTB parameters.
sfq {perturb} - SFQ scheduler parameters if used in classes.
esfq {perturb|hash} - ESFQ scheduler parameters if used in classes.
imq {autoredirect} - IMQ interface options.
type standard-class|wrapper|do-not-shape|virtual - available outside the regular class standard-class, we have three additional predefined types.
Each option of classes can be placed in a functional section configuration, so becomes to be defaults to not repeat the same values for each class. Next if you wish these defaults can be overwrited in classes with individual values.

Basics filters tests:

proto tcp|udp|icmp - protocol.
srcip - source IP address.
dstip - destination IP address.
srcport|sport - source port. Needs to choose tcp or udp protocol.
dstport|dport - destination port. Needs to choose tcp or udp protocol.
in-iface - input interface.
out-iface - output interface.
to-local - allows to control local machine bandwidth, supercedes dstip in filter. Check "how to deal with local machine" for more details. Needs physical interface (not imq) in in-iface test.
from-local - as to-local, supercedes srcip in filter. Needs out-iface test.
srcip and dstip can match single ip address or network with subnet mask. In second case allows bits counter notation e.g. /24 or doted notation e.g. 255.255.255.0. Mask can be non-continuous (e.g. 255.255.128.255) but in this case needs mark-on-ifaces because of it needs fw filter instead of u32.

Example filters:

match srcip 192.168.0.77 - packets with source ip address 192.168.0.77.
match srcip 217.74.65.69 srcport 110 dstip 192.168.0.0/29 proto tcp - mail retrieving by pop3 from 217.74.65.69 to 192.168.0.0/29 subnet.

Tests requiring packets marking on a class interface:

Iptables is equipped with a huge number of filters that are unfortunately not feasible using u32 filter. Therefore, these filters require packet marking by mark-on-ifaces directive. Each packet captured and marked by iptables can now easily be enqueued to the appropriate HTB class thanks to received mark value. CAUTION! Some of these filters need additional kernel and iptables compiled in features.
not-srcip - source addresses other than specified.
not-dstip - destination addresses other than specified.
not-srcport|not-sport - source ports other than specified (specify tcp or udp protocol needed).
not-dstport|not-dport - destination ports different than specified (specify tcp or udp protocol needed).
length - packet length in bytes, e.g. 500, :500 (lower and equal 500), 500: (500 and greater), 128:500 (128 to 500).
state new|established|related|invalid|untracked - packet state:
tos - TOS field value.
ttl - TTL equal to the specified value.
ttl-lower - TTL smaller than a given value.
ttl-greater - TTL greater than the specified value.
mark - packets associated with given mark. This mark value will be protected, so NiceShaper will not assign automatically the same value to another class, and does not change the value on his own.
set-mark - to be exact it is a parameter rather than a filter test. It works similarly to a stand-alone set-mark class directive except that it only affects a filter. Override assigned to the filter (automatically or by the class set-mark or mark test) the value of the mark.

Packet marking:

Package marking a procedure to assign a virtual tag to a packet, thanks that even after changing the source address by SNAT (IP masquerade) it is still possible to identify his sender. This value is assigned by iptables, maintained by the Linux kernel and recognizable by iptables and the kernel fw filter used by HTB so by NiceShaper too. FW filter assigns packets into a appropriate HTB class using test based on a virtual tag not on a header. Marking packages do not require patching iptables, iproute or kernel and NiceShaper manages all completely automatically so there is a mechanism very easy to run. Therefore, packet marking is a good way to avoid use of IMQ interfaces, which are comfortable but required patching the Operating System important components. Marking allows you to comfortable control upload of your masqueraded computers.
So if on the interface by directive mark-on-ifaces is packet marking turned on, NiceShaper for each class working on this interface will assign a unique tag value, a u32 type kernel filter on the interface will be replaced with fw one. All this is done completely automatically through the use of directive mark-on-ifaces. However, if necessary it is possible intervention in the process by the mark test and set-mark classes and filters parameter.
procedure for awarding mark value is as follows (the order is the key here):
Example with two classes:
class upload eth0 pc75-76
class upload eth1 pc77-79
In first class filters received automatically generated the same value of a mark. This value is not guessed before you start the program, but be sure 6, 8, 11 and any value assigned automatically to other configured class will not be used in any another class In the second class, the first filter uses the tag value of 6 which is the default for all filters in the class as set by class set-mark directive. The second and third filter will overwrite the 6 value by respectively 8 and 11. If the second and third filter, mark and set-mark has not been used filters are also given to automatic 6. The second filter to qualify the class packets with address 192.168.0.78, provided that they are marked with the value of 8 too.

Triggers

Triggers are a mechanism that allows you to automatically change the values of some class when a defined case occurs. In the current version NiceShapera two triggers are implemented, alter and quota.

Controllable parameters of the class:

low - the minimum bandwidth allocation (default: 8b/s)
ceil - the maximum bandwidth allocation (default is equal to the section shape).
rate - fixed bandwidth allocation.

Control parameters of triggers:

alter {low|ceil|rate} {time-period} - Alter trigger in a certain period of time replaces the defined parameters, for example to increase allocations at night.
quota {low|ceil|rate} {day|week|month} [reset-hour] [reset-wday] [reset-mday] - quota trigger is to change the selected class parameter when a class data transfer exceed a limit. This trigger is equipped with three counters: daily, weekly and monthly. Quota trigger is active whenever one or more counters exceed a limit.
Triggers are class directives, most convenient way to define them within the section, such as:
<download>
The quota trigger have higher priority than the alter trigger if both have to be enabled. Triggers work only for standard-class. Counters of trigger quota between running the program are stored in files section_name.quota in /var/lib/niceshaper directory. These files are updated when NiceShaper is stopping and during his work at 5 minute intervals. If that files write fails, counters will be irretrievably lost!

The use of interfaces IMQ

From the configuration of NiceShaper, IMQ interfaces are the same way as physical ones. Practically, you can forget about their virtuality, with complete freedom to mix classes on physical and IMQ interfaces. NiceShaper automatically targeted traffic to IMQ interface and this behavior is configurable from the sections and classes:
imq autoredirect yes|no
If you disable the automatic redirect to the IMQ you need to make it your self for NiceShaper by something like iptables ... -j IMQ --todev imqX. If choose to not default the most convenient way is to put this directive in a section configuration, so it becomes the default for all classes belonging to a section. After that this behavior can be independently modified again within each class. Example snip from config.conf file:
<upload>
And class.conf:
class upload imq5 pc5.82
class upload imq5 pc5.83

Traffic control to and from the router

In addition to forwarding traffic between the local network and the Internet, router also for their own needs retrieves and sends data such as resolving DNS names or lease IP addresses by DHCP. Most are negligibly small in relation to the capacity of a controlled amount of data throughput. However, in the real world of a small business and an amateur networks, the router with Linux often works as a web, mail or file server, etc. Due to the fact that the shaping takes place at the interface on which packets exits a machine, shaping incoming traffic is difficult, requires use of IMQ interfaces. Traffic between the router and the local network requires to bypass shaping. Should not be shaping to the fact that local ethernet connection is fast and big mistake would be qualify them as uplink usage with rest of traffic. If the computers in the local network are masquaraded when going out the router, it is a problem to distinguish customer traffic from router traffic on interface. After these few sentences admission shows that the issue becomes a bit more complicated than it may seems at first glance. Due to the NiceShaper architecture which is using iptables mangle table for counting the traffic, and if needed marking or/and redirecting on the IMQ devices and yet completely independent QOS by HTB, NiceShaper needs some acrobatics to make these works together. To practically deal with this topic, the most convenient is the breakdown of the issues on four separate scenarios:
a) Traffic between the router and the internet (using uplink bandwidth). b) Traffic between the router and the local network (uplink bandwidth is not involved).
In all cases, you need to add to the filters pairs of test - that is, from-local with out-iface and to-local with in-iface:
from-local ip - replace srcip test. Specified IP address must be configured correctly on one of the router interfaces. In a situation where the iptables hook of a section is PREROUTING, alter iptables filter configuration method. Is created duplicated filter in OUTPUT with the destination in section chain. This is necessary because the packets outgoing from the router itself, does not appear in the PREROUTING chain.
to-local ip - analogous to from-local except that it replaces dstip test and a duplicated filter is created in INPUT chain, if iptables hook of a section is POSTROUTING.
out-iface iface - the specified interface is added to iptables filter as the outgoing interface.
in-iface iface - the specified interface is added to iptables filter as the incoming interface.
Keep in mind that in most cases classes of this type should be on the top of the list of classes, unless you want to achieve a different effect than I can provide in the following examples. Turning to the examples. Let's make assumption that the uplink is connected to eth0 and LAN to eth1. Router's external public address is 80.53.211.226 and the local network 192.168.0.0/24. Have been set up sections named download and upload of modes like their names.

1. Internet => Router - downloading data from the internet to the router.

Internet traffic to the router, such as the webpages retrieves by a proxy server or system updates may steal a bandwidth of clients:
class download eth0 from_internet
Using a class in download mode section and filter to-local does not require extensive commentary here. Local address and input interface, provide belief that traffic to the router is properly classified under processing inside the iptables chains. Classes belonging to a download mode section puts their filters in the chain targeted from POSTROUTING chain, where interests to us packets will never be, so to-local creates a link from the INPUT chain. In addition, bandwidth is shared with clients internet bandwidth so naturally this traffic should be counted to download bandwidth usage. To prevent deflection of the dynamic traffic shaping. However, there is a big problem if you do not use the IMQ interfaces, we have no control over a traffic of this classes only counting. Let's note that the indication of eth0 makes no sense, there is only because of the configuration syntax checks of NiceShaper require that the interface is given. HTB class on this interface does not fulfill its role and the router will obtain priority over the users. This situation may be acceptable in a situation where we value the most web traffic, we make available to customers using a proxy server. Then you can consider the acceptance of the fact that any other traffic will be discriminated against in favor of the proxy server. The use of IMQ is just to specify this type of interface in class header directive. NiceShaper will make redirection to this interface, and create a HTB class that fulfill his work.
class download imq0 from_internet
What is important within an in-iface remains unchanged physical interface eth0. Iptables filter must be based on the physical interface, when packets comes into the router iptables rules it is not yet IMQ interface. Further redirecting is indicated by class header.

2. Router => Internet - sending data from the router to the Internet.

For example, packets generated locally while sending to the world: mail, webpages and other services on the router-server.
class upload eth0 www_to_internet
class upload eth0 mx_to_internet
Again use of class of mode upload section and filter with a parameter from-local does not require extensive commentary here. Provide belief that traffic from the router to the internet is properly classified under processing. Class of mode upload is targeted from PREROUTING chain, where interest to us locally generated packets will never occur, from-local tells NiceShaper to create duplicated filter in the OUTPUT chain. We use a outgoing bandwidth of uplink, so naturally that does not misalign the dynamic traffic shaping we have to account and control this traffic. If the local hosts are maskquaraded to an external router address, mandatory outgoing interface must be listed in the directive mark-on-ifaces.

3. Router => Localnet - downloading data from the router to the local network..

For example, a local ftp server, samba, pop3 etc. It should start by explaining that for scenarios 3 and 4 where traffic is between the router and the local network, whether the class will belong to the download or upload mode section is trivial. We will try such a traffic to not counted with the traffic generated with the internet. So the sample assignment to a specified sections was due to the fact that intuitively bandwidth used for sending data from the LAN to the router is part of the client upload and the other direct from the router to the local network is customers download.
class download eth1 pop3_from_localhost
It is recommended that a class to be one of two following predefined types:
do-not-shape - transfers are local so you do not want to counting and shaping.
wrapper - transfers are local but we are afraid to overload wireless if we have such link, so shaping but with statically allocated bandwidth, still do not count.

4. Localnet => Router - sending data from the local network to the router.

Traffic from the LAN to the router. For example, sending e-mail via the local SMTP server, place the file on the local file server, etc. The situation is clear, intuitively create a class in the upload mode section because our local hosts sends datas. Here again there is a problem described in scenario 1, the filters define the standard way but, if you do not use the IMQ interfaces have no control over the traffic, a wrapper class will not work. Class might look like this:
class upload eth1 smtp_to_localhost
Here the problem is smaller, this traffic does not share the uplink bandwidth, so you just do not count it. To achieve this, use the do-not-shape type class. We can, however, shaping the traffic if, for example you do not want to overload the wireless link, again using IMQ interface:
class upload imq0 smtp_to_localhost