Packaging snapshots for analysis
⚠️ This page is outdated. Please see new version ⚠️
Vendor- and file-specific instructions
Batfish expects configuration files to be organized according to a folder structure outlined below. The names in bold are keywords and must be used in your network. Your snapshot need not have all of these components, e.g., if you are not analyzing hosts or iptables configurations, the corresponding folders are not needed.
snapshot [top-level folder]
-
configs [folder with configurations for network devices]
- router1.cfg
- router2.cfg
- ....
-
hosts [folder with host configurations (e.g., pointers to their iptables files)]
- host1.json [see below for the expected format]
- host2.json
- ....
- iptables [folder with iptables configuration files; host JSON files should point to these files]
- host1.iptables
- host2.iptables
- ....
- aws_configs [AWS configuration, see below for expected format]
-
batfish [miscellaneous information (not network device configuration) used by Batfish]
- isp_config.json [configuration file used to model Internet Service Providers (ISPs), see below for expected format]
See the example snapshot in the repository as an example. For convenience, this folder contains some extra files that are not used by Batfish.
When you supply the snapshot as a zipped file, the top-level folder (called "snapshot" above) should be part of the zip archive.
F5 BIG-IP configuration spans multiple individual files. Follow the instructions here to properly package them for analysis.
Cumulus devices can be configured by editing individual files, such as /etc/network/interfaces, /etc/cumulus/ports.conf, and /etc/frr/frr.conf or invoking the Network Command-Line Utility (NCLU)
Batfish supports processing of either NCLU configuration output, or the Cumulus configuration files themselves (concatenated into one file per device). We recommend using the configuration files, because Batfish can extract more data from them than from the NCLU output.
Note about BGP Unnumbered: If you are using the BGP Unnumbered feature on Cumulus devices, you will need to supply a Layer1 topology file.
Batfish processes the cumulus configuration files /etc/network/interfaces, /etc/cumulus/ports.conf, and /etc/frr/frr.conf concatenated into a single file per device. The format is as follows:
- hostname (single line)
- Contents of
/etc/network/interfacesfile - Contents of
/etc/cumulus/ports.conffile - Contents of
/etc/frr/frr.conffile
Batfish detects the boundary between each the concatenated files by looking for comments or declarations that typically occur at the start of each file. To ensure they are present for Batfish to find, we recommend adding them in case they are missing. Here's an example bash snippet:
hostname=$(cat /etc/hostname)
(
# hostname
echo $hostname
# Signal start of /etc/network/interfaces
echo "# This file describes the network interfaces"
cat /etc/network/interfaces
# Signal start of /etc/cumulus/ports.conf
echo "# ports.conf --"
cat /etc/cumulus/ports.conf
# Signal start of /etc/frr/frr.conf
echo "frr version"
cat /etc/frr/frr.conf
) > $hostname.cfg
To retrieve the Cumulus configuration in the NCLU format, issue net show config commands and save the output to a file.
Batfish supports Palo Alto Networks devices with or without Panorama. For each device, concatenate the following show commands into one file.
set cli config-output-format set
set cli pager off
show config pushed-shared-policy
show config pushed-shared-policy vsys <value> // run for each vsys
show config merged
The first two commands may not be available on all PAN-OS versions; just make sure that the output is NOT in XML format (first command) and that definitions are not truncated (second command).
The host JSON files contain basic information about the hosts attached to the network, including their names, a pointer to their iptables configuration file, and their interfaces. An example file is:
{
"hostname" : "host1",
"iptablesFile" : "iptables/host1.iptables",
"hostInterfaces" : {
"eth0" : {
"name": "eth0",
"prefix" : "2.128.0.101/24",
"gateway": "2.128.0.1"
}
}
}iptables/host1.iptables is the path relative to the snapshot where this host's iptables configuration can be found. iptables configuration files should be in the format that is generated by iptables-save.
Batfish understands AWS VPC configurations and analyzes it just like physical networks. To use this functionality, place AWS configs in a top-level folder called aws_configs. The subfolders in this folder correspond to individual regions. If there is only one region, then this level of hierarchy may be skipped.
The configuration files for a region should be the JSON output of the following API calls:
- For EC2:
describe_addresses,describe_availability_zones,describe_customer_gateways,describe_internet_gateways,describe_network_acls,describe_network_interfaces,describe_instances,describe_route_tables,describe_security_groups,describe_subnets,describe_vpc_endpoints,describe_vpcs,describe_vpn_connections,describe_vpn_gateways - For ES:
describe_elasticsearch_domains - For RDS:
describe_db_instances
This output can be collected using the AWS CLI or using the boto3 Python SDK.
An example script that packages AWS data into a Batfish snapshot is here.
An example snapshot, which includes both physical and AWS configs, is here. It is OK to have only AWS configs in a snapshot.
Normally Batfish infers layer-3 interface adjacencies based on IP address configuration on interfaces.
For instance, if there are two interfaces in the network with IP assignments 192.168.1.1/24 and 192.128.1.2/24 respectively, Batfish will infer that these interfaces are adjacent.
However, you may override this behavior by supplying a layer-1 topology file. In this case, layer-3 adjacencies are computed by combining the supplied layer-1 adjacencies with layer-2 and layer-3 configuration to get a more accurate model. This is especially useful if IP addresses are reused across the network on interfaces that are not actually adjacent in practice.
Batfish can take the topology file in JSON format:
The expected JSON file has a list of edge records, where each edge record has node and interface names of the two ends. An example file is:
{
"edges": [
{
"node1": {
"hostname": "as1border1",
"interfaceName": "GigabitEthernet0/0"
},
"node2": {
"hostname": "as1core1",
"interfaceName": "GigabitEthernet1/0"
}
},
{
"node1": {
"hostname": "as1border1",
"interfaceName": "GigabitEthernet1/0"
},
"node2": {
"hostname": "as2border1",
"interfaceName": "GigabitEthernet0/0"
}
}
]
}Your file name should be called layer1_topology.json for it to be considered by Batfish.
Batfish can model routers representing ISPs (and Internet) for a given network. The modeling is based on a json configuration file (isp_config.json), which tells Batfish about the interfaces on border routers which peer with the ISPs. An example file is:
{
"borderInterfaces": [
{
"borderInterface": {
"hostname": "as2border1",
"interface": "GigabitEthernet3/0"
}
}, {
"borderInterface": {
"hostname": "as2border2",
"interface": "GigabitEthernet3/0"
}
}
],
"filter": {
"onlyRemoteAsns": [],
"onlyRemoteIps": []
}
}Here borderInterfaces contains the list of interfaces on border routers which are meant to peer with the ISPs. onlyRemoteAsns (list of ASNs) and onlyRemoteIps (list of IPs) provide a way to apply additional filter by restricting to ISPs having specific ASNs or IPs.
Batfish will not try to model any ISP routers in the absence of this configuration file.
An example network with ISP modeling configuration is here.