faucet package

Submodules

faucet.acl module

Configuration for ACLs.

class faucet.acl.ACL(_id, dp_id, conf)

Bases: faucet.conf.Conf

Contains the state for an ACL, including the configuration.

ACL Config

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. The key ‘actions’ contains a dictionary with keys/values as follows:

• allow (int): if 1 allow the packet to continue through the Faucet pipeline, if 0 drop the packet.
• force_port_vlan (int): if 1, do not verify the VLAN/port association for this packet and override any VLAN ACL on the forced VLAN.
• meter (str): meter to apply to the packet
• output (dict): used to output a packet directly. details below.
• cookie (int): set flow cookie to this value on this flow

The output action contains a dictionary with the following elements:

• port (int or string): the port to output the packet to
• ports (list): a list of the ports (int or string) to output the packet to
• set_fields (list): a list of fields to set with values
• dl_dst (str): old style request to set eth_dst to a value (set_fields recommended)
• pop_vlans: (int): pop the packet vlan before outputting
• vlan_vid: (int): push the vlan vid on the packet when outputting
• vlan_vids: (list): push the list of vlans on the packet when outputting, with option eth_type
• swap_vid (int): rewrite the vlan vid of the packet when outputting
• failover (dict): Output with a failover port (experimental)

actions_types = {'allow': <class 'int'>, 'force_port_vlan': <class 'int'>, 'meter': <class 'str'>, 'mirror': (<class 'str'>, <class 'int'>), 'output': <class 'dict'>}

build(meters, vid, port_num)

Check that ACL can be built from config.

check_config()

Check config at instantiation time for errors, typically via assert.

defaults = {'exact_match': False, 'rules': None}

defaults_types = {'exact_match': <class 'bool'>, 'rules': <class 'list'>}

get_meters()

get_mirror_destinations()

output_actions_types = {'dl_dst': <class 'str'>, 'failover': <class 'dict'>, 'pop_vlans': <class 'int'>, 'port': (<class 'str'>, <class 'int'>), 'ports': <class 'list'>, 'set_fields': <class 'list'>, 'swap_vid': <class 'int'>, 'vlan_vid': <class 'int'>, 'vlan_vids': <class 'list'>}

resolve_ports(resolve_port_cb)

rule_types = {'actions': <class 'dict'>, 'arp_op': (<class 'str'>, <class 'int'>), 'arp_sha': (<class 'str'>, <class 'int'>), 'arp_spa': (<class 'str'>, <class 'int'>), 'arp_tha': (<class 'str'>, <class 'int'>), 'arp_tpa': (<class 'str'>, <class 'int'>), 'cookie': <class 'int'>, 'description': <class 'str'>, 'dl_dst': (<class 'str'>, <class 'int'>), 'dl_src': (<class 'str'>, <class 'int'>), 'dl_type': (<class 'str'>, <class 'int'>), 'dl_vlan': (<class 'str'>, <class 'int'>), 'eth_dst': (<class 'str'>, <class 'int'>), 'eth_src': (<class 'str'>, <class 'int'>), 'eth_type': (<class 'str'>, <class 'int'>), 'icmpv4_code': (<class 'str'>, <class 'int'>), 'icmpv4_type': (<class 'str'>, <class 'int'>), 'icmpv6_code': (<class 'str'>, <class 'int'>), 'icmpv6_type': (<class 'str'>, <class 'int'>), 'in_phy_port': (<class 'str'>, <class 'int'>), 'in_port': (<class 'str'>, <class 'int'>), 'ip_dscp': (<class 'str'>, <class 'int'>), 'ip_ecn': (<class 'str'>, <class 'int'>), 'ip_proto': (<class 'str'>, <class 'int'>), 'ipv4_dst': (<class 'str'>, <class 'int'>), 'ipv4_src': (<class 'str'>, <class 'int'>), 'ipv6_dst': (<class 'str'>, <class 'int'>), 'ipv6_exthdr': (<class 'str'>, <class 'int'>), 'ipv6_flabel': (<class 'str'>, <class 'int'>), 'ipv6_nd_sll': (<class 'str'>, <class 'int'>), 'ipv6_nd_target': (<class 'str'>, <class 'int'>), 'ipv6_nd_tll': (<class 'str'>, <class 'int'>), 'ipv6_src': (<class 'str'>, <class 'int'>), 'metadata': (<class 'str'>, <class 'int'>), 'mpls_bos': (<class 'str'>, <class 'int'>), 'mpls_label': (<class 'str'>, <class 'int'>), 'mpls_tc': (<class 'str'>, <class 'int'>), 'nw_dst': (<class 'str'>, <class 'int'>), 'nw_proto': (<class 'str'>, <class 'int'>), 'nw_src': (<class 'str'>, <class 'int'>), 'pbb_isid': (<class 'str'>, <class 'int'>), 'sctp_dst': (<class 'str'>, <class 'int'>), 'sctp_src': (<class 'str'>, <class 'int'>), 'tcp_dst': (<class 'str'>, <class 'int'>), 'tcp_src': (<class 'str'>, <class 'int'>), 'tunnel_id': (<class 'str'>, <class 'int'>), 'udp_dst': (<class 'str'>, <class 'int'>), 'udp_src': (<class 'str'>, <class 'int'>), 'vlan_pcp': (<class 'str'>, <class 'int'>), 'vlan_vid': (<class 'str'>, <class 'int'>)}

faucet.check_faucet_config module

Standalone script to check FAUCET configuration, return 0 if provided config OK.

faucet.check_faucet_config.check_config(conf_files, debug_level, check_output_file)

Return True and successful config dict, if all config can be parsed.

faucet.check_faucet_config.main()

Mainline.

faucet.conf module

Base configuration implementation.

class faucet.conf.Conf(_id, dp_id, conf=None)

Bases: object

Base class for FAUCET configuration.

check_config()

Check config at instantiation time for errors, typically via assert.

conf_hash(dyn=False, subconf=True, ignore_keys=None)

Return hash of keys configurably filtering attributes.

defaults = None

defaults_types = None

dyn_finalized = False

dyn_hash = None

finalize()

Configuration parsing marked complete.

ignore_subconf(other, ignore_keys=None)

Return True if this config same as other, ignoring sub config.

merge_dyn(other_conf)

Merge dynamic state from other conf object.

mutable_attrs = frozenset()

set_defaults()

Set default values and run any basic sanity checks.

to_conf()

Return configuration as a dict.

update(conf)

Parse supplied YAML config and sanity check.

exception faucet.conf.InvalidConfigError

Bases: Exception

This error is thrown when the config file is not valid.

faucet.conf.test_config_condition(cond, msg)

Evaluate condition and raise InvalidConfigError if condition not True.

faucet.config_parser module

Implement configuration file parsing.

faucet.config_parser.dp_parser(config_file, logname)

Parse a config file into DP configuration objects with hashes of config include/files.

faucet.config_parser.get_config_for_api(valves)

Return config as dict for all DPs.

faucet.config_parser.watcher_parser(config_file, logname, prom_client)

Return Watcher instances from config.

faucet.config_parser_util module

Utility functions supporting FAUCET/Gauge config parsing.

class faucet.config_parser_util.UniqueKeyLoader(stream)

Bases: yaml.loader.Loader

construct_mapping(node, deep=False)

Check for duplicate YAML keys.

faucet.config_parser_util.config_changed(top_config_file, new_top_config_file, config_hashes)

Return True if configuration has changed.

Parameters:

• top_config_file (str) – name of FAUCET config file
• new_top_config_file (str) – name, possibly new, of FAUCET config file.
• config_hashes (dict) – map of config file/includes and hashes of contents.

Returns:

True if the file, or any file it includes, has changed.

Return type:

bool

faucet.config_parser_util.config_file_hash(config_file_name)

Return hash of YAML config file contents.

faucet.config_parser_util.dp_config_path(config_file, parent_file=None)

Return full path to config file.

faucet.config_parser_util.dp_include(config_hashes, config_file, logname, top_confs)

Handles including additional config files

faucet.config_parser_util.get_logger(logname)

Return logger instance for config parsing.

faucet.config_parser_util.read_config(config_file, logname)

Return a parsed YAML config file or None.

faucet.dp module

Configuration for a datapath.

class faucet.dp.DP(_id, dp_id, conf)

Bases: faucet.conf.Conf

Stores state related to a datapath controlled by Faucet, including configuration.

add_acl(acl_ident, acl)

Add an ACL to this DP.

add_port(port)

Add a port to this DP.

add_router(router_ident, router)

Add a router to this DP.

classmethod add_stack_link(graph, dp, port)

Add a stack link to the stack graph.

bgp_vlans()

Return list of VLANs with BGP enabled.

check_config()

Check config at instantiation time for errors, typically via assert.

classification_table()

default_table_sizes_types = {'classification': <class 'int'>, 'eth_dst': <class 'int'>, 'eth_dst_hairpin': <class 'int'>, 'eth_src': <class 'int'>, 'flood': <class 'int'>, 'ipv4_fib': <class 'int'>, 'ipv6_fib': <class 'int'>, 'port_acl': <class 'int'>, 'vip': <class 'int'>, 'vlan': <class 'int'>, 'vlan_acl': <class 'int'>}

defaults = {'advertise_interval': 30, 'arp_neighbor_timeout': 30, 'cache_update_guard_time': 0, 'combinatorial_port_flood': False, 'cookie': 1524372928, 'description': None, 'dot1x': None, 'dp_acls': None, 'dp_id': None, 'drop_broadcast_source_address': True, 'drop_spoofed_faucet_mac': True, 'egress_pipeline': False, 'fast_advertise_interval': 5, 'faucet_dp_mac': '0e:00:00:00:00:01', 'global_vlan': 0, 'group_table': False, 'hardware': 'Open vSwitch', 'high_priority': None, 'highest_priority': None, 'idle_dst': True, 'ignore_learn_ins': 10, 'interface_ranges': {}, 'interfaces': {}, 'lacp_timeout': 30, 'learn_ban_timeout': 0, 'learn_jitter': 0, 'lldp_beacon': {}, 'low_priority': None, 'lowest_priority': None, 'max_host_fib_retry_count': 10, 'max_hosts_per_resolve_cycle': 5, 'max_resolve_backoff_time': 64, 'max_wildcard_table_size': 1280, 'metrics_rate_limit_sec': 0, 'min_wildcard_table_size': 32, 'multi_out': True, 'name': None, 'nd_neighbor_timeout': 30, 'ofchannel_log': None, 'packetin_pps': None, 'priority_offset': 0, 'proactive_learn_v4': True, 'proactive_learn_v6': True, 'stack': None, 'strict_packet_in_cookie': True, 'table_sizes': {}, 'timeout': 300, 'use_classification': False, 'use_idle_timeout': False}

