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 Type Default Description
advertise_interval int 30  
arp_neighbor_timeout int 250  
cookie int 1524372928  
description str None  
dp_id int None  
drop_bpdu bool True  
drop_broadcast_source_address bool True  
drop_lldp bool True  
drop_spoofed_faucet_mac bool True  
group_table bool False  
group_table_routing bool False  
hardware str Open vSwitch  
high_priority int None  
highest_priority int None  
ignore_learn_ins int 3  
interface_ranges dict {}  
interfaces dict {}  
learn_ban_timeout int 10  
learn_jitter int 10  
low_priority int None  
lowest_priority int None  
max_host_fib_retry_count int 10  
max_hosts_per_resolve_cycle int 5  
max_resolve_backoff_time int 32  
name str None  
ofchannel_log str None  
packetin_pps int 0  
pipeline_config_dir str /etc/ryu/faucet  
priority_offset int 0  
proactive_learn bool True  
stack dict None  
timeout int 300  
use_idle_timeout bool False  

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 int None  


Attribute Type Default Description
max_per_interval int None  
send_interval int None  


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 Type Default Description
acl_in str int None  
description str None  
enabled bool True  
hairpin bool False  
lacp int 0  
loop_protect bool False  
max_hosts int 255  
mirror str int None  
name str None  
native_vlan str int None  
number int None  
output_only bool False  
permanent_learn bool False  
stack dict None  
tagged_vlans list None  
unicast_flood bool True  

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
priority int None  


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 None  


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 Type Default Description
acl_in int str None  
bgp_as int None  
bgp_local_address str None  
bgp_neighbor_addresses list []  
bgp_neighbor_as int None  
bgp_neighbour_addresses list []  
bgp_neighbour_as int None  
bgp_port int 9179  
bgp_routerid str None  
bgp_server_addresses list [‘’, ‘::’]  
description str None  
faucet_mac str 0e:00:00:00:00:01  
faucet_vips list None  
max_hosts int 255  
minimum_ip_size_check bool True  
name str None  
proactive_arp_limit int None  
proactive_nd_limit int None  
routes list None  
targeted_gw_resolution bool False  
unicast_flood bool True  
vid int None  

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.

/acls/<acl name>/[list]/rule
Attribute Type Default Description
exact_match bool False  
rules list None  

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

The actions dictionary can acontain the following elements:

/acls/<acl name>/[list]/rule/actions/
Attribute Type Default Description
allow int None  
meter dict None  
mirror str int None  
output dict None  

The output action contains a dictionary with the following elements:

/acls/<acl name>/[list]/rule/actions/output/
Attribute Type Default Description
dl_dst str None  
failover dict None  
pop_vlans int None  
port str int None  
ports list None  
set_fields list None  
swap_vid int None  
vlan_vid int None  
vlan_vids list None  

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.