Skip to content

Commit

Permalink
Merge branch 'master' into issues/297-wiregaurd-docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@nemesifier
nemesifier authored Nov 4, 2024
2 parents 40cc3cf + 8afbb38 commit fdb11d3
Show file tree
Hide file tree
Showing 15 changed files with 1,134 additions and 160 deletions.
15 changes: 15 additions & 0 deletions .github/FUNDING.yml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# These are supported funding model platforms

github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: # Replace with a single Open Collective username
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
polar: # Replace with a single Polar username
buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
thanks_dev: # Replace with a single thanks.dev username
custom: ["https://openwisp.org/sponsorship/"]
227 changes: 227 additions & 0 deletions docs/source/backends/openwrt.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -641,8 +641,42 @@ key name type default allowed values
``max_age`` integer ``20`` timeout in seconds until
topology updates on link
loss
``vlan_filtering`` list ``[]``` a list of ``dict ({})``
defining VLANs for the
bridge

Refer to the :ref:`VLAN
options table
<bridge_vlan_options>` below
for a list of available
options.
=========================== ======= ========= ============================

.. _bridge_vlan_options:

VLAN options:

========= ======= =======================================================
key name type allowed values
========= ======= =======================================================
``vlan`` integer VLAN ID
``ports`` list A list of ``dict`` defining interfaces participating in
the VLAN

=============== ======= ===============================
key name type allowed values
=============== ======= ===============================
``ifname`` string interface name (this interface
should be a bridge member)
``tagging`` string whether the port is tagged
(``t``) or untagged (``u``)
``primary_vid`` boolean whether the current VLAN should
be used for all untagged
incoming traffic on this
interface
=============== ======= ===============================
========= ======= =======================================================

Bridge interface example
~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -700,6 +734,89 @@ Will be rendered as follows:
option netmask '255.255.255.0'
option proto 'static'

Using VLAN Filtering on a Bridge
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following *configuration dictionary*:

.. code-block:: python
{
"interfaces": [
{
"type": "bridge",
"bridge_members": ["lan1", "lan2", "lan3"],
"name": "br-lan",
"vlan_filtering": [
{
"vlan": 1,
"ports": [
{
"ifname": "lan1",
"tagging": "t",
"primary_vid": True,
},
{"ifname": "lan2", "tagging": "t"},
],
},
{
"vlan": 2,
"ports": [
{
"ifname": "lan1",
"tagging": "t",
"primary_vid": False,
},
{
"ifname": "lan3",
"tagging": "u",
"primary_vid": True,
},
],
},
],
}
]
}
Will be rendered as follows:

.. code-block::
package network
config device 'device_br_lan'
option name 'br-lan'
list ports 'lan1'
list ports 'lan2'
list ports 'lan3'
option type 'bridge'
option vlan_filtering '1'
config bridge-vlan 'vlan_br_lan_1'
option device 'br-lan'
list ports 'lan1:t*'
list ports 'lan2:t'
option vlan '1'
config bridge-vlan 'vlan_br_lan_2'
option device 'br-lan'
list ports 'lan1:t'
list ports 'lan3:u*'
option vlan '2'
config interface 'vlan_br_lan_1'
option device 'br-lan.1'
option proto 'none'
config interface 'vlan_br_lan_2'
option device 'br-lan.2'
option proto 'none'
config interface 'br_lan'
option device 'br-lan'
option proto 'none'
Wireless settings
-----------------

Expand Down Expand Up @@ -1693,6 +1810,8 @@ The following *configuration dictionary*:
"name": "modem0",
"mtu": 1500,
"signalrate": 5,
"loglevel": "ERR",
"force_link": True,
}
]
}
Expand All @@ -1710,6 +1829,8 @@ Will be rendered as follows:
config interface 'modem0'
option apn 'apn.operator.com'
option device '/sys/devices/platform/ahb/1b000000.usb/usb1/1-1'
option force_link '1'
option loglevel 'ERR'
option lowpower '0'
option metric '50'
option password 'pwd123456'
Expand All @@ -1718,6 +1839,112 @@ Will be rendered as follows:
option signalrate '5'
option username 'user123'

VLAN 802.1q / VLAN 802.1ad settings
-----------------------------------

.. note::

The configuration setting for **VLAN 802.1q** and **VLAN 802.1ad** are
exactly same, except the ``type`` setting. Hence, the documentation
only explains **VLAN 802.1q**.

Interfaces of type ``vlan_8021q`` contain a few options that are specific
to VLAN 802.1q interfaces.

These are the ``OpenWrt`` backend NetJSON extensions for VLAN 802.1q
interfaces:

======================= ======= ============== ===========================
key name type default allowed values
======================= ======= ============== ===========================
``type`` string ``vlan_8021q`` type of interface
(``vlan_8021ad`` for VLAN
802.1ad)
``vid`` integer empty VLAN ID
``ingress_qos_mapping`` string empty Defines a mapping of VLAN
header priority to the
Linux internal packet
priority on incoming frames
``egress_qos_mapping`` string empty Defines a mapping of Linux
internal packet priority to
VLAN header priority but
for outgoing frames
======================= ======= ============== ===========================

VLAN 802.1q example
~~~~~~~~~~~~~~~~~~~

The following *configuration dictionary*:

.. code-block:: python
{
"interfaces": [
{
"type": "8021q",
"vid": 1,
"name": "br-lan",
"mac": "E8:6A:64:3E:4A:3A",
"mtu": 1500,
"ingress_qos_mapping": ["1:1"],
"egress_qos_mapping": ["2:2"],
}
]
}
Will be rendered as follows:

.. code-block:: text
package network
config device 'device_br_lan_1'
list egress_qos_mapping '2:2'
option ifname 'br-lan'
list ingress_qos_mapping '1:1'
option macaddr 'E8:6A:64:3E:4A:3A'
option mtu '1500'
option name 'br-lan.1'
option type '8021q'
option vid '1'
config interface 'vlan_br_lan_1'
option device 'br-lan.1'
option proto 'none'
VLAN 802.1ad example
~~~~~~~~~~~~~~~~~~~~

The following *configuration dictionary*:

.. code-block:: python
{
"interfaces": [
{
"type": "8021ad",
"vid": 6,
"name": "eth0",
}
]
}
Will be rendered as follows:

.. code-block:: text
package network
config device 'device_eth0_6'
option ifname 'eth0'
option name 'eth0.6'
option type '8021ad'
option vid '6'
config interface 'vlan_eth0_6'
option device 'eth0.6'
option proto 'none'
Radio settings
--------------

Expand Down
30 changes: 25 additions & 5 deletions docs/source/backends/zerotier.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,12 @@ See an example of initialization and rendering below:
"tags": [{"default": 1, "id": 1}],
"remoteTraceTarget": "7f5d90eb87",
"remoteTraceLevel": 1,
"client_options": {
"allow_managed": True,
"allowed_global": False,
"allowed_default": False,
"allowed_dns": False,
},
}
]
}
Expand Down Expand Up @@ -268,6 +274,20 @@ key name type default description
``tags`` list ``[{}]`` list of network tags dictionaries
``remoteTraceTarget`` string remote target ID for network tracing
``remoteTraceLevel`` integer level of network tracing
``client_options`` dict ``{}`` These options are only used for client configurations

=================== ======= ==========================================
key name type description
=================== ======= ==========================================
``allow_managed`` boolean allow ZeroTier to set IP addresses and
routes
``allowed_global`` boolean allow ZeroTier to set
global/public/not-private range IPs and
routes
``allowed_default`` boolean allow ZeroTier to set the default route on
the system
``allowed_dns`` boolean allow ZeroTier to set DNS servers
=================== ======= ==========================================
===================== ======= =========== =======================================================================

Client specific settings
Expand Down Expand Up @@ -314,7 +334,7 @@ key name type default description
determined
``port`` integer ``9993`` port number of the
zerotier service
``local_conf`` string path of the local
``local_conf_path`` string path of the local
zerotier configuration
(only used for advanced
configuration)
Expand Down Expand Up @@ -404,8 +424,8 @@ OpenWrt device, such as setting up trusted paths, blacklisting physical
paths, setting up physical path hints for certain nodes, and defining
trusted upstream devices, this can be achieved by creating a file named
``local.conf`` in a persistent filesystem location, such as
``/etc/openwisp/zerotier/local.conf`` and then adding the ``local_conf``
option to the ZeroTier UCI configuration.
``/etc/openwisp/zerotier/local.conf`` and then adding the
``local_conf_path`` option to the ZeroTier UCI configuration.

For example, let's create a local configuration file at
``/etc/openwisp/zerotier/local.conf`` (JSON) to blacklist a specific
Expand All @@ -421,7 +441,7 @@ physical network path **(10.0.0.0/24)** from all ZeroTier traffic.
}
}
Now add ``local_conf`` option to ``/etc/config/zerotier``:
Now add ``local_conf_path`` option to ``/etc/config/zerotier``:

.. code-block:: text
Expand All @@ -431,7 +451,7 @@ Now add ``local_conf`` option to ``/etc/config/zerotier``:
option enabled '1'
list join '9536600adf654322'
option secret '{{secret}}'
option local_conf '/etc/openwisp/zerotier/local.conf'
option local_conf_path '/etc/openwisp/zerotier/local.conf'
**More information**

Expand Down
Loading

0 comments on commit fdb11d3

Please sign in to comment.