defaults_types = {'advertise_interval': <class 'int'>, 'arp_neighbor_timeout': <class 'int'>, 'cache_update_guard_time': <class 'int'>, 'combinatorial_port_flood': <class 'bool'>, 'cookie': <class 'int'>, 'description': <class 'str'>, 'dot1x': <class 'dict'>, 'dp_acls': <class 'list'>, 'dp_id': <class 'int'>, 'drop_broadcast_source_address': <class 'bool'>, 'drop_spoofed_faucet_mac': <class 'bool'>, 'egress_pipeline': <class 'bool'>, 'fast_advertise_interval': <class 'int'>, 'faucet_dp_mac': <class 'str'>, 'global_vlan': <class 'int'>, 'group_table': <class 'bool'>, 'hardware': <class 'str'>, 'high_priority': <class 'int'>, 'highest_priority': <class 'int'>, 'idle_dst': <class 'bool'>, 'ignore_learn_ins': <class 'int'>, 'interface_ranges': <class 'dict'>, 'interfaces': <class 'dict'>, 'lacp_timeout': <class 'int'>, 'learn_ban_timeout': <class 'int'>, 'learn_jitter': <class 'int'>, 'lldp_beacon': <class 'dict'>, 'low_priority': <class 'int'>, 'lowest_priority': <class 'int'>, 'max_host_fib_retry_count': <class 'int'>, 'max_hosts_per_resolve_cycle': <class 'int'>, 'max_resolve_backoff_time': <class 'int'>, 'max_wildcard_table_size': <class 'int'>, 'metrics_rate_limit_sec': <class 'int'>, 'min_wildcard_table_size': <class 'int'>, 'multi_out': <class 'bool'>, 'name': <class 'str'>, 'nd_neighbor_timeout': <class 'int'>, 'ofchannel_log': <class 'str'>, 'packetin_pps': <class 'int'>, 'priority_offset': <class 'int'>, 'proactive_learn_v4': <class 'bool'>, 'proactive_learn_v6': <class 'bool'>, 'stack': <class 'dict'>, 'strict_packet_in_cookie': <class 'bool'>, 'table_sizes': <class 'dict'>, 'timeout': <class 'int'>, 'use_classification': <class 'bool'>, 'use_idle_timeout': <class 'bool'>}

dot1x_defaults_types = {'nfv_intf': <class 'str'>, 'nfv_sw_port': <class 'int'>, 'radius_ip': <class 'str'>, 'radius_port': <class 'int'>, 'radius_secret': <class 'str'>}

dot1x_ports()

Return list of ports with 802.1x enabled.

finalize_config(dps)

Perform consistency checks after initial config parsing.

get_config_changes(logger, new_dp)

Detect any config changes.

Parameters:

• logger (ValveLogger) – logger instance
• new_dp (DP) – new dataplane configuration.

Returns:

changes tuple containing:

deleted_ports (set): deleted port numbers. changed_ports (set): changed/added port numbers. changed_acl_ports (set): changed ACL only port numbers. deleted_vlans (set): deleted VLAN IDs. changed_vlans (set): changed/added VLAN IDs. all_ports_changed (bool): True if all ports changed.

Return type:

(tuple)

get_config_dict()

Return DP config as a dict for API call.

get_native_vlan(port_num)

Return native VLAN for a port by number, or None.

get_tables()

Return tables as dict for API call.

in_port_tables()

Return list of tables that specify in_port as a match.

is_stack_edge()

Return True if this DP is a stack edge.

is_stack_root()

Return True if this DP is the root of the stack.

lldp_beacon_defaults_types = {'max_per_interval': <class 'int'>, 'send_interval': <class 'int'>, 'system_name': <class 'str'>}

lldp_beacon_send_ports(now)

Return list of ports to send LLDP packets; stacked ports always send LLDP.

match_tables(match_type)

Return list of tables with matches of a specific match type.

static modify_stack_topology(graph, dp, port, add=True)

Add/remove an edge to the stack graph which originates from this dp and port.

mutable_attrs = frozenset({'stack', 'vlans'})

output_table()

output_tables()

Return tables that cause a packet to be forwarded.

peer_stack_up_ports(peer_dp)

Return list of stack ports that are up towards a peer.

port_no_valid(port_no)

Return True if supplied port number valid on this datapath.

classmethod remove_stack_link(graph, dp, port)

Remove a stack link to the stack graph.

reset_refs(vlans=None)

resolve_port(port_name)

Resolve a port by number or name.

resolve_stack_topology(dps)

Resolve inter-DP config for stacking.

set_defaults()

Set default values and run any basic sanity checks.

shortest_path(dest_dp, src_dp=None)

Return shortest path to a DP, as a list of DPs.

shortest_path_port(dest_dp)

Return first port on our DP, that is the shortest path towards dest DP.

shortest_path_to_root()

Return shortest path to root DP, as list of DPs.

stack_defaults_types = {'priority': <class 'int'>}

table_by_id(table_id)

to_conf()

Return DP config as dict.

faucet.faucet module

RyuApp shim between Ryu and Valve.

class faucet.faucet.EventFaucetAdvertise

Bases: ryu.controller.event.EventBase

Event used to trigger periodic network advertisements (eg IPv6 RAs).

class faucet.faucet.EventFaucetExperimentalAPIRegistered

Bases: ryu.controller.event.EventBase

Event used to notify that the API is registered with Faucet.

class faucet.faucet.EventFaucetFastAdvertise

Bases: ryu.controller.event.EventBase

Event used to trigger periodic fast network advertisements (eg LACP).

class faucet.faucet.EventFaucetFastStateExpire

Bases: ryu.controller.event.EventBase

Event used to trigger fast expiration of state in controller.

class faucet.faucet.EventFaucetMetricUpdate

Bases: ryu.controller.event.EventBase

Event used to trigger update of metrics.

class faucet.faucet.EventFaucetResolveGateways

Bases: ryu.controller.event.EventBase

Event used to trigger gateway re/resolution.

class faucet.faucet.EventFaucetStateExpire

Bases: ryu.controller.event.EventBase

Event used to trigger expiration of state in controller.

class faucet.faucet.Faucet(*args, **kwargs)

Bases: faucet.valve_ryuapp.RyuAppBase

A RyuApp that implements an L2/L3 learning VLAN switch.

Valve provides the switch implementation; this is a shim for the Ryu event handling framework to interface with Valve.

bgp = None

desc_stats_reply_handler(ryu_event)

Handle OFPDescStatsReply from datapath.

Parameters:ryu_event (ryu.controller.ofp_event.EventOFPDescStatsReply) – trigger.

error_handler(ryu_event)

Handle an OFPError from a datapath.

Parameters:ryu_event (ryu.controller.ofp_event.EventOFPErrorMsg) – trigger

exc_logname = 'faucet.exception'

features_handler(ryu_event)

Handle receiving a switch features message from a datapath.

Parameters:ryu_event (ryu.controller.ofp_event.EventOFPStateChange) – trigger.

flowremoved_handler(ryu_event)

Handle a flow removed event.

Parameters:ryu_event (ryu.controller.ofp_event.EventOFPFlowRemoved) – trigger.

get_config()

FAUCET experimental API: return config for all Valves.

get_tables(dp_id)

FAUCET experimental API: return config tables for one Valve.

logname = 'faucet'

metric_update(_)

Handle a request to update metrics in the controller.

metrics = None

notifier = None

packet_in_handler(ryu_event)

Handle a packet in event from the dataplane.

Parameters:ryu_event (ryu.controller.event.EventReplyBase) – packet in message.

port_status_handler(ryu_event)

Handle a port status change event.

Parameters:ryu_event (ryu.controller.ofp_event.EventOFPPortStatus) – trigger.

reload_config(ryu_event)

Handle a request to reload configuration.

start()

Start controller.

valves_manager = None

faucet.faucet_bgp module

BGP implementation for FAUCET.

class faucet.faucet_bgp.BgpSpeakerKey(dp_id, vlan_vid, ipv)

Bases: object

Uniquely describe a BGP speaker.

class faucet.faucet_bgp.FaucetBgp(logger, exc_logname, metrics, send_flow_msgs)

Bases: object

Wrapper for Ryu BGP speaker.

exc_logname = None

reset(valves)

Set up a BGP speaker for every VLAN that requires it.

shutdown_bgp_speakers()

Shutdown any active BGP speakers.

update_metrics(_now)

Update BGP metrics.

faucet.faucet_dot1x module

802.1x implementation for FAUCET.

class faucet.faucet_dot1x.FaucetDot1x(logger, metrics, send_flow_msgs)

Bases: object

Wrapper for experimental Chewie 802.1x authenticator.

auth_handler(address, port_id)

Callback for when a successful auth happens.

create_flow_pair(dot1x_port, nfv_sw_port, valve)

Creates the pair of flows that redirects the eapol packets to/from the supplicant and nfv port

Parameters:

• dot1x_port (Port) –
• nfv_sw_port (int) –
• valve (Valve) –

Returns:

list

failure_handler(address, port_id)

Callback for when a EAP failure happens.

static get_dot1x_port_match_priority(dot1x_port, port_acl_table, valve)

Create the match for eapol coming from the supplicant’s port. :param dot1x_port: supplicant port. :type dot1x_port: Port :param port_acl_table: :type port_acl_table: ValveTable :param valve: :type valve: Valve

Returns:dict containing a match and priority.

static get_nfv_sw_port_match_priority(mac, nfv_sw_port, port_acl_table, valve)

Create the match for eapol coming from the nfv_sw_port. :param mac: the MacAddress of the dot1x (supplicant port) :type mac: str :param nfv_sw_port: :type nfv_sw_port: int :param port_acl_table: :type port_acl_table: ValveTable :param valve: :type valve: Valve

Returns:dict containing a match and priority.

get_port_acls(valve, dot1x_port)

Setup the dot1x forward port acls. :param dot1x_port: :param valve:

Returns:list of flowmods

get_valve_and_port(port_id)

Finds the valve and port that this address corresponds to :param port_id: is a macaddress string

logoff_handler(address, port_id)

Callback for when an EAP logoff happens.

port_down(valve, dot1x_port)

Remove the acls added by FaucetDot1x.get_port_acls :param valve: :param dot1x_port:

Returns:list of flowmods

reset(valves)

Set up a dot1x speaker.

set_mac_str(valve, valve_index, port_num)

Parameters:

• valve (Valve) –
• valve_index (int) –
• port_num (int) –

Returns:

str

faucet.faucet_dot1x.get_mac_str(valve_index, port_num)

Gets the mac address string for the valve/port combo :param valve_index: The internally used id of the valve. :type valve_index: int :param port_num: port number :type port_num: int

Returns:str

faucet.faucet_experimental_api module

Implement experimental API.

class faucet.faucet_experimental_api.FaucetExperimentalAPI(*_args, **_kwargs)

Bases: object

An experimental API for communicating with Faucet.

Contains methods for interacting with a running Faucet controller from within a RyuApp. This app should be run together with Faucet in the same ryu-manager process.

add_port_acl(port, acl)

Add an ACL to a port.

add_vlan_acl(vlan, acl)

Add an ACL to a VLAN.

delete_port_acl(port, acl)

Delete an ACL from a port.

delete_vlan_acl(vlan, acl)

Delete an ACL from a VLAN.

get_config()

Get the current running config of Faucet as a python dictionary.

get_tables(dp_id)

Get current FAUCET tables as a dict of table name: table no.

is_registered()

Return True if registered and ready to serve API requests.

push_config(config)

Push supplied config to FAUCET.

reload_config()

Reload config from config file in FAUCET_CONFIG env variable.

faucet.faucet_experimental_event module

Experimental FAUCET event notification.

class faucet.faucet_experimental_event.FaucetExperimentalEventNotifier(socket_path, metrics, logger)

Bases: object

Event notification, via Unix domain socket.

check_path(socket_path)

Check that socket_path is valid.

notify(dp_id, dp_name, event_dict)

Notify of an event.

start()

Start socket server.

class faucet.faucet_experimental_event.NonBlockLock

Bases: object

Non blocking lock that can be used as a context manager.

acquire_nonblock()

Attempt to acquire a lock.

release()

Release lock when done.

faucet.faucet_metadata module

This module contains code relating to the use of OpenFlow Metadata within Faucet.

faucet.faucet_metadata.get_egress_metadata(port_num, vid)

Return the metadata value to output a packet to port port_num on vlan vid

faucet.faucet_metrics module

Implement Prometheus statistics.

class faucet.faucet_metrics.FaucetMetrics(reg=None)

Bases: faucet.prom_client.PromClient

