From 16aaa384c05e7f001646b39dea7551b343e89c4a Mon Sep 17 00:00:00 2001 From: Ffhener Date: Wed, 13 Dec 2023 15:45:03 +0100 Subject: [PATCH] DEVELOPER.md: Rewrite for locations/ Rewrite of the file to account for the new standard of using single file locations. Added wireless profiles and some other smaller hints as well. It would make sense to write better docs for the profiles in the future. --- DEVELOPER.md | 299 +++++++++++++++++++++++++++------------------------ 1 file changed, 161 insertions(+), 138 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 8d06695ed..e74f4350b 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -4,70 +4,38 @@ This guide explains the directory structure of the project and variables within ## locations/ -`locations/` holds a single file format for locations as an alternative to the old way of using `groups_vars/` and `host_vars/`. Instead everything is simply written into a single file named `$LOCATIONNAME.yml`. +`locations/` holds all the location specific configuration. To create a new location add a new file named `$LOCATIONNAME.yml`. The name should only contain `a-z`, `0-9` and `-`. -## group_vars/ +As this format is new there are still some old locationdata you can find at `groups_vars/` and `host_vars/`. These old configurations work the same way exept being spilt into different files. For new locations only use `locations/`. -`group_vars/` holds tree types of resources: the `all/`-directory, location directories and model files. +There are default values defined in `group_vars/all/`. You can override the variables by redefining them in the `$LOCATIONNAME.yml`. -### all/ - -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. +The following chapters describes the individual parts of the configuration file. -There are also files for the standard ssh keys and definitions for the Wi-Fi profiles. +### location name -### model_files - -These files define how bbb-configs needs to handle different hardware models. This example shows a WDR4900: +This name has to be consistent with the filename and the prefix for individual devices. ```yml --- -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: [1, 2, 3, 4] # 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 - band: 5g - htmode_prefix: VHT - path: ffe09000.pcie/pci9000:00/9000:00:00.0/9000:01:00.0 - ifname_hint: wlan5 - - name: 11g_standard # 2.4GHz radio - band: 2g - htmode_prefix: VHT - path: ffe0a000.pcie/pcia000:02/a000:02:00.0/a000:03:00.0 - ifname_hint: wlan2 +location: magda # a string with the name of the location ``` +### general infos -Possible values for band are 2g for 2.4 GHz, 5g for 5 GHz, 6g for 6 GHz and 60g for 60 GHz. -Band replaces hwmode since 21.02.2. - -Possible values for htmode_prefix are HT (802.11n), VHT (802.11ac) and HE (802.11ax). -The htmode_prefix setting corresponds with the htmode option. - -For a model using DSA instead of swconfig, you may refer to [`model_ubnt_edgerouter_x_sfp.yml`](https://github.com/freifunk-berlin/bbb-configs/blob/master/group_vars/model_ubnt_edgerouter_x_sfp.yml) +This part defines general values that are used e.g. in [Hopglass](https://hopglass.berlin.freifunk.net) and [OpenWifiMap](https://openwifimap.net). -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. - -### location-directories - -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. +```yml +location_nice: roof top, Example-Street 24, 10573 Berlin # any string that describes your location. It should contain an address. +latitude: 52.484948320 +longitude: 13.443380903 +``` -#### general.yml +### contact details -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](https://config.berlin.freifunk.net)_. +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](https://config.berlin.freifunk.net). Locations maintained by the entire community can use `community: true` instead. This will set default community values. ```yml ---- contact_name: 'Petrosilius Quaccus' contact_nickname: 'Petro' # contacts must be a list. Even if only one contact is given @@ -75,25 +43,72 @@ contacts: - 'quaccus@example.com' - 'https://config.berlin.freifunk.net/contact/446x/ImZmZnctZV0LTA0Ig.FFbQ8w._ZCA4hFY3zR8MdDVNrv3okqwPU' ``` +### hosts -#### owm.yml +This section describes every OpenWrt-device. -This file defines some values to get the location to the [OpenWifiMap](https://openwifimap.net). +```yml +hosts: + - hostname: magda-core # the name of the device. The location-part of the name must match `location:` defined above + role: corerouter # devices role. Could either be 'corerouter', 'ap' or '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 default only APs have activated wifi. +``` + +Some devices use POE-Ports. To enable them, just give the parameter `poe_on` and the port. For example: ```yml ---- -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.443380903 + poe_on: [0] ``` -#### networks.yml +Multiple ports can be specified as a list: -This 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: +```yml + poe_on: [0,1,2,3] +``` +### monitoring + +All OpenWrt-devices have monitoring enabled. To activate monitoring for other devices we use SNMP. The core router will collect and report statistics for the devices. Make shure SNMP is activated on the properitary device. You can find an overview with all available profiles at `group_vars/all/snmp_profiles.yml` + +```yml +snmp_devices: + - hostname: segen-f2a # hostname + address: 10.31.6.11 # static ip of the device + snmp_profile: airos_8 # SNMP profile + + - hostname: segen-test + address: 10.31.6.12 + snmp_profile: af60 + + - hostname: segen-sw + address: 10.31.6.13 + snmp_profile: airos_6 +``` + +### airos dfs reset + +This section 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. + +```yml +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" +``` + +### network + +This part defines IP-Addresses, WIFI-Properties, Mesh and so on. Lets have a (shortened) example of a `networks.yml` from the magda-location: ```yml ---- # mesh: 10.31.83.60/30 # add a overview of all reserved adresses at the top as a comment # dhcp: 10.31.83.192/26 @@ -104,10 +119,12 @@ ipv6_prefix: "2001:bf7:860::/56" networks: - vid: 10 # vlan-id role: mesh # what this vlan does (mesh vs. dhcp) - name: mesh_sama + name: mesh_sama # the name has a 12 characters limit. It should only contain lower letters and underscores ptp: true # changing the mode from mesh to ether for reducing the airtraffic for point to point connections by ignoring the hidden node problem prefix: 10.31.83.60/32 # single ipv4-address for meshing - ipv6_subprefix: -1 # take an address from the back of the IPv6-block + ipv6_subprefix: -10 # take an address from the back of the IPv6-block. Best practise is to use the same value as the vlan-id to avoid duplicate adresses. + mesh_metric_lqm: ['default 0.8'] # link quality multiplier is used to artificially make routes worse, so certain links are preferred. Must be higher then 0.2, otherwise link wont work. + untagged: true # untags the vlan. It is commenly used for tunnel-uplinks - vid: 11 role: mesh @@ -115,6 +132,13 @@ networks: prefix: 10.31.83.61/32 ipv6_subprefix: -2 + - 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 + - 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 @@ -132,13 +156,6 @@ networks: 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 @@ -146,7 +163,7 @@ location__channel_assignments_11a_standard__to_merge: magda-ap3: 44-20-15 ``` -The VLAN ID (vid) usually follow this numbering convention. +The VLAN ID (vid) usually follow this numbering convention. They should be sorted in ascending order in the file. ```yml 10+ for airmax & co mesh links @@ -156,12 +173,16 @@ The VLAN ID (vid) usually follow this numbering convention. 50 Wireguardtunnel ``` -##### uplink via tunnel +### uplink via tunnel +A local uplink over a "normal" internet connection can be added. All the traffic will be routed through a Wireguard-VPN-Tunnel. The lo 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 you can add one or more tunnel networks: ```yml + - vid: 50 + role: uplink + - role: tunnel ifname: ts_wg0 mtu: 1280 @@ -186,111 +207,113 @@ for uplinks that should only act as backup connection. If you have multiple uplinks and want one to be prefered, set different link metrics for the different uplinks. -#### ssh-key.yml and ssh-keys.yml +### ssh-keys -By 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: +By default the ssh-keys within `all/ssh-keys.yml` will be installed on all hosts. To add additional ssh keys use this format: ```yml ---- location__ssh_keys__to_merge: - comment: John key: ssh-ed25519 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Keyname ``` -If you do not want the ssh-keys within `all/ssh-keys.yml` installed, you can create a `ssh-keys.yml` file that replaces -the default file: +If you do not want the ssh-keys within `all/ssh-keys.yml` installed, you can use this way to override the default keys: ```yml ---- ssh_keys: - comment: John key: ssh-ed25519 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX Keyname ``` +### wireless profiles -#### snmp.yml + -The file holds information about SNMP enabled devices and the corresponding SNMP profiles. The core router will collect -and report statistics for the devices. +An individual wireless profile can be added to your location. A common use case is a private SSID. ```yml ---- -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_6 +location__wireless_profiles__to_merge: + + - name: foobar + devices: + - radio: 11a_standard + legacy_rates: false + country: DE + - radio: 11g_standard + legacy_rates: false + country: DE + + ifaces: + - mode: ap + ssid: berlin.freifunk.net + encryption: none + network: dhcp + radio: [11a_standard, 11g_standard] + ifname_hint: ff + + - mode: ap + ssid: berlin.freifunk.net Encrypted + encryption: owe + network: dhcp + radio: [11a_standard, 11g_standard] + ifname_hint: ffowe + ieee80211w: 1 + + - mode: ap + ssid: Private Wifi + encryption: psk2 + key: 'file:/root/wifi_pass' + network: prdhcp + radio: [11a_standard, 11g_standard] + ifname_hint: prdhcp ``` -#### airos_dfs_reset.yml - -The 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. - -```yml ---- +## groups_vars/ -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" -``` - -## host_vars/ +### all/ -The `host-vars`-dir contains a host directory for every OpenWrt-device. +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. -### host-directories +There are also files for the standard ssh keys and definitions for the Wi-Fi profiles. -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`. +### model_files -#### base.yml +These files define how bbb-configs needs to handle different hardware models. This example shows a WDR4900: ```yml --- +target: "ipq40xx/generic" # target of router model -location: sama # locations short name, like defined in location-directories -role: corerouter # devices role. Could either be 'corerouter', 'ap' or 'gateway' -model: "avm_fritzbox-7530" # model name like written in the corresponding file name in group_vars/ +switch_ports: 6 # number of physical ports + one (CPU) +switch_int_port: 0 # port-id of the CPU +switch_ignore_ports: [1, 2, 3, 4] # omit ports, that exist in software but not in hardware (i.e. MikroTik SXTsq 5ac) -wireless_profile: freifunk_default # activates wifi with freifunk-default-settings on this device by overriding default wireless profile for corerouters, which is the profile disable -``` +int_port: eth0 # hardware-device on which swconfig works on -Some devices use POE-Ports. To enable them, just give the parameter `poe_on` and the port. For example: +wireless_devices: # definitions for the devices radios + - name: 11a_standard # 5GHz radio + band: 5g + htmode_prefix: VHT + path: ffe09000.pcie/pci9000:00/9000:00:00.0/9000:01:00.0 + ifname_hint: wlan5 + - name: 11g_standard # 2.4GHz radio + band: 2g + htmode_prefix: VHT + path: ffe0a000.pcie/pcia000:02/a000:02:00.0/a000:03:00.0 + ifname_hint: wlan2 +``` -```yml ---- +Possible values for band are 2g for 2.4 GHz, 5g for 5 GHz, 6g for 6 GHz and 60g for 60 GHz. +Band replaces hwmode since 21.02.2. -location: koepi -role: ap -target: "ath79/generic" -model: "ubnt_nanostation-m5_xm" +Possible values for htmode_prefix are HT (802.11n), VHT (802.11ac) and HE (802.11ax). +The htmode_prefix setting corresponds with the htmode option. -poe_on: [0] -``` +For a model using DSA instead of swconfig, you may refer to [`model_ubnt_edgerouter_x_sfp.yml`](https://github.com/freifunk-berlin/bbb-configs/blob/master/group_vars/model_ubnt_edgerouter_x_sfp.yml) -Multiple ports can be specified as a list: +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. -```yml -poe_on: [0,1,2,3] -``` ## inventory/