Host Configuration

The host configuration is a YAML file that resides on the ParaDrop device and controls many aspects of system functioning, particularly network and wireless device configuration. The host configuration may also appear in JSON format when manipulating it through the Local HTTP API or through the cloud controller. This page describes the structure and interpretation of values in the host configuration.

Host Configuration Object

Name Type Description Validations
firewall object Firewall settings that apply to all network interfaces.  
firewall.defaults object Refer to: firewall defaults object.  
lan object Configuration for LAN interfaces (wired and wireless).  
lan.dhcp object Refer to: dhcp object  
lan.firewall object Firewall settings for the LAN interfaces.  
lan.firewall.defaults object Refer to: firewall defaults object.  
lan.firewall.forwarding object Settings for packet forwarding.  
lan.interfaces[] array List of wired interfaces to include in the LAN bridge, e.g. eth1.  
lan.ipaddr string IP address to use on the LAN bridge.  
lan.netmask string Network mask for LAN.  
lan.proto string Method for setting interface IP address. ‘auto’ will choose a subnet that avoids conflict with the WAN interface.
  • It must be equal to one of the elements in [“auto”, “static”]
system object Configure Paradrop system behaviors.  
system.autoUpdate boolean Enable automatically updating system software packages.  
system.chutePrefixSize integer The IP network size to assign to each chute.
  • It must be lower than or equal to 32
  • It must be greater than or equal to 0
system.chuteSubnetPool string The IP range available for chutes in CIDR notation or ‘auto’. ‘auto’ will choose a subnet that avoids conflict with the WAN interface.  
system.onMissingWiFi string Behavior if expected wireless devices are missing on boot.
  • It must be equal to one of the elements in [“ignore”, “reboot”, “warn”]
telemetry object Configure telemetry function for collecting device measurements.  
telemetry.enabled boolean Enable sending device measurements to cloud controller.  
telemetry.interval integer Reporting interval (in seconds).
  • It must be greater than or equal to 1
vlan-interfaces[] array Configure handling of VLAN tags on wired interfaces.  
wan object Configuration for WAN interface.  
wan.firewall object Firewall settings for the WAN interface.  
wan.firewall.defaults object Refer to firewall defaults object.  
wan.interface string Name of interface to use for WAN.  
wan.proto string Method of acquiring interface IP address.
  • It must be equal to one of the elements in [“dhcp”]
wifi[] array List of physical Wi-Fi devices and their configuration.  
wifi-interfaces[] array List of virtual Wi-Fi interfaces and their configuration.  
zerotier object Configure ZeroTier service, which enables VPN-like functionality.  
zerotier.enabled boolean Enable the ZeroTier service.  
zerotier.networks[] array List of ZeroTier networks to join, using their string IDs.
  • Its elements must be unique

DHCP Object

Name Type Description Validations
leasetime string Duration of client leases, e.g. 2h  
limit integer Size of address range beginning at start value.
  • It must be greater than or equal to 1
start integer Starting offset for address assignment.
  • It must be greater than or equal to 0

Firewall Defaults Object

Name Type Description Validations
conntrack object    
forward string  
  • It must be equal to one of the elements in [“ACCEPT”, “REJECT”, “DROP”]
input string  
  • It must be equal to one of the elements in [“ACCEPT”, “REJECT”, “DROP”]
masq object    
masq_src[] array List of source addresses or subnets to which SNAT should be applied.
  • Its elements must be unique
output string  
  • It must be equal to one of the elements in [“ACCEPT”, “REJECT”, “DROP”]

Wi-Fi Device Object

Objects in the wifi array define physical device settings such as the channel and transmit power. These settings affect all interfaces in the “wifi-interfaces” array that use the corresponding device.

ParaDrop uses a deterministic system for identifying Wi-Fi devices, so that settings are applied to the same device on startup as long as there have been no hardware changes. ParaDrop numbers PCI and USB devices separately starting from zero, so a ParaDrop host with two PCI Wi-Fi cards and one USB card will have device IDs pci-wifi-0, pci-wifi-1, and usb-wifi-0.

The spectrum band is determined by the hwmode setting and the channel setting. They must be compatible. For 2.4 GHz channels (1-13), set hwmode to 11g. For 5 GHz channels (36-165), set hwmode to 11a.

Higher data rates and channel sizes (802.11n and 802.11ac) are configured with the htmode setting. For a 40 MHz channel width in 802.11n, set htmode=HT40 or htmode=HT40-. Plus means add the next higher channel, and minus means add the lower channel. For example, setting channel=36 and htmode=HT40+ results in using channels 36 and 40 as a 40 MHz channel.

If the hardware supports it, you can enable short guard interval for slightly higher data rates. There are separate settings for each channel width: short_gi_20, short_gi_40, and short_gi_80.

Name Type Description Validations
channel integer Wi-Fi channel number.
  • It must be lower than or equal to 165
  • It must be greater than or equal to 1
htmode string Enable 802.11n or 802.11ac modes.
  • It must be equal to one of the elements in [null, “HT20”, “HT40+”, “HT40-“, “VHT20”, “VHT40”, “VHT80”]
hwmode string Basic operating mode (11b for old hardware, 11g for 2.4 GHz, 11a for 5 GHz).
  • It must be equal to one of the elements in [“11b”, “11g”, “11a”]
id string Physical identifier, e.g. pci-wifi-1 or usb-wifi-0.  
rx_stbc integer Indicates support for receiving frames using STBC.
  • It must be lower than or equal to 1
  • It must be greater than or equal to 0
short_gi_20 boolean Enable short guard interval (higher data rates) in 20 MHz channels, must be supported by device.  
short_gi_40 boolean Enable short guard interval (higher data rates) in 40 MHz channel, must be supported by device.  
short_gi_80 boolean Enable short guard interval (higher data rates) in 80 MHz channel, must be supported by device.  
tx_stbc integer Indicates support for transmitting frames using STBC.
  • It must be lower than or equal to 1
  • It must be greater than or equal to 0

Wi-Fi Interface Object

Objects in the wifi-interfaces array configure virtual interfaces. Each virtual interface has an underlying physical device, but there can be multiple interfaces per device up to a limit determined by the hardware. Virtual interfaces can be configured as APs or in other operating modes (with limited support).

The encryption setting can take a number of different values. The most common options are: “none” for an open access point, “psk2” for WPA2 Personal (PSK), and “wpa2” for WPA2 Enterprise. WPA2 Enterprise requires additional configuration to interact with an external RADIUS server.

Name Type Description Validations
device string Physical device used by this interface, must match a device id in the wifi section.  
encryption string Type of wireless network security to use, e.g. none, psk2, wpa2 (Enterprise).  
mode string Operating mode for the interface.
  • It must be equal to one of the elements in [“airshark”, “ap”, “managed”, “monitor”]
network string Network name the interface should be attached to, typically lan for ap mode interfaces.  
ssid string ESSID for ap and managed mode interfaces.