Container class for objects that can be exported to Prometheus.

inc_var(var, labels, val=1)

reset_dpid(dp_labels)

Set all DPID-only counter/gauges to 0.

faucet.faucet_pipeline module

Standard FAUCET pipeline.

class faucet.faucet_pipeline.ValveTableConfig(name, table_id, exact_match=None, meter=None, output=True, miss_goto=None, size=None, match_types=None, set_fields=None, dec_ttl=None, vlan_port_scale=None, next_tables=None, metadata_match=0, metadata_write=0)

Bases: object

Configuration for a single table.

faucet.fctl module

Report state based on FAUCET/Gauge/Prometheus variables.

faucet.fctl.decode_value(metric_name, value)

Convert values to human readible format based on metric name

faucet.fctl.main()

faucet.fctl.parse_args(sys_args)

Parse and return CLI args.

faucet.fctl.report_label_match_metrics(report_metrics, metrics, display_labels=None, nonzero_only=False, delim='\t', label_matches=None)

Text report on a list of Prometheus metrics.

faucet.fctl.scrape_prometheus(endpoints, retries=3, err_output_file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>)

Scrape a list of Prometheus/FAUCET/Gauge endpoints and aggregate results.

faucet.gauge module

RyuApp shim between Ryu and Gauge.

class faucet.gauge.Gauge(*args, **kwargs)

Bases: faucet.valve_ryuapp.RyuAppBase

Ryu app for polling Faucet controlled datapaths for stats/state.

It can poll multiple datapaths. The configuration files for each datapath should be listed, one per line, in the file set as the environment variable GAUGE_CONFIG. It logs to the file set as the environment variable GAUGE_LOG,

exc_logname = 'gauge.exception'

logname = 'gauge'

prom_client = None

reload_config(ryu_event)

Handle request for Gauge config reload.

update_watcher_handler(ryu_event)

Handle port status change event.

Parameters:ryu_event (ryu.controller.event.EventReplyBase) – port status change event.

faucet.gauge_influx module

Library for interacting with InfluxDB.

