Faucet is configured with a YAML-based configuration file, faucet.yaml. The following is example demonstrating a few common features:

    - acls.yaml

        vid: 100
        description: "office network"
        acl_in: office-vlan-protect
        faucet_mac: "0e:00:00:00:10:01"
        faucet_vips: ['', '2001:100::1/64', 'fe80::c00:00ff:fe00:1001/64']
            - route:
                ip_dst: ''
                ip_gw: ''
        vid: 200
        description: "guest network"
        faucet_mac: "0e:00:00:00:20:01"
        faucet_vips: ['', '2001:200::1/64', 'fe80::c00:00ff:fe00:2001/64']

        vlans: [office, guest]

        dp_id: 0x1
        hardware: "Open vSwitch"
        proactive_learn: True
                name: "h1"
                description: "host1 container"
                native_vlan: office
                acl_in: access-port-protect
                name: "h2"
                description: "host2 container"
                native_vlan: office
                acl_in: access-port-protect
                name: "g1"
                description: "guest1 container"
                native_vlan: guest
                acl_in: access-port-protect
                name: "s1"
                description: "services1 container"
                native_vlan: office
                acl_in: service-port-protect
                name: "trunk"
                description: "VLAN trunk to sw2"
                tagged_vlans: [office]
                acl_in: access-port-protect
        dp_id: 0x2
        hardware: "Allied-Telesis"
                name: "pi"
                description: "Raspberry Pi"
                native_vlan: office
                acl_in: access-port-protect
                name: "laptop"
                description: "Guest Laptop"
                native_vlan: guest
                acl_in: access-port-protect
                name: "trunk"
                description: "VLAN trunk to sw1"
                tagged_vlans: [office, guest]

The datapath ID may be specified as an integer or hex string (beginning with 0x).

A port not explicitly defined in the YAML configuration file will be left down and will drop all packets.

Gauge is configured similarly with, gauge.yaml. The following is example demonstrating a few common features:

# Recommended configuration is Prometheus for all monitoring, with all_dps: True
    - '/etc/ryu/faucet/faucet.yaml'
        type: 'port_state'
        all_dps: True
        #dps: ['sw1', 'sw2']
        db: 'prometheus'
        type: 'port_stats'
        all_dps: True
        #dps: ['sw1', 'sw2']
        interval: 10
        db: 'prometheus'
        #db: 'influx'
        type: 'flow_table'
        all_dps: True
        interval: 60
        db: 'prometheus'
        #db: 'couchdb'
        type: 'prometheus'
        prometheus_addr: ''
        prometheus_port: 9303
        type: 'text'
        compress: True
        file: 'flow_table.yaml.gz'
        type: 'influx'
        influx_db: 'faucet'
        influx_host: 'influxdb'
        influx_port: 8086
        influx_user: 'faucet'
        influx_pwd: 'faucet'
        influx_timeout: 10
        type: gaugedb
        gdb_type: nosql
        nosql_db: couch
        db_username: couch
        db_password: 123
        db_ip: 'couchdb'
        db_port: 5984
        driver: 'couchdb'
            switch_view: '_design/switches/_view/switch'
            match_view: '_design/flows/_view/match'
            tag_view: '_design/tags/_view/tags'
        switches_doc: 'switches_bak'
        flows_doc: 'flows_bak'
        db_update_counter: 2

Verifying configuration

You can verify that your configuration is correct with the check_faucet_config script:

check_faucet_config /etc/ryu/faucet/faucet.yaml

Configuration examples

For complete working examples of configuration features, see the unit tests, tests/ For example, FaucetUntaggedACLTest shows how to configure an ACL to block a TCP port, FaucetTaggedIPv4RouteTest shows how to configure static IPv4 routing.

Applying configuration updates

You can update FAUCET’s configuration by sending it a HUP signal. This will cause it to apply the minimum number of flow changes to the switch(es), to implement the change.

pkill -HUP -f faucet.faucet

Configuration in separate files

Extra DP, VLAN or ACL data can also be separated into different files and included into the main configuration file, as shown below. The include field is used for configuration files which are required to be loaded, and Faucet will log an error if there was a problem while loading a file. Files listed on include-optional will simply be skipped and a warning will be logged instead.

Files are parsed in order, and both absolute and relative (to the configuration file) paths are allowed. DPs, VLANs or ACLs defined in subsequent files overwrite previously defined ones with the same name.


    - /etc/ryu/faucet/dps.yaml
    - /etc/ryu/faucet/vlans.yaml

    - acls.yaml


