firehol-router

title: firehol-router(5)

summary: create a router definition

text:
# firehol-router(5)

## NAME
firehol-router - create a router definition

## SYNOPSIS
{ router | router46 } name rule-params

router4 name rule-params

router6 name rule-params

## DESCRIPTION
A router definition consists of a set of rules for traffic passing through the host running the firewall.

The default policy for router definitions is RETURN, meaning packets are not dropped by any particular router. Packets not matched by any router are dropped at the end of the firewall.

The behaviour of the defined router is controlled by adding subcommands from those listed in ROUTER SUBCOMMANDS.

Note

Writing router4 is equivalent to writing ipv4 router and ensures the defined router is created only in the IPv4 firewall along with any rules within it.

Writing router6 is equivalent to writing ipv6 router and ensures the defined router is created only in the IPv6 firewall along with any rules within it.

Writing router46 is equivalent to writing both router and ensures the defined router is created in both the IPv4 and IPv6 firewalls. Any rules within it will also be applied to both, unless they specify otherwise.

## PARAMETERS
name

This is a name for this router. You should use short names (10 characters maximum) without spaces or other symbols.

A name should be unique for all FireHOL interface and router definitions.

rule-params

The set of rule parameters to further restrict the traffic that is matched to this router.

See firehol-params(5) for information on the parameters that can be used. Some examples:

```
router mylan inface ppp+ outface eth0 src not ${UNROUTABLE_IPS}
router myrouter
```

See firehol.conf(5) for an explanation of ${UNROUTABLE_IPS}.

## WORKING WITH ROUTERS
Routers create stateful iptables(8) rules which match traffic in both directions.

To match some client or server traffic, the input/output interface or source/destination of the request must be specified. All inface/outface and src/dst firehol-params(5) can be given on the router statement (in which case they will be applied to all subcommands for the router) or just within the subcommands of the router.

For example, to define a router which matches requests from any PPP interface and destined for eth0, and on this allowing HTTP servers (on eth0) to be accessed by clients (from PPP) and SMTP clients (from eth0) to access any servers (on PPP):

```
router mylan inface ppp+ outface eth0
  server http accept
  client smtp accept
```

Note

The client subcommand reverses any optional rule parameters passed to the router, in this case the inface and outface.

Equivalently, to define a router which matches all forwarded traffic and within the the router allow HTTP servers on eth0 to be accessible to PPP and any SMTP servers on PPP to be accessible from eth0:

```
router mylan
  server http accept inface ppp+ outface eth0
  server smtp accept inface eth0 outface ppp
```

Note

In this instance two server subcommands are used since there are no parameters on the router to reverse. Avoid the use of the client subcommand in routers unless the inputs and outputs are defined as part of the router.

Any number of routers can be defined and the traffic they match can overlap. Since the default policy is RETURN, any traffic that is not matched by any rules in one will proceed to the next, in order, until none are left.

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

firehol-modifiers(5) - ipv4/ipv6 selection

•

firehol-interface(5) - interface definition

•

firehol-iptables(5) - iptables helper

•

firehol-masquerade(5) - masquerade helper

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

### Router Subcommands
•

firehol-policy(5) - policy command

•

firehol-protection(5) - protection command

•

firehol-server(5) - server, route commands

•

firehol-client(5) - client command

•

firehol-group(5) - group command

•

firehol-tcpmss(5) - tcpmss helper

## AUTHORS
FireHOL Team.


firehol-server

package: firehol

title: firehol-server(5)

text:
# firehol-server(5)

## NAME
firehol-server - server, route commands: accept requests to a service

## SYNOPSIS
{ server | server46 } service action rule-params

server4 service action rule-params

server6 service action rule-params

{ route | route46 } service action rule-params

route4 service action rule-params

route6 service action rule-params

## DESCRIPTION
The server subcommand defines a server of a service on an interface or router. Any rule-params given to a parent interface or router are inherited by the server.

For FireHOL a server is the destination of a request. Even though this is more complex for some multi-socket services, to FireHOL a server always accepts requests.

The route subcommand is an alias for server which may only be used in routers.

The service parameter is one of the supported service names from firehol-services(5). Multiple services may be specified, space delimited in quotes.

The action can be any of the actions listed in firehol-actions(5).

The rule-params define a set of rule parameters to further restrict the traffic that is matched to this service. See firehol-params(5) for more details.

Note

Writing server4 is equivalent to writing ipv4 server and ensures this subcommand is applied only in the IPv4 firewall rules.

Writing server6 is equivalent to writing ipv6 server and ensures this subcommand is applied only in the IPv6 firewall rules.

Writing server46 is equivalent to writing both server and ensures this subcommand is applied in both the IPv4 and IPv6 firewall rules; it cannot be used as part an interface or router that is IPv4 or IPv6 only.

The default server inherits its behaviour from the enclosing interface or router.

The same rules apply to the variations of route.

## EXAMPLES