class faucet.gauge_influx.GaugeFlowTableInfluxDBLogger(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugeFlowTablePoller, faucet.gauge_influx.InfluxShipper

Example

> use faucet
Using database faucet
> show series where table_id = '0' and in_port = '2'
key
---
flow_byte_count,dp_name=windscale-faucet-1,eth_type=2048,in_port=2,ip_proto=17,priority=9099,table_id=0,udp_dst=53
flow_byte_count,dp_name=windscale-faucet-1,eth_type=2048,in_port=2,ip_proto=6,priority=9098,table_id=0,tcp_dst=53
flow_byte_count,dp_name=windscale-faucet-1,in_port=2,priority=9097,table_id=0
flow_packet_count,dp_name=windscale-faucet-1,eth_type=2048,in_port=2,ip_proto=17,priority=9099,table_id=0,udp_dst=53
flow_packet_count,dp_name=windscale-faucet-1,eth_type=2048,in_port=2,ip_proto=6,priority=9098,table_id=0,tcp_dst=53
flow_packet_count,dp_name=windscale-faucet-1,in_port=2,priority=9097,table_id=0
> select * from flow_byte_count where table_id = '0' and in_port = '2' and ip_proto = '17' and time > now() - 5m
name: flow_byte_count
time                arp_tpa dp_name            eth_dst eth_src eth_type icmpv6_type in_port ip_proto ipv4_dst ipv6_dst priority table_id tcp_dst udp_dst value vlan_vid
----                ------- -------            ------- ------- -------- ----------- ------- -------- -------- -------- -------- -------- ------- ------- ----- --------
1501154797000000000         windscale-faucet-1                 2048                 2       17                         9099     0                53      9414
1501154857000000000         windscale-faucet-1                 2048                 2       17                         9099     0                53      10554
1501154917000000000         windscale-faucet-1                 2048                 2       17                         9099     0                53      10554
1501154977000000000         windscale-faucet-1                 2048                 2       17                         9099     0                53      12164
1501155037000000000         windscale-faucet-1                 2048                 2       17                         9099     0                53      12239

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.gauge_influx.GaugePortStateInfluxDBLogger(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugePortStatePoller, faucet.gauge_influx.InfluxShipper

Example

> use faucet
Using database faucet
> precision rfc3339
> select * from port_state_reason where port_name = 'port1.0.1' order by time desc limit 10;
name: port_state_reason
-----------------------
time                    dp_name                 port_name       value
2017-02-21T02:12:29Z    windscale-faucet-1      port1.0.1       2
2017-02-21T02:12:25Z    windscale-faucet-1      port1.0.1       2
2016-07-27T22:05:08Z    windscale-faucet-1      port1.0.1       2
2016-05-25T04:33:00Z    windscale-faucet-1      port1.0.1       2
2016-05-25T04:32:57Z    windscale-faucet-1      port1.0.1       2
2016-05-25T04:31:21Z    windscale-faucet-1      port1.0.1       2
2016-05-25T04:31:18Z    windscale-faucet-1      port1.0.1       2
2016-05-25T04:27:07Z    windscale-faucet-1      port1.0.1       2
2016-05-25T04:27:04Z    windscale-faucet-1      port1.0.1       2
2016-05-25T04:24:53Z    windscale-faucet-1      port1.0.1       2

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.gauge_influx.GaugePortStatsInfluxDBLogger(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugePortStatsPoller, faucet.gauge_influx.InfluxShipper

Periodically sends a port stats request to the datapath and parses and outputs the response.

Example

> use faucet
Using database faucet
> show measurements
name: measurements
------------------
bytes_in
bytes_out
dropped_in
dropped_out
errors_in
packets_in
packets_out
port_state_reason
> precision rfc3339
> select * from packets_out where port_name = 'port1.0.1' order by time desc limit 10;
name: packets_out
-----------------
time                    dp_name                 port_name       value
2017-03-06T05:21:42Z    windscale-faucet-1      port1.0.1       76083431
2017-03-06T05:21:33Z    windscale-faucet-1      port1.0.1       76081172
2017-03-06T05:21:22Z    windscale-faucet-1      port1.0.1       76078727
2017-03-06T05:21:12Z    windscale-faucet-1      port1.0.1       76076612
2017-03-06T05:21:02Z    windscale-faucet-1      port1.0.1       76074546
2017-03-06T05:20:52Z    windscale-faucet-1      port1.0.1       76072730
2017-03-06T05:20:42Z    windscale-faucet-1      port1.0.1       76070528
2017-03-06T05:20:32Z    windscale-faucet-1      port1.0.1       76068211
2017-03-06T05:20:22Z    windscale-faucet-1      port1.0.1       76065982
2017-03-06T05:20:12Z    windscale-faucet-1      port1.0.1       76063941

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.gauge_influx.InfluxShipper

Bases: object

Convenience class for shipping values to InfluxDB.

Inheritors must have a WatcherConf object as conf.

conf = None

logger = None

static make_point(tags, rcv_time, stat_name, stat_val)

Make an InfluxDB point.

make_port_point(dp_name, port_name, rcv_time, stat_name, stat_val)

Make an InfluxDB point about a port measurement.

ship_error_prefix = 'error shipping points: '

ship_points(points)

Make a connection to InfluxDB and ship points.

faucet.gauge_pollers module

Library for polling dataplanes for statistics.

class faucet.gauge_pollers.GaugeFlowTablePoller(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugeThreadPoller

Periodically dumps the current datapath flow table as a yaml object.

Includes a timestamp and a reference ($DATAPATHNAME-flowtables). The flow table is dumped as an OFFlowStatsReply message (in yaml format) that matches all flows.

no_response()

Called when a polling cycle passes without receiving a response.

send_req()

Send a stats request to a datapath.

class faucet.gauge_pollers.GaugePoller(conf, logname, prom_client)

Bases: object

Abstraction for a poller for statistics.

static is_active()

Return True if the poller is controlling the request loop for its stat

no_response()

Called when a polling cycle passes without receiving a response.

report_dp_status(dp_status)

Report DP status.

running()

Return True if the poller is running.

send_req()

Send a stats request to a datapath.

start(ryudp, active)

Start the poller.

stop()

Stop the poller.

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.gauge_pollers.GaugePortStatePoller(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugePoller

Abstraction for port state poller.

no_response()

Called when a polling cycle passes without receiving a response.

send_req()

Send a stats request to a datapath.

class faucet.gauge_pollers.GaugePortStatsPoller(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugeThreadPoller

Periodically sends a port stats request to the datapath and parses and outputs the response.

no_response()

Called when a polling cycle passes without receiving a response.

send_req()

Send a stats request to a datapath.

class faucet.gauge_pollers.GaugeThreadPoller(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugePoller

A ryu thread object for sending and receiving OpenFlow stats requests.

The thread runs in a loop sending a request, sleeping then checking a response was received before sending another request.

The methods send_req, update and no_response should be implemented by subclasses.

is_active()

Return True if the poller is controlling the request loop for its stat

no_response()

Called when a polling cycle passes without receiving a response.

send_req()

Send a stats request to a datapath.

start(ryudp, active)

Start the poller.

stop()

Stop the poller.

faucet.gauge_prom module

Prometheus for Gauge.

class faucet.gauge_prom.GaugeFlowTablePrometheusPoller(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugeFlowTablePoller

Export flow table entries to Prometheus.

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.gauge_prom.GaugePortStatePrometheusPoller(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugePortStatePoller

Export port state changes to Prometheus.

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.gauge_prom.GaugePortStatsPrometheusPoller(conf, logger, prom_client)

Bases: faucet.gauge_pollers.GaugePortStatsPoller

Exports port stats to Prometheus.

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.gauge_prom.GaugePrometheusClient(reg=None)

Bases: faucet.prom_client.PromClient

Wrapper for Prometheus client that is shared between all pollers.

reregister_flow_vars(table_name, table_tags)

Register the flow variables needed for this client

faucet.meter module

Configure meters.

class faucet.meter.Meter(_id, dp_id, conf)

Bases: faucet.conf.Conf

Implement FAUCET configuration for an OpenFlow meter.

defaults = {'entry': None, 'meter_id': None}

defaults_types = {'entry': <class 'dict'>, 'meter_id': <class 'int'>}

entry = None

entry_msg = None

meter_id = None

faucet.port module

Port configuration.

class faucet.port.Port(_id, dp_id, conf=None)

Bases: faucet.conf.Conf

Stores state for ports, including the configuration.

check_config()

Check config at instantiation time for errors, typically via assert.

defaults = {'acl_in': None, 'acls_in': None, 'description': None, 'dot1x': False, 'enabled': True, 'hairpin': False, 'hairpin_unicast': False, 'lacp': 0, 'lacp_active': False, 'lldp_beacon': {}, 'loop_protect': False, 'max_hosts': 255, 'max_lldp_lost': 3, 'mirror': None, 'name': None, 'native_vlan': None, 'number': None, 'opstatus_reconf': True, 'output_only': False, 'override_output_port': None, 'permanent_learn': False, 'receive_lldp': False, 'stack': None, 'tagged_vlans': None, 'unicast_flood': True}

defaults_types = {'acl_in': (<class 'str'>, <class 'int'>), 'acls_in': <class 'list'>, 'description': <class 'str'>, 'dot1x': <class 'bool'>, 'enabled': <class 'bool'>, 'hairpin': <class 'bool'>, 'hairpin_unicast': <class 'bool'>, 'lacp': <class 'int'>, 'lacp_active': <class 'bool'>, 'lldp_beacon': <class 'dict'>, 'loop_protect': <class 'bool'>, 'max_hosts': <class 'int'>, 'max_lldp_lost': <class 'int'>, 'mirror': (<class 'list'>, <class 'str'>, <class 'int'>), 'name': <class 'str'>, 'native_vlan': (<class 'str'>, <class 'int'>), 'number': <class 'int'>, 'opstatus_reconf': <class 'bool'>, 'output_only': <class 'bool'>, 'override_output_port': (<class 'str'>, <class 'int'>), 'permanent_learn': <class 'bool'>, 'receive_lldp': <class 'bool'>, 'stack': <class 'dict'>, 'tagged_vlans': <class 'list'>, 'unicast_flood': <class 'bool'>}

finalize()

Configuration parsing marked complete.

hosts(vlans=None)

Return all host cache entries this port has learned (on all or specified VLANs).

hosts_count(vlans=None)

Return count of all hosts this port has learned (on all or specified VLANs).

is_stack_admin_down()

Return True if port is in ADMIN_DOWN state.

is_stack_down()

Return True if port is in DOWN state.

is_stack_init()

Return True if port is in INIT state.

is_stack_up()

Return True if port is in UP state.

lldp_beacon_defaults_types = {'enable': <class 'bool'>, 'org_tlvs': <class 'list'>, 'port_descr': <class 'str'>, 'system_name': <class 'str'>}

lldp_beacon_enabled()

Return True if LLDP beacon enabled on this port.

lldp_org_tlv_defaults_types = {'info': (<class 'str'>, <class 'bytearray'>), 'oui': (<class 'int'>, <class 'bytearray'>), 'subtype': (<class 'int'>, <class 'bytearray'>)}

mirror_actions()

Return OF actions to mirror this port.

running()

Return True if port enabled and up.

set_defaults()

Set default values and run any basic sanity checks.

stack_admin_down()

Change the current stack state to ADMIN_DOWN.

stack_defaults_types = {'dp': <class 'str'>, 'port': (<class 'str'>, <class 'int'>)}

stack_down()

Change the current stack state to DOWN.

stack_init()

Change the current stack state to INIT_DOWN.

stack_up()

Change the current stack state to UP.

to_conf()

Return configuration as a dict.

vlans()

Return all VLANs this port is in.

faucet.prom_client module

Implement Prometheus client.

class faucet.prom_client.PromClient(reg=None)

Bases: object

Prometheus client.

REQUIRED_LABELS = ['dp_id', 'dp_name']

server = None

start(prom_port, prom_addr, use_test_thread=False)

Start webserver.

thread = None

faucet.prom_client.make_wsgi_app(registry)

Create a WSGI app which serves the metrics from a registry.

faucet.router module

Configure routing between VLANs.

class faucet.router.Router(_id, dp_id, conf)

Bases: faucet.conf.Conf

Implement FAUCET configuration for a router.

check_config()

Check config at instantiation time for errors, typically via assert.

defaults = {'vlans': None}

defaults_types = {'vlans': <class 'list'>}

finalize()

Configuration parsing marked complete.

vip_map(ipa)

Return VIP for IP address, if any.

faucet.tfm_pipeline module

Configure switch tables with TFM messages.

faucet.tfm_pipeline.load_tables(dp, valve_cl)

Configure switch tables with TFM messages.

faucet.valve module

Implementation of Valve learning layer 2/3 switch.

class faucet.valve.AlliedTelesis(dp, logname, metrics, notifier, dot1x)

Bases: faucet.valve.OVSValve

Valve implementation for AT.

DEC_TTL = False

class faucet.valve.ArubaValve(dp, logname, metrics, notifier, dot1x)

Bases: faucet.valve.TfmValve

Valve implementation for Aruba.

DEC_TTL = False

class faucet.valve.CiscoC9KValve(dp, logname, metrics, notifier, dot1x)

Bases: faucet.valve.TfmValve

Valve implementation for C9K.

class faucet.valve.NoviFlowValve(dp, logname, metrics, notifier, dot1x)

Bases: faucet.valve.Valve

Valve implementation for NoviFlow with static pipeline.

STATIC_TABLE_IDS = True

USE_BARRIERS = True

class faucet.valve.OVSValve(dp, logname, metrics, notifier, dot1x)

Bases: faucet.valve.Valve

Valve implementation for OVS.

USE_BARRIERS = False

class faucet.valve.TfmValve(dp, logname, metrics, notifier, dot1x)

Bases: faucet.valve.Valve

Valve implementation that uses OpenFlow send table features messages.

class faucet.valve.Valve(dp, logname, metrics, notifier, dot1x)

Bases: object

Generates the messages to configure a datapath as a l2 learning switch.

Vendor specific implementations may require sending configuration flows. This can be achieved by inheriting from this class and overwriting the function switch_features.

DEC_TTL = True

GROUPS = True

STATIC_TABLE_IDS = False

USE_BARRIERS = True

add_authed_mac(port_num, mac)

Add authed mac address

add_route(vlan, ip_gw, ip_dst)

Add route to VLAN routing table.

advertise(now, _other_values)

Called periodically to advertise services (eg. IPv6 RAs).

base_prom_labels

close_logs()

Explicitly close any active loggers.

datapath_connect(now, discovered_up_ports)

Handle Ryu datapath connection event and provision pipeline.

Parameters:

• now (float) – current epoch time.
• discovered_up_ports (list) – datapath port numbers that are up.

Returns:

OpenFlow messages to send to datapath.

Return type:

list

datapath_disconnect()

Handle Ryu datapath disconnection event.

del_authed_mac(port_num, mac)

del_route(vlan, ip_dst)

Delete route from VLAN routing table.

dot1x

dp

dp_init()

Initialize datapath state at connection/re/config time.

fast_advertise(now, _other_valves)

Called periodically to send LLDP/LACP packets.

fast_state_expire(now, other_valves)

Called periodically to verify the state of stack ports.

flood_manager

flow_timeout(now, table_id, match)

Call flow timeout message handler:

Parameters:

• now (float) – current epoch time.
• table_id (int) – ID of table where flow was installed.
• match (dict) – match conditions for expired flow.

Returns:

OpenFlow messages, if any.

Return type:

list

get_config_dict()

Return datapath config as a dict for experimental API.

host_manager

lacp_down(port, cold_start=False)

Return OpenFlow messages when LACP is down on a port.

lacp_handler(now, pkt_meta)

Handle a LACP packet.

We are a currently a passive, non-aggregateable LACP partner.

Parameters:

• now (float) – current epoch time.
• pkt_meta (PacketMeta) – packet for control plane.

Returns:

OpenFlow messages, if any.

Return type:

list

lacp_up(port)

Return OpenFlow messages when LACP is up on a port.

lldp_handler(now, pkt_meta, other_valves)

Handle an LLDP packet.

Parameters:pkt_meta (PacketMeta) – packet for control plane.

logger

logname

metrics

notifier

ofchannel_log(ofmsgs)

Log OpenFlow messages in text format to debugging log.

ofchannel_logger

ofdescstats_handler(body)

Handle OF DP description.

oferror(msg)

Correlate OFError message with flow we sent, if any.

Parameters:msg (ryu.controller.ofp_event.EventOFPMsgBase) – message from datapath.

parse_pkt_meta(msg)

Parse OF packet-in message to PacketMeta.

parse_rcv_packet(in_port, vlan_vid, eth_type, data, orig_len, pkt, eth_pkt, vlan_pkt)

Parse a received packet into a PacketMeta instance.

Parameters:

• in_port (int) – port packet was received on.
• vlan_vid (int) – VLAN VID of port packet was received on.
• eth_type (int) – Ethernet type of packet.
• data (bytes) – Raw packet data.
• orig_len (int) – Original length of packet.
• pkt (ryu.lib.packet.packet) – parsed packet received.
• ekt_pkt (ryu.lib.packet.ethernet) – parsed Ethernet header.
• vlan_pkt (ryu.lib.packet.vlan) – parsed VLAN Ethernet header.

Returns:

PacketMeta instance.

pipeline

port_add(port_num)

Handle addition of a single port.

Parameters:port_num (list) – list of port numbers. Returns:OpenFlow messages, if any. Return type:list

port_delete(port_num)

Return flow messages that delete port from pipeline.

port_labels(port)

port_status_handler(port_no, reason, state)

Return OpenFlow messages responding to port operational status change.

ports_add(port_nums, cold_start=False, log_msg='up')

Handle the addition of ports.

Parameters:

• port_num (list) – list of port numbers.
• cold_start (bool) – True if configuring datapath from scratch.

Returns:

OpenFlow messages, if any.

Return type:

list

ports_delete(port_nums, log_msg='down')

Handle the deletion of ports.

Parameters:port_nums (list) – list of port numbers. Returns:OpenFlow messages, if any. Return type:list

prepare_send_flows(flow_msgs)

Prepare to send flows to datapath.

Parameters:flow_msgs (list) – OpenFlow messages to send.

rate_limit_packet_ins(now)

Return True if too many packet ins this second.

rcv_packet(now, other_valves, pkt_meta)

Handle a packet from the dataplane (eg to re/learn a host).

The packet may be sent to us also in response to FAUCET initiating IPv6 neighbor discovery, or ARP, to resolve a nexthop.

Parameters:

• other_valves (list) – all Valves other than this one.
• pkt_meta (PacketMeta) – packet for control plane.

Returns:

OpenFlow messages, if any.

Return type:

list

recent_ofmsgs

reload_config(now, new_dp)

Reload configuration new_dp.

Following config changes are currently supported:

• Port config: support all available configs

  (e.g. native_vlan, acl_in) & change operations (add, delete, modify) a port

• ACL config:support any modification, currently reload all

  rules belonging to an ACL

• VLAN config: enable, disable routing, etc…

Parameters:

• now (float) – current epoch time.
• new_dp (DP) – new dataplane configuration.

Returns:

OpenFlow messages.

Return type:

ofmsgs (list)

resolve_gateways(now, _other_valves)

Call route managers to re/resolve gateways.

Returns:OpenFlow messages, if any. Return type:list

send_flows(ryu_dp, flow_msgs)

Send flows to datapath.

Parameters:

• ryu_dp (ryu.controller.controller.Datapath) – datapath.
• flow_msgs (list) – OpenFlow messages to send.

state_expire(now, _other_valves)

Expire controller caches/state (e.g. hosts learned).

Returns:OpenFlow messages, if any. Return type:list

switch_features(_msg)

Send configuration flows necessary for the switch implementation.

Parameters:msg (OFPSwitchFeatures) – msg sent from switch.

Vendor specific configuration should be implemented here.

update_config_metrics()

Update table names for configuration.

update_metrics(now, updated_port=None, rate_limited=False)

Update Gauge/metrics.

class faucet.valve.ValveLogger(logger, dp_id, dp_name)

Bases: object

Logger for a Valve that adds DP ID.

debug(log_msg)

Log debug level message.

error(log_msg)

Log error level message.

info(log_msg)

Log info level message.

warning(log_msg)

Log warning level message.

faucet.valve.valve_factory(dp)

Return a Valve object based dp’s hardware configuration field.

Parameters:dp (DP) – DP instance with the configuration for this Valve.

faucet.valve_acl module

Compose ACLs on ports.

faucet.valve_acl.build_acl_entry(acl_table, rule_conf, meters, acl_allow_inst, acl_force_port_vlan_inst, port_num=None, vlan_vid=None)

Build flow/groupmods for one ACL rule entry.

faucet.valve_acl.build_acl_ofmsgs(acls, acl_table, acl_allow_inst, acl_force_port_vlan_inst, highest_priority, meters, exact_match, port_num=None, vlan_vid=None)

Build flow/groupmods for all entries in an ACL.

faucet.valve_acl.build_output_actions(acl_table, output_dict)

Implement actions to alter packet/output.

faucet.valve_acl.push_vlan(acl_table, vlan_vid)

Push a VLAN tag with optional selection of eth type.

faucet.valve_acl.rewrite_vlan(acl_table, output_dict)

Implement actions to rewrite VLAN headers.

faucet.valve_flood module

Manage flooding to ports on VLANs.

class faucet.valve_flood.ValveFloodManager(flood_table, eth_src_table, flood_priority, bypass_priority, use_group_table, groups, combinatorial_port_flood)

Bases: faucet.valve_manager_base.ValveManagerBase

Implement dataplane based flooding for standalone dataplanes.

FLOOD_DSTS = ((True, None, None), (False, '01:80:c2:00:00:00', 'ff:ff:ff:00:00:00'), (False, '01:00:5E:00:00:00', 'ff:ff:ff:00:00:00'), (False, '33:33:00:00:00:00', 'ff:ff:00:00:00:00'), (False, 'ff:ff:ff:ff:ff:ff', None))

add_vlan(vlan)

install flows in response to a new vlan

build_flood_rules(vlan, modify=False)

Add flows to flood packets to unknown destinations on a VLAN.

static edge_learn_port(_other_valves, pkt_meta)

Possibly learn a host on a port.

Parameters:

• other_valves (list) – All Valves other than this one.
• pkt_meta (PacketMeta) – PacketMeta instance for packet received.

Returns:

port to learn host on.

initialise_tables()

initialise the flood table with filtering flows

update_stack_topo(event, dp, port=None)

Update the stack topology. It has nothing to do for non-stacking DPs.

class faucet.valve_flood.ValveFloodStackManager(flood_table, eth_src_table, flood_priority, bypass_priority, use_group_table, groups, combinatorial_port_flood, stack, stack_ports, dp_shortest_path_to_root, shortest_path_port)

Bases: faucet.valve_flood.ValveFloodManager

Implement dataplane based flooding for stacked dataplanes.

build_flood_rules(vlan, modify=False)

Add flows to flood packets to unknown destinations on a VLAN.

edge_learn_port(other_valves, pkt_meta)

Possibly learn a host on a port.

Parameters:

• other_valves (list) – All Valves other than this one.
• pkt_meta (PacketMeta) – PacketMeta instance for packet received.

Returns:

port to learn host on, or None.

update_stack_topo(event, dp, port=None)

Update the stack topo according to the event.

faucet.valve_host module

Manage host learning on VLANs.

class faucet.valve_host.ValveHostFlowRemovedManager(logger, ports, vlans, eth_src_table, eth_dst_table, eth_dst_hairpin_table, pipeline, learn_timeout, learn_jitter, learn_ban_timeout, low_priority, host_priority, cache_update_guard_time, idle_dst)

Bases: faucet.valve_host.ValveHostManager

Trigger relearning on flow removed notifications.

Note

not currently reliable.

expire_hosts_from_vlan(_vlan, _now)

Expire hosts from VLAN cache.

flow_timeout(now, table_id, match)

Handle a flow timed out message from dataplane.

learn_host_timeouts(port)

Calculate flow timeouts for learning on a port.

class faucet.valve_host.ValveHostManager(logger, ports, vlans, eth_src_table, eth_dst_table, eth_dst_hairpin_table, pipeline, learn_timeout, learn_jitter, learn_ban_timeout, low_priority, host_priority, cache_update_guard_time, idle_dst)

Bases: faucet.valve_manager_base.ValveManagerBase

Manage host learning on VLANs.

ban_rules(pkt_meta)

Limit learning to a maximum configured on this port/VLAN.

Parameters:pkt_meta – PacketMeta instance. Returns:OpenFlow messages, if any. Return type:list

delete_host_from_vlan(eth_src, vlan)

Delete a host from a VLAN.

expire_hosts_from_vlan(vlan, now)

Expire hosts from VLAN cache.

flow_timeout(_now, _table_id, _match)

Handle a flow timed out message from dataplane.

initialise_tables()

initialise tables controlled by this manager

learn_host_on_vlan_port_flows(port, vlan, eth_src, delete_existing, refresh_rules, src_rule_idle_timeout, src_rule_hard_timeout, dst_rule_idle_timeout)

Return flows that implement learning a host on a port.

learn_host_on_vlan_ports(now, port, vlan, eth_src, delete_existing=True, last_dp_coldstart_time=None)

Learn a host on a port.

learn_host_timeouts(port)

Calculate flow timeouts for learning on a port.

faucet.valve_manager_base module

Valve Manager base class

class faucet.valve_manager_base.ValveManagerBase

Bases: object

Base class for ValveManager objects.

Expected to control the installation of flows into datapath tables.

Ideally each datapath table should be controlled by 1 manager only.

add_vlan(vlan)

install flows in response to a new vlan

initialise_tables()

initialise tables controlled by this manager

faucet.valve_of module

Utility functions to parse/create OpenFlow messages.

faucet.valve_of.apply_actions(actions)

Return instruction that applies action list.

Parameters:actions (list) – list of OpenFlow actions. Returns:instruction of actions. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPInstruction

faucet.valve_of.apply_meter(meter_id)

Return instruction to apply a meter.

faucet.valve_of.barrier()

Return OpenFlow barrier request.

Returns:barrier request. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPBarrierRequest

faucet.valve_of.bucket(weight=0, watch_port=4294967295, watch_group=4294967295, actions=None)

Return a group action bucket with provided actions.

faucet.valve_of.build_match_dict(in_port=None, vlan=None, eth_type=None, eth_src=None, eth_dst=None, eth_dst_mask=None, icmpv6_type=None, nw_proto=None, nw_dst=None, metadata=None, metadata_mask=None)

faucet.valve_of.controller_pps_meteradd(datapath=None, pps=0)

Add a PPS meter towards controller.

faucet.valve_of.controller_pps_meterdel(datapath=None)

Delete a PPS meter towards controller.

faucet.valve_of.dec_ip_ttl()

Return OpenFlow action to decrement IP TTL.

Returns:decrement IP TTL. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPActionDecNwTtl

faucet.valve_of.dedupe_ofmsgs(input_ofmsgs)

Return deduplicated ofmsg list.

faucet.valve_of.dedupe_output_port_acts(output_port_acts)

Deduplicate parser.OFPActionOutputs (because Ryu doesn’t define __eq__).

Parameters:of ryu.ofproto.ofproto_v1_3_parser.OFPActionOutput (list) – output to port actions. Returns:output to port actions. Return type:list of ryu.ofproto.ofproto_v1_3_parser.OFPActionOutput

faucet.valve_of.desc_stats_request(datapath=None)

Query switch description.

faucet.valve_of.devid_present(vid)

Return VLAN VID without VID_PRESENT flag set.

Parameters:vid (int) – VLAN VID with VID_PRESENT. Returns:VLAN VID. Return type:int

faucet.valve_of.faucet_async(datapath=None, notify_flow_removed=False, packet_in=True, port_status=True)

Return async message config for FAUCET/Gauge

faucet.valve_of.faucet_config(datapath=None)

Return switch config for FAUCET.

faucet.valve_of.flood_port_outputs(tagged_ports, untagged_ports, in_port=None, exclude_ports=None)

Return actions for both tagged and untagged ports.

faucet.valve_of.flood_tagged_port_outputs(ports, in_port=None, exclude_ports=None)

Return list of actions necessary to flood to list of tagged ports.

faucet.valve_of.flood_untagged_port_outputs(ports, in_port=None, exclude_ports=None)

Return list of actions necessary to flood to list of untagged ports.

faucet.valve_of.flowmod(cookie, command, table_id, priority, out_port, out_group, match_fields, inst, hard_timeout, idle_timeout, flags=0)

faucet.valve_of.goto_table(table)

Return instruction to goto table.

Parameters:table (ValveTable) – table to goto. Returns:goto instruction. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPInstruction

faucet.valve_of.group_act(group_id)

Return an action to run a group.

faucet.valve_of.group_flood_buckets(ports, untagged)

faucet.valve_of.groupadd(datapath=None, type_=0, group_id=0, buckets=None)

Add a group.

faucet.valve_of.groupadd_ff(datapath=None, group_id=0, buckets=None)

Add a fast failover group.

faucet.valve_of.groupdel(datapath=None, group_id=4294967292)

Delete a group (default all groups).

faucet.valve_of.groupmod(datapath=None, type_=0, group_id=0, buckets=None)

Modify a group.

faucet.valve_of.groupmod_ff(datapath=None, group_id=0, buckets=None)

Modify a fast failover group.

faucet.valve_of.ignore_port(port_num)

Return True if FAUCET should ignore this port.

Parameters:port_num (int) – switch port. Returns:True if FAUCET should ignore this port. Return type:bool

faucet.valve_of.is_apply_actions(instruction)

Return True if an apply action.

Parameters:instruction – OpenFlow instruction. Returns:True if an apply action. Return type:bool

faucet.valve_of.is_delete(ofmsg)

faucet.valve_of.is_flowdel(ofmsg)

Return True if flow message is a FlowMod and a delete.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a FlowMod delete/strict. Return type:bool

faucet.valve_of.is_flowmod(ofmsg)

Return True if flow message is a FlowMod.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a FlowMod Return type:bool

faucet.valve_of.is_groupadd(ofmsg)

Return True if OF message is a GroupMod and command is add.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a GroupMod add Return type:bool

faucet.valve_of.is_groupdel(ofmsg)

Return True if OF message is a GroupMod and command is delete.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a GroupMod delete Return type:bool

faucet.valve_of.is_groupmod(ofmsg)

Return True if OF message is a GroupMod.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a GroupMod Return type:bool

faucet.valve_of.is_meter(instruction)

Return True if a meter.

Parameters:instruction – OpenFlow instruction. Returns:True if a meter. Return type:bool

faucet.valve_of.is_meteradd(ofmsg)

Return True if OF message is a MeterMod and command is add.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a MeterMod add Return type:bool

faucet.valve_of.is_meterdel(ofmsg)

Return True if OF message is a MeterMod and command is delete.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a MeterMod delete Return type:bool

faucet.valve_of.is_metermod(ofmsg)

Return True if OF message is a MeterMod.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a MeterMod Return type:bool

faucet.valve_of.is_packetout(ofmsg)

Return True if OF message is a PacketOut

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a PacketOut Return type:bool

faucet.valve_of.is_set_field(action)

faucet.valve_of.is_table_features_req(ofmsg)

Return True if flow message is a TFM req.

Parameters:ofmsg – ryu.ofproto.ofproto_v1_3_parser message. Returns:True if is a TFM req. Return type:bool

faucet.valve_of.match(match_fields)

Return OpenFlow matches from dict.

Parameters:match_fields (dict) – match fields and values. Returns:matches. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPMatch

faucet.valve_of.match_from_dict(match_dict)

faucet.valve_of.metadata_goto_table(metadata, mask, table)

Return instructions to write metadata and goto table.

Parameters:

• metadata (int) – metadata to write to packet
• maks (int) – mask to apply to metadata
• table (ValveTable) – table to goto.

Returns:

list of OFPInstructions

faucet.valve_of.meteradd(meter_conf)

Add a meter based on YAML configuration.

faucet.valve_of.meterdel(datapath=None, meter_id=4294967295)

Delete a meter (default all meters).

faucet.valve_of.output_controller(max_len=128)

Return OpenFlow action to packet in to the controller.

Parameters:max_len (int) – max number of bytes from packet to output. Returns:packet in action. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPActionOutput

faucet.valve_of.output_in_port()

Return OpenFlow action to output out input port.

Returns:ryu.ofproto.ofproto_v1_3_parser.OFPActionOutput.

faucet.valve_of.output_port(port_num, max_len=0)

Return OpenFlow action to output to a port.

Parameters:

• port_num (int) – port to output to.
• max_len (int) – maximum length of packet to output (default no maximum).

Returns:

output to port action.

Return type:

ryu.ofproto.ofproto_v1_3_parser.OFPActionOutput

faucet.valve_of.packetout(port_num, data)

Return OpenFlow action to packet out to dataplane from controller.

Parameters:

• port_num (int) – port to output to.
• data (str) – raw packet to output.

Returns:

packet out action.

Return type:

ryu.ofproto.ofproto_v1_3_parser.OFPActionOutput

faucet.valve_of.packetouts(port_nums, data)

Return OpenFlow action to mulltiply packet out to dataplane from controller.

Parameters:

• port_num (list) – ints, ports to output to.
• data (str) – raw packet to output.

Returns:

packet out action.

Return type:

ryu.ofproto.ofproto_v1_3_parser.OFPActionOutput

faucet.valve_of.pop_vlan()

Return OpenFlow action to pop outermost Ethernet 802.1Q VLAN header.

Returns:Pop VLAN. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPActionPopVlan

faucet.valve_of.port_status_from_state(state)

Return True if OFPPS_LINK_DOWN is not set.

faucet.valve_of.push_vlan_act(table, vlan_vid, eth_type=33024)

Return OpenFlow action list to push Ethernet 802.1Q header with VLAN VID.

Parameters:vid (int) – VLAN VID Returns:actions to push 802.1Q header with VLAN VID set. Return type:list

faucet.valve_of.set_field(**kwds)

Return action to set any field.

Parameters:kwds (dict) – exactly one field to set Returns:set field action. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPActionSetField

faucet.valve_of.table_features(body)

faucet.valve_of.valve_flowreorder(input_ofmsgs, use_barriers=True)

Reorder flows for better OFA performance.

faucet.valve_of.valve_match_vid(value)

faucet.valve_of.vid_present(vid)

Return VLAN VID with VID_PRESENT flag set.

Parameters:vid (int) – VLAN VID Returns:VLAN VID with VID_PRESENT. Return type:int

faucet.valve_of_old module

Deprecated OF matches.

faucet.valve_packet module

Utility functions for parsing and building Ethernet packet/contents.

class faucet.valve_packet.PacketMeta(data, orig_len, pkt, eth_pkt, vlan_pkt, port, valve_vlan, eth_src, eth_dst, eth_type)

Bases: object

Original, and parsed Ethernet packet metadata.

ETH_TYPES_PARSERS = {2048: (4, <function ipv4_parseable>, <class 'ryu.lib.packet.ipv4.ipv4'>), 2054: (None, None, <class 'ryu.lib.packet.arp.arp'>), 34525: (6, None, <class 'ryu.lib.packet.ipv6.ipv6'>)}

MAX_ETH_TYPE_PKT_SIZE = {2048: 110, 2054: 64}

MIN_ETH_TYPE_PKT_SIZE = {2048: 38, 2054: 46, 34525: 58}

data

eth_dst

eth_pkt

eth_src

eth_type

ip_ver()

Return IP version number.

l3_dst

l3_pkt

l3_src

log()

orig_len

packet_complete()

True if we have the complete packet.

pkt

port

reparse(max_len)

Reparse packet using data up to the specified maximum length.

reparse_all()

Reparse packet with all available data.

reparse_ip(payload=0)

Reparse packet with specified IP header type and optionally payload.

vlan

vlan_pkt

faucet.valve_packet.arp_reply(vid, eth_src, eth_dst, src_ip, dst_ip)

Return an ARP reply packet.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – Ethernet source address.
• eth_dst (str) – destination Ethernet MAC address.
• src_ip (ipaddress.IPv4Address) – source IPv4 address.
• dst_ip (ipaddress.IPv4Address) – destination IPv4 address.

Returns:

serialized ARP reply packet.

Return type:

ryu.lib.packet.arp

faucet.valve_packet.arp_request(vid, eth_src, eth_dst, src_ip, dst_ip)

Return an ARP request packet.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – Ethernet source address.
• eth_dst (str) – Ethernet destination address.
• src_ip (ipaddress.IPv4Address) – source IPv4 address.
• dst_ip (ipaddress.IPv4Address) – requested IPv4 address.

Returns:

serialized ARP request packet.

Return type:

ryu.lib.packet.arp

faucet.valve_packet.build_pkt_header(vid, eth_src, eth_dst, dl_type)

Return an Ethernet packet header.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – source Ethernet MAC address.
• eth_dst (str) – destination Ethernet MAC address.
• dl_type (int) – EtherType.

Returns:

Ethernet packet with header.

Return type:

ryu.lib.packet.ethernet

faucet.valve_packet.echo_reply(vid, eth_src, eth_dst, src_ip, dst_ip, data)

Return an ICMP echo reply packet.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – Ethernet source address.
• eth_dst (str) – destination Ethernet MAC address.
• src_ip (ipaddress.IPv4Address) – source IPv4 address.
• dst_ip (ipaddress.IPv4Address) – destination IPv4 address.

Returns:

serialized ICMP echo reply packet.

Return type:

ryu.lib.packet.icmp

faucet.valve_packet.faucet_lldp_stack_state_tlvs(dp, port)

Return a LLDP TLV for state of a stack port.

faucet.valve_packet.faucet_lldp_tlvs(dp)

Return LLDP TLVs for a datapath.

faucet.valve_packet.faucet_oui(mac)

Return first 3 bytes of MAC address (given as str).

faucet.valve_packet.faucet_tlvs(lldp_pkt, faucet_dp_mac)

Return list of TLVs with FAUCET OUI.

faucet.valve_packet.icmpv6_echo_reply(vid, eth_src, eth_dst, src_ip, dst_ip, hop_limit, id_, seq, data)

Return IPv6 ICMP echo reply packet.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – source Ethernet MAC address.
• eth_dst (str) – destination Ethernet MAC address.
• src_ip (ipaddress.IPv6Address) – source IPv6 address.
• dst_ip (ipaddress.IPv6Address) – destination IPv6 address.
• hop_limit (int) – IPv6 hop limit.
• id (int) – identifier for echo reply.
• seq (int) – sequence number for echo reply.
• data (str) – payload for echo reply.

Returns:

Serialized IPv6 ICMP echo reply packet.

Return type:

ryu.lib.packet.ethernet

faucet.valve_packet.int_from_mac(mac)

faucet.valve_packet.int_in_mac(mac, to_int)

faucet.valve_packet.ipv4_parseable(ip_header_data)

Return True if an IPv4 packet we could parse.

faucet.valve_packet.ipv6_link_eth_mcast(dst_ip)

Return an Ethernet multicast address from an IPv6 address.

See RFC 2464 section 7.

Parameters:dst_ip (ipaddress.IPv6Address) – IPv6 address. Returns:Ethernet multicast address. Return type:str

faucet.valve_packet.ipv6_solicited_node_from_ucast(ucast)

Return IPv6 solicited node multicast address from IPv6 unicast address.

See RFC 3513 section 2.7.1.

Parameters:ucast (ipaddress.IPv6Address) – IPv6 unicast address. Returns:IPv6 solicited node multicast address. Return type:ipaddress.IPv6Address

faucet.valve_packet.lacp_reqreply(eth_src, actor_system, actor_key, actor_port, actor_state_synchronization=0, actor_state_activity=0, partner_system='00:00:00:00:00:00', partner_key=0, partner_port=0, partner_system_priority=0, partner_port_priority=0, partner_state_defaulted=0, partner_state_expired=0, partner_state_timeout=0, partner_state_collecting=0, partner_state_distributing=0, partner_state_aggregation=0, partner_state_synchronization=0, partner_state_activity=0)

Return a LACP frame.

Parameters:

• eth_src (str) – source Ethernet MAC address.
• actor_system (str) – actor system ID (MAC address)
• actor_key (int) – actor’s LACP key assigned to this port.
• actor_port (int) – actor port number.
• actor_state_synchronization (int) – 1 if we will use this link.
• actor_state_activity (int) – 1 if actively sending LACP.
• partner_system (str) – partner system ID (MAC address)
• partner_key (int) – partner’s LACP key assigned to this port.
• partner_port (int) – partner port number.
• partner_system_priority (int) – partner’s system priority.
• partner_port_priority (int) – partner’s port priority.
• partner_state_defaulted (int) – 1 if partner reverted to defaults.
• partner_state_expired (int) – 1 if partner thinks LACP expired.
• partner_state_timeout (int) – 1 if partner has short timeout.
• partner_state_collecting (int) – 1 if partner receiving on this link.
• partner_state_distributing (int) – 1 if partner transmitting on this link.
• partner_state_aggregation (int) – 1 if partner can aggregate this link.
• partner_state_synchronization (int) – 1 if partner will use this link.
• partner_state_activity (int) – 1 if partner actively sends LACP.

Returns:

Ethernet packet with header.

Return type:

ryu.lib.packet.ethernet

faucet.valve_packet.lldp_beacon(eth_src, chassis_id, port_id, ttl, org_tlvs=None, system_name=None, port_descr=None)

Return an LLDP frame suitable for a host/access port.

Parameters:

• eth_src (str) – source Ethernet MAC address.
• chassis_id (str) – Chassis ID.
• port_id (int) – port ID,
• TTL (int) – TTL for payload.
• org_tlvs (list) – list of tuples of (OUI, subtype, info).

Returns:

Ethernet packet with header.

Return type:

ryu.lib.packet.ethernet

faucet.valve_packet.mac_addr_is_unicast(mac_addr)

Returns True if mac_addr is a unicast Ethernet address.

Parameters:mac_addr (str) – MAC address. Returns:True if a unicast Ethernet address. Return type:bool

faucet.valve_packet.mac_byte_mask(mask_bytes=0)

Return a MAC address mask with n bytes masked out.

faucet.valve_packet.nd_advert(vid, eth_src, eth_dst, src_ip, dst_ip)

Return IPv6 neighbor avertisement packet.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – source Ethernet MAC address.
• eth_dst (str) – destination Ethernet MAC address.
• src_ip (ipaddress.IPv6Address) – source IPv6 address.
• dst_ip (ipaddress.IPv6Address) – destination IPv6 address.

Returns:

Serialized IPv6 neighbor discovery packet.

Return type:

ryu.lib.packet.ethernet

faucet.valve_packet.nd_request(vid, eth_src, eth_dst, src_ip, dst_ip)

Return IPv6 neighbor discovery request packet.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – source Ethernet MAC address.
• eth_dst (str) – Ethernet destination address.
• src_ip (ipaddress.IPv6Address) – source IPv6 address.
• dst_ip (ipaddress.IPv6Address) – requested IPv6 address.

Returns:

Serialized IPv6 neighbor discovery packet.

Return type:

ryu.lib.packet.ethernet

faucet.valve_packet.parse_eth_pkt(pkt)

Return parsed Ethernet packet.

Parameters:pkt (ryu.lib.packet.packet) – packet received from dataplane. Returns:Ethernet packet. Return type:ryu.lib.packet.ethernet

faucet.valve_packet.parse_faucet_lldp(lldp_pkt, faucet_dp_mac)

Parse and return FAUCET TLVs from LLDP packet.

faucet.valve_packet.parse_lacp_pkt(pkt)

Return parsed LACP packet.

Parameters:pkt (ryu.lib.packet.packet) – packet received from dataplane. Returns:LACP packet. Return type:ryu.lib.packet.lacp

faucet.valve_packet.parse_lldp(pkt)

Return parsed LLDP packet.

Parameters:pkt (ryu.lib.packet.packet) – packet received from dataplane. Returns:LLDP packet. Return type:ryu.lib.packet.lldp

faucet.valve_packet.parse_packet_in_pkt(data, max_len, eth_pkt=None, vlan_pkt=None)

Parse a packet received via packet in from the dataplane.

Parameters:

• data (bytearray) – packet data from dataplane.
• max_len (int) – max number of packet data bytes to parse.

Returns:

raw packet ryu.lib.packet.ethernet: parsed Ethernet packet. int: Ethernet type of packet (inside VLAN) int: VLAN VID (or None if no VLAN)

Return type:

ryu.lib.packet.packet

faucet.valve_packet.router_advert(vid, eth_src, eth_dst, src_ip, dst_ip, vips, pi_flags=6)

Return IPv6 ICMP Router Advert.

Parameters:

• vid (int or None) – VLAN VID to use (or None).
• eth_src (str) – source Ethernet MAC address.
• eth_dst (str) – dest Ethernet MAC address.
• src_ip (ipaddress.IPv6Address) – source IPv6 address.
• vips (list) – prefixes (ipaddress.IPv6Address) to advertise.
• pi_flags (int) – flags to set in prefix information field (default set A and L)

Returns:

Serialized IPv6 ICMP RA packet.

Return type:

ryu.lib.packet.ethernet

faucet.valve_packet.tlv_cast(tlvs, tlv_attr, cast_func)

Return cast’d attribute of first TLV or None.

faucet.valve_packet.tlvs_by_subtype(tlvs, subtype)

Return list of TLVs with matching type.

faucet.valve_packet.tlvs_by_type(tlvs, tlv_type)

Return list of TLVs with matching type.

faucet.valve_pipeline module

Manages movement of packets through the faucet pipeline.

class faucet.valve_pipeline.ValvePipeline(dp)

Bases: faucet.valve_manager_base.ValveManagerBase

Responsible for maintaing the integrity of the Faucet pipeline for a single valve.

Controls what packets a module sees in its tables and how it can pass packets through the pipeline.

Responsible for installing flows in the vlan, egress and classification tables

accept_to_l2_forwarding(actions=None)

Get instructions to forward packet through the pipeline to l2 forwarding. :param actions: (optional) list of actions to apply to packet.

Returns:list of instructions

filter_packets(_target_table, match_dict)

get a list of flow modification messages to filter packets from the pipeline. :param _target_table: the table requesting the filtering :param match_dict: a dictionary specifying the match fields

initialise_tables()

Install rules to initialise the classification_table

output(port, vlan)

Get instructions list to output a packet through the regular pipeline.

Parameters:

• port – Port object of port to output packet to
• vlan – Vlan object of vlan to output packet on

Returns:

list of Instructions

select_packets(target_table, match_dict, actions=None)

retrieve rules to redirect packets matching match_dict to table

faucet.valve_route module

Valve IPv4/IPv6 routing implementation.

class faucet.valve_route.AnonVLAN(vid)

Bases: object

class faucet.valve_route.NextHop(eth_src, port, now)

Bases: object

Describes a directly connected (at layer 2) nexthop.

age(now)

Return age of this nexthop.

cache_time

dead(max_fib_retries)

Return True if this nexthop is considered dead.

eth_src

last_retry_time

next_retry(now, max_resolve_backoff_time)

Increment state for next retry.

next_retry_time

port

resolution_due(now, max_age)

Return True if this nexthop is due to be re resolved/retried.

resolve_retries

class faucet.valve_route.ValveIPv4RouteManager(logger, global_vlan, neighbor_timeout, max_hosts_per_resolve_cycle, max_host_fib_retry_count, max_resolve_backoff_time, proactive_learn, dec_ttl, multi_out, fib_table, vip_table, pipeline, route_priority, routers)

Bases: faucet.valve_route.ValveRouteManager

Implement IPv4 RIB/FIB.

CONTROL_ETH_TYPES = (2048, 2054)

ETH_TYPE = 2048

ICMP_SIZE = 110

ICMP_TYPE = 1

IPV = 4

IP_PKT

alias of ryu.lib.packet.ipv4.ipv4

advertise(_vlan)

control_plane_handler(now, pkt_meta)

class faucet.valve_route.ValveIPv6RouteManager(logger, global_vlan, neighbor_timeout, max_hosts_per_resolve_cycle, max_host_fib_retry_count, max_resolve_backoff_time, proactive_learn, dec_ttl, multi_out, fib_table, vip_table, pipeline, route_priority, routers)

Bases: faucet.valve_route.ValveRouteManager

Implement IPv6 FIB.

CONTROL_ETH_TYPES = (34525,)

ETH_TYPE = 34525

ICMP_TYPE = 58

IPV = 6

IP_PKT

alias of ryu.lib.packet.ipv6.ipv6

advertise(vlan)

control_plane_handler(now, pkt_meta)

class faucet.valve_route.ValveRouteManager(logger, global_vlan, neighbor_timeout, max_hosts_per_resolve_cycle, max_host_fib_retry_count, max_resolve_backoff_time, proactive_learn, dec_ttl, multi_out, fib_table, vip_table, pipeline, route_priority, routers)

Bases: faucet.valve_manager_base.ValveManagerBase

Base class to implement RIB/FIB.

CONTROL_ETH_TYPES = ()

ETH_TYPE = None

ICMP_SIZE = 128

ICMP_TYPE = None

IPV = 0

IP_PKT = None

active

add_host_fib_route_from_pkt(now, pkt_meta)

Add a host FIB route given packet from host.

Parameters:

• now (float) – seconds since epoch.
• pkt_meta (PacketMeta) – received packet.

Returns:

OpenFlow messages.

Return type:

list

add_route(vlan, ip_gw, ip_dst)

Add a route to the RIB.

Parameters:

• vlan (vlan) – VLAN containing this RIB.
• ip_gw (ipaddress.ip_address) – IP address of nexthop.
• ip_dst (ipaddress.ip_network) – destination IP network.

Returns:

OpenFlow messages.

Return type:

list

add_vlan(vlan)

install flows in response to a new vlan

advertise(vlan)

control_plane_handler(now, pkt_meta)

dec_ttl

del_route(vlan, ip_dst)

Delete a route from the RIB.

Only one route with this exact destination is supported.

Parameters:

• vlan (vlan) – VLAN containing this RIB.
• ip_dst (ipaddress.ip_network) – destination IP network.

Returns:

OpenFlow messages.

Return type:

list

fib_table

global_routing

global_vlan

logger

max_host_fib_retry_count

max_hosts_per_resolve_cycle

max_resolve_backoff_time

multi_out

neighbor_timeout

nexthop_dead(nexthop_cache_entry)

pipeline

proactive_learn

resolve_expire_hosts(vlan, now, resolve_all=True)

Re/resolve hosts.

Parameters:

• vlan (vlan) – VLAN containing this RIB/FIB.
• now (float) – seconds since epoch.
• resolve_all (bool) – attempt to resolve all unresolved gateways.

Returns:

OpenFlow messages.

Return type:

list

resolve_gateways(vlan, now, resolve_all=True)

Re/resolve gateways.

Parameters:

• vlan (vlan) – VLAN containing this RIB/FIB.
• now (float) – seconds since epoch.
• resolve_all (bool) – attempt to resolve all unresolved gateways.

Returns:

OpenFlow messages.

Return type:

list

route_priority

routers

vip_table

faucet.valve_ryuapp module

RyuApp base class for FAUCET/Gauge.

class faucet.valve_ryuapp.EventReconfigure

Bases: ryu.controller.event.EventBase

Event sent to controller to cause config reload.

class faucet.valve_ryuapp.RyuAppBase(*args, **kwargs)

Bases: ryu.base.app_manager.RyuApp

RyuApp base class for FAUCET/Gauge.

OFP_VERSIONS = [4]

connect_or_disconnect_handler(ryu_event)

Handle connection or disconnection of a datapath.

Parameters:ryu_event (ryu.controller.dpset.EventDP) – trigger.

exc_logname = ''

get_setting(setting, path_eval=False)

Return config setting prefaced with logname.

logname = ''

reconnect_handler(ryu_event)

Handle reconnection of a datapath.

Parameters:ryu_event (ryu.controller.dpset.EventDPReconnected) – trigger.

reload_config(_ryu_event)

Handle reloading configuration.

signal_handler(sigid, _)

Handle signals.

Parameters:sigid (int) – signal received.

start()

Start controller.

faucet.valve_table module

Abstraction of an OF table.

class faucet.valve_table.ValveGroupEntry(table, group_id, buckets)

Bases: object

Abstraction for a single OpenFlow group entry.

add()

Return flows to add this entry to the group table.

delete()

Return flow to delete an existing group entry.

modify()

Return flow to modify an existing group entry.

update_buckets(buckets)

Update entry with new buckets.

class faucet.valve_table.ValveGroupTable

Bases: object

Wrap access to group table.

delete_all()

Delete all groups.

entries = None

get_entry(group_id, buckets)

Update entry with group_id with buckets, and return the entry.

static group_id_from_str(key_str)

Return a group ID based on a string key.

class faucet.valve_table.ValveTable(name, table_config, flow_cookie, notify_flow_removed=False, next_tables=None)

Bases: object

Wrapper for an OpenFlow table.

flowcontroller(match=None, priority=None, inst=None, max_len=96)

Add flow outputting to controller.

flowdel(match=None, priority=None, out_port=4294967295, strict=False)

Delete matching flows from a table.

flowdrop(match=None, priority=None, hard_timeout=0)

Add drop matching flow to a table.

flowmod(match=None, priority=None, inst=None, command=0, out_port=0, out_group=0, hard_timeout=0, idle_timeout=0, cookie=None)

Helper function to construct a flow mod message with cookie.

goto(next_table)

Add goto next table instruction.

goto_miss(next_table)

Add miss goto table instruction.

goto_this()

static match(in_port=None, vlan=None, eth_type=None, eth_src=None, eth_dst=None, eth_dst_mask=None, icmpv6_type=None, nw_proto=None, nw_dst=None, metadata=None, metadata_mask=None)

Compose an OpenFlow match rule.

set_field(**kwds)

Return set field action.

set_vlan_vid(vlan_vid)

Set VLAN VID with VID_PRESENT flag set.

Parameters:vid (int) – VLAN VID Returns:set VID with VID_PRESENT. Return type:ryu.ofproto.ofproto_v1_3_parser.OFPActionSetField

faucet.valve_util module

Utility functions for FAUCET.

faucet.valve_util.close_logger(logger)

Close all handlers on logger object.

faucet.valve_util.dpid_log(dpid)

Log a DP ID as hex/decimal.

faucet.valve_util.get_logger(logname, logfile, loglevel, propagate)

Create and return a logger object.

faucet.valve_util.get_setting(name, path_eval=False)

Returns value of specified configuration setting.

faucet.valve_util.get_sys_prefix()

Returns an additional prefix for log and configuration files when used in a virtual environment

faucet.valve_util.kill_on_exception(logname)

decorator to ensure functions will kill ryu when an unhandled exception occurs

faucet.valve_util.stat_config_files(config_hashes)

Return dict of a subset of stat attributes on config files.

faucet.valve_util.utf8_decode(msg_str)

Gracefully decode a possibly UTF-8 string.

faucet.valves_manager module

Manage a collection of Valves.

class faucet.valves_manager.ConfigWatcher

Bases: object

Watch config for file or content changes.

config_file = None

config_file_stats = None

config_hashes = None

content_changed(new_config_file)

Return True if config file content actually changed.

files_changed()

Return True if any config files changed.

update(new_config_file, new_config_hashes=None)

Update state with new config file/hashes.

class faucet.valves_manager.ValvesManager(logname, logger, metrics, notifier, bgp, dot1x, send_flows_to_dp_by_id)

Bases: object

Manage a collection of Valves.

load_configs(now, new_config_file, delete_dp=None)

Load/apply new config to all Valves.

new_valve(new_dp)

parse_configs(new_config_file)

Return parsed configs for Valves, or None.

request_reload_configs(now, new_config_file, delete_dp=None)

Process a request to load config changes.

update_metrics(now)

Update metrics in all Valves.

valve_flow_services(now, valve_service)

Call a method on all Valves and send any resulting flows.

valve_packet_in(now, valve, msg)

Time a call to Valve packet in handler.

valves = None

faucet.vlan module

VLAN configuration.

class faucet.vlan.AnyVLAN

Bases: object

Placeholder any tagged VLAN.

name = 'Any VLAN'

vid = 4096

class faucet.vlan.HostCacheEntry(eth_src, port, cache_time)

Bases: object

Association of a host with a port.

cache_time

eth_src

eth_src_int

port

class faucet.vlan.NullVLAN

Bases: object

Placeholder null VLAN.

name = 'Null VLAN'

vid = 0

class faucet.vlan.VLAN(_id, dp_id, conf=None)

Bases: faucet.conf.Conf

Contains state for one VLAN, including its configuration.

add_cache_host(eth_src, port, cache_time)

Add/update a host to the cache on a port at at time.

add_route(ip_dst, ip_gw)

Add an IP route.

all_ip_gws(ipv)

Return all IP gateways for specified IP version.

bgp_ipvs()

Return list of IP versions for BGP configured on this VLAN.

bgp_neighbor_addresses_by_ipv(ipv)

Return BGP neighbor addresses with specified IP version on this VLAN.

bgp_server_addresses_by_ipv(ipv)

Return BGP server addresses with specified IP version on this VLAN.

cached_host(eth_src)

Return host from cache or None.

cached_host_on_port(eth_src, port)

Return host cache entry if host in cache and on specified port.

cached_hosts_count_on_port(port)

Return count of all hosts learned on a port.

cached_hosts_on_port(port)

Return all hosts learned on a port.

check_config()

Check config at instantiation time for errors, typically via assert.

clear_cache_hosts_on_port(port)

Clear all hosts learned on a port.

defaults = {'acl_in': None, 'acls_in': None, 'bgp_as': None, 'bgp_connect_mode': 'passive', 'bgp_local_address': None, 'bgp_neighbor_addresses': [], 'bgp_neighbor_as': None, 'bgp_neighbour_addresses': [], 'bgp_neighbour_as': None, 'bgp_port': 9179, 'bgp_routerid': None, 'bgp_server_addresses': ['0.0.0.0', '::'], 'description': None, 'faucet_mac': '0e:00:00:00:00:01', 'faucet_vips': None, 'max_hosts': 256, 'minimum_ip_size_check': True, 'name': None, 'proactive_arp_limit': 0, 'proactive_nd_limit': 0, 'routes': None, 'targeted_gw_resolution': True, 'unicast_flood': True, 'vid': None}

defaults_types = {'acl_in': (<class 'int'>, <class 'str'>), 'acls_in': <class 'list'>, 'bgp_as': <class 'int'>, 'bgp_connect_mode': <class 'str'>, 'bgp_local_address': <class 'str'>, 'bgp_neighbor_addresses': <class 'list'>, 'bgp_neighbor_as': <class 'int'>, 'bgp_neighbour_addresses': <class 'list'>, 'bgp_neighbour_as': <class 'int'>, 'bgp_port': <class 'int'>, 'bgp_routerid': <class 'str'>, 'bgp_server_addresses': <class 'list'>, 'description': <class 'str'>, 'faucet_mac': <class 'str'>, 'faucet_vips': <class 'list'>, 'max_hosts': <class 'int'>, 'minimum_ip_size_check': <class 'bool'>, 'name': <class 'str'>, 'proactive_arp_limit': <class 'int'>, 'proactive_nd_limit': <class 'int'>, 'routes': <class 'list'>, 'targeted_gw_resolution': <class 'bool'>, 'unicast_flood': <class 'bool'>, 'vid': <class 'int'>}

del_route(ip_dst)

Delete an IP route.

exclude_same_lag_member_ports(in_port=None)

Ensure output on only one member of a LAG.

expire_cache_host(eth_src)

Expire a host from caches.

expire_cache_hosts(now, learn_timeout)

Expire stale host entries.

faucet_vips_by_ipv(ipv)

Return VIPs with specified IP version on this VLAN.

flood_pkt(packet_builder, multi_out=True, *args)

static flood_ports(configured_ports, exclude_unicast)

from_connected_to_vip(src_ip, dst_ip)

Return True if src_ip in connected network and dst_ip is a VIP.

Parameters:

• src_ip (ipaddress.ip_address) – source IP.
• dst_ip (ipaddress.ip_address) – destination IP

Returns:

True if local traffic for a VIP.

get_ports()

Return all ports on this VLAN.

hairpin_ports()

Return all ports with hairpin enabled.

hosts_count()

Return number of hosts learned on this VLAN.

ip_dsts_for_ip_gw(ip_gw)

Return list of IP destinations, for specified gateway.

ip_in_vip_subnet(ipa, faucet_vip=None)

Return faucet_vip if IP in same IP network as a VIP on this VLAN.

ipvs()

Return IP versions configured on this VLAN.

is_faucet_vip(ipa, faucet_vip=None)

Return True if IP is a VIP on this VLAN.

is_host_fib_route(host_ip)

Return True if IP destination is a host FIB route.

Parameters:host_ip – (ipaddress.ip_address): potential host FIB route. Returns:True if a host FIB route (and not used as a gateway).

lacp_ports()

Return ports that have LACP on this VLAN.

lacp_up_ports()

Return ports that have LACP up on this VLAN.

lags()

Return dict of LAGs mapped to member ports.

lags_up()

Return dict of LAGs mapped to member ports that have LACP up.

link_and_other_vips(ipv)

Return link local and non-link local VIPs.

mirrored_ports()

Return ports that are mirrored on this VLAN.

mutable_attrs = frozenset({'untagged', 'tagged'})

neigh_cache_by_ipv(ipv)

Return neighbor cache for specified IP version on this VLAN.

neigh_cache_count_by_ipv(ipv)

Return number of hosts in neighbor cache for specified IP version on this VLAN.

output_port(port, hairpin=False)

pkt_out_port(packet_builder, port, *args)

port_is_tagged(port)

Return True if port number is an tagged port on this VLAN.

port_is_untagged(port)

Return True if port number is an untagged port on this VLAN.

reset_caches()

Reset dynamic caches.

reset_ports(ports)

Reset tagged and untagged port lists.

route_count_by_ipv(ipv)

Return route table count for specified IP version on this VLAN.

routes_by_ipv(ipv)

Return route table for specified IP version on this VLAN.

set_defaults()

Set default values and run any basic sanity checks.

tagged_flood_ports(exclude_unicast)

to_conf()

Return configuration as a dict.

untagged_flood_ports(exclude_unicast)

static vid_valid(vid)

Return True if VID valid.

vip_map(ipa)

faucet.watcher module

Gauge watcher implementations.

class faucet.watcher.GaugeFlowTableLogger(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugeFlowTablePoller

Periodically dumps the current datapath flow table as a yaml object.

Includes a timestamp and a reference ($DATAPATHNAME-flowtables). The flow table is dumped as an OFFlowStatsReply message (in yaml format) that matches all flows.

optionally the output can be compressed by setting compressed: true in the config for this watcher

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.watcher.GaugePortStateLogger(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugePortStatePoller

Abstraction for port state logger.

static no_response()

Called when a polling cycle passes without receiving a response.

static send_req()

Send a stats request to a datapath.

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

class faucet.watcher.GaugePortStatsLogger(conf, logname, prom_client)

Bases: faucet.gauge_pollers.GaugePortStatsPoller

Abstraction for port statistics logger.

update(rcv_time, dp_id, msg)

Handle the responses to requests.

Called when a reply to a stats request sent by this object is received by the controller.

It should acknowledge the receipt by setting self.reply_pending to false.

Parameters:

• rcv_time – the time the response was received
• dp_id – DP ID
• msg – the stats reply message

faucet.watcher.watcher_factory(conf)

Return a Gauge object based on type.

Parameters:conf (GaugeConf) – object with the configuration for this valve.

faucet.watcher_conf module

Gauge watcher configuration.

class faucet.watcher_conf.WatcherConf(_id, dp_id, conf, prom_client)

Bases: faucet.conf.Conf

Stores the state and configuration to monitor a single stat.

Watcher Config

Watchers are configured in the watchers config block in the config for gauge.

The following elements can be configured for each watcher, at the level of /watchers/<watcher name>/:

• type (string): The type of watcher (IE what stat this watcher monitors). The types are ‘port_state’, ‘port_stats’ or ‘flow_table’.
• dps (list): A list of dps that should be monitored with this watcher.
• db (string): The db that will be used to store the data once it is retreived.
• interval (int): if this watcher requires polling the switch, it will monitor at this interval.

The config for a db should be created in the gauge config file under the dbs config block.

The following elements can be configured for each db, at the level of /dbs/<db name>/:

• type (string): the type of db. The available types are ‘text’ and ‘influx’ for port_state, ‘text’, ‘influx’and ‘prometheus’ for port_stats and ‘text’ and flow_table.

The following config elements then depend on the type. For text:

• file (string): the filename of the file to write output to.
• compress (bool): compress (with gzip) flow_table output while writing it

For influx:

• influx_db (str): The name of the influxdb database. Defaults to ‘faucet’.
• influx_host (str): The host where the influxdb is reachable. Defaults to ‘localhost’.
• influx_port (int): The port that the influxdb host will listen on. Defaults to 8086.
• influx_user (str): The username for accessing influxdb. Defaults to ‘’.
• influx_pwd (str): The password for accessing influxdb. Defaults to ‘’.
• influx_timeout (int): The timeout in seconds for connecting to influxdb. Defaults to 10.
• influx_retries (int): The number of times to retry connecting to influxdb after failure. Defaults to 3.

For Prometheus:

• prometheus_port (int): The port used to export prometheus data. Defaults to 9303.
• prometheus_addr (ip addr str): The address used to export prometheus data. Defaults to ‘127.0.0.1’.

add_db(db_conf)

Add database config to this watcher.

add_dp(dp)

Add a datapath to this watcher.

defaults = {'all_dps': False, 'compress': False, 'db': None, 'db_type': 'text', 'dbs': None, 'dps': None, 'file': None, 'influx_db': 'faucet', 'influx_host': 'localhost', 'influx_port': 8086, 'influx_pwd': '', 'influx_retries': 3, 'influx_timeout': 10, 'influx_user': '', 'interval': 30, 'name': None, 'prometheus_addr': '0.0.0.0', 'prometheus_port': 9303, 'prometheus_test_thread': False, 'type': None}

defaults_types = {'all_dps': <class 'bool'>, 'compress': <class 'bool'>, 'db': <class 'str'>, 'db_type': <class 'str'>, 'dbs': <class 'list'>, 'dps': <class 'list'>, 'file': <class 'str'>, 'influx_db': <class 'str'>, 'influx_host': <class 'str'>, 'influx_port': <class 'int'>, 'influx_pwd': <class 'str'>, 'influx_retries': <class 'int'>, 'influx_timeout': <class 'int'>, 'influx_user': <class 'str'>, 'interval': <class 'int'>, 'name': <class 'str'>, 'prometheus_addr': <class 'str'>, 'prometheus_port': <class 'int'>, 'prometheus_test_thread': <class 'bool'>, 'type': <class 'str'>}

Module contents