# Recursive include is allowed, if needed.
# Again, relative paths are relative to this configuration file.
    - override.yaml


Configuration options

Top Level

Attribute Type Default Description
acls dictionary {} Configuration specific to acls. The keys are names of each acl, and the values are config dictionaries holding the acl’s configuration (see below).
dps dictionary {} Configuration specific to datapaths. The keys are names or dp_ids of each datapath, and the values are config dictionaries holding the datapath’s configuration (see below).
routers dictionary {} Configuration specific to routers. The keys are names of each router, and the values are config dictionaries holding the router’s configuration (see below).
version integer 2 The config version. 2 is the only supported version.
vlans dictionary {} Configuration specific to vlans. The keys are names or vids of each vlan, and the values are config dictionaries holding the vlan’s configuration (see below).


DP configuration is entered in the ‘dps’ configuration block. The ‘dps’ configuration contains a dictionary of configuration blocks each containing the configuration for one datapath. The keys can either be string names given to the datapath, or the OFP datapath id.

dps/<dp name or id>/
Attribute Default Type Description
dp_id None int Name for this dp, used for stats reporting and configuration
name None str  
interfaces {} dict  
interface_ranges {} dict How much to offset default priority by
priority_offset 0 int Some priority values
lowest_priority None int  
low_priority None int  
high_priority None int  
highest_priority None int  
cookie 1524372928 int Identification cookie value to allow for multiple controllers to control the same datapath
timeout 300 int inactive MAC timeout
description None str description, strictly informational
hardware ‘Open vSwitch’ str The hardware maker (for chosing an openflow driver)
arp_neighbor_timeout 250 int ARP and neighbor timeout (seconds)
ofchannel_log None str OF channel log
stack None dict stacking config, when cross connecting multiple DPs
ignore_learn_ins 3 int Ignore every approx nth packet for learning.2 will ignore 1 out of 2 packets; 3 will ignore 1 out of 3 packets.This limits control plane activity when learning new hosts rapidly.Flooding will still be done by the dataplane even with a packetis ignored for learning purposes.
drop_broadcast_source_address True bool By default drop packets with a broadcast source address
drop_spoofed_faucet_mac True bool By default drop packets on datapath spoofing the FAUCET_MAC
drop_bpdu True bool By default drop STP BPDU frames
drop_lldp True bool By default, drop LLDP. Set to False, to enable NFV offload of LLDP.
group_table False bool Use GROUP tables for VLAN flooding
group_table_routing False bool Use GROUP tables for routing (nexthops)
max_hosts_per_resolve_cycle 5 int Max hosts to try to resolve per gateway resolution cycle.
max_host_fib_retry_count 10 int Max number of times to retry resolution of a host FIB route.
max_resolve_backoff_time 32 int Max number of seconds to back off to when resolving nexthops.
packetin_pps 0 int Ask switch to rate limit packet pps. TODO: Not supported by OVS in 2.7.0
learn_jitter 10 int Jitter learn timeouts by up to this many seconds
learn_ban_timeout 10 int When banning/limiting learning, wait this many seconds before learning can be retried
advertise_interval 30 int How often to advertise (eg. IPv6 RAs)
proactive_learn True bool whether proactive learning is enabled for IP nexthops
pipeline_config_dir get_setting(‘FAUCET_PIPELINE_DIR’) str where config files for pipeline are stored (if any).
use_idle_timeout False bool Turn on/off the use of idle timeout for src_table, default OFF.

Stacking (DP)

Stacking is configured in the dp configuration block and in the interface configuration block. At the dp level the following attributes can be configured withing the configuration block ‘stack’:

dps/<dp name or id>/stack/
Attribute Type Default Description
priority integer 0 setting any value for stack priority indicates that this datapath should be the root for the stacking topology.


Configuration for each interface is entered in the ‘interfaces’ configuration block withing the config for the datapath. Each interface configuration block is a dictionary keyed by the interface name.

Defaults for groups of interfaces can also be configured under the ‘interface-ranges’ attribute within the datapath configuration block. These provide default values for a number of interfaces which can be overwritten with the config block for an individual interface. These are keyed with a string containing a comma separated list of OFP port numbers, interface names or with OFP port number ranges (eg. 1-6).