```
server smtp accept
server "smtp pop3" accept
server smtp accept src 192.0.2.1
server smtp accept log "mail packet" src 192.0.2.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-modifiers(5) - ipv4/ipv6 selection

•

firehol-services(5) - services list

•

firehol-actions(5) - actions for rules

•

firehol-params(5) - optional rule parameters

•

firehol-client(5) - client subcommand

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.

branch: sisyphus


firehol-services

title: firehol-services(5)

summary: configure synproxy

text:
# firehol-services(5)

## NAME
firehol-synproxy - configure synproxy

## SYNOPSIS
synproxy type rules-to-match-request action [action options]

## DESCRIPTION
•

type defines where the SYNPROXY will be attached. It can be input (or in), forward (or pass):

•

use input (or in) when the IP of the real server is an IP assigned to a physical interface of the machine (i.e. the IP is at the firewall itself)

•

use forward (or pass) when the IP of the real server is routed by the machine (i.e. SYNPROXY should look at the FORWARD chain for this traffic).

•

rules to match request are FireHOL optional rule parameters and should match the original client REQUEST, before any destination NAT. inface and dst are required:

•

inface is one or more interfaces the REQUEST should be received from

•

dst is the IP of the real server, as seen by the client (before any destination NAT)

•

action defines how SYNPROXY will reach the real server and can be:

•

accept to just allow the REQUEST reach the real server without any destination NAT

•

dnat to IP:PORT or dnat to IP1-IP2:PORT1-PORT2 or dnat to IP or dnat to :PORT to have SYNPROXY reach a server on another machine in a DMZ (different IP and/or PORT compared to the original request). The synproxy statement supports everything supported by the dnat helper (see firehol-nat(5)).

•

redirect to PORT to divert the request to a port on the firewall itself. The synproxy statement supports everything supported by the redirect helper (see firehol-nat(5)).

•

action CUSTOM_ACTION to have any other FireHOL action performed on the NEW socket. Use the action helper to define custom actions (see [firehol-action(5)][]).

•

action options are everything supported by FireHOL optional rule parameters that should be applied only on the final action of SYN packet from SYNPROXY to the real server. For example this can be used to append loglimit "TEXT" to have something logged by iptables, or limit the concurrent sockets with connlimit. Generally, everything you can write on the same line after server http accept is also accepted here.

## BACKGROUND
SYNPROXY is a TCP SYN packets proxy. It can be used to protect any TCP server (like a web server) from SYN floods and similar DDos attacks.

SYNPROXY is a netfilter module, in the Linux kernel. It is optimized to handle millions of packets per second utilizing all CPUs available without any concurrency locking between the connections.

The net effect of this, is that the real servers will not notice any change during the attack. The valid TCP connections will pass through and served, while the attack will be stopped at the firewall.

For more information on why you should use a SYNPROXY, check these articles:

•

http://rhelblog.redhat.com/2014/04/11/mitigate-tcp-syn-flood-attacks-with-red-hat-enterprise-linux-7-beta/

•

https://r00t-services.net/knowledgebase/14/Homemade-DDoS-Protection-Using-IPTables-SYNPROXY.html

SYNPROXY is included in the Linux kernels since version 3.12.

## HOW IT WORKS
•

When a SYNPROXY is used, clients transparently get connected to the SYNPROXY. So the 3-way TCP handshake happens first between the client and the SYNPROXY:

•

Clients send TCP SYN to server A

•

At the firewall, when this packet arrives it is marked as UNTRACKED

•

The UNTRACKED TCP SYN packet is then given to SYNPROXY

•

SYNPROXY gets this and responds (as server A) with TCP SYN+ACK (UNTRACKED)

•

Client responds with TCP ACK (marked as INVALID or UNTRACKED in iptables) which is also given to SYNPROXY

•

Once a client has been connected to the SYNPROXY, SYNPROXY automatically initiates a 3-way TCP handshake with the real server, spoofing the SYN packet so that the real server will see that the original client is attempting to connect:

•

SYNPROXY sends TCP SYN to real server A. This is a NEW connection in iptables and happens on the OUTPUT chain. The source IP of the packet is the IP of the client

•

The real server A responds with SYN+ACK to the client

•

SYNPROXY receives this and responds back to the server with ACK. The connection is now marked as ESTABLISHED

•

Once the connection has been established, SYNPROXY leaves the traffic flow between the client and the server

So, SYNPROXY can be used for any kind of TCP traffic. It can be used for both unencrypted and encrypted traffic, since it does not interfere with the content itself.

## USE CASES
In FireHOL SYNPROXY support is implemented as a helper. The synproxy command can be used to set up any number of SYNPROXYs.

FireHOL can set up SYNPROXY for any of these cases:

1.

real server on the firewall itself, on the same port (e.g. SYNPROXY on port 80, real server on port 80 too).

2.

real server on the firewall itself, on a different port (e.g. SYNPROXY on port 2200, real server on port 22).

3.

real server on a different machine, without NAT (e.g. SYNPROXY on a router catching traffic towards IP A, port 80 and real server is at IP A port 80 too).

4.

real server on a different machine, with NAT (e.g. SYNPROXY on a router catching traffic towards IP A, port 80 and real server is at IP 10.1.1.1 port 90).

5.

screening incoming traffic that should never be sent to a real server so that traps and dynamic blacklists can be created using traffic that has been screened by SYNPROXY (eliminate "internet noise" and spoofed packets).

So, generally, all cases are covered.

## DESIGN
The general guidelines for using synproxy in FireHOL, are:

1.

Design your firewall as you would normally do without SYNPROXY

2.

Test that it works without SYNPROXY. Test especially the servers you want to protect. They should be working too

3.

Add synproxy statements for the servers you want to protect.

To achieve these requirements:

1.

The helper will automatically do everything needed for SYNPROXY to:

•

receive the initial SYN packet from the client

•

respond back to the client with SYN+ACK

•

receive the first ACK packet from the client

•

send the initial SYN packet to the server

There are cases where the above are very tricky to achieve. You don't need to match these in your firehol.conf. The synproxy helper will automatically take care of them. However:

You do need the allow the flow of traffic between the real server and the real client (as you normally do without a synproxy, with a client, server, or route statement in an interface or router section).

2.

The helper will prevent the 3-way TCP handshake between SYNPROXY and the real server interact with other destination NAT rules you may have. However for this to happen, make sure you place the synproxy statements above any destination NAT rules (redirect, dnat, transparent_squid, transparent_proxy, tproxy, etc). So:

SYNPROXY will interact with destination NAT you have in firehol.conf only if the synproxy statements are place below the destination NAT ones.

You normally do not need to have synproxy interact with other destination NAT rules. The synproxy helper will handle the destination NAT (dnat or redirect) it needs by itself.

So place synproxy statements above all destination NAT statements, unless you know what you are doing.

3.

The helper will allow the 3-way TCP handshake between SYNPROXY and the real server interact with source NAT rules you may have (snat, masquerade), since these may be needed to reach the real server.

## LIMITATIONS
1.

Internally there are matches that are made without taking into account the original inface. So, in case different actions have to be taken depending on the interface the request is received, src should be added to differentiate the traffic between the two flows.

2.

SYNPROXY does not inherit MARKs from the original request packets. It should and it would make matching a lot easier, but it does not. This means that for all packets generated by SYNPROXY, inface is lost.

3.

FireHOL internally uses a MARK to tag packets send from SYNPROXY to the target server. This is used for 3 reasons:

•

isolate these packets from other destination NAT rules. If they were not isolated from the destination NAT rules, then packets from the SYNPROXY could be matched by a transparent proxy and enter your web proxy. They could be matched by a transparent proxy because they actually originate from the local machine.

•

isolate the same packets from the rest of the packet filtering rules. Without this isolation, most probably the packets will have been dropped since they come from lo.

•

report if orphan synproxy packets are encountered. So packets the FireHOL engine failed to match properly, should appear with a iptables log saying "ORPHAN SYNPROXY->SERVER". If you don't have such logs, everything works as expected.

## OTHER OPTIONS
You can change the TCP options used by synproxy by setting the variable FIREHOL_SYNPROXY_OPTIONS. The default is this:

```
FIREHOL_SYNPROXY_OPTIONS="--sack-perm --timestamp --wscale 7 --mss 1460"
```

If you want to see it in action in the iptables log, then enable logging:

```
FIREHOL_SYNPROXY_LOG=1
```

The default is disabled (0). If you enable it, every step of the 3-way setup between the client and SYNPROXY and the SYN packet of SYNPROXY towards the real server will be logged by iptables.

Using the variable FIREHOL_CONNTRACK_LOOSE_MATCHING you can set net.netfilter.nf_conntrack_tcp_loose. FireHOL will automatically set this to 0 when a synproxy is set up.

Using the variable FIREHOL_TCP_TIMESTAMPS you can set net.ipv4.tcp_timestamps. FireHOL will automatically set this to 1 when a synproxy is set up.

Using the variable FIREHOL_TCP_SYN_COOKIES you can set net.ipv4.tcp_syncookies. FireHOL will automatically set this to 1 when a synproxy is set up.

On a busy server, you are advised to increase the maximum connection tracker entries and its hash table size.

•

Using the variable FIREHOL_CONNTRACK_HASHSIZE you can set /sys/module/nf_conntrack/parameters/hashsize.

•

Using the variable FIREHOL_CONNTRACK_MAX you can set net.netfilter.nf_conntrack_max.

FireHOL will not alter these variables by itself.

## SYNPROXY AND DYNAMIC IP
By default the synproxy helper requires from you to define a dst IP of the server that is to be protected. This is required because the destination IP will be used to match the SYN packet the synproxy sends to the server.

There is however another way that allows the use of synproxy in environments where the IP of the server is unknown (like a dynamic IP DSL):

1.

First you need to set FIREHOL_SYNPROXY_EXCLUDE_OWNER=1. This will make synproxy not match packets that are generated by the local machine, even if the process that generates them uses your public IP (the packets in order to be matched they will need not have a UID or GID).

2.

Next you will need to exclude you lan IPs by adding src not "${UNROUTABLE_IPS}" (or any other network you know you use) to the synproxy statement.

## EXAMPLES
Protect a web server running on the firewall with IP 1.2.3.4, from clients on eth0:

```
ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 80 accept
interface eth0 wan
    server http accept
```

Protect a web server running on port 90 on the firewall with IP 1.2.3.4, from clients on eth0 that believe the web server is running on port 80:

```
server_myhttp_ports="tcp/90"
client_myhttp_ports="default"
ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 80 redirect to 90
interface eth0 wan
    server myhttp accept # packet filtering works with the real ports
```

Protect a web server running on another machine (5.6.7.8), while the firewall is the router (without NAT):

```
ipv4 synproxy forward inface eth0 dst 5.6.7.8 dport 80 accept
router wan2lan inface eth0 outface eth1
    server http accept dst 5.6.7.8
