Skip to content

Commit 6455974

Browse files
pandafynemesifier
pandafy
authored and
nemesifier
committed
[docs] Added documentation for WireGuard and VXLAN VPN backend
- Added examples for WireGuard, VXLAN and VXLAN over WireGuard - Updated OpenWrt documentation to describle usage of auto_client methods
1 parent b3ebe35 commit 6455974

7 files changed

Lines changed: 568 additions & 9 deletions

File tree

‎README.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ netjsonconfig
1616

1717
.. image:: https://badge.fury.io/py/netjsonconfig.svg
1818
:target: http://badge.fury.io/py/netjsonconfig
19-
19+
2020
.. image:: https://pepy.tech/badge/netjsonconfig
2121
:target: https://pepy.tech/project/netjsonconfig
2222
:alt: downloads
@@ -43,6 +43,7 @@ Its main features are listed below for your reference:
4343
* `OpenWRT <http://openwrt.org>`_ / `LEDE <https://www.lede-project.org/>`_ support
4444
* `OpenWisp Firmware <https://github.com/openwisp/OpenWISP-Firmware>`_ support
4545
* `OpenVPN <https://openvpn.net>`_ support
46+
* `WireGuard <https://www.wireguard.com/>`_ support
4647
* Possibility to support more firmwares via custom backends
4748
* Based on the `NetJSON RFC <http://netjson.org/rfc.html>`_
4849
* **Validation** based on `JSON-Schema <http://json-schema.org/>`_

