[RFC] docs/site-example: add minimal domain config

[kb-light]

depends on #1216

[christf]

... will not work as is... there is a typo in there.

How about: This is not a complete working example. You are required to make community-specific changes to it to make it work.

[kb-light]

This is copied from the current site.conf example, if there is a typo, we should fix that in the current example and I will update this PR accordingly.

[mweinelt]

as is

is the correct ending to that sentence. Why not update it in this PR, it's just a typo.

[rotanid]

i fixed it in the current example now, so you can change it in your PR, too.

[mweinelt]

As nodes expose both a site_code and a domain_code the filename ffxx-def sounds like site ffxx and domain def, while the domain_code should probably be just defor default.

[neocturne]

This will need to be updated with the changes mentioned in #1216 (comment) ; in addition the the example, the list of supported site config options must be extended with information which options are valid in what config files.

A more high-level explanation of the multi-domain feature would also be nice.

[neocturne]

@mweinelt I think for single-domain setups, making the site code and domain code equal makes sense. The pretty name of the domain will be displayed on the status page, so it's preferable not to use something like "Default" there.

[lemoer]

allowed in both site and domain config

• autoupdater.branches
• autoupdater.branches.*.mirrors
• wifi*
• wifi*.channel
• wifi*.basic_rate
• wifi*.ap
• wifi*.ap.disabled
• wifi*.ibss
• wifi*.ibss.mcast_rate
• wifi*.ibss.vlan
• wifi*.ibss.disabled
• wifi*.mesh
• wifi*.mcast_rate
• wifi*.disabled
• opkg
• opkg.lede
• opkg.extra
• opkg.extra.*
• ntp_servers
• dns
• dns.cacheentries
• dns.servers
• nextnode
• mesh
• mesh.batman_adv
• mesh.batman_adv.gw_sel
• mesh.batman_adv.routing_algo
• mesh_vpn.enabled
• mesh_vpn.mtu
• mesh_vpn.fastd.methods
• mesh_vpn.fastd.groups
• mesh_vpn.fastd.groups.*.limit
• mesh_vpn.fastd.groups.*.groups
• mesh_vpn.fastd.groups.*.peers
• mesh_vpn.fastd.groups.*.peers.remotes
• mesh_vpn.tunneldigger.brokers

allowed in site only

• authorized_keys
• autoupdater.branch
• autoupdater.branches.*.name
• autoupdater.branches.*.good_signatures
• autoupdater.branches.*.pubkeys
• config_mode
• config_mode.owner
• config_mode.owner.obligatory
• config_mode.remote_login
• config_mode.geo_location
• config_mode.geo_location.show_altitude
• config_mode.remote_login.show_password_form
• config_mode.remote_login.min_password_length
• site_code
• site_name
• site_seed
• hostname_prefix
• timezone
• regdom
• wifi*.ibss.supported_basic_rates
• poe_passthrough
• wifi*.mesh.supported_basic_rates
• mesh_on_wan
• mesh_on_lan
• single_as_lan
• mesh_vpn.fastd.configurable
• mesh_vpn.fastd.syslog_level
• roles.default
• roles.list
• setup_mode.skip
• mesh_vpn.bandwidth_limit (only applied at first boot)
• mesh_vpn.bandwidth_limit.enabled
• mesh_vpn.bandwidth_limit.ingress
• mesh_vpn.bandwidth_limit.egress

allowed in domain only

• next_node.mac
• next_node.ip4
• next_node.ip6
• prefix4
• prefix6
• wifi*.ap.ssid (clients could roam between domains otherwise)
• wifi*.ibss.ssid
• wifi*.ibss.bssid
• wifi*.mesh.id
• extra_prefixes6
• mesh_vpn.fastd.groups.*.peers.key (an attacker with control over the packet flow could make nodes connect to the wrong instance)

[lemoer]

Here is the updated list of allowed places for config options. I'm not sure, how we should add them to the documentation? As a tags "domain config", "site config" per section in the explanation in the "site configuration" page? As the documentation is splitted into sections e.g. mesh_vpn, we cant simply add tags to the whole section, because mesh_vpn.fastd.groups.*.peers.key is allowed in domain only and mesh_vpn.fastd.groups.*.peers is allowed in both site and domain config.

[kb-light]

@lemoer some updates for your list according to current gluon master:
allowed in both site and domain config:
- wifi*.mcast_rate
+ wifi*.mesh.mcast_rate
- mesh_vpn.enabled
- mesh_vpn.fastd.groups.*.peers.remotes

allowed in site only:
- site_seed
+ mesh_vpn.enabled

allowed in domain only:
+ domain_name
+ domain_seed
+ mesh_vpn.fastd.groups.*.peers.remotes

[neocturne]

docs/user/site.rst will need to be updated with

• An explanatory text at the top
• An annotation "site only"/"domain only" in the list of options (or in the text, if restrictions apply only to individual options)

I would like to rename the example domain from "def"/"Default Domain" to "ffxx"/"Freifunk Alpha Centauri" (make domain code and domain name match site code and site name). As we want to extend the status page with a "domain name" field, it should display a proper domain name and not "Default Domain" even in single-domain setups. Recommending to make the domain match the site makes sense for such setups in my opinion.

An alternative would be to allow disabling domain support in site.mk - while I originally liked the idea of always enabling domains to keep the code simple, I'm less convinced now. And as we already merge site and domain whereever we use them, only small parts of the code would need to be adjusted.

Opinions?

[neocturne]

Multidomain support is merged now. It is disabled by default and can be enabled by setting GLUON_MULTIDOMAIN=1 in site.mk.

[rotanid]

a little reminder that this is one of the few release blockers
relevant section in the protocol of our last meeting:
https://github.com/freifunk-gluon/gluon/wiki/Meeting-2018-01#41-domain-documentation-1261

[lemoer]

Thanks for the reminder. I'll try to do this in today's evening.

[lemoer]

Here is my first draft: https://md.darmstadt.ccc.de/gluon-multidomain_doc

Please feel free to improve it, since it's very raw for now.

[neocturne]

This PR is superseded by #1365. If anything is missing from that PR, please contribute there or help with the review.