dps/<dp name or id>/interfaces/<interface name or OFP port number>/
Attribute Default Type Description
number None int  
name None str  
description None str  
enabled True bool  
permanent_learn False bool if True, a host once learned on this port cannot be learned on another port.
unicast_flood True bool if True, do classical unicast flooding on this port (False floods ND/ARP/bcast only).
mirror None (str, int)  
native_vlan None (str, int) Set untagged VLAN on this port.
tagged_vlans None list Set tagged VLANs on this port.
acl_in None (str, int) ACL for input on this port.
stack None dict Configure a stack peer on this port.
max_hosts 255 int maximum number of hosts
hairpin False bool if True, then switch between hosts on this port (eg WiFi radio).
lacp 0 int if non 0 (LAG ID), experimental LACP support enabled on this port.
loop_protect False bool if True, do simple loop protection on this port.
output_only False bool if True, all packets input from this port are dropped.

Stacking (Interfaces)

Stacking port configuration indicates how datapaths are connected when using stacking. The configuration is found under the ‘stack’ attribute of an interface configuration block. The following attributes can be configured:

dps/<dp name or id>/interfaces/<interface name or port number/stack/
Attribute Type Default Description
dp integer or string None the name of dp_id of the dp connected to this port
port integer or string None the name or OFP port number of the interface on the remote dp connected to this interface.


Routers config is used to allow routing between vlans. Routers configuration is entered in the ‘routers’ configuration block at the top level of the faucet configuration file. Configuration for each router is an entry in the routers dictionary and is keyed by a name for the router. The following attributes can be configured:

routers/<router name>/:
Attribute Type Default Description
vlans list of integers or strings None Enables inter-vlan routing on the given vlans


VLANs are configured in the ‘vlans’ configuration block at the top level of the faucet config file. The config for each vlan is an entry keyed by its vid or a name. The following attributes can be configured:

vlans/<vlan name or vid>/:
Attribute Default Type Description
name None str  
description None str  
acl_in None (int, str)  
faucet_vips None list  
faucet_mac FAUCET_MAC str set MAC for FAUCET VIPs on this VLAN
unicast_flood True bool  
bgp_as None int  
bgp_local_address None str  
bgp_port 9179 int  
bgp_server_addresses [‘’, ‘::’] list  
bgp_routerid None str  
bgp_neighbour_addresses [] list  
bgp_neighbor_addresses [] list  
bgp_neighbour_as None int  
bgp_neighbor_as None int  
routes None list  
max_hosts 255 int Limit number of hosts that can be learned on a VLAN.
vid None int  
proactive_arp_limit None int Don’t proactively ARP for hosts if over this limit (None unlimited)
proactive_nd_limit None int Don’t proactively ND for hosts if over this limit (None unlimited)
targeted_gw_resolution False bool If True, and a gateway has been resolved, target the first re-resolution attempt to the same port rather than flooding.
minimum_ip_size_check True bool If False, don’t check that IP packets have a payload (must be False for OVS trace/tutorial to work)

Static Routes

Static routes are given as a list. Each entry in the list contains a dictionary keyed with the keyword ‘route’ and contains a dictionary configuration block as follows:

vlans/<vlan name or vid>/routes/[list]/route/:
Attribute Type Default Description
ip_dst string (IP subnet) None The destination subnet.
ip_gw string (IP address) None The next hop for this route


ACLs are configured under the ‘acls’ configuration block. The acls block contains a dictionary of individual acls each keyed by its name.

Each acl contains a list of rules, a packet will have the first matching rule applied to it.

Each rule is a dictionary containing the single key ‘rule’ with the value the matches and actions for the rule.

The matches are key/values based on the ryu RESTFul API.

/acls/<acl name>/[list]/rule/actions
Attribute Type Default Description
allow boolean False If True allow the packet to continue through the Faucet pipeline, if False drop the packet.
cookie int, 0-2**16 defaults to datapath cookie value If set, cookie on this flow will be set to this value.
meter string None meter to apply to the packet
output dict None used to output a packet directly. Details below.

The output action contains a dictionary with the following elements:

/acls/<acl name>/[list]/rule/actions/output/
set_fields list of dicts None A list of fields to set with values, eg. eth_dst: “1:2:3:4:5:6”
port integer or string None The port to output the packet to.
swap_vid integer None Rewrite the vlan vid of the packet when outputting
failover dict None Output with a failover port (see below).

Failover is an experimental option, but can be configured as follows:

/acls/<acl name>/[list]/rule/actions/output/failover/
Attribute Type Default Description
group_id integer None The OFP group id to use for the failover group
ports list None The list of ports the packet can be output through.