‎docs/source/backends/openwrt.rst‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2285,6 +2285,289 @@ Will be rendered as follows::
22852285
option proto 'udp'
22862286
option tls_server '1'
22872287
2288+
WireGuard
2289+
---------
2290+
2291+
This backend includes the schema of the ``Wireguard`` backend, inheriting its features.
2292+
2293+
For details regarding the **WireGuard** schema please see :ref:`wireguard_backend_schema`.
2294+
2295+
Schema additions
2296+
~~~~~~~~~~~~~~~~
2297+
2298+
The ``OpenWrt`` backend adds a few properties to the WireGuard schema, see below.
2299+
2300+
+-----------------+---------+--------------+-------------------------------------------------------------+
2301+
| key name | type | default | description |
2302+
+=================+=========+==============+=============================================================+
2303+
| ``network`` | string | ``None`` | logical interface name (UCI specific), |
2304+
| | | | |
2305+
| | | | 2 to 15 alphanumeric characters, dashes and underscores |
2306+
+-----------------+---------+--------------+-------------------------------------------------------------+
2307+
| ``nohostroute`` | boolean | ``False`` | do not add routes to ensure the tunnel endpoints are routed |
2308+
| | | | via non-tunnel device |
2309+
+-----------------+---------+--------------+-------------------------------------------------------------+
2310+
| ``fwmark`` | string | ``None`` | firewall mark to apply to tunnel endpoint packets |
2311+
+-----------------+---------+--------------+-------------------------------------------------------------+
2312+
| ``ip6prefix`` | list | ``[]`` | IPv6 prefixes to delegate to other interfaces |
2313+
+-----------------+---------+--------------+-------------------------------------------------------------+
2314+
| ``addresses`` | list | ``[]`` | list of unique IPv4 or IPv6 addresses |
2315+
+-----------------+---------+--------------+-------------------------------------------------------------+
2316+
2317+
The ``OpenWrt`` backend also adds ``wireguard_peers`` option for sepecifying a list of
2318+
WireGuard Peers. It add the following properties to the ``wireguard_peers`` property of
2319+
WireGuard schema.
2320+
2321+
+-----------------------+---------+-----------+------------------------------------------------------------------------+
2322+
| key name | type | default | description |
2323+
+=======================+=========+===========+========================================================================+
2324+
| ``interface`` | string | ``None`` | name of the wireguard interface, |
2325+
| | | | |
2326+
| | | | 2 to 15 alphanumeric characters, dashes and underscores |
2327+
+-----------------------+---------+-----------+------------------------------------------------------------------------+
2328+
| ``route_allowed_ips`` | boolean | ``False`` | automatically create a route for each of the Allowed IPs for this peer |
2329+
+-----------------------+---------+-----------+------------------------------------------------------------------------+
2330+
2331+
WireGuard example
2332+
~~~~~~~~~~~~~~~~~
2333+
2334+
The following *configuration dictionary*:
2335+
2336+
.. code-block:: python
2337+
2338+
{
2339+
"interfaces": [
2340+
{
2341+
"name": "wg",
2342+
"type": "wireguard",
2343+
"private_key": "QFdbnuYr7rrF4eONCAs7FhZwP7BXX/jD/jq2LXCpaXI=",
2344+
"port": 51820,
2345+
"mtu": 1420,
2346+
"nohostroute": False,
2347+
"fwmark": "",
2348+
"ip6prefix": [],
2349+
"addresses": [
2350+
{
2351+
"proto": "static",
2352+
"family": "ipv4",
2353+
"address": "10.0.0.5/32",
2354+
"mask": 32,
2355+
}
2356+
],
2357+
"network": "",
2358+
}
2359+
],
2360+
"wireguard_peers": [
2361+
{
2362+
"interface": "wg",
2363+
"public_key": "94a+MnZSdzHCzOy5y2K+0+Xe7lQzaa4v7lEiBZ7elVE=",
2364+
"allowed_ips": ["10.0.0.1/32"],
2365+
"endpoint_host": "wireguard.test.com",
2366+
"endpoint_port": 51820,
2367+
"preshared_key": "",
2368+
"persistent_keepalive": 60,
2369+
"route_allowed_ips": True,
2370+
}
2371+
]
2372+
}
2373+
2374+
Will be rendered as follows:
2375+
2376+
.. code-block:: text
2377+
2378+
package network
2379+
2380+
config interface 'wg'
2381+
list addresses '10.0.0.5/32/32'
2382+
option listen_port '51820'
2383+
option mtu '1420'
2384+
option nohostroute '0'
2385+
option private_key 'QFdbnuYr7rrF4eONCAs7FhZwP7BXX/jD/jq2LXCpaXI='
2386+
option proto 'wireguard'
2387+
2388+
config wireguard_wg 'wgpeer'
2389+
list allowed_ips '10.0.0.1/32'
2390+
option endpoint_host 'wireguard.test.com'
2391+
option endpoint_port '51820'
2392+
option persistent_keepalive '60'
2393+
option public_key '94a+MnZSdzHCzOy5y2K+0+Xe7lQzaa4v7lEiBZ7elVE='
2394+
option route_allowed_ips '1'
2395+
2396+
VXLAN
2397+
-----
2398+
2399+
``OpenWrt`` backend includes the schema requied for generating VXLAN
2400+
interface configouration. This is useful of setting up layer 2 tunnels.
2401+
2402+
2403+
VXLAN Settings
2404+
~~~~~~~~~~~~~~
2405+
2406+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2407+
| key name | type | default | description |
2408+
+=============+===================+==============+=============================================================+
2409+
| ``network`` | string | ``None`` | name of interface, |
2410+
| | | | |
2411+
| | | | 2 to 15 alphanumeric characters, dashes and underscores |
2412+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2413+
| ``vtep`` | string | ``False`` | VXLAN tunnel endpoint |
2414+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2415+
| ``port`` | integer | ``4789`` | port for VXLAN connection |
2416+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2417+
| ``vni`` | integer or string | ``None`` | VXLAN Network Identifier |
2418+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2419+
| ``tunlink`` | list | ``[]`` | interface to which the VXLAN tunnel will be bound |
2420+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2421+
| ``rxcsum`` | boolean | ``True`` | use checksum validation in RX direction |
2422+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2423+
| ``txcsum`` | boolean | ``True`` | use checksum validation in TX direction |
2424+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2425+
| ``mtu`` | integer | ``1280`` | MTU for route, only numbers are allowed |
2426+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2427+
| ``ttl`` | integer | ``64`` | TTL of the encapsulation packets |
2428+
+-------------+-------------------+--------------+-------------------------------------------------------------+
2429+
2430+
VXLAN example
2431+
~~~~~~~~~~~~~
2432+
2433+
The following *configuration dictionary*:
2434+
2435+
.. code-block:: python
2436+
2437+
{
2438+
"interfaces": [
2439+
{
2440+
"name": "vxlan",
2441+
"type": "vxlan",
2442+
"vtep": "10.0.0.1",
2443+
"port": 4789,
2444+
"vni": 1,
2445+
"tunlink": "",
2446+
"rxcsum": True,
2447+
"txcsum": True,
2448+
"mtu": 1280,
2449+
"ttl": 64,
2450+
"mac": "",
2451+
"disabled": False,
2452+
"network": "",
2453+
},
2454+
]
2455+
}
2456+
2457+
Will be rendered as follows:
2458+
2459+
.. code-block:: text
2460+
2461+
package network
2462+
2463+
config interface 'vxlan'
2464+
option enabled '0'
2465+
option ifname 'vxlan'
2466+
option mtu '1280'
2467+
option peeraddr '10.0.0.1'
2468+
option port '4789'
2469+
option proto 'vxlan'
2470+
option rxcsum '1'
2471+
option ttl '64'
2472+
option txcsum '1'
2473+
option vid '1'
2474+
2475+
VXLAN over WireGuard example
2476+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2477+
2478+
Since a layer 2 tunnel can be encapsulated in a layer 3 tunnel, here is an
2479+
example configuration for setting up a VXLAN tunnel over WireGuard.
2480+
2481+
The following *configuration dictionary*:
2482+
2483+
.. code-block:: python
2484+
2485+
{
2486+
"interfaces": [
2487+
{
2488+
"name": "wgvxlan",
2489+
"type": "wireguard",
2490+
"private_key": "QFdbnuYr7rrF4eONCAs7FhZwP7BXX/jD/jq2LXCpaXI=",
2491+
"port": 51820,
2492+
"mtu": 1420,
2493+
"nohostroute": False,
2494+
"fwmark": "",
2495+
"ip6prefix": [],
2496+
"addresses": [
2497+
{
2498+
"proto": "static",
2499+
"family": "ipv4",
2500+
"address": "10.0.0.5/32",
2501+
"mask": 32,
2502+
}
2503+
],
2504+
"network": "",
2505+
},
2506+
{
2507+
"name": "vxlan",
2508+
"type": "vxlan",
2509+
"vtep": "10.0.0.1",
2510+
"port": 4789,
2511+
"vni": 1,
2512+
"tunlink": "wgvxlan",
2513+
"rxcsum": True,
2514+
"txcsum": True,
2515+
"mtu": 1280,
2516+
"ttl": 64,
2517+
"mac": "",
2518+
"disabled": False,
2519+
"network": "",
2520+
},
2521+
],
2522+
"wireguard_peers": [
2523+
{
2524+
"interface": "wgvxlan",
2525+
"public_key": "94a+MnZSdzHCzOy5y2K+0+Xe7lQzaa4v7lEiBZ7elVE=",
2526+
"allowed_ips": ["10.0.0.1/32"],
2527+
"endpoint_host": "wireguard.test.com",
2528+
"endpoint_port": 51820,
2529+
"preshared_key": "",
2530+
"persistent_keepalive": 60,
2531+
"route_allowed_ips": True,
2532+
}
2533+
]
2534+
}
2535+
2536+
Will be rendered as follows:
2537+
2538+
.. code-block:: text
2539+
2540+
package network
2541+
2542+
config interface 'wgvxlan'
2543+
list addresses '10.0.0.5/32/32'
2544+
option listen_port '51820'
2545+
option mtu '1420'
2546+
option nohostroute '0'
2547+
option private_key 'QFdbnuYr7rrF4eONCAs7FhZwP7BXX/jD/jq2LXCpaXI='
2548+
option proto 'wireguard'
2549+
2550+
config interface 'vxlan'
2551+
option enabled '1'
2552+
option ifname 'vxlan'
2553+
option mtu '1280'
2554+
option peeraddr '10.0.0.1'
2555+
option port '4789'
2556+
option proto 'vxlan'
2557+
option rxcsum '1'
2558+
option ttl '64'
2559+
option tunlink 'wgvxlan'
2560+
option txcsum '1'
2561+
option vid '1'
2562+
2563+
config wireguard_wgvxlan 'wgpeer'
2564+
list allowed_ips '10.0.0.1/32'
2565+
option endpoint_host 'wireguard.test.com'
2566+
option endpoint_port '51820'
2567+
option persistent_keepalive '60'
2568+
option public_key '94a+MnZSdzHCzOy5y2K+0+Xe7lQzaa4v7lEiBZ7elVE='
2569+
option route_allowed_ips '1'
2570+
22882571
All the other settings
22892572
----------------------
22902573

‎docs/source/backends/vpn.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
============
2+
VPN Backends
3+
============
4+
5+
.. include:: ../_github.rst
6+
7+
``netjsonconfig`` currently supports three VPN backends:
8+
9+
.. toctree::
10+
:maxdepth: 2
11+
12+
/backends/openvpn
13+
/backends/wireguard
14+
/backends/vxlan_over_wireguard

0 commit comments

Comments
 (0)