```

Protect a web server running on another machine in a DMZ (public IP is 1.2.3.4 on eth0, web server IP is 10.1.1.1 on eth1):

```
ipv4 synproxy input inface eth0 \
    dst 1.2.3.4 dport 80 dnat to 10.1.1.1
router wan2lan inface eth0 outface eth1
    server http accept dst 10.1.1.1
```

Note that we used input not forward, because the firewall has the IP 1.2.3.4 on its eth0 interface. The client request is expected on input.

Protect an array of 10 web servers running on 10 other machines in a DMZ (public IP is 1.2.3.4 on eth0, web servers IPs are 10.1.1.1 to 10.1.1.10 on eth1):

```
ipv4 synproxy input inface eth0 \
    dst 1.2.3.4 dport 80 dnat to 10.1.1.1-10.1.1.10 persistent
router wan2lan inface eth0 outface eth1
    server http accept dst 10.1.1.1-10.1.1.10
```

The above configuration is a load balancer. Requests towards 1.2.3.4 port 80 will be distributed to the 10 web servers with persistence (each client will always see one of them).

Catch all traffic towards SSH port tcp/22 and send it to TRAP_AND_DROP as explained in Working With Traps (Working-with-traps). At the same time, allow SSH on port tcp/2200 (without altering the ssh server):

```
 # definition of action TRAP_AND_DROP
 ipv4 action TRAP_AND_DROP sockets_suspects_trap 3600 86400 1 src not "${UNROUTABLE_IPS}" next action DROP
 # send ssh traffic to TRAP_AND_DROP
 ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 22 action TRAP_AND_DROP
 # accept ssh traffic on tcp/2200
 ipv4 synproxy input inface eth0 dst 1.2.3.4 dport 2200 redirect to 22
 interface eth0 wan
    server ssh accept
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

firehol-params(5) - optional rule parameters

•

firehol-masquerade(5) - masquerade helper

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

