firehol-synproxy

title: firehol-synproxy(5)

summary: configure synproxy

text:
# firehol-synproxy(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-tcpmss

package: firehol

title: firehol-tcpmss(5)

text:
# firehol-tcpmss(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-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)

summary: apply suggested TOS values to packets

text:
# firehol-tosfix(5)

## NAME
firehol-tosfix - apply suggested TOS values to packets

## SYNOPSIS
tosfix

## DESCRIPTION
The tosfix helper command sets the Type of Service (TOS) field in packet headers based on the suggestions given by Erik Hensema in iptables and tc shaping tricks (http://www.docum.org/docum.org/faq/cache/49.html).

The following TOS values are set:

•

All TCP ACK packets with length less than 128 bytes are assigned Minimize-Delay, while bigger ones are assigned Maximize-Throughput

•

All packets with TOS Minimize-Delay, that are bigger than 512 bytes are set to Maximize-Throughput, except for short bursts of 2 packets per second

The tosfix command must be used before the first router or interface.

## EXAMPLE

```
tosfix

```

## SEE ALSO
•

firehol(1) - FireHOL program

•

firehol.conf(5) - FireHOL configuration

•

firehol-tos(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-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: FireQOS configuration file

text:
# fireqos-conf(5)

## NAME
fireqos.conf - FireQOS configuration file

## DESCRIPTION
This file defines the traffic shaping that will be applied by fireqos(1).

The default configuration file is /etc/firehol/fireqos.conf. It can be overridden from the command line.

A configuration consists of a number of input and output interface definitions (see fireqos-interface(5)). Each interface can define any number of (optionally nested) classes (see fireqos-class(5)) which shape the traffic which they match (see fireqos-match(5)).

## SPEED UNITS
In FireQOS, speeds can be expressed in the following units:

\#bps

\# bytes per second

\#kbps; #Kbps

\# kilobytes per second

\#mbps; #Mbps

\# megabytes per second

\#gbps; #Gbps

\# gigabytes per second

\#bit

\# bits per second

\#kbit; #Kbit; #

\# kilobits per second (default)

\#mbit; #Mbit

\# megabits per second

\#gbit; #Gbit

\# gigabits per second

\#%

In a class, uses this percentage of the enclosing rate.

Note

The default, kbit is different to tc(8) which assumes bytes per second when no unit is specified.

## EXAMPLE
This example uses match statements.

```
 # incoming traffic from my ADSL router
 interface eth2 adsl-in input rate 10500kbit adsl remote pppoe-llc
   class voip commit 100kbit pfifo
     match udp ports 5060,10000:10100 # asterisk sip and rtp
     match udp ports 16393:16402 # apple facetime
   class realtime commit 10%
     match tcp port 22,1195:1198,1753 # ssh, openvpn, pptp
     match udp port 53 # dns
     match proto GRE
     match icmp
     match tcp syn
     match tcp ack
   class clients commit 10%
     match tcp port 20,21,25,80,143,443,465,873,993 # mail, web, ftp, etc
 # unmatched traffic goes here ('default' is a special name)
   class default max 90%
 # I define torrents beneath the default class, so they slow
 # down when the default class is willing to get bandwidth
   class torrents max 90%
     match port 51414 # my torrent client
 # outgoing traffic to my ADSL router
 interface eth2 adsl-out output rate 800kbit adsl remote pppoe-llc
   class voip commit 100kbit pfifo
     match udp ports 5060,10000:10100 # asterisk sip and rtp
     match udp ports 16393:16402 # apple facetime
   class realtime commit 10%
     match tcp port 22,1195:1198,1753 # ssh, openvpn, pptp
     match udp port 53 # dns
     match proto GRE
     match icmp
     match tcp syn
     match tcp ack
   class clients commit 10%
     match tcp port 20,21,25,80,143,443,465,873,993 # mail, web, ftp, etc
 # unmatched traffic goes here ('default' is a special name)
   class default max 90%
 # I define torrents beneath the default class, so they slow
 # down when the default class is willing to get bandwidth
   class torrents max 90%
     match port 51414 # my torrent client
```

This example uses server/client statements in a bidirectional interface. Of course match statements can also be specified. FireQOS will create 2 interfaces out of this: world-in and world-out.

```
  DEVICE=dsl0
  INPUT_SPEED="12000kbit"
  OUTPUT_SPEED="800kbit"
  LINKTYPE="adsl local pppoe-llc"
  # a few service definitions
  # all the rest that are used in this example
  # are defined by FireQOS
  server_netdata_ports="tcp/19999"
  server_rtp_ports="udp/10000:10100"
  server_openvpn_ports="any/1195:1198"
  server_mytorrent_ports="any/60000"
  server_mytorrenttransfers_ports="any/60001:64999"
  server_myssh_ports="tcp/2222"
  # League Of Legends game (yes! I have kids)
  server_lol_ports="udp/5000:5500 tcp/8393:8400,2099,5223,5222,8088"

  interface $DEVICE world bidirectional $LINKTYPE input rate $INPUT_SPEED output rate $OUTPUT_SPEED

    class voip commit 100kbit pfifo
      server sip
      client sip
      server rtp
      client stun
    class interactive input commit 20% output commit 10%
      server icmp limit 50%
      server dns
      client dns
      server ssh
      client ssh
      server myssh
      client myssh
      client teamviewer
      client lol
    class chat input commit 1000kbit output commit 30%
      client facetime
      server hangouts
      client hangouts
      client gtalk
      client jabber
    class vpns input commit 20% output commit 30%
      server pptp
      server GRE
      server openvpn
    class servers
      server netdata
      server http
    # a class group to favor tcp handshake over transfers
    class group surfing prio keep commit 5%
      client surfing
      client rsync
      class synacks
        match tcp syn
        match tcp ack
    class group end
    class synacks commit 5%
      match tcp syn
      match tcp ack
    class default
    class background commit 4%
      client torrents
      server mytorrent
      server mytorrenttransfers
```

## SEE ALSO
•

fireqos(1) - FireQOS program

•

fireqos-interface(5) - QOS interface definition

•

fireqos-class(5) - QOS class 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/)

•

tc(8) (http://lartc.org/manpages/tc.html) - show / manipulate traffic control settings

## 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: QOS traffic match

text:
# fireqos-match(5)

## NAME
fireqos-match - QOS traffic match

## SYNOPSIS
{match|match4|match6|match46} optional-match-params

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

Writing match4 includes only IPv4 traffic in the match.

Writing match6 includes only IPv6 traffic in the match.

Writing match46 includes both IPv4 and IPv6 traffic in the match.

You can add as many match statements as you like to a FireQOS configuration. They assign traffic to a class: by default to the class after which they are declared.

The sequence that matches appear in the configuration defines their priority, with the first match being given a prio of 10, with 10 added for each subsequent match (10, 20, 30, ...).

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

If one match statement generates multiple tc(8) filter statements, all filters generated by the same match statement will have the same prio.

Note

match rules are attached to the parent of the class they appear in. Within the configuration they are written under a class, but in reality they are attached to their class parent, so that they classify the parent's traffic that they match, into the class.

It is also possible to group all match statements together below the classes. This allows them to be arranged in preferred order, without the need for any explicit prio parameters. In this case however, each match statement must specify to which class it classifies the packets it matches, using the class parameter. See fireqos-params-match(5) and the examples below.

You can also write client and server statements, much like FireHOL allows, with the same service definitions. For FireQOS however, the client ports are ignored. server statements match the server ports on this linux side, while client statements match the server ports on the remote side.

Example:

```
    server_myrtp_ports="10000:10100"
    interface eth0 lan bidirectional rate 1Gbit
      class voip
        server sip
        client sip

        server myrtp
      class dns
        server dns
      class mail
        server smtp
```

## PARAMETERS
optional-match-params

The set of optional parameters which describe this match. See fireqos-params-match(5).

## EXAMPLES
Match traffic within classes:

```
    interface eth0 lan output rate 1Gbit
      class voip
        match udp ports 5060,10000:10100
      class dns
        match udp port 53
      class mail
        match tcp port 25
```

Matches split out and explicitly assigning traffic to classes (N.B. without the class parameters, all traffic would be classified into 'mail'):

```
    interface eth0 lan output rate 1Gbit
      class voip
      class dns
      class mail
      match udp ports 5060,10000:10100 class voip
      match tcp port 25 class mail
      match tcp port 80 class web
```

## SEE ALSO
•

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

•

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/)

•

tc(8) (http://lartc.org/manpages/tc.html) - show / manipulate traffic control settings

## 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 match parameters

text:
# fireqos-params-match(5)

## NAME
fireqos-params-match - optional match parameters

## SYNOPSIS
at { root | name }

class name

syn|syns

ack|acks

{ proto|protocol protocol [,protocol...] } |tcp|udp|icmp|gre|ipv6

{ tos | priority } tosid [,tosid...]

{ DSCP } classname [,classname...]

mark mark [,mark...]

connmark mark [,mark...]

rawmark mark [,mark...]

custommark name mark [,mark...]

{ port | ports } port[:range] [ ,port[:range]... ]

{ sport | sports } port[:range] [ ,port[:range]... ]

{ dport | dports } port[:range] [ ,port[:range]... ]

{ ip | net | host } net [,net...]

src net [,net...]

dst net [,net...]

{ srcmac | smac } mac

{ dstmac | dmac } mac

prio id

input

output

custom 'custom tc parameters'

estimator interval decay

police police

insidegre

## DESCRIPTION
These options apply to match statements.

### input, output
On bidirectional interfaces, input and output will check the current direction of the interface. If the match is input but the interface is output the match will be reversed. The same will happen if output is given at the match and the interface is input.

The parameters that are reversed are:

•

src and dst

•

sport and dport

•

srcmac and dstmac

This allows a definition like this:

```
  interface dsl0 world bidirectional ...
    class surfing ...
      match input sport 0:1023
```

The above will match sport 0:1023 at the input interface, and will automatically reverse it to match dport 0:1023 at the output interface.

### at
By default a match is attached to the parent of its parent class. For example, if its parent is a class directly under the interface, then the match is attached to the interface and is compared against all traffic of the interface. For nested classes, a match of a leaf, is attached to the parent class and is compared against all traffic of this parent class.

With the at parameter, a match can be attached any class. The name parameter should be a class name. The name root attaches the match to the interface.

### class
Defines the name of the class that will get the packets matched by this match.

By default it is the name of the class the match statement appears under.

Note

There is also a class definition for traffic, see fireqos-class(5).

### syn, syns
Match TCP SYN packets. Note that the tcp parameter must be specified.

If the same match statement includes more protocols than TCP, then this match will work for the TCP packets (it will be silently ignored for all other protocols).

For example, syn is ignored when generating the UDP filter in the below:

```
match tcp syn
match proto tcp,udp syn
```

### ack, acks
Same as syn, but matching small TCP packets with the ACK bit set.

### proto, protocol, tcp, udp, icmp, gre, ipv6
Match the protocol in the IP header.

### tos, priority
Match to TOS field of ipv4 or the priority field of ipv6. The tosid can be a value/mask in any format tc(8) accepts, or one of the following:

•

min-delay, minimize-delay, minimum-delay, low-delay, interactive

•

maximize-throughput, maximum-throughput, max-throughput, high-throughput, bulk

•

maximize-reliability, maximum-reliability, max-reliability, reliable

•

min-cost, minimize-cost, minimum-cost, low-cost, cheap, normal-service, normal

Note

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

### dscp
Match to DSCP value in IP TOS header field. The classname has to be one of the following values:

•

CS1, CS2, CS3, CS4, CS5, CS6, CS7

•

AF11, AF12, AF13

•

AF21, AF22, AF23

•

AF31, AF32, AF33

•

AF41, AF42, AF43

•

EF

Note

tc-filter only supports ToS parameters. That is why a lookaside table is configured within fireqos code to translate the DSCP value to their matching TOS value. See RFC2474 for more information.

### mark, connmark, custommark, rawmark
Match an iptables(8) MARK. This works the same way it works for FireHOL. FireHOL and FireQOS share the same marks and their masks.

Matching iptables(8) MARKs do not work on input interfaces. You can use them only on output. The IFB devices that are used for shaping inbound traffic do not have any iptables hooks to allow matching MARKs. If you try it, FireQOS will attempt to do it, but currently you will get an error from the tc(8) command executed or they will be silently ignored by it.

On some Linux distributions (e.g. OpenWRT) there is a module called act_commark that will enable this feature. Set this within your fireqos.conf to enable it:

```
FIREQOS_CONNMARK_RESTORE="act_connmark"
```

Also note that matching marks requires a suitably configured kernel (with CONFIG_CLS_U32_MARK=y). There is no error if the kernel is not configured correctly; it just silently drops the rules. For details see this error report (https://github.com/firehol/firehol/issues/231).

### ports, sports, dports
Match ports of the IP header. ports will create rules for matching source and destination ports (separate rules for each). dports matches destination ports, sports matches source ports.

### ip, net, host, src, dst
Match IPs of the IP header. ip, net and host will create rules for matching source and destination IPs (separate rules for each). src matches source IPs and dst destination IPs.

Note

If the class these matches appear in are IPv4, then only IPv4 IPs can be used. To override use match6 ... src/dst *IPV6_IP*

Similarly, if the class is IPv6, then only IPv6 IPs can be used. To override use match4 ... src/dst *IPV4_IP*.

You can mix IPv4 and IPv6 in any way you like. FireQOS supports inheritance, to figure out for each statement which is the default. For example:

```
interface46 eth0 lan output rate 1Gbit # ipv4 and ipv6 enabled
  class voip # ipv4 and ipv6 class, as interface is both
    match udp port 53 # ipv4 and ipv6 rule, as class is both
    match4 src 192.0.2.1 # ipv4 only rule
    match6 src 2001:db8::1 # ipv6 only rule
  class4 realtime # ipv4 only class
    match src 198.51.100.1 # ipv4 only rule, as class is ipv4-only
  class6 servers # ipv6 only class
        match src 2001:db8::2 # ipv6 only rule, as class is ipv6-only
```

To convert an IPv4 interface to IPv6, just replace interface with interface6. All the rules in that interface, will automatically inherit the new protocol. Of course, if you use IP addresses for matching packets, make sure they are IPv6 IPs too.

### prio (match)
Note

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

All match statements are attached to the interface. They forward traffic to their class, but they are actually executed for all packets that are leaving the interface (note: input matches are actually output matches on an IFB device).

By default, the priority they are executed, is the priority they appear in the configuration file, i.e. the first match of the first class is executed first, then the rest matches of the first class in the sequence they appear, then the matches of the second class, etc.

It is sometimes necessary to control the order of matches. For example, when you want host 192.0.2.1 to be assigned the first class, except port tcp/1234 which should be assigned the second class. The following will not work:

```
interface eth0 lan output rate 1Gbit
  class high
    match host 192.0.2.1
  class low
    match host 192.0.2.1 port 1234 # Will never match
```

In this case, the first match is assigned priority 10 and the second priority 20. The second match will never match anything, since all traffic for the host is already matched by the first one.

Setting an explicit priority allows you to change the order in which the matches are executed. FireQOS gives priority 10 to the first match of every interface, 20 to the second match, 30 to the third match, etc. So the default is 10 x the sequence number. You can set prio to overwrite this number.

To force executing the second match before the first, just set a lower priority for it. For example, this will cause the desired behaviour:

```
interface eth0 lan output rate 1Gbit
  class high
    match host 192.0.2.1
  class low
    match host 192.0.2.1 port 1234 prio 1 # Matches before host-only
```

### insidegre
By specifying keyword insidegre a GRE (Generic Routing Encapsulation) packet can be matched on the encapsulated IP packet header information.

insidegre is available for the following matches:

•

src

•

dst

•

protocol

•

port

•

tos

•

dscp

```
  interface eth0 world ...
    class surfing commit 128kbit ceil 1024kbit prio 7
      match src 10.1.128.230 dst 8.8.8.8 insidegre
      match protocol ospf insidegre
      match port 25 insidegre
      match tos 3 insidegre
      match dscp ef insidegre
```

## SEE ALSO
•

fireqos(1) - FireQOS program

•

fireqos.conf(5) - FireQOS configuration file

•

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.


vnetbuild-conf

title: vnetbuild-conf(5)

summary: VNetBuild configuration file

text:
# vnetbuild-conf(5)

## NAME
vnetbuild.conf - VNetBuild configuration file

## SYNOPSIS

```
host *ID*
    dev *DEVICE* [ *ID*/*PAIRDEV* ] [ *IP*/*MASK*... ]
    ...
    bridgedev *BRIDGE* [ *DEVICE*... ] [ *IP*/*MASK*... ]
    ...
    route *ROUTECMD*
    ...
    pre_up *DEVICE* *CUSTOMCMD*
    ...
    exec *CUSTOMCMD*
    ...
...
switch *ID*
    dev *DEVICE* [ *ID*/*PAIRDEV* ]
    ...
    pre_up *DEVICE* *CUSTOMCMD*
    ...
    exec *CUSTOMCMD*
    ...
...

```

## DESCRIPTION
There is no default configuration file for vnetbuild(1); one must always be specified on the command line.

The configuration file defines a set of namespaces that will be operated on.

VNetBuild defines two types of namespace, a host and a switch. Any number of each may be specified, with any number of configuration statements in each.

Note

The Linux kernel does not see any difference between a host and a switch namespace. VNetBuild provides the distinction to make it easy build full virtual networks.

## NAMESPACE DEFINITIONS
Namespace definitions come in two types, host and switch. Simply provide a simple unique alphanumeric ID. Any subsequent statements apply to this namespace until the next host or switch statement.

A host definition is designed to work like a physical machine. It allows you to specify any number of dev entries for network interfaces, with their IP addresses. You can also define any number of Linux bridges with bridgedev to add your defined interfaces to.

A host also allows any number of custom exec commands for extensibility and provides a route statement to deal with the common case of wanting to add network routes to the host.

A switch definition is designed to work like a physical network switch. It allows you to add any number of dev entries (and also custom exec commands for extensibility) but nothing else.

In addition, dev entries in a switch may only specify device names, they cannot have an IP address associated. A switch has a bridge automatically created in it and all dev entries are automatically added to it.

## CONFIGURATION STATEMENTS
dev DEVICE ...

Define a virtual ethernet device, DEVICE in a host or switch.

Devices must exist in pairs. A dev must first be defined unpaired in a namespace, then some subsequent dev must define the pair:

```
host a
  dev veth0
host b
  dev vppp0 a/veth0
```

Any DEVICE name which is acceptable to the Linux kernel may be used. We recommend sticking to e.g. veth0, vppp0 etc. to make it clear that they are virtual and also how you are thinking of the device in terms of your setup. Devices will be created as type veth, irrespective of what you call them.

Hosts may optionally specify one or more IP/MASK values which will be applied (along with the calculated broadcast address) automatically, e.g.:

```
host a
  dev veth0 10.0.0.1/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)


firejail-profile

title: firejail-profile(5)

text:
# firejail-profile(5)

## NAME
profile - Security profile file syntax, and information about building new application profiles.

## SYNOPSIS
Using a specific profile:

firejail --profile=filename.profile

Example:

$ firejail --appimage --profile=/etc/firejail/kdenlive.profile kdenlive.appimage

firejail --profile=profile_name

Example:

$ firejail --appimage --profile=kdenlive kdenlive.appimage

Building a profile manually:

Start with the template in /usr/share/doc/firejail/profile.template and modify it in a text editor. To integrate the program in your desktop environment copy the profile file in ~/.config/firejail directory and run "sudo firecfg".

Aliases and redirections:

In some cases the same profile can be used for several applications. One such example is LibreOffice. Build a regular profile for the main application, and for the rest use /usr/share/doc/firejail/redirect_alias-profile.template.

Running the profile builder:

firejail --build=appname.profile appname

Example:

$ firejail --build=blobby.profile blobby

Run the program in "firejail --build" and try to exercise as many program features as possible. The profile is extracted and saved in the current directory. Open it in a text editor and add or remove sandboxing options as necessary. Test again after modifying the profile. To integrate the program in your desktop environment copy the profile file in ~/.config/firejail directory and run "sudo firecfg".

## DESCRIPTION
Several command line options can be passed to the program using profile files. Firejail chooses the profile file as follows:

1. If a profile file is provided by the user with --profile option, the profile file is loaded. If a profile name is given, it is searched for first in the ~/.config/firejail directory and if not found then in /etc/firejail directory. Profile names do not include the .profile suffix. Example:

$ firejail --profile=/home/netblue/icecat.profile icecat

Reading profile /home/netblue/icecat.profile

[...]

$ firejail --profile=icecat icecat-wrapper.sh

Reading profile /etc/firejail/icecat.profile

[...]

2. If a profile file with the same name as the application is present in ~/.config/firejail directory or in /etc/firejail, the profile is loaded. ~/.config/firejail takes precedence over /etc/firejail. Example:

$ firejail icecat

Command name #icecat#

Found icecat profile in /home/netblue/.config/firejail directory

Reading profile /home/netblue/.config/firejail/icecat.profile

[...]

3. Use a default.profile file if the sandbox is started by a regular user, or a server.profile file if the sandbox is started by root. Firejail looks for these files in ~/.config/firejail directory, followed by /etc/firejail directory. To disable default profile loading, use --noprofile command option. Example:

$ firejail

Reading profile /etc/firejail/default.profile

Parent pid 8553, child pid 8554

Child process initialized

[...] $ firejail --noprofile

Parent pid 8553, child pid 8554

Child process initialized

[...]

## Templates
In /usr/share/doc/firejail there are two templates to write new profiles.

profile.template - for regular profiles

redirect_alias-profile.template - for aliasing/redirecting profiles

## Scripting
Scripting commands:

File and directory names

File and directory names containing spaces are supported. The space character ' ' should not be escaped. Example: "blacklist ~/My Virtual Machines"

\# this is a comment

Example: # disable networking

net none # this command creates an empty network namespace

?CONDITIONAL: profile line

Conditionally add profile line. Example: "?HAS_APPIMAGE: whitelist ${HOME}/special/appimage/dir"

This example will load the whitelist profile line only if the --appimage option has been specified on the command line.

Currently the only conditionals supported this way are HAS_APPIMAGE, HAS_NET, HAS_NODBUS, HAS_NOSOUND, HAS_PRIVATE and HAS_X11. The conditionals ALLOW_TRAY, BROWSER_DISABLE_U2F and BROWSER_ALLOW_DRM can be enabled or disabled globally in Firejail's configuration file.

The profile line may be any profile line that you would normally use in a profile except for "quiet" and "include" lines.

Note: When using one or more conditionals and --profile, it is recommended that the relevant option(s) (such as --appimage) be specified before --profile, so that their respective conditional(s) (such as ?HAS_APPIMAGE) inside of the profile evaluate to true.

include other.profile

Include other.profile file. Example: "include /etc/firejail/disable-common.inc"

The file name can be prefixed with a macro such as ${HOME} or ${CFG}. ${HOME} is expanded as user home directory, and ${CFG} is expanded as Firejail system configuration directory - in most cases /etc/firejail or /usr/local/etc/firejail.

Example: "include ${HOME}/myprofiles/profile1" will load "~/myprofiles/profile1" file.

Example: "include ${CFG}/firefox.profile" will load "/etc/firejail/firefox.profile" file.

The file name may also be just the name without the leading directory components. In this case, first the user config directory (${HOME}/.config/firejail) is searched for the file name and if not found then the system configuration directory is search for the file name. Note: Unlike the --profile option which takes a profile name without the '.profile' suffix, include must be given the full file name.

Example: "include firefox.profile" will load "${HOME}/.config/firejail/firefox.profile" file and if it does not exist "${CFG}/firefox.profile" will be loaded.

System configuration files in ${CFG} are overwritten during software installation. Persistent configuration at system level is handled in ".local" files. For every profile file in ${CFG} directory, the user can create a corresponding .local file storing modifications to the persistent configuration. Persistent .local files are included at the start of regular profile files.

noblacklist file_name

If the file name matches file_name, the file will not be blacklisted in any blacklist commands that follow. Example: "noblacklist ${HOME}/.mozilla"

nowhitelist file_name

If the file name matches file_name, the file will not be whitelisted in any whitelist commands that follow. Example: "nowhitelist ~/.config"

ignore

Ignore command. Example: "ignore seccomp"

Example: "ignore net eth0"

quiet

Disable Firejail's output. This should be the first uncommented command in the profile file. Example: "quiet"

## Filesystem
These profile entries define a chroot filesystem built on top of the existing host filesystem. Each line describes a file/directory that is inaccessible (blacklist), a read-only file or directory (read-only), a tmpfs mounted on top of an existing directory (tmpfs), or mount-bind a directory or file on top of another directory or file (bind). Use private to set private mode. File globbing is supported, and PATH and HOME directories are searched, see the firejail FILE GLOBBING section for more details. Examples:

blacklist file_or_directory

Blacklist directory or file. Examples: blacklist /usr/bin

blacklist /usr/bin/gcc*

blacklist ${PATH}/ifconfig

blacklist ${HOME}/.ssh

blacklist-nolog file_or_directory

When --tracelog flag is set, blacklisting generates syslog messages if the sandbox tries to access the file or directory. blacklist-nolog command disables syslog messages for this particular file or directory. Examples: blacklist-nolog /usr/bin

blacklist-nolog /usr/bin/gcc*

bind directory1,directory2

Mount-bind directory1 on top of directory2. This option is only available when running as root.

bind file1,file2

Mount-bind file1 on top of file2. This option is only available when running as root.

disable-mnt

Disable /mnt, /media, /run/mount and /run/media access.

keep-config-pulse

Disable automatic ~/.config/pulse init, for complex setups such as remote pulse servers or non-standard socket paths.

keep-dev-shm

/dev/shm directory is untouched (even with private-dev).

keep-var-tmp

/var/tmp directory is untouched.

mkdir directory

Create a directory in user home, under /tmp, or under /run/user/<UID> before the sandbox is started. The directory is created if it doesn't already exist. Use this command for whitelisted directories you need to preserve when the sandbox is closed. Without it, the application will create the directory, and the directory will be deleted when the sandbox is closed. Subdirectories are recursively created. Example from firefox profile:

mkdir ~/.mozilla

whitelist ~/.mozilla

mkdir ~/.cache/mozilla/firefox

whitelist ~/.cache/mozilla/firefox

For files in /run/user/<PID> use ${RUNUSER} macro:

mkdir ${RUNUSER}/firejail-testing

mkfile file

Similar to mkdir, this command creates an empty file in user home, or /tmp, or under /run/user/<UID> before the sandbox is started. The file is created if it doesn't already exist.

noexec file_or_directory

Remount the file or the directory noexec, nodev and nosuid.

private

Mount new /root and /home/user directories in temporary filesystems. All modifications are discarded when the sandbox is closed.

private directory

Use directory as user home. --private and --private=directory cannot be used together. Bug: Even with this enabled, some commands (such as mkdir, mkfile and private-cache) will still operate on the original home directory. Workaround: Disable the incompatible commands, such as by using "ignore mkdir" and "ignore mkfile". For details, see #903

private-bin file,file

Build a new /bin in a temporary filesystem, and copy the programs in the list. The files in the list must be expressed as relative to the /bin, /sbin, /usr/bin, /usr/sbin, or /usr/local/bin directories. The same directory is also bind-mounted over /sbin, /usr/bin and /usr/sbin. Multiple private-bin commands are allowed and they accumulate.

private-cache

Mount an empty temporary filesystem on top of the .cache directory in user home. All modifications are discarded when the sandbox is closed.

private-cwd

Set working directory inside jail to the home directory, and failing that, the root directory.

private-cwd directory

Set working directory inside the jail. Full directory path is required. Symbolic links are not allowed.

private-dev

Create a new /dev directory. Only disc, dri, dvb, hidraw, null, full, zero, tty, pts, ptmx, random, snd, urandom, video, log, shm and usb devices are available. Use the options no3d, nodvd, nosound, notv, nou2f and novideo for additional restrictions.

private-etc file,directory

Build a new /etc in a temporary filesystem, and copy the files and directories in the list. The files and directories in the list must be expressed as relative to the /etc directory, and must not contain the / character (e.g., /etc/foo must be expressed as foo, but /etc/foo/bar -- expressed as foo/bar -- is disallowed). All modifications are discarded when the sandbox is closed. Multiple private-etc commands are allowed and they accumulate.

private-home file,directory

Build a new user home in a temporary filesystem, and copy the files and directories in the list in the new home. The files and directories in the list must be expressed as relative to the current user's home directory. All modifications are discarded when the sandbox is closed.

private-lib file,directory

Build a new /lib directory and bring in the libraries required by the application to run. The files and directories in the list must be expressed as relative to the /lib directory. This feature is still under development, see man 1 firejail for some examples.

private-opt file,directory

Build a new /opt in a temporary filesystem, and copy the files and directories in the list. The files and directories in the list must be expressed as relative to the /opt directory, and must not contain the / character (e.g., /opt/foo must be expressed as foo, but /opt/foo/bar -- expressed as foo/bar -- is disallowed). All modifications are discarded when the sandbox is closed.

private-srv file,directory

Build a new /srv in a temporary filesystem, and copy the files and directories in the list. The files and directories in the list must be expressed as relative to the /srv directory, and must not contain the / character (e.g., /srv/foo must be expressed as foo, but /srv/foo/bar -- expressed as foo/bar -- is disallowed). All modifications are discarded when the sandbox is closed.

private-tmp

Mount an empty temporary filesystem on top of /tmp directory whitelisting /tmp/.X11-unix.

read-only file_or_directory

Make directory or file read-only.

read-write file_or_directory

Make directory or file read-write.

tmpfs directory

Mount an empty tmpfs filesystem on top of directory. Directories outside user home or not owned by the user are not allowed. Sandboxes running as root are exempt from these restrictions.

tracelog

Blacklist violations logged to syslog.

whitelist file_or_directory

Whitelist directory or file. A temporary file system is mounted on the top directory, and the whitelisted files are mount-binded inside. Modifications to whitelisted files are persistent, everything else is discarded when the sandbox is closed. The top directory can be all directories in / (except /proc and /sys), /sys/module, /run/user/$UID, $HOME and all directories in /usr. Symbolic link handling: with the exception of user home, both the link and the real file should be in the same top directory. For user home, both the link and the real file should be owned by the user.

whitelist-ro file_or_directory

Equivalent to "whitelist file_or_directory" followed by "read-only file_or_directory"

writable-etc

Mount /etc directory read-write.

writable-run-user

Disable the default blacklisting of run/user/$UID/systemd and /run/user/$UID/gnupg.

writable-var

Mount /var directory read-write.

writable-var-log

Use the real /var/log directory, not a clone. By default, a tmpfs is mounted on top of /var/log directory, and a skeleton filesystem is created based on the original /var/log.

## Security filters
The following security filters are currently implemented:

allow-debuggers

Allow tools such as strace and gdb inside the sandbox by whitelisting system calls ptrace and process_vm_readv.

caps

Enable default Linux capabilities filter. See capabilities(7) for details.

caps.drop capability,capability,capability

Blacklist given Linux capabilities.

caps.drop all

Blacklist all Linux capabilities.

caps.keep capability,capability,capability

Whitelist given Linux capabilities.

memory-deny-write-execute

Install a seccomp filter to block attempts to create memory mappings that are both writable and executable, to change mappings to be executable or to create executable shared memory.

nonewprivs

Sets the NO_NEW_PRIVS prctl. This ensures that child processes cannot acquire new privileges using execve(2); in particular, this means that calling a suid binary (or one with file capabilities) does not result in an increase of privilege.

noprinters

Disable printers.

protocol protocol1,protocol2,protocol3

Enable protocol filter. The filter is based on seccomp and checks the first argument to socket system call. Recognized values: unix, inet, inet6, netlink, packet, and bluetooth. Multiple protocol commands are allowed and they accumulate.

restrict-namespaces

Install a seccomp filter that blocks attempts to create new cgroup, ipc, net, mount, pid, time, user or uts namespaces.

restrict-namespaces cgroup,ipc,net,mnt,pid,time,user,uts

Install a seccomp filter that blocks attempts to create any of the specified namespaces.

seccomp

Enable seccomp filter and blacklist the syscalls in the default list. See man 1 firejail for more details.

seccomp.32

Enable seccomp filter and blacklist the syscalls in the default list for 32 bit system calls on a 64 bit architecture system.

seccomp syscall,syscall,syscall

Enable seccomp filter and blacklist the system calls in the list on top of default seccomp filter.

seccomp.32 syscall,syscall,syscall

Enable seccomp filter and blacklist the system calls in the list on top of default seccomp filter for 32 bit system calls on a 64 bit architecture system.

seccomp.block-secondary

Enable seccomp filter and filter system call architectures so that only the native architecture is allowed.

seccomp.drop syscall,syscall,syscall

Enable seccomp filter and blacklist the system calls in the list.

seccomp.32.drop syscall,syscall,syscall

Enable seccomp filter and blacklist the system calls in the list for 32 bit system calls on a 64 bit architecture system.

seccomp.keep syscall,syscall,syscall

Enable seccomp filter and whitelist the system calls in the list.

seccomp.32.keep syscall,syscall,syscall

Enable seccomp filter and whitelist the system calls in the list for 32 bit system calls on a 64 bit architecture system.

seccomp-error-action kill | log | ERRNO

Return a different error instead of EPERM to the process, kill it when an attempt is made to call a blocked system call, or allow but log the attempt.

x11

Enable X11 sandboxing.

x11 none

Blacklist /tmp/.X11-unix directory, ${HOME}/.Xauthority and file specified in ${XAUTHORITY} environment variable. Remove DISPLAY and XAUTHORITY environment variables. Stop with error message if X11 abstract socket will be accessible in jail.

x11 xephyr

Enable X11 sandboxing with Xephyr server.

x11 xorg

Enable X11 sandboxing with X11 security extension.

x11 xpra

Enable X11 sandboxing with Xpra server.

x11 xvfb

Enable X11 sandboxing with Xvfb server.

xephyr-screen WIDTHxHEIGHT

Set screen size for x11 xephyr. This command should be included in the profile file before x11 xephyr command. Example:

xephyr-screen 640x480

x11 xephyr

## DBus filtering
Access to the session and system DBus UNIX sockets can be allowed, filtered or disabled. To disable the abstract sockets (and force applications to use the filtered UNIX socket) you would need to request a new network namespace using --net command. Another option is to remove unix from the --protocol set.

Filtering requires installing the xdg-dbus-proxy utility. Filter rules can be specified for well-known DBus names, but they are also propagated to the owning unique name, too. The permissions are "sticky" and are kept even if the corresponding well-known name is released (however, applications rarely release well-known names in practice). Names may have a .* suffix to match all names underneath them, including themselves (e.g. "foo.bar.*" matches "foo.bar", "foo.bar.baz" and "foo.bar.baz.quux", but not "foobar"). For more information, see xdg-dbus-proxy(1).

Examples:

dbus-system filter

Enable filtered access to the system DBus. Filters can be specified with the dbus-system.talk and dbus-system.own commands.

dbus-system none

Disable access to the system DBus. Once access is disabled, it cannot be relaxed to filtering.

dbus-system.own org.gnome.ghex.*

Allow the application to own the name org.gnome.ghex and all names underneath in on the system DBus.

dbus-system.talk org.freedesktop.Notifications

Allow the application to talk to the name org.freedesktop.Notifications on the system DBus.

dbus-system.see org.freedesktop.Notifications

Allow the application to see but not talk to the name org.freedesktop.Notifications on the system DBus.

dbus-system.call org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications

Allow the application to call methods of the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the system DBus.

dbus-system.broadcast org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications

Allow the application to receive broadcast signals from the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the system DBus.

dbus-user filter

Enable filtered access to the session DBus. Filters can be specified with the dbus-user.talk and dbus-user.own commands.

dbus-user none

Disable access to the session DBus. Once access is disabled, it cannot be relaxed to filtering.

dbus-user.own org.gnome.ghex.*

Allow the application to own the name org.gnome.ghex and all names underneath in on the session DBus.

dbus-user.talk org.freedesktop.Notifications

Allow the application to talk to the name org.freedesktop.Notifications on the session DBus.

dbus-user.see org.freedesktop.Notifications

Allow the application to see but not talk to the name org.freedesktop.Notifications on the session DBus.

dbus-user.call org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications

Allow the application to call methods of the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the session DBus.

dbus-user.broadcast org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications

Allow the application to receive broadcast signals from the the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the session DBus.

nodbus (deprecated)

Disable D-Bus access (both system and session buses). Equivalent to dbus-system none and dbus-user none.

Individual filters can be overridden via the --ignore command. Supposing a profile has

[...]

dbus-user filter

dbus-user.own org.mozilla.firefox.*

dbus-user.talk org.freedesktop.Notifications

dbus-system none

[...]

and the user wants to disable notifications, this can be achieved by putting the below in a local override file:

[...]

ignore dbus-user.talk org.freedesktop.Notifications

[...]

## Resource limits, CPU affinity
These profile entries define the limits on system resources (rlimits) for the processes inside the sandbox. The limits can be modified inside the sandbox using the regular ulimit command. cpu command configures the CPU cores available.

Examples:

cpu 0,1,2

Use only CPU cores 0, 1 and 2.

nice -5

Set a nice value of -5 to all processes running inside the sandbox.

rlimit-as 123456789012

Set the maximum size of the process's virtual memory to 123456789012 bytes.

rlimit-cpu 123

Set the maximum CPU time in seconds.

rlimit-fsize 1024

Set the maximum file size that can be created by a process to 1024 bytes.

rlimit-nproc 1000

Set the maximum number of processes that can be created for the real user ID of the calling process to 1000.

rlimit-nofile 500

Set the maximum number of files that can be opened by a process to 500.

rlimit-sigpending 200

Set the maximum number of processes that can be created for the real user ID of the calling process to 200.

timeout hh:mm:ss

Kill the sandbox automatically after the time has elapsed. The time is specified in hours/minutes/seconds format.

## User Environment
allusers

All user home directories are visible inside the sandbox. By default, only current user home directory is visible.

env name=value

Set environment variable. Examples: env LD_LIBRARY_PATH=/opt/test/lib

env CFLAGS="-W -Wall -Werror"

ipc-namespace

Enable IPC namespace.

keep-fd

Inherit open file descriptors to sandbox.

name sandboxname

Set sandbox name. Example: name browser

no3d

Disable 3D hardware acceleration.

noautopulse (deprecated)

See keep-config-pulse.

nodvd

Disable DVD and audio CD devices.

nogroups

Disable supplementary user groups

noinput

Disable input devices.

nosound

Disable sound system.

notv

Disable DVB (Digital Video Broadcasting) TV devices.

nou2f

Disable U2F devices.

novideo

Disable video capture devices.

machine-id

Spoof id number in /etc/machine-id file - a new random id is generated inside the sandbox.

shell none

Run the program directly, without a shell.

## Networking
Networking features available in profile files.

defaultgw address

Use this address as default gateway in the new network namespace.

dns address

Set a DNS server for the sandbox. Up to three DNS servers can be defined.

hostname name

Set a hostname for the sandbox.

hosts-file file

Use file as /etc/hosts.

ip address

Assign IP addresses to the last network interface defined by a net command. A default gateway is assigned by default. Example:

net eth0

ip 10.10.20.56

ip none

No IP address and no default gateway are configured for the last interface defined by a net command. Use this option in case you intend to start an external DHCP client in the sandbox. Example:

net eth0

ip none

ip dhcp

Acquire an IP address and default gateway for the last interface defined by a net command, as well as set the DNS servers according to the DHCP response. This command requires the ISC dhclient DHCP client to be installed and will start it automatically inside the sandbox. Example:

net br0

ip dhcp

This command should not be used in conjunction with the dns command if the DHCP server is set to configure DNS servers for the clients, because the manually specified DNS servers will be overwritten.

The DHCP client will NOT release the DHCP lease when the sandbox terminates. If your DHCP server requires leases to be explicitly released, consider running a DHCP client and releasing the lease manually in conjunction with the net none command.

ip6 address

Assign IPv6 addresses to the last network interface defined by a net command. Example:

net eth0

ip6 2001:0db8:0:f101::1/64

ip6 dhcp

Acquire an IPv6 address and default gateway for the last interface defined by a net command, as well as set the DNS servers according to the DHCP response. This command requires the ISC dhclient DHCP client to be installed and will start it automatically inside the sandbox. Example:

net br0

ip6 dhcp

This command should not be used in conjunction with the dns command if the DHCP server is set to configure DNS servers for the clients, because the manually specified DNS servers will be overwritten.

The DHCP client will NOT release the DHCP lease when the sandbox terminates. If your DHCP server requires leases to be explicitly released, consider running a DHCP client and releasing the lease manually.

iprange address,address

Assign an IP address in the provided range to the last network interface defined by a net command. A default gateway is assigned by default. Example:

net eth0

iprange 192.168.1.150,192.168.1.160

mac address

Assign MAC addresses to the last network interface defined by a net command.

mtu number

Assign a MTU value to the last network interface defined by a net command.

net bridge_interface

Enable a new network namespace and connect it to this bridge interface. Unless specified with option --ip and --defaultgw, an IP address and a default gateway will be assigned automatically to the sandbox. The IP address is verified using ARP before assignment. The address configured as default gateway is the bridge device IP address. Up to four --net bridge devices can be defined. Mixing bridge and macvlan devices is allowed.

net ethernet_interface|wireless_interface

Enable a new network namespace and connect it to this ethernet interface using the standard Linux macvlan or ipvlan driver. Unless specified with option --ip and --defaultgw, an IP address and a default gateway will be assigned automatically to the sandbox. The IP address is verified using ARP before assignment. The address configured as default gateway is the default gateway of the host. Up to four --net devices can be defined. Mixing bridge and macvlan devices is allowed.

net none

Enable a new, unconnected network namespace. The only interface available in the new namespace is a new loopback interface (lo). Use this option to deny network access to programs that don't really need network access.

net tap_interface

Enable a new network namespace and connect it to this ethernet tap interface using the standard Linux macvlan driver. If the tap interface is not configured, the sandbox will not try to configure the interface inside the sandbox. Please use ip, netmask and defaultgw to specify the configuration.

netfilter

If a new network namespace is created, enabled default network filter.

netfilter filename

If a new network namespace is created, enabled the network filter in filename.

netlock

Generate a custom network filter and enable it.

netmask address

Use this option when you want to assign an IP address in a new namespace and the parent interface specified by --net is not configured. An IP address and a default gateway address also have to be added.

netns namespace

Run the program in a named, persistent network namespace. These can be created and configured using "ip netns".

veth-name name

Use this name for the interface connected to the bridge for --net=bridge_interface commands, instead of the default one.

## Other
deterministic-exit-code

Always exit firejail with the first child's exit status. The default behavior is to use the exit status of the final child to exit, which can be nondeterministic.

deterministic-shutdown

Always shut down the sandbox after the first child has terminated. The default behavior is to keep the sandbox alive as long as it contains running processes.

join-or-start sandboxname

Join the sandbox identified by name or start a new one. Same as "firejail --join=sandboxname" command if sandbox with specified name exists, otherwise same as "name sandboxname".

## FILES
/etc/firejail/appname.profile

Global Firejail configuration consisting mainly of profiles for each application supported by default.

$HOME/.config/firejail/appname.profile

User application profiles, will take precedence over the global profiles.

/usr/share/doc/firejail/profile.template

Template for building new profiles.

/usr/share/doc/firejail/redirect_alias-profile.template

Template for aliasing/redirecting profiles.

## 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-login(5), firejail-users(5), jailcheck(1)

https://github.com/netblue30/firejail/wiki/Creating-Profiles