This guide explains the directory structure of the project and variables within the config files.
group_vars/ holds tree types of resources: the all/-directory, location directories and model files.
This directory holds base configuration options that will be inserted into every router configuration. Each device will get this options, like timezones, DNS-servers, the packagefeed-URL and so on.
There are also files for the standard ssh keys and definitions for the wifi profiles.
These files define how bbb-configs needs to handle different hardware models. This example shows a WDR4900:
---
target: "ipq40xx/generic" # target of router model
switch_ports: 6 # number of physical ports + one (CPU)
switch_int_port: 0 # port-id of the CPU
switch_ignore_ports: [] # omit ports, that exist in software but not in hardware (i.e. MikroTik SXTsq 5ac)
int_port: eth0 # hardware-device on which swconfig works on
wireless_devices: # definitions for the devices radios
- name: 11a_standard # 5GHz radio
hwmode: 11a
path: ffe09000.pcie/pci9000:00/9000:00:00.0/9000:01:00.0
ifname_hint: wlan5
- name: 11g_standard # 2.4GHz radio
hwmode: 11g
path: ffe0a000.pcie/pcia000:02/a000:02:00.0/a000:03:00.0
ifname_hint: wlan2For a model using DSA instead of swconfig, you may refer to model_ubnt_edgerouter_x_sfp.yml
Note: If you want to create a new model_file you can have a look at /etc/config/wireless on a standard OpenWRT install to obtain the path information for the wireless_devices.
When defining a new location, you need to create a directory named like location_$NAME/. In that directory goes the location specific configuration. It consists of several files. You can override the variables defined from the all directory by creating a file named like that one in all/ and redefine any variable.
This file might be fairly self-explanatory. Please mind that a contact is mandatory. If you don't like to give your email address, you can use the link to the contact form, that you've got from config.berlin.freifunk.net.
---
contact_name: 'Petrosilius Quaccus'
contact_nickname: 'Petro'
contact_email: '[email protected]'
# or:
contact_email: 'https://config.berlin.freifunk.net/contact/446x/ImZmZnctZV0LTA0Ig.FFbQ8w._ZCA4hFY3zR8MdDVNrv3okqwPU'This file defines some values to get the location to the OpenWifiMap.
---
location_nice: roof top, Example-Street 24, 10573 Berlin # any string that describes your location. Could be an address or something
latitude: 52.484948320
longitude: 13.443380903This file is the most important one of your setup. It defines IP-Addresses, WIFI-Properties, Mesh and so on. Lets have a (shortened) example of a networks.yml from the magda-location:
---
ipv6_prefix: "2001:bf7:860::/56"
# Mesh: 10.31.83.60/30
networks:
- vid: 10 # vlan-id
role: mesh # what this vlan does (mesh vs. dhcp)
name: mesh_sama
prefix: 10.31.83.60/32 # single ipv4-address for meshing
ipv6_subprefix: -1 # take an address from the back of the IPv6-block
- vid: 11
role: mesh
name: mesh_ost
prefix: 10.31.83.61/32
ipv6_subprefix: -2
- vid: 42
role: mgmt # create a management vlan in which we can reach every device on this site for maintenance
prefix: 10.31.83.112/28
gateway: 1
dns: 1
ipv6_subprefix: 1
assignments: # assign static(!) addresses from mngt-network to individual devices/interfaces.
magda-core: 1 # core router gets 1st address. In result it will be reachable at 10.31.83.113
magda-switch: 2 # 10.31.83.114 ...
magda-sama: 3 # interface for mesh link to sama def'd at vid-10 (see above) gets 3rd address (for mngt only)
magda-ost-5ghz: 4 # mesh link on vid-11
magda-ap1: 5
magda-ap2: 6
magda-ap3: 7
magda-ap4: 8
- vid: 40
role: dhcp # dhcp server will run on core-router and serve it's network on vid 40
prefix: 10.31.83.192/26
ipv6_subprefix: 0
assignments: # assign static addresses to devices
magda-core: 1
location__channel_assignments_11a_standard__to_merge:
# AP-id, wifi-channel, bandwidth, txpower
magda-ap1: 36-20-15
magda-ap2: 40-20-15
magda-ap3: 44-20-15The VLAN ID (vid) usually follow this numbering convention.
10+ for airmax & co mesh links
20+ for 11s
40+ DHCP Clients
42 MGMT
if for some reason you are in need of an uplink via a "normal" internet connection, a wireguard tunnel can be an easy and safe solution. in that case add another vlan to the networks.yml
- vid: 13
untagged: true # option to don't tag this vlan - useful if the corerouter is plugged into a normal home router
name: uplink
role: ext
tunnel_wan_ip: 192.168.1.2/24 # put here the address and subnet of the corerouter inside the uplink network
tunnel_wan_gw: 192.168.1.1 # gateway of the uplink network
tunnel_connections: 2 # default value, number of different tunnels to create
tunnel_timeout: 600 # timeout in seconds after this the tunnel is destroyed and attempted to be rebuild
tunnel_mesh_prefix_ipv4: 10.31.142.120/30 # ip subnet to pick addresses for the endpoints of the tunnelsBy default the ssh-keys within all/ssh-keys.yml will be installed on all hosts. To add additional ssh keys a ssh-key.yml file can be created with additional keys in the following format:
---
location__ssh_keys__to_merge:
- comment: John
key: ssh-ed25519 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX KeynameThe file holds information about SNMP enabled devices and the corresponding SNMP profiles. The core router will collect and report statistics for the devices.
---
snmp_devices:
- hostname: segen-f2a # hostname
address: 10.31.6.11 # static ip of the device
snmp_profile: airos_8 # SNMP profile
- hostname: segen-mabb
address: 10.31.6.12
snmp_profile: airos_8
- hostname: segen-sw
address: 10.31.6.13
snmp_profile: airos_6The file holds information about airos devices and how to access them. The information is used to initiate a DFS reset within a specific time window after a DFS event was detected.
---
airos_dfs_reset:
- name: "segen-f2a" # name of the device
target: "10.31.6.11" # static ip of the device
username: "ubnt" # root username
password: "file:/root/pwd" # location to a password file within the core-router
daytime_limit: "2-7" # time window for DFS reset
- name: "segen-mabb"
target: "10.31.6.12"
username: "ubnt"
password: "file:/root/pwd"
daytime_limit: "2-7"The host-vars-dir contains a host directory for every OpenWrt-device.
When defining a new device within a location, you need to create a directory named like example-core/. The directory-name is the routers hostname. In that directory goes the device specific configuration. It consists of only one file, called base.yml.
---
location: sama # locations short name, like defined in location-directories
role: corerouter # devices role. Could either be 'corerouter', 'ap' or 'uplink_gateway'
model: "avm_fritzbox-7530" # model name like written in the corresponding file name in group_vars/
wireless_profile: freifunk_default # activates wifi with freifunk-default-settings on this device by overriding default wireless profile for corerouters, which is the profile disableSome devices use POE-Ports. To enable them, just give the parameter poe_on and the port. For example:
---
location: koepi
role: ap
target: "ath79/generic"
model: "ubnt_nanostation-m5_xm"
poe_on: [0]Multiple ports can be specified as a list:
poe_on: [0,1,2,3]This is an internal diretory on which you don't need to care about now. If you like to learn mor on it, you might read the README.md file inside of it.
This directory contains magical ansible-stuff. Unless you want to develop for this system you can safely ignore this.