NAT HOWTO (http://www.netfilter.org/documentation/HOWTO/NAT-HOWTO-6.html)

•

netfilter flow diagram (http://upload.wikimedia.org/wikipedia/commons/3/37/Netfilter-packet-flow.svg)

## AUTHORS
FireHOL Team.


firehol-synproxy

title: firehol-synproxy(5)

text:
# firehol-synproxy(5)

## NAME
firehol-tcpmss - set the MSS of TCP SYN packets for routers

## SYNOPSIS
tcpmss { mss | auto } [if-list]

## DESCRIPTION
The tcpmss helper command sets the MSS (Maximum Segment Size) of TCP SYN packets routed through the firewall. This can be used to overcome situations where Path MTU Discovery is not working and packet fragmentation is not possible.

A numeric mss will set MSS of TCP connections to the value given. Using the word auto will set the MSS to the MTU of the outgoing interface minus 40 (clamp-mss-to-pmtu).

If used within a router or interface definition the MSS will be applied to outgoing traffic on the outface(s) of the router or interface.

If used before any router or interface definitions it will be applied to all traffic passing through the firewall. If if-list is given, the MSS will be applied only to those interfaces.

## EXAMPLES

```
tcpmss auto
tcpmss 500
tcpmss 500 "eth1 eth2 eth3"
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

TCPMSS target in the iptables tutorial (https://www.frozentux.net/iptables-tutorial/iptables-tutorial.html#TCPMSSTARGET)

## AUTHORS
FireHOL Team.


firehol-tcpmss

title: firehol-tcpmss(5)

text:
# firehol-tcpmss(5)

## NAME
firehol-tcpmss - set the MSS of TCP SYN packets for routers

## SYNOPSIS
tcpmss { mss | auto } [if-list]

## DESCRIPTION
The tcpmss helper command sets the MSS (Maximum Segment Size) of TCP SYN packets routed through the firewall. This can be used to overcome situations where Path MTU Discovery is not working and packet fragmentation is not possible.

A numeric mss will set MSS of TCP connections to the value given. Using the word auto will set the MSS to the MTU of the outgoing interface minus 40 (clamp-mss-to-pmtu).

If used within a router or interface definition the MSS will be applied to outgoing traffic on the outface(s) of the router or interface.

If used before any router or interface definitions it will be applied to all traffic passing through the firewall. If if-list is given, the MSS will be applied only to those interfaces.

## EXAMPLES

```
tcpmss auto
tcpmss 500
tcpmss 500 "eth1 eth2 eth3"
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-interface(5) - interface definition

•

firehol-router(5) - router definition

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

•

TCPMSS target in the iptables tutorial (https://www.frozentux.net/iptables-tutorial/iptables-tutorial.html#TCPMSSTARGET)

## AUTHORS
FireHOL Team.


firehol-tos

title: firehol-tos(5)

text:
# firehol-tos(5)

## NAME
firehol-tos - set the Type of Service (TOS) of packets

## SYNOPSIS
tos value chain [rule-params]

## DESCRIPTION
The tos helper command sets the Type of Service (TOS) field in packet headers.

Note

There is also a tos parameter which allows matching TOS values within individual rules (see firehol-params(5)).

The value can be an integer number (decimal or hexadecimal) or one of the descriptive values accepted by iptables(8) (run iptables -j TOS --help for a list).

The chain will be used to find traffic to mark. It can be any of the iptables(8) built in chains belonging to the mangle table. The chain names are: INPUT, FORWARD, OUTPUT, PREROUTING and POSTROUTING. These names are case-sensitive.

The rule-params define a set of rule parameters to match the traffic that is to be marked within the chosen chain. See firehol-params(5) for more details.

Any tos commands will affect all traffic matched. They must be declared before the first router or interface.

## EXAMPLES

```
 # set TOS to 16, packets sent by the local machine
 tos 16 OUTPUT
 # set TOS to 0x10 (16), packets routed by the local machine
 tos 0x10 FORWARD
 # set TOS to Maximize-Throughput (8), packets routed by the local
 #              machine, destined for port TCP/25 of 198.51.100.1
 tos Maximize-Throughput FORWARD proto tcp dport 25 dst 198.51.100.1
```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-params(5) - optional rule parameters

•

firehol-tosfix(5) - tosfix config helper

•

iptables(8) (http://ipset.netfilter.org/iptables.man.html) - administration tool for IPv4 firewalls

•

ip6tables(8) (http://ipset.netfilter.org/ip6tables.man.html) - administration tool for IPv6 firewalls

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-tosfix

title: firehol-tosfix(5)

text:
# firehol-tosfix(5)

## NAME
firehol-version - set version number of configuration file

## SYNOPSIS
version 6

## DESCRIPTION
The version helper command states the configuration file version.

If the value passed is newer than the running version of FireHOL supports, FireHOL will not run.

You do not have to specify a version number for a configuration file, but by doing so you will prevent FireHOL trying to process a file which it cannot handle.

The value that FireHOL expects is increased every time that the configuration file format changes.

Note

If you pass version 5 to FireHOL, it will disable IPv6 support and warn you that you must update your configuration.

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


firehol-version

title: firehol-version(5)

text:
# firehol-version(5)

## NAME
firehol-version - set version number of configuration file

## SYNOPSIS
version 6

## DESCRIPTION
The version helper command states the configuration file version.

If the value passed is newer than the running version of FireHOL supports, FireHOL will not run.

You do not have to specify a version number for a configuration file, but by doing so you will prevent FireHOL trying to process a file which it cannot handle.

The value that FireHOL expects is increased every time that the configuration file format changes.

Note

If you pass version 5 to FireHOL, it will disable IPv6 support and warn you that you must update your configuration.

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

FireHOL Website (http://firehol.org/)

•

FireHOL Online PDF Manual (http://firehol.org/firehol-manual.pdf)

•

FireHOL Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


fireqos-class

title: fireqos-class(5)

summary: traffic class definition

text:
# fireqos-class(5)

## NAME
fireqos-class - traffic class definition

## SYNOPSIS
{class|class4|class6|class46} [group] name [optional-class-params]

{class|class4|class6|class46} group end

## DESCRIPTION
There is also an optional match parameter called class; see fireqos-params-match(5).

Writing class inherits the IPv4/IPv6 version from its enclosing interface (see fireqos-interface(5)).

Writing class4 includes only IPv4 traffic in the class.

Writing class6 includes only IPv6 traffic in the class.

Writing class46 includes both IPv4 and IPv6 traffic in the class.

The actual traffic to be matched by a class is defined by adding matches. See fireqos-match(5).

The sequence that classes appear in the configuration defines their priority. The first class is the most important one. Unless otherwise limited it will get all available bandwidth if it needs to.

The second class is less important than the first, the third is even less important than the second, etc. The idea is very simple: just put the classes in the order of importance to you.

Classes can have their priority assigned explicitly with the prio parameter. See fireqos-params-class(5).

Note

The underlying Linux qdisc used by FireQOS, HTB, supports only 8 priorities, from 0 to 7. If you use more than 8 priorities, all after the 8th will get the same priority (prio 7).

All classes in FireQOS share the interface bandwidth. However, every class has a committed rate (the minimum guaranteed speed it will get if it needs to) and a ceiling (the maximum rate this class can reach, provided there is capacity available and even if there is spare).

Classes may be nested to any level by using the class group syntax.

By default FireQOS creates nested classes as classes directly attached to their parent class. This way, nesting does not add any delays.

FireQOS can also emulate new hardware at the group class level. This may be needed, when for example you have an ADSL router that you connect to via Ethernet: you want the LAN traffic to be at Ethernet speed, but WAN traffic at ADSL speed with proper ADSL overheads calculation.

To accomplish hardware emulation nesting, you add a linklayer definition (ethernet, adsl, atm, etc.), or just an mtu to the group class. FireQOS will create a qdisc within the class, where the linklayer parameters will be assigned and the child classes will be attached to this qdisc. This adds some delay to the packets of the child classes, but allows you to emulate new hardware. For linklayer options, see fireqos-params-class(5).

There is special class, called default. Default classes can be given explicitly in the configuration file. If they are not found in the config, FireQOS will append one at the end of each interface or class group.

## PARAMETERS
group

It is possible to nest classes by using a group. Grouped classes must be closed with the class group end command. Class groups can be nested.

name

This is a single-word name for this class and is used for displaying status information.

optional-class-params

The set of optional class parameters to apply to this class.

The following optional class parameters are inherited from the interface the class is in:

•

ceil

•

burst

•

cburst

•

quantum

•

qdisc

If you define one of these at the interface level, then all classes within the interface will get the value by default. These values can be overwritten by defining the parameter on the class too. The same inheritance works on class groups.

Optional class parameters not in the above list are not inherited from interfaces.

FireQOS will by default commit 1/100th of the parent bandwidth to each class. This can be overwritten per class by adding a commit to the class, or adding a minrate at the parent.

## EXAMPLES
To create a nested class, called servers, containing http and smtp:

```
interface eth0 lan input rate 1Gbit
  class voip commit 1Mbit
    match udp ports 5060,10000:10100
  class group servers commit 50%  # define the parent class
    match tcp                     # apply to all child classes
    class mail commit 50%         # 50% of parent ('servers')
      match port 25               # matches within parent ('servers')
    class web commit 50%
      match port 80
  class group end                 # end the group 'servers'
  class streaming commit 30%
```

To create a nested class which emulates an ADSL modem:

```
interface eth0 lan output rate 1Gbit ethernet
  class lan
    match src 192.168.0.0/24 # LAN traffic
  class group adsl rate 10Mbit ceil 10Mbit adsl remote pppoe-llc
    match all # all non-lan traffic in this emulated hardware group
    class voip # class within adsl
      match udp port 5060
    class web # class within adsl
      match tcp port 80,443
  class group end
```

## SEE ALSO
•

fireqos-params-class(5) - QOS class parameters

•

fireqos(1) - FireQOS program

•

fireqos.conf(5) - FireQOS configuration file

•

fireqos-interface(5) - QOS interface definition

•

fireqos-match(5) - QOS traffic match

•

FireHOL Website (http://firehol.org/)

•

FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)

•

FireQOS Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


fireqos-conf

title: fireqos-conf(5)

summary: create an interface definition

text:
# fireqos-conf(5)

## NAME
fireqos-interface - create an interface definition

## SYNOPSIS
{ interface | interface4 } device name direction [optional-class-params] { rate | commit | min } speed

interface46 ...

interface6 ...

## DESCRIPTION
Writing interface or interface4 applies traffic shaping rules only to IPv4 traffic.

Writing interface6 applies traffic shaping rules only to IPv6 traffic.

Writing interface46 applies traffic shaping rules to both IPv4 and IPv6 traffic.

The actual traffic shaping behaviour of a class is defined by adding classes. See fireqos-class(5).

Note

To achieve best results with incoming traffic shaping, you should not use 100% of the available bandwidth at the interface level.

If you use all there is, at 100% utilisation of the link, the neighbour routers will start queuing packets. This will destroy prioritisation. Try 85% or 90% instead.

## PARAMETERS
device

This is the interface name as shown by ip link show (e.g. eth0, ppp1, etc.)

name

This is a single-word name for this interface and is used for retrieving status information later.

direction

If set to input, traffic coming in to the interface is shaped.

If set to output, traffic going out via the interface is shaped.

if set to bidirectional traffic for both input and output can be shaped. If you need to differentiate input and output parameters per statements within the interface, you can prefix them with input or output like this:

```
interface eth0 lan bidirectional ...
    class voip input commit 1Mbit output commit 2Mbit ...
```

optional-class-params

For a list of optional class parameters which can be applied to an interface, see fireqos-params-class(5).

speed

For an interface, the committed speed must be specified with the rate option. The speed can be expressed in any of the units described in fireqos.conf(5).

## EXAMPLES
To create an input policy on eth0, capable of delivering up to 1Gbit of traffic:

```
interface eth0 lan-in input rate 1Gbit
```

## SEE ALSO
•

fireqos.conf(5) - FireQOS configuration file

•

fireqos-class(5) - QOS class definition

•

fireqos-params-class(5) - QOS class parameters

•

FireHOL Website (http://firehol.org/)

•

FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)

•

FireQOS Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


fireqos-interface

title: fireqos-interface(5)

summary: create an interface definition

text:
# fireqos-interface(5)

## NAME
fireqos-interface - create an interface definition

## SYNOPSIS
{ interface | interface4 } device name direction [optional-class-params] { rate | commit | min } speed

interface46 ...

interface6 ...

## DESCRIPTION
Writing interface or interface4 applies traffic shaping rules only to IPv4 traffic.

Writing interface6 applies traffic shaping rules only to IPv6 traffic.

Writing interface46 applies traffic shaping rules to both IPv4 and IPv6 traffic.

The actual traffic shaping behaviour of a class is defined by adding classes. See fireqos-class(5).

Note

To achieve best results with incoming traffic shaping, you should not use 100% of the available bandwidth at the interface level.

If you use all there is, at 100% utilisation of the link, the neighbour routers will start queuing packets. This will destroy prioritisation. Try 85% or 90% instead.

## PARAMETERS
device

This is the interface name as shown by ip link show (e.g. eth0, ppp1, etc.)

name

This is a single-word name for this interface and is used for retrieving status information later.

direction

If set to input, traffic coming in to the interface is shaped.

If set to output, traffic going out via the interface is shaped.

if set to bidirectional traffic for both input and output can be shaped. If you need to differentiate input and output parameters per statements within the interface, you can prefix them with input or output like this:

```
interface eth0 lan bidirectional ...
    class voip input commit 1Mbit output commit 2Mbit ...
```

optional-class-params

For a list of optional class parameters which can be applied to an interface, see fireqos-params-class(5).

speed

For an interface, the committed speed must be specified with the rate option. The speed can be expressed in any of the units described in fireqos.conf(5).

## EXAMPLES
To create an input policy on eth0, capable of delivering up to 1Gbit of traffic:

```
interface eth0 lan-in input rate 1Gbit
```

## SEE ALSO
•

fireqos.conf(5) - FireQOS configuration file

•

fireqos-class(5) - QOS class definition

•

fireqos-params-class(5) - QOS class parameters

•

FireHOL Website (http://firehol.org/)

•

FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)

•

FireQOS Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


fireqos-match

title: fireqos-match(5)

summary: shared class/match parameters

text:
# fireqos-match(5)

## NAME
fireqos-params - shared class/match parameters

## SYNOPSIS
prio

priority

## DESCRIPTION
Some optional parameter names are the same for both class and match. This page exists as a placeholder to help you find the appropriate documentation.

If you are searching for FireQOS parameters in general, see both fireqos-params-class(5) and/or fireqos-params-match(5) depending upon your need.

prio

For the class version, see fireqos-params-class(5).

For the match version, see fireqos-params-match(5).

priority

For the class version, see fireqos-params-match(5).

For the match version, see fireqos-params-class(5).

## SEE ALSO
•

fireqos-params-class(5) - QOS class parameters

•

fireqos-params-match(5) - QOS match parameters

•

FireHOL Website (http://firehol.org/)

•

FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)

•

FireQOS Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


fireqos-params

title: fireqos-params(5)

summary: shared class/match parameters

text:
# fireqos-params(5)

## NAME
fireqos-params - shared class/match parameters

## SYNOPSIS
prio

priority

## DESCRIPTION
Some optional parameter names are the same for both class and match. This page exists as a placeholder to help you find the appropriate documentation.

If you are searching for FireQOS parameters in general, see both fireqos-params-class(5) and/or fireqos-params-match(5) depending upon your need.

prio

For the class version, see fireqos-params-class(5).

For the match version, see fireqos-params-match(5).

priority

For the class version, see fireqos-params-match(5).

For the match version, see fireqos-params-class(5).

## SEE ALSO
•

fireqos-params-class(5) - QOS class parameters

•

fireqos-params-match(5) - QOS match parameters

•

FireHOL Website (http://firehol.org/)

•

FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)

•

FireQOS Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


fireqos-params-class

title: fireqos-params-class(5)

summary: optional class parameters

text:
# fireqos-params-class(5)

## NAME
fireqos-params-class - optional class parameters

## SYNOPSIS
rate | commit | min speed

ceil | max speed

minrate speed

{ qdisc qdisc-name | pfifo|bfifo|sfq|fq_codel|codel|none } [options "qdisc-options"]

prio { 0..7 | keep | last }

{ linklayer linklayer-name } | { adsl {local|remote} encapsulation } | ethernet | atm

mtu bytes

mpu bytes

tsize size

overhead bytes

r2q factor

burst bytes

cburst bytes

quantum bytes

priority | balanced

input | output

## DESCRIPTION
All of the options apply to interface and class statements.

Units for speeds are defined in fireqos.conf(5).

### input, output
For bidirectional interfaces, input and output define the direction for which the parameters following it are applied.

Only the following parameters are affected (all the others are applied to both input and output):

•

minrate

•

rate, min, commit

•

ceil, max

If one of the above is not defined for either input or output, its default will be used.

### rate, commit, min
When a committed rate of speed is provided to a class, it means that the bandwidth will be given to the class when it needs it. If the class does not need the bandwidth, it will be available for any other class to use.

For interfaces, a rate must be defined.

For classes the rate defaults to 1/100 of the interface capacity.

## ceil, max
Defines the maximum speed a class can use. Even there is available bandwidth, a class will not exceed its ceil speed.

For interfaces, the default is the rate speed of the interface.

For classes, the defaults is the ceil of the their interfaces.

### minrate
Defines the default committed speed for all classes not specifically given a rate in the config file. It forces a recalculation of tc(8) r2q.

When minrate is not given, FireQOS assigns a default value of 1/100 of the interface rate.

### qdisc qdisc-name, pfifo, bfifo, sfq, fq_codel, codel, none
The qdisc defines the method to distribute class bandwidth to its sockets. It is applied within the class itself and is useful in cases where a class gets saturated. For information about these, see the Traffic Control Howto (http://www.tldp.org/HOWTO/Traffic-Control-HOWTO/classless-qdiscs.html)

A qdisc is only useful when applied to a class. It can be specified at the interface level in order to set the default for all of the included classes.

To pass options to a qdisc, you can specify them through an environment variable or explicitly on each class.

Set the variable FIREQOS_DEFAULT_QDISC_OPTIONS_qdiscname in the config file. For example, for sfq:

```
FIREQOS_DEFAULT_QDISC_OPTIONS_sfq="perturb 10 quantum 2000".
```

Using this variable each sfq will get these options by default. You can still override this by specifying explicit options for individual qdiscs, for example to add some sfq options you would write:

```
class classname sfq options "perturb 10 quantum 2000"
```

The options keyword must appear just after the qdisc name.

### prio (class)
Note

There is also a match parameter called prio, see fireqos-params-match(5).

HTB supports 8 priorities, from 0 to 7. Any number less than 0 will give priority 0. Any number above 7 will give priority 7.

By default, FireQOS gives the first class priority 0, and increases this number by 1 for each class it encounters in the config file. If there are more than 8 classes, all classes after the 8th will get priority 7. In balanced mode (see balanced, below), all classes will get priority 4 by default.

FireQOS restarts priorities for each interface and class group.

The class priority defines how the spare bandwidth is spread among the classes. Classes with higher priorities (lower prio) will get all spare bandwidth. Classes with the same priority will get a percentage of the spare bandwidth, proportional to their committed rates.

The keywords keep and last will make a class use the priority of the class just above / before it. So to make two consecutive classes have the same prio, just add prio keep to the second one.

### linklayer linklayer-name, ethernet, atm
The linklayer can only be given on interfaces. It is used by the kernel to calculate the overheads in the packets.

### adsl
adsl is a special linklayer that automatically calculates ATM overheads for the link.

local is used when linux is running PPPoE.

remote is used when PPPoE is running on the router.

Note

This special case has not yet been demonstrated for sure. Experiment a bit and if you find out, let us know to update this page. In practice, this parameter lets the kernel know that the packets it sees, have already an ethernet header on them.

encapsulation can be one of (all the labels on the same line are aliases):

•

IPoA-VC/Mux or ipoa-vcmux or ipoa-vc or ipoa-mux,

•

IPoA-LLC/SNAP or ipoa-llcsnap or ipoa-llc or ipoa-snap

•

Bridged-VC/Mux or bridged-vcmux or bridged-vc or bridged-mux

•

Bridged-LLC/SNAP or bridged-llcsnap or bridged-llc or bridged-snap

•

PPPoA-VC/Mux or pppoa-vcmux or pppoa-vc or pppoa-mux

•

PPPoA-LLC/SNAP or pppoa-llcsnap or pppoa-llc or pppoa-snap

•

PPPoE-VC/Mux or pppoe-vcmux or pppoe-vc or pppoe-mux

•

PPPoE-LLC/SNAP or pppoe-llcsnap or pppoe-llc or pppoe-snap

If your adsl router can give you the mtu, it would be nice to add an mtu parameter too. For detailed info, see here (http://ace-host.stuart.id.au/russell/files/tc/tc-atm/).

### mtu
Defines the MTU of the interface in bytes.

FireQOS will query the interface to find its MTU. You can overwrite this behaviour by giving this parameter to a class or interface.

### mpu
Defines the MPU of the interface in bytes.

FireQOS does not set a default value. You can set your own using this parameter.

### tsize
FireQOS does not set a default size. You can set your own using this parameter.

### overhead
FireQOS automatically calculates the bytes overhead for ADSL. For all other technologies, you can specify the overhead in the config file.

### r2q
FireQOS calculates the proper r2q factor, so that you can control speeds in steps of 1/100th of the interface speed (if that is possible).

Note

The HTB manual states that this parameter is ignored when a quantum have been set. By default, FireQOS sets quantum to interface MTU, so r2q is probably is ignored by the kernel.

### burst
burst specifies the number of bytes that will be sent at once, at ceiling speed, when a class is allowed to send traffic. It is like a 'traffic unit'. A class is allowed to send at least burst bytes before trying to serve any other class.

burst should never be lower that the interface mtu and class groups and interfaces should never have a smaller burst value than their children. If you do specify a higher burst for a child class, its parent may get stuck sometimes (the child will drain the parent).

By default, FireQOS lets the kernel decide this parameter, which calculates the lowest possible value (the minimum value depends on the rate of the interface and the clock speed of the CPU).

burst is inherited from interfaces to classes and from group classes to their subclasses. FireQOS will not allow you to set a burst at a subclass, higher than its parent. Setting a burst of a subclass higher than its parent will drain the parent class, which may be stuck for up to a minute when this happens. For this check to work, FireQOS uses just its configuration (it does not query the kernel to check how the value specified in the config file for a subclass relates to the actual value of its parent).

### cburst
cburst is like burst, but at hardware speed (not just ceiling speed).

By default, FireQOS lets the kernel decide this parameter.

cburst is inherited from interfaces to classes and from group classes to their subclasses. FireQOS will not allow you to set a cburst at a subclass, higher to its parent. Setting a cburst of a subclass higher than its parent, will drain the parent class, which may be stuck for up to a minute when this happens. For this check to work, FireQOS uses just its configuration (it does not query the kernel to check how the value specified in the config file for a subclass relates to the actual value of its parent).

### quantum
quantum specifies the number of bytes a class is allowed to send at once, when it is borrowing spare bandwidth from other classes.

By default, FireQOS sets quantum to the interface mtu.

quantum is inherited from interfaces to classes and from group classes to their subclasses.

### priority, balanced
These parameters set the priority mode of the child classes.

priority

priority is the default mode, where FireQOS assigns an incremental priority to each class. In this mode, the first class takes prio 0, the second prio 1, etc. When a class has a higher prio than the others (higher = smaller number), this high priority class will get all the spare bandwidth available, when it needs it. Spare bandwidth will be allocate to lower priority classes only when the higher priority ones do not need it.

balanced

balanced mode gives prio 4 to all child classes. When multiple classes have the same prio, the spare bandwidth available is spread among them, proportionally to their committed rate. The value 4 can be overwritten by setting FIREQOS_BALANCED_PRIO at the top of the config file to the prio you want the balanced mode to assign for all classes.

The priority mode can be set in interfaces and class groups. The effect is the same. The classes that are defined as child classes, will get by default the calculated class prio based on the priority mode given.

These options affect only the default prio that will be assigned by FireQOS. The default is used only if you don't explicitly use a prio parameter on a class.

Note

There is also a match parameter called priority, see fireqos-params-match(5).

## SEE ALSO
•

fireqos(1) - FireQOS program

•

fireqos.conf(5) - FireQOS configuration file

•

fireqos-interface(5) - QOS interface definition

•

fireqos-class(5) - QOS class definition

•

FireHOL Website (http://firehol.org/)

•

FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)

•

FireQOS Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


fireqos-params-match

title: fireqos-params-match(5)

summary: optional class parameters

text:
# fireqos-params-match(5)

## NAME
fireqos-params-class - optional class parameters

## SYNOPSIS
rate | commit | min speed

ceil | max speed

minrate speed

{ qdisc qdisc-name | pfifo|bfifo|sfq|fq_codel|codel|none } [options "qdisc-options"]

prio { 0..7 | keep | last }

{ linklayer linklayer-name } | { adsl {local|remote} encapsulation } | ethernet | atm

mtu bytes

mpu bytes

tsize size

overhead bytes

r2q factor

burst bytes

cburst bytes

quantum bytes

priority | balanced

input | output

## DESCRIPTION
All of the options apply to interface and class statements.

Units for speeds are defined in fireqos.conf(5).

### input, output
For bidirectional interfaces, input and output define the direction for which the parameters following it are applied.

Only the following parameters are affected (all the others are applied to both input and output):

•

minrate

•

rate, min, commit

•

ceil, max

If one of the above is not defined for either input or output, its default will be used.

### rate, commit, min
When a committed rate of speed is provided to a class, it means that the bandwidth will be given to the class when it needs it. If the class does not need the bandwidth, it will be available for any other class to use.

For interfaces, a rate must be defined.

For classes the rate defaults to 1/100 of the interface capacity.

## ceil, max
Defines the maximum speed a class can use. Even there is available bandwidth, a class will not exceed its ceil speed.

For interfaces, the default is the rate speed of the interface.

For classes, the defaults is the ceil of the their interfaces.

### minrate
Defines the default committed speed for all classes not specifically given a rate in the config file. It forces a recalculation of tc(8) r2q.

When minrate is not given, FireQOS assigns a default value of 1/100 of the interface rate.

### qdisc qdisc-name, pfifo, bfifo, sfq, fq_codel, codel, none
The qdisc defines the method to distribute class bandwidth to its sockets. It is applied within the class itself and is useful in cases where a class gets saturated. For information about these, see the Traffic Control Howto (http://www.tldp.org/HOWTO/Traffic-Control-HOWTO/classless-qdiscs.html)

A qdisc is only useful when applied to a class. It can be specified at the interface level in order to set the default for all of the included classes.

To pass options to a qdisc, you can specify them through an environment variable or explicitly on each class.

Set the variable FIREQOS_DEFAULT_QDISC_OPTIONS_qdiscname in the config file. For example, for sfq:

```
FIREQOS_DEFAULT_QDISC_OPTIONS_sfq="perturb 10 quantum 2000".
```

Using this variable each sfq will get these options by default. You can still override this by specifying explicit options for individual qdiscs, for example to add some sfq options you would write:

```
class classname sfq options "perturb 10 quantum 2000"
```

The options keyword must appear just after the qdisc name.

### prio (class)
Note

There is also a match parameter called prio, see fireqos-params-match(5).

HTB supports 8 priorities, from 0 to 7. Any number less than 0 will give priority 0. Any number above 7 will give priority 7.

By default, FireQOS gives the first class priority 0, and increases this number by 1 for each class it encounters in the config file. If there are more than 8 classes, all classes after the 8th will get priority 7. In balanced mode (see balanced, below), all classes will get priority 4 by default.

FireQOS restarts priorities for each interface and class group.

The class priority defines how the spare bandwidth is spread among the classes. Classes with higher priorities (lower prio) will get all spare bandwidth. Classes with the same priority will get a percentage of the spare bandwidth, proportional to their committed rates.

The keywords keep and last will make a class use the priority of the class just above / before it. So to make two consecutive classes have the same prio, just add prio keep to the second one.

### linklayer linklayer-name, ethernet, atm
The linklayer can only be given on interfaces. It is used by the kernel to calculate the overheads in the packets.

### adsl
adsl is a special linklayer that automatically calculates ATM overheads for the link.

local is used when linux is running PPPoE.

remote is used when PPPoE is running on the router.

Note

This special case has not yet been demonstrated for sure. Experiment a bit and if you find out, let us know to update this page. In practice, this parameter lets the kernel know that the packets it sees, have already an ethernet header on them.

encapsulation can be one of (all the labels on the same line are aliases):

•

IPoA-VC/Mux or ipoa-vcmux or ipoa-vc or ipoa-mux,

•

IPoA-LLC/SNAP or ipoa-llcsnap or ipoa-llc or ipoa-snap

•

Bridged-VC/Mux or bridged-vcmux or bridged-vc or bridged-mux

•

Bridged-LLC/SNAP or bridged-llcsnap or bridged-llc or bridged-snap

•

PPPoA-VC/Mux or pppoa-vcmux or pppoa-vc or pppoa-mux

•

PPPoA-LLC/SNAP or pppoa-llcsnap or pppoa-llc or pppoa-snap

•

PPPoE-VC/Mux or pppoe-vcmux or pppoe-vc or pppoe-mux

•

PPPoE-LLC/SNAP or pppoe-llcsnap or pppoe-llc or pppoe-snap

If your adsl router can give you the mtu, it would be nice to add an mtu parameter too. For detailed info, see here (http://ace-host.stuart.id.au/russell/files/tc/tc-atm/).

### mtu
Defines the MTU of the interface in bytes.

FireQOS will query the interface to find its MTU. You can overwrite this behaviour by giving this parameter to a class or interface.

### mpu
Defines the MPU of the interface in bytes.

FireQOS does not set a default value. You can set your own using this parameter.

### tsize
FireQOS does not set a default size. You can set your own using this parameter.

### overhead
FireQOS automatically calculates the bytes overhead for ADSL. For all other technologies, you can specify the overhead in the config file.

### r2q
FireQOS calculates the proper r2q factor, so that you can control speeds in steps of 1/100th of the interface speed (if that is possible).

Note

The HTB manual states that this parameter is ignored when a quantum have been set. By default, FireQOS sets quantum to interface MTU, so r2q is probably is ignored by the kernel.

### burst
burst specifies the number of bytes that will be sent at once, at ceiling speed, when a class is allowed to send traffic. It is like a 'traffic unit'. A class is allowed to send at least burst bytes before trying to serve any other class.

burst should never be lower that the interface mtu and class groups and interfaces should never have a smaller burst value than their children. If you do specify a higher burst for a child class, its parent may get stuck sometimes (the child will drain the parent).

By default, FireQOS lets the kernel decide this parameter, which calculates the lowest possible value (the minimum value depends on the rate of the interface and the clock speed of the CPU).

burst is inherited from interfaces to classes and from group classes to their subclasses. FireQOS will not allow you to set a burst at a subclass, higher than its parent. Setting a burst of a subclass higher than its parent will drain the parent class, which may be stuck for up to a minute when this happens. For this check to work, FireQOS uses just its configuration (it does not query the kernel to check how the value specified in the config file for a subclass relates to the actual value of its parent).

### cburst
cburst is like burst, but at hardware speed (not just ceiling speed).

By default, FireQOS lets the kernel decide this parameter.

cburst is inherited from interfaces to classes and from group classes to their subclasses. FireQOS will not allow you to set a cburst at a subclass, higher to its parent. Setting a cburst of a subclass higher than its parent, will drain the parent class, which may be stuck for up to a minute when this happens. For this check to work, FireQOS uses just its configuration (it does not query the kernel to check how the value specified in the config file for a subclass relates to the actual value of its parent).

### quantum
quantum specifies the number of bytes a class is allowed to send at once, when it is borrowing spare bandwidth from other classes.

By default, FireQOS sets quantum to the interface mtu.

quantum is inherited from interfaces to classes and from group classes to their subclasses.

### priority, balanced
These parameters set the priority mode of the child classes.

priority

priority is the default mode, where FireQOS assigns an incremental priority to each class. In this mode, the first class takes prio 0, the second prio 1, etc. When a class has a higher prio than the others (higher = smaller number), this high priority class will get all the spare bandwidth available, when it needs it. Spare bandwidth will be allocate to lower priority classes only when the higher priority ones do not need it.

balanced

balanced mode gives prio 4 to all child classes. When multiple classes have the same prio, the spare bandwidth available is spread among them, proportionally to their committed rate. The value 4 can be overwritten by setting FIREQOS_BALANCED_PRIO at the top of the config file to the prio you want the balanced mode to assign for all classes.

The priority mode can be set in interfaces and class groups. The effect is the same. The classes that are defined as child classes, will get by default the calculated class prio based on the priority mode given.

These options affect only the default prio that will be assigned by FireQOS. The default is used only if you don't explicitly use a prio parameter on a class.

Note

There is also a match parameter called priority, see fireqos-params-match(5).

## SEE ALSO
•

fireqos(1) - FireQOS program

•

fireqos.conf(5) - FireQOS configuration file

•

fireqos-interface(5) - QOS interface definition

•

fireqos-class(5) - QOS class definition

•

FireHOL Website (http://firehol.org/)

•

FireQOS Online PDF Manual (http://firehol.org/fireqos-manual.pdf)

•

FireQOS Online Documentation (http://firehol.org/documentation/)

## AUTHORS
FireHOL Team.


vnetbuild-conf

title: vnetbuild-conf(5)

text:
# vnetbuild-conf(5)

## NAME
vnetbuild - an easy to use but powerful namespace setup tool

## SYNOPSIS
sudo vnetbuild CONFIGFILE { start | stop | status }

vnetbuild CONFIGFILE graphviz OUTFILE.{gv|png|pdf|ps}

## DESCRIPTION
VNetBuild is a program that helps you set up groups of interconnected network namespaces, to simulate networks of any complexity without resorting to using real or virtual machines.

This is ideal for testing complex multi-host configurations with a minimal amount of resources on a single machine:

•

Each namespace can have its own network setup, including firewall and QOS configuration.

•

Commands can be run in the namespace and will have that specific view of the network, including running standard network tools and daemons.

Run without any arguments, vnetbuild will present some help on usage.

## COMMANDS
start

Sets up a series of network namespaces as defined in CONFIGFILE. vnetbuild creates interconnected network devices as specified in the configuration, sets up routing and runs any custom commands that are given within the namespace.

stop

Removes any devices from the namespaces defined in CONFIGFILE and kills any processes running with the namespaces, then removes the namespaces themselves.

status

For each namespace defined in CONFIGFILE, shows if it is active and if so its network devices and their configuration.

graphviz OUTFILE

Generates a graph of the network defined in CONFIGFILE. This does not need root access, nor does it require the namespaces to have been started.

OUTFILE can be png pdf or ps. If the extension gv is given the output is a graphviz(7) file which you can process separately.

## RUNNING COMMANDS IN A NAMESPACE
Once you have created a set of network namespaces, you can easily run any commands you want within them. If for instance you defined three hosts (host_a with IP 10.0.0.1, host_b with IP 10.0.0.2 and host_c with IP 10.0.0.3) connected via a common switch sw0:

```
 # ping host_b and host_c from host_a
 sudo ip netns exec host_a ping 10.0.0.2
 sudo ip netns exec host_a ping 10.0.0.3
 # use netcat to listen on host_a and send data from host_b
 # (use two terminals to run the commands simultaneously)
 sudo ip netns exec host_a nc -l -p 23
 sudo ip netns exec host_b nc -q 0 10.0.0.1 23 < /etc/hosts
 # capture traffic passing through the switch, then view it
 sudo ip netns exec sw0 tcpdump -i switch -w capfile
 wireshark capfile
 # Use 'firehol panic' in host_b to block all traffic
 # (you could equally load a full config etc.)
 sudo ip netns exec host_b firehol panic
 # this is now blocked
 sudo ip netns exec host_a ping 10.0.0.2
 # not blocked (host_b not involved)
 sudo ip netns exec host_a ping 10.0.0.3
 # obtain a shell for your regular user, only "in" host_c
 sudo ip netns exec host_c sudo -i -u $USER
 ip a | grep 10.0.0.3
```

## SEE ALSO
•

vnetbuild.conf(5) - VNetBuild configuration file

•

firehol(1) - FireHOL program

•

fireqos(1) - FireQOS program

•

FireHOL Website (http://firehol.org/)

•

VNetBuild Online PDF Manual (http://firehol.org/vnetbuild-manual.pdf)

•

VNetBuild Online Documentation (http://firehol.org/documentation/) 8 192.168.1.2/24 host b dev vppp0 a/veth0 10.0.0.2/8 192.168.1.3/24 ````

A dev may not specify an IP address if it is in a switch. Switches exist just to tie together multiple devices in hosts, just like a physical network switch.

bridgedev BRIDGE ...

Define an ethernet bridge, BRIDGE in a host. These are setup automatically using ip(8) and shown with bridge(8).

A bridge can specify network devices from its own namespace to be automatically added, as well as its own IP address(es).

```
host a
  dev veth0
  dev veth1 otherns/vdev0
  bridgedev vbr0 veth0 veth1 10.0.0.3/8
```

Devices included in a bridge generally do not need their own IP address (although that is permitted).

Bridges cannot have a pair themselves, but any devices added to a bridge need a pair as usual.

route ROUTECMD

Specify an additional network route for a host.

Most commonly to add a default route from hosts on a "LAN" to the machine that acts as a gateway, e.g.:

```
route default via 10.0.0.254
```

The syntax of ROUTECMD is anything that can fit this pattern:

```
ip route add ROUTECMD
```

See ip(8) and ip-route(8) for help adding routes. If you want to do anything more complex than simply adding routes, use the exec configuration statement.

pre_up DEVICE CUSTOMCMD

Execute custom commands in a host or switch just before bringing up the specified device. All of the pre_up statements for a device are combined and executed in the namespace.

In addition to any explicitly defined interfaces, switches have an implicit bridge device called switch which can also be used in pre_up commands.

Bridges always start after other devices, so to run a command after all everything has been created but before any interfaces are up, you can make use of pre_up on the first defined dev.

See below for some common uses for custom pre_up and exec commands.

exec CUSTOMCMD

Execute a custom command in a host or switch once the rest of the namespace setup is complete.

Once all the namespaces are created, the final step in setting each one up is to have its exec statements combined and executed.

It is roughly the equivalent to writing your own script and executing it after vnetbuild start has finished:

```
sudo ip netns exec myns ./myscript.sh
```

See below for some common uses for custom pre_up and exec commands.

## COMMON CUSTOM COMMANDS
For the most part it doesn't matter whether these commands are used in pre_up or exec operations - the only difference is when they will execute, so e.g. if you want a firewall in place before any interfaces come up then start it from the pre_up of the first device. If you only want the firewall after all devices are up, put it in exec, e.g.:

```
host myfirewall
    ...
    exec firehol myfirewall.conf start
```

Forwarding is not enabled by the Linux kernel when a namespace is first created. This can be easily done for any hosts that need to forward traffic:

```
host mygateway
    ...
    exec echo 1 > /proc/sys/net/ipv4/ip_forward
```

The exec operates in the mygateway namespace so your host is not affected.

Bridges are created without STP being enabled. To enable STP to ensure loops are not created, the following can be done:

```
host myhost
    bridgedev vbr0 ...
    ...
    pre_up vbr0 echo 2 > /sys/class/net/vbr0/bridge/stp_state
switch myswitch
    ...
    pre_up switch echo 2 > /sys/class/net/vbr0/bridge/stp_state
```

You could also use brctl stp vbr0 on and brctl stp switch on instead of setting the values directly. To disable multicast snooping you can use exactly the same method e.g.:

```
switch myswitch
    ...
    pre_up switch echo 0 > /sys/class/net/switch/bridge/multicast_snooping
```

It is possible to run firehol within a namespace to set up custom

Logs from network namespaces are not included in the normal system logs. To enable iptables logging you must start an instance of ulogd(8) in the namespace and use ULOG or NFLOG logging. For FireHOL, that means set FIREHOL_LOG_MODE=ULOG or FIREHOL_LOG_MODE=NFLOG. Note that NFLOG only works with ulogd version 2.

The default configuration for ulogd(8) is /etc/ulogd.conf. Assuming the default place it will write iptables logs to is /var/log/ulog/syslogemu.log (otherwise change the sed command as required), it is simple to set up per-namespace logging:

```
host mygateway
  ...
  exec sed 's:/var/log/ulog/syslogemu.log:/var/log/ulog/mygateway.log:' /etc/ulogd.conf > $NSTMP/ulogd.conf
  exec /usr/sbin/ulogd -d -c $NSTMP/ulogd.conf
```

The -d flag to ulogd(8) makes it become a daemon; when vnetbuild stop executes it will automatically kill any programs running in the namespaces is is stopping, which includes the logging daemon.

The configuration file will get cleaned as soon as vnetbuild start is finished. To be able to access such files you need to write them to a location not under $NSTMP or create them outside the vnetbuild configuration altogether.

## EXAMPLE
A simple LAN arrangement with two hosts, one of which is a gateway to third host:

```
host host01
  dev veth0 10.0.0.1/8
  dev vppp0 192.168.0.1/24
  exec echo 1 > /proc/sys/net/ipv4/ip_forward
  route default via 192.168.0.1
host host02
  dev veth0 10.0.0.2/8
  route default via 10.0.0.1
switch lan
  dev d01 host01/veth0
  dev d02 host02/veth0
host extern01
  dev veth0 host01/vppp0 192.168.0.254/24
  route default via 192.168.0.1
  exec echo 1 > /proc/sys/net/ipv4/ip_forward
```

## LIMITATIONS
When created, the namespaces setup by vnetbuild are completely disconnected from any real network. There is no way of defining such a connection in the vnetbuild configuration as allowing it would lead to conflicts with the normal network setup tools and configuration files in most distributions.

It is possible to arrange your network so you can connect real devices into one or more network namespaces. For the general approach see this mailing list post (http://lists.firehol.org/pipermail/firehol-support/2015-April/003043.html).

## SEE ALSO
•

vnetbuild(1) - VNetBuild program

•

FireHOL Website (http://firehol.org/)

•

VNetBuild Online PDF Manual (http://firehol.org/vnetbuild-manual.pdf)

•

VNetBuild Online Documentation (http://firehol.org/documentation/)

•

ip(8) (http://manpages.ubuntu.com/manpages/trusty/man8/ip.8.html) - show/manipulate network devices

•

ip-route(8) (http://manpages.ubuntu.com/manpages/trusty/man8/ip-route.8.html) - routing table management

•

bridge(8) (http://manpages.ubuntu.com/manpages/trusty/man8/bridge.8.html) - routing table management

•

ulogd(8) (http://manpages.ubuntu.com/manpages/trusty/man8/ulogd.8.html) - netfilter/iptables logging daemon

## AUTHORS
FireHOL Team.


firejail-login

package: firejail

title: firejail-login(5)

summary: Login file syntax for Firejail

text:
# firejail-login(5)

## NAME
login.users - Login file syntax for Firejail

## DESCRIPTION
/etc/firejail/login.users file describes additional arguments passed to the firejail executable upon user logging into a Firejail restricted shell. Each user entry in the file consists of a user name followed by the arguments passed to firejail. The format is as follows:

user_name: arguments

Example:

netblue: --net=none --protocol=unix

Wildcard patterns are accepted in the user name field:

user*: --private

## RESTRICTED SHELL
To configure a restricted shell, replace /bin/bash with /usr/bin/firejail in the /etc/passwd file for each user that needs to be restricted. Alternatively, you can specify /usr/bin/firejail using the `adduser` or `usermod` commands:

adduser --shell /usr/bin/firejail username

usermod --shell /usr/bin/firejail username

## FILES
/etc/firejail/login.users

## LICENSE
Firejail is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Homepage: https://firejail.wordpress.com

## SEE ALSO
firejail(1), firemon(1), firecfg(1), firejail-profile(5), firejail-users(5), jailcheck(1)