diff --git a/.DS_Store b/.DS_Store index a5da4753..f2338631 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/.gitignore b/.gitignore index 69fa449d..521c4095 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ _build/ +images/old-ones \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index f5015265..7974634a 100644 --- a/Dockerfile +++ b/Dockerfile @@ -60,6 +60,4 @@ RUN sed -i '/link rel=\"prev\"/a \ \ \ \ ' /usr/share/nginx/html/pro/pro-relay-server.html -RUN sed -i '/link rel=\"prev\"/a \ \ \ \ ' /usr/share/nginx/html/turn-server.html - RUN sed -i '/link rel=\"prev\"/a \ \ \ \ ' /usr/share/nginx/html/ui-reference.html diff --git a/README.md b/README.md index 193e50c2..6adb16e0 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ apt-get install make apt-get install python3-sphinx apt-get install python3-pip pip install git+https://github.com/bashtage/sphinx-material.git +pip install markupsafe ``` 1. Clone the repo diff --git a/about.rst b/about.rst index 135929a8..2055f5a2 100644 --- a/about.rst +++ b/about.rst @@ -2,12 +2,12 @@ About ========== + .. image:: images/netmaker-simple.png :width: 60% :alt: Netmaker Architecture Diagram :align: center - What is Netmaker? ================== @@ -57,4 +57,14 @@ This list is not all-encompassing but provides a sample of how many users use Ne 2. Secure access to a home or office network 3. Provide remote access to resources like an AWS VPC, data center, or K8S cluster 4. Create distributed, cross-cloud Kubernetes clusters or database clusters - 5. Manage a secure mesh of IoT devices \ No newline at end of file + 5. Manage a secure mesh of IoT devices + + +Architecture +================== + +.. toctree:: + :maxdepth: 1 + + architecture + diff --git a/acls.rst b/acls.rst index 8d5c1ac1..bd69e17f 100644 --- a/acls.rst +++ b/acls.rst @@ -1,6 +1,8 @@ -===================================== -Access Control Lists -===================================== +.. _acls: + +====== +ACLs +====== Introduction =============== @@ -32,7 +34,7 @@ Node ACL Screen Alternatively, you can reach the individual node ACLs by clicking on a Node in either the Node List or the Graph view. This will give you the ACLs for just this individual node, making it easier to enable/disable peers at an individual level. -.. image:: images/acls-2.png +.. image:: images/acls-2.jpg :width: 80% :alt: ACLs :align: center @@ -45,8 +47,7 @@ When you create a network, you set a "default ACL" of either "Allow" or "Deny." As of 0.16.0, there is another option, the default node-level ACL. -.. image:: images/acls-4.png - :width: 80% +.. image:: images/acls-4.jpg :alt: ACLs :align: center diff --git a/advanced-client-install.rst b/advanced-client-install.rst index fac81cfe..346a5380 100644 --- a/advanced-client-install.rst +++ b/advanced-client-install.rst @@ -82,7 +82,7 @@ i. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linu Modes and System Compatibility ================================== -**Note: If you would like to connect non-Linux/Unix machines to your network such as phones and Windows desktops, please see the documentation on External Clients** +**Note: If you would like to connect non-Linux/Unix machines to your network such as phones and Windows desktops, please see the documentation on Remote Access Clients(previously External Clients)** The netclient can be run in a few "modes". System compatibility depends on which modes you intend to use. These modes can be mixed and matched across a network, meaning all machines do not have to run with the same "mode." diff --git a/api.rst b/api.rst index c48c4626..220a5fc0 100644 --- a/api.rst +++ b/api.rst @@ -1,7 +1,3 @@ -============================================= -API Reference -============================================= - API Usage ========================== diff --git a/architecture.rst b/architecture.rst index 0f4e861f..c33a2310 100644 --- a/architecture.rst +++ b/architecture.rst @@ -1,6 +1,5 @@ -=============== Architecture -=============== +============= .. image:: images/nm-diagram-3.png :width: 100% @@ -38,7 +37,7 @@ A full `mesh network ` This is in contrast to a hub-and-spoke network, where each machine must first pass its traffic through a relay server before it can reach other machines. -In certain situations, you may either want or need a *partial mesh* network, where only some devices can reach each other directly, and other devices must route their traffic through a relay/gateway. Netmaker can use this model in some use cases where it makes sense. In the diagram at the top of this page, the setup is a partial mesh because the servers (nodes A-D) are meshed, but then external clients come in via a gateway and are not meshed. +In certain situations, you may either want or need a *partial mesh* network, where only some devices can reach each other directly, and other devices must route their traffic through a relay/gateway. Netmaker can use this model in some use cases where it makes sense. In the diagram at the top of this page, the setup is a partial mesh because the servers (nodes A-D) are meshed, but then Remote Access Clients come in via a gateway and are not meshed. Mesh networks are generally faster than other topologies but are also more complicated to set up. WireGuard on its own gives you the means to create encrypted tunnels between devices, but it does not provide a method for setting up a full network. This is where Netmaker comes in. @@ -122,14 +121,36 @@ Netmaker can be used in its entirety without the UI, but the UI makes things a l CoreDNS -------- -As of 0.12.0, CoreDNS is not an active part of the Netmaker system. Nodes DO NOT receive their DNS updates using a nameserver. Instead, DNS entries are added to the local "hosts" file directly. The CoreDNS component can be safely removed from the setup and DNS will continue to function. +As of 0.22.0, CoreDNS is an active part of the Netmaker system. We deprecated setting entries on the hosts file which was not an ideal implementation. +Netmaker server actively sets the dns entries on the CoreDNS server. +After you install the netmaker server components, you can see the corendns container running as well. +You need to make some changes manually to activate the corendns server, follow these steps on the netmaker server: + + +1. Make sure that UDP Port 53 and TCP Port 53 are allowed to pass in the network where your netmaker server lies + +2. Make sure the `network_mode: host` is set on the coredns container spec in `/root/docker-compose.yml` and run `docker-compose up -d` + +3. disable the systemd-resolved (Reason: to avoid port conflict with coredns server) + +.. code-block:: -Previously, CoreDNS was used as a nameserver and the netclient would set the nameserver per peer. However, this only worked on a subset of Linux systems, because it required resolvectl. The new method (using the hosts file) works across OSs. + sudo systemctl disable systemd-resolved.service + sudo systemctl stop systemd-resolved -However, we still maintain CoreDNS in the default deployment for two reasons: - 1. You may wish to add a nameserver to "Ext Clients". CoreDNS can still be used for this. - 2. You may wish to integrate the Netmaker nameserver with your existing DNS setup. +4. `**IMPORTANT:**` Since you have disabled systemd-resolved service on server, make sure to set the nameserver to the public ip of the machine, which basically points to the coredns server. +And now you can point any machine in the network to use this DNS server and you can reach the other peers in the network by their domain names. For external clients running linux, install 'resolvconf' before setting the Wireguard configurations. + +Refer to your operating system documentation for information about how to configure custom DNS network settings. Here are some general help guides on how to add custom DNS server: + +1. Linux - https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-linux.html. Configuration depends on what distribution of Linux you use. + +2. Mac - https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-mac.html + +3. Windows - https://devilbox.readthedocs.io/en/latest/howto/dns/add-custom-dns-server-on-win.html + +If your machine is virtually hosted in a cloud, you might want to refer to your VM provider's documention on how to permanently set the custom DNS resolver. Caddy ------- @@ -141,18 +162,18 @@ Caddy simplifies management because the configuration file is very short, severa Traefik was previously the default and is still a functioning option, but We are moving guidance towards Caddy by default. If you are maintaining an installation that relies on Traefik, you can continue to use it with Netmaker. -External Client ----------------- +Remote Access Clients +--------------------- -The external client is simply a manually configured WireGuard connection to your network, which Netmaker helps to manage. +The Remote Access Clients (client external to the mesh network) is simply a configured WireGuard connection to your network, which Netmaker helps to manage. Most machines can run WireGuard. Setting up a WireGuard connection to a single endpoint is fairly simple. It is setting up mesh networks and other topologies like site-to-site which becomes complicated. -Mac, Windows, and Linux are handled natively by the Netclient, though you can still add them as ext clients if you wish. Primarily, iPhone and Android are the main systems unsupported by the Netclient which MUST be handled via external client. +Mac, Windows, and Linux are handled natively by the Netclient, though you can still add them as ext clients if you wish. Primarily, iPhone and Android are the main systems unsupported by the Netclient which MUST be handled via Remote Access Client. -External clients hook into a Netmaker network via an "Ingress Gateway," which is configured for a given node and allows traffic to flow into the network. External clients are also reachable via the gateway. While this is a "concentrator" and not peer-to-peer, this is often desirable. +Remote Access Clients hook into a Netmaker network via an "Remote Access Gateway (ingress)," which is configured for a given node and allows traffic to flow into the network. Remote Access Clients are also reachable via the gateway. While this is a "concentrator" and not peer-to-peer, this is often desirable. -Many users use external clients as a convenient way to manage remote access for their users. Why? It works with vanilla WireGuard for one. You simply download the config and load it into WireGuard on the client device. No additional software is required. It can also be quite helpful to have a "choke point" for traffic (the gateway) rather than direct p2p connections to every machine. +Many users use Remote Access Clients clients as a convenient way to manage remote access for their users. Why? It works with vanilla WireGuard for one. You simply download the config and load it into WireGuard on the client device. No additional software is required. It can also be quite helpful to have a "choke point" for traffic (the gateway) rather than direct p2p connections to every machine. Technical Process ==================== @@ -205,4 +226,4 @@ Limitations Install limitations mostly include platform-specific dependencies. A failed netclient install should display information about which command is failing, or which libraries are missing. This can often be solved via machine upgrade, installing missing dependencies, or setting kernel headers on the machine for WireGuard (e.x.: `Installing Kernel Headers on Debian `_) -It is very helpful if an install fails to run "netclient join -t -v 4". By default, the install runs with minimal logging. The -v flags will display any encountered errors. You can set the verbosity fron 0-4. \ No newline at end of file +It is very helpful if an install fails to run "netclient join -t -v 4". By default, the install runs with minimal logging. The -v flags will display any encountered errors. You can set the verbosity fron 0-4. diff --git a/conf.py b/conf.py index 08524b3e..b6f395cb 100644 --- a/conf.py +++ b/conf.py @@ -22,7 +22,7 @@ author = 'Netmaker' # The full version, including alpha/beta/rc tags -release = '0.21.2' +release = '0.22.0' # -- General configuration --------------------------------------------------- diff --git a/egress-gateway.rst b/egress-gateway.rst index 7f801383..9c0bd632 100644 --- a/egress-gateway.rst +++ b/egress-gateway.rst @@ -1,6 +1,8 @@ -===================================== -Egress Gateway -===================================== +.. _egress: + +======= +egress +======= Introduction =============== @@ -35,7 +37,7 @@ Once you have determined the subnet, and deployed your netclient, you can go to :alt: Gateway :align: center -At this point you will choose your selected host to use as an egress. You can choose if you would like to use NAT or not with the switch. You also have a choice of using this host as an internet gateway. more on that in a bit. You can put the selected CIDR for your egress range(s) in the field. click the add range button to add more egress ranges for the host. The interface is automatically chosen and will not be shown in this window. With everything filled out, click the create button. +At this point you will choose your selected host to use as an egress. You can choose if you would like to use NAT or not with the switch. You can put the selected CIDR for your egress range(s) in the field. click the add range button to add more egress ranges for the host. The interface is automatically chosen and will not be shown in this window. With everything filled out, click the create button. .. image:: images/ui-6.png :width: 80% @@ -65,28 +67,6 @@ In some scenarios, a single node will act as both ingress and egress! For instan :alt: Gateway :align: center -2) / NAT Gateway ------------------------ - -Most people think of a VPN as a remote server that keeps your internet traffic secure while you browse the web, or as a tool for accessing internet services in another country, using a VPN server based in that country. - -These are not typical use cases for Netmaker, but can be easily enabled. - -Navigate to the egress setup mentioned above. Instead of inputting a range, just click the internet gateway switch. the range of ``0.0.0.0/0`` will be automatically put in for you. (The IPv6 version ``::/0`` is still under construction) Click create. - -.. image:: images/internet-gateway.png - :width: 80% - :alt: Internet Gateway - :align: center - -After that, your public traffic will be routed through your egressing client. - - -.. image:: images/egress5.png - :width: 50% - :alt: Gateway - :align: center - Advanced Use Cases ====================== @@ -111,4 +91,20 @@ Advanced Use Cases iptables -t nat -I POSTROUTING -s networkRangeB -d egressGwRangeB -j MASQUERADE - iptables -t nat -I POSTROUTING -s egressGwRangeB -d networkRangeB -j MASQUERADE \ No newline at end of file + iptables -t nat -I POSTROUTING -s egressGwRangeB -d networkRangeB -j MASQUERADE + +2) IPv6 NAT Masquerading for Egress Gateways + + Currently IPv6 Egress Gateways are not working because the default kernel builds for most common linux distributions do not support ipv6 masquerading. Custom linux kernel needs to be built with flag for enabling ipv6 masquerading to get ipv6 egress gateways working. + + Some online resources about the topic: + +.. code-block:: + + https://superuser.com/questions/1751062/ipv6-masquerading-on-linux + + https://www.kernelconfig.io/config_nf_nat_masquerade_ipv6?q=&kernelversion=5.15.116&arch=x86 + + https://www.reddit.com/r/PFSENSE/comments/vb4r3s/ip6_masquerading + + diff --git a/examplecode/docker-compose.v0.20.3.yml b/examplecode/docker-compose.v0.20.3.yml index e7b5db1f..9041c33c 100644 --- a/examplecode/docker-compose.v0.20.3.yml +++ b/examplecode/docker-compose.v0.20.3.yml @@ -22,10 +22,6 @@ services: - COREDNS_ADDR=${SERVER_HOST} # Overrides SERVER_HOST if set. Useful for making HTTP available via different interfaces/networks. - SERVER_HTTP_HOST=api.${NM_DOMAIN} - # domain for your turn server - - TURN_SERVER_HOST=turn.${NM_DOMAIN} - # domain of the turn api server - - TURN_SERVER_API_HOST=https://turnapi.${NM_DOMAIN} netmaker-ui: container_name: netmaker-ui @@ -81,21 +77,6 @@ services: - mosquitto_logs:/mosquitto/log - mosquitto_data:/mosquitto/data - turn: - container_name: turn - image: gravitl/turnserver:v1.0.0 - env_file: ./netmaker.env - environment: - # config-dependant vars - - USERNAME=${TURN_USERNAME} - - PASSWORD=${TURN_PASSWORD} - # domain for your turn server - - TURN_SERVER_HOST=turn.${NM_DOMAIN} - network_mode: "host" - volumes: - - turn_server:/etc/config - restart: always - volumes: caddy_data: { } # runtime data for caddy caddy_conf: { } # configuration file for Caddy @@ -103,4 +84,3 @@ volumes: dnsconfig: { } # storage for coredns mosquitto_logs: { } # storage for mqtt logs mosquitto_data: { } # storage for mqtt data - turn_server: { } diff --git a/examplecode/myclient.conf b/examplecode/myclient.conf index 614e94f8..695569ce 100644 --- a/examplecode/myclient.conf +++ b/examplecode/myclient.conf @@ -5,6 +5,5 @@ PrivateKey = EJf6Yy51M/YDaZgedRpuxMmrqul35WfjmHvRZR1rQ0U= [Peer] PublicKey = m/RPuMVsbpgQ+RkxlgK2mG+dDFlzqn+ua2zJt8Wn7GA= AllowedIPs = 10.7.11.0/24 -Endpoint = 3.236.60.247:51822 +Endpoint = :51822 PersistentKeepalive = 20 - diff --git a/examplecode/netmaker.default.env b/examplecode/netmaker.default.env index e714c19a..520378fa 100644 --- a/examplecode/netmaker.default.env +++ b/examplecode/netmaker.default.env @@ -6,10 +6,6 @@ NM_DOMAIN= SERVER_HOST= # The admin master key for accessing the API. Change this in any production installation. MASTER_KEY= -# The username to set for turn api access -TURN_USERNAME= -# The password to set for turn api access -TURN_PASSWORD= # The username to set for MQ access MQ_USERNAME= # The password to set for MQ access @@ -46,12 +42,7 @@ SERVER_BROKER_ENDPOINT="ws://mq:1883" # For EMQX websockets use `SERVER_BROKER_E STUN_PORT="3478" # Logging verbosity level - 1, 2, or 3 VERBOSITY="1" -# Port to access turn server -TURN_PORT="3479" -# Config for using turn, accepts either true/false -USE_TURN="true" DEBUG_MODE="off" -TURN_API_PORT="8089" # Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST). # Change to "off" to turn off. REST_BACKEND="on" diff --git a/external-clients.rst b/external-clients.rst index c8ed2758..7364caf0 100644 --- a/external-clients.rst +++ b/external-clients.rst @@ -1,5 +1,7 @@ +.. _remote-access: + ===================================== -Ingress + External Clients +Remote Access Gateways and Clients ===================================== Introduction @@ -10,30 +12,33 @@ Introduction :alt: Gateway :align: center -Netmaker allows for "external clients" to reach into a network and access services via an Ingress Gateway. So what is an "external client"? An external client is any machine which cannot or should not be meshed. This can include: +Netmaker allows for **Remote Access Clients (RAC)** to reach into a network and access services via a Remote Access Gateway (ingress). So what is a "Remote Access Clients"? A remote access clients is any machine which cannot or should not be meshed, but can be connected to a Netmaker network. They are more or less VPN clients of a remote access gateway. This can include: - Phones - Laptops - Desktops + - Other devices that support WireGuard + +Remote Access Client can also refer to the slim client software that runs on a machine to allow it to connect to a Netmaker network. + +A remote access client is not "managed," meaning it does not automatically pull the latest network configuration or push changes to its configuration. Instead, it uses a generated WireGuard config file to access the designated **Remote Access Gateway**, which **is** a managed server (ie: a machine running netclient). This server then forwards traffic to the appropriate endpoint, acting as a middleman/relay. -An external client is not "managed," meaning it does not automatically pull the latest network configuration or push changes to its configuration. Instead, it uses a generated WireGuard config file to access the designated **Ingress Gateway**, which **is** a managed server (running netclient). This server then forwards traffic to the appropriate endpoint, acting as a middle-man/relay. +By using this method, you can hook any machine that can run WireGuard into a netmaker network. -By using this method, you can hook any machine into a netmaker network that can run WireGuard. +It is recommended to run the netclient where compatible, but for all other cases, a machine can be configured as a Remote Access Clients. -It is recommended to run the netclient where compatible, but for all other cases, a machine can be configured as an external client. -Important to note, that an external client is not **reachable** by the network, meaning the client can establish connections to other machines, but those machines cannot independently establish a connection back. The External Client method should only be used in use cases where one wishes to access resources running on the virtual network and **not** for use cases where one wishes to make a resource accessible on the network. For that, use netclient. -Configuring an Ingress Gateway -================================== +Configuring a Remote Access Gateway +==================================== -External Clients must attach to an Ingress Gateway. By default, your network will not have an ingress gateway. To configure an ingress gateway, navigate to the network name and go to the clients tab. +Clients must attach to a Remote Access Gateway. By default, your network will not have a remote access gateway. To configure one, navigate to the network and go to the "Remote Access" tab. .. image:: images/extclient1.png :width: 80% :alt: Gateway :align: center -After clicking the create client button, a modal window will pop up asking you which host you would like to use as an ingress gateway. You can use any host in your network, but it should have a public IP address (not behind a NAT). Your Netmaker server can be an ingress gateway and makes for a good default choice if you are unsure of which node to select. +After clicking the "Create Client Config" button, a modal window will pop up asking which host you would like to use as a gateway. You can use any host in your network, but it should have a public IP address (not behind a NAT). Your Netmaker server can be a remote access gateway and makes for a good default choice if you are unsure of which node to select. You can also specify whether the gateway should route all public traffic to the internet (internet gateway). Lastly, there is an option to specify a default DNS server for all attached Clients. .. image:: images/extclient2.png :width: 80% @@ -43,14 +48,14 @@ After clicking the create client button, a modal window will pop up asking you w Adding Clients to a Gateway ============================= -Once you have figured out your gateway, You can fill in any other info you need for your client. You can give it a name. You can use your own public key if you like. You can set a default DNS for the client, and any specific addresses you would need for the client. You can also leave these fields blank and the name, address, and public key will be automatically configured for you. Clients will be able to access other nodes in the network just as the gateway node does. +Once you have figured out your gateway, You can fill in any other info you need for your client. You can give it a name (Client ID), otherwise one will be auto-generated for you. You can specify your own public key for better security. You can set a DNS for the client (if left empty, fallback would be the gateway's default client DNS), and any specific addresses you would need for the client. You can also leave these fields blank and the name, address, and public key will be automatically configured for you. Clients will be able to access other nodes in the network just as the gateway does, of course unless blocked via network ACLs. .. image:: images/extclient3.png :width: 80% - :alt: Edit External Client Name + :alt: Edit Remote Access Client Name :align: center -After clicking create, your external client will be ready for your device. +After clicking create, your Remote Access Client configuration will be ready. .. image:: images/extclient4.png :width: 80% @@ -71,21 +76,38 @@ Example config file: Your client should now be able to access the network! A client can be invalidated at any time by simply deleting it from the UI. -Disabling External Clients -========================== +Disabling Remote Access Clients +================================ -To (temporarily) disable an external client's access to the Netmaker network that it belongs to, click the switch below "Enabled" on the line with the Client ID that you would like to disable. Click "Accept" when asked "Are you sure you want to disable access to this Ext. Client?" +To (temporarily) disable an Remote Access Client's access to the Netmaker network that it belongs to, click the switch below "Enabled" on the line with the Client ID that you would like to disable. Click "Accept" when asked "Are you sure you want to disable access to this Ext. Client?" .. image:: images/extclient-disable.png :width: 80% - :alt: Disable an External Client + :alt: Disable an Remote Access Client :align: center After you click the switch and click Accept the ext client will no longer be reachable and the switch will be turned off. .. image:: images/extclient-disabled.png :width: 80% - :alt: Disabled External Client + :alt: Disabled Remote Access Client :align: center To re-enable the client click the switch again and accept. It will turn on again and the client will be re-enabled. + + +Internet Gateway/Traditional VPN +================================= + +Most people think of a VPN as a remote server that keeps your internet traffic secure while you browse the web, or as a tool for accessing internet services in another country, using a VPN server based in that country. +This is not a typical use case for Netmaker, but can be easily enabled via the Remote Access Gateway feature. This is a **Pro-only** feature. + +Navigate to the remote access gateway setup mentioned above. Click the Internet Gateway switch. Click "Create Gateway". + +.. image:: images/internet-gateway.png + :width: 80% + :alt: Internet Gateway + :align: center + +After that, your public IPv4 traffic for any connected client, will be routed through the internet gateway. Support for IPv6 is work in progress. +**NOTE**: You need to specify the "Default client DNS" so as to avoid DNS leaks. If you do not specify a Default client DNS, the client's local gateway DNS will be most likely used. diff --git a/features.rst b/features.rst new file mode 100644 index 00000000..03682802 --- /dev/null +++ b/features.rst @@ -0,0 +1,49 @@ +========= +Features +========= + + +Egress Gateway +=============== + +Allows clients (nodes and ext clients) to reach external networks. + +:ref:`egress` + + +Remote Access Gateways & Clients +================================= + +A remote access gateway enables "external" clients to connect to the network. External clients refer to clients that are not part of the mesh network, but need to connect to it. This could be a laptop, mobile device, or even a server that is not part of the network. + +:ref:`remote-access` + + + +Access Control Lists +====================== + +ACLs control communications between nodes on a network + +:ref:`acls` + + +Netmaker Professional +====================== + +Netmaker Professional is our advanced Netmaker offering for business use cases. It offers all the features of community edition plus: + +- **Metrics:** Nodes collect networking metrics such as latency, transfer, and connectivity status. These are displayed in the Netmaker UI, and also exported to Grafana via Prometheus. + +- **Users:** On community you can only create admin users, where as on PRO it gives ability to create non-admin users which you can pair with remote-access gateway to segment users on different networks. + +- **Remote Access Client:** Netmaker Professional comes with a remote access client that allows you to connect to your network from anywhere. This is a great way to connect to your network from a laptop or mobile device (soon). + +- **FailOvers:** FailOvers are made to help two peers communicate where they cannot talk directly due to their firewall restrictions, in which case their connection falls back through a failover node set by the user in the network. + +- **Relays:** All traffic routing to and from in a network for a relayed machine will go through the relay machine. + +.. toctree:: + :maxdepth: 1 + + pro/index diff --git a/getting-started.rst b/getting-started.rst index f97ca04c..39bd9398 100644 --- a/getting-started.rst +++ b/getting-started.rst @@ -4,6 +4,16 @@ Getting Started Once you have Netmaker installed via the :doc:`Quick Install <./quick-start>` guide, you can use this Getting Started guide to help create and manage your first network. +.. toctree:: + :maxdepth: 1 + + install + quick-start + netclient + advanced-client-install + server-installation + oauth + Setup ================= @@ -15,7 +25,7 @@ Create a Network ================= -.. image:: images/create-net.png +.. image:: images/create-net.jpg :width: 80% :alt: Create Network Screen :align: center @@ -28,7 +38,7 @@ If you are running a small (less than 254 machines) network, and are unsure of w - 10.11.12.0/24 - 10.20.30.0/24 -- 100.99.98.0/24 +- 10.99.98.0/24 Network Settings Description ------------------------------- @@ -43,7 +53,7 @@ The Network creation form has a few fields which may seem unfamiliar. Here is a Once your network is created, you should see the network (wg-net here but it will be the name you chose when creating the network): -.. image:: images/network-created.png +.. image:: images/network-created.jpg :width: 80% :alt: Node Screen :align: center @@ -53,7 +63,7 @@ When you click on the NetId and then the Nodes button (or go direct via the left As of v0.18.0, netclient has been moved out of the netmaker repo and into its own repo. This means that the netmaker server will no longer create its own default node. To recreate that default node, Netclient will also have to be installed on the netmaker server and joined to the network. You can then set that node as a default node in the Hosts tab. This will make every new network have that node automatically on creation. More on hosts are mentioned in the manage Nodes/Hosts section of this page. -.. image:: images/netmaker-node.png +.. image:: images/netmaker-node.jpg :width: 80% :alt: Node Screen :align: center @@ -66,28 +76,28 @@ Adding nodes to the network typically requires a key. If You are on version 0.18 Navigate to the enrollment keys tab on the side menu. You should see a create button in the top right corner. After clicking that, you should be brought to a window like this. -.. image:: images/enrollmentkeycreate.png +.. image:: images/enrollmentkeycreate.jpg :width: 80% :alt: Enrollment Key Screen :align: center This will give you a few different options on how you want to set up your enrollment key. you can set it up with unlimited uses, limited uses, or timebound uses. You can also setup one or multiple networks to join, or you can set it to no networks and then join a network through the UI in the hosts tab. Click on newly registered host and go to the networks tab. Then click on show all networks. You can also create any tags you would like for that key -.. image:: images/networkjoinui.png +.. image:: images/networkjoinui.jpg :width: 80% :alt: Join network through UI :align: center If an enrollment key runs out of uses, or is expired, the key will show as invalid like in the image below. -.. image:: images/enrollmentkeyinvalid.png +.. image:: images/enrollmentkeyinvalid.jpg :width: 80% :alt: Enrollment Key Screen with invalid keys :align: center After your enrollment key is created, you can click on that key to get the registration token. -.. image:: images/enrollmentkeytoken.png +.. image:: images/enrollmentkeytoken.jpg :width: 80% :alt: Enrollment Key token window :align: center @@ -112,8 +122,7 @@ Deploy Nodes You should get output similar to the below. The netclient retrieves local settings, submits them to the server for processing, and retrieves updated settings. Then it sets the local network configuration. For more information about this process, see the :doc:`client installation <./netclient>` documentation. If this process failed and you do not see your node in the console (see below), then reference the :doc:`troubleshooting <./troubleshoot>` documentation. -.. image:: images/nc-install-output.png - :width: 80% +.. image:: images/nc-install-output.jpg :alt: Output from Netclient Install :align: center @@ -123,8 +132,7 @@ Repeat the above steps for every machine you would like to add to your network. Once installed on all nodes, you can test the connection by pinging the private address of any node from any other node. -.. image:: images/ping-node.png - :width: 80% +.. image:: images/ping-node.jpg :alt: Node Success :align: center @@ -133,29 +141,28 @@ Manage Nodes/Hosts Your machines should now be visible in the control panel. -.. image:: images/nodes.png +.. image:: images/nodes.jpg :width: 80% :alt: Node Success :align: center As of v0.18.0 each node has an associated host. The host is a structure that encapsulates the node and gives it the information it needs like the name and network. The host will have features like creating a proxy, setting the hosted node as a default node, joining the hosted node to new networks without the need for another access key, setting verbosity, and changing listening ports and default interfaces. Server relays will also be handled by the host. The Hosts can be found in the Hosts tab on the UI. You should be taken to a screen like this. -.. image:: images/netmakerhostpage.png +.. image:: images/netmakerhostpage.jpg :width: 80% :alt: Host page :align: center In here you can see the host's name, the endpoint of the server running netclient, the public key for that host, the version number, and a switch to set that host's node as the default node. When this is switched on, that node will serve as the default node when a network is created (similar to netmaker-1 in versions before v0.18.0). Clicking on a host will bring you to the host's details. -.. image:: images/hostdetails.png +.. image:: images/hostdetails.jpg :width: 80% :alt: details screen of the host :align: center This will give you more information like the firewall in use, MTUs, and listening port. You can also see networks associated with that host and options to edit or delete the host. If you are going to delete a Host, you need to delete the associated node first. -.. image:: images/hostedit.png - :width: 80% +.. image:: images/hostedit.jpg :alt: Edit screen of a host :align: center @@ -163,7 +170,7 @@ In the edit screen, you can make changes to the logging verbosity, listening por You can view/modify/delete any node by selecting it in the NODES tab. For instance, you can change the name to something more sensible like "workstation" or "api server". You can also modify network settings here, such as keys or the WireGuard port. These settings will be picked up by the node on its next check-in. For more information, see Advanced Configuration in the :doc:`Using Netmaker <./usage>` docs. -.. image:: images/node-details.png +.. image:: images/node-details.jpg :width: 80% :alt: Node Success :align: center diff --git a/how-to-guides.rst b/how-to-guides.rst new file mode 100644 index 00000000..6f0c892f --- /dev/null +++ b/how-to-guides.rst @@ -0,0 +1,65 @@ +============== +How-to-Guides +============== + + +Egress Gateway +=============== + + +Netmaker allows your clients to reach external networks via an Egress Gateway. The Egress Gateway is a netclient which has been deployed to a server or router with access to a given subnet. + +In the Netmaker UI, that node is set as an "egress gateway." Range(s) are specified which this node has access to. Once created, all clients (and all new ext clients) in the network will be able to reach those ranges via the gateway. + +.. toctree:: + :maxdepth: 2 + + egress-gateway + +Ingress Gateway/External Clients +================================= + +Netmaker allows for "external clients" to reach into a network and access services via an Ingress Gateway. So what is an "external client"? An external client is any machine which cannot or should not be meshed. This can include: + - Phones + - Laptops + - Desktops + +.. toctree:: + :maxdepth: 2 + + external-clients + +Access Control Lists +====================== +By default, Netmaker creates a "full mesh," meaning every node in your network can talk to every other node. You don't always want this to be the case. Sometimes, only some connections should be valid. That's why Netmaker has ACLs. By using Netmaker's ACL feature, you can enable/disable any peer-to-peer connection in your network to remove its ability to communicate. + +.. toctree:: + :maxdepth: 2 + + acls + +Netmaker Professional +====================== + +Netmaker Professional is our advanced Netmaker offering for business use cases. It offers all the features of community edition plus: + +- **Metrics:** Nodes collect networking metrics such as latency, transfer, and connectivity status. These are displayed in the Netmaker UI, and also exported to Grafana via Prometheus. + +- **Users:** Community netmaker has rudimentary users, but Professional gives you the ability to create access levels to control network access, and even create groups to organize users. This allows users to log into the dashboard who can only manage ext clients for themselves, or nodes. + +- **Remote Access Client:** Netmaker Professional comes with a remote access client that allows you to connect to your network from anywhere. This is a great way to connect to your network from a laptop or mobile device (soon). + +- **Rely:** Netmaker Professional enables a node to be designated as a relay and to identify which node(s) it should relay. All traffic to/from relayed node(s) will transverse via the relay. + +.. toctree:: + :maxdepth: 1 + + pro/index + +External Guides +================ + +.. toctree:: + :maxdepth: 2 + + usage diff --git a/images/acls-2.jpg b/images/acls-2.jpg new file mode 100644 index 00000000..878de353 Binary files /dev/null and b/images/acls-2.jpg differ diff --git a/images/acls-2.png b/images/acls-2.png deleted file mode 100644 index 79b814b8..00000000 Binary files a/images/acls-2.png and /dev/null differ diff --git a/images/acls-4.jpg b/images/acls-4.jpg new file mode 100644 index 00000000..a8e6cccf Binary files /dev/null and b/images/acls-4.jpg differ diff --git a/images/acls-4.png b/images/acls-4.png deleted file mode 100644 index 28e2a9ea..00000000 Binary files a/images/acls-4.png and /dev/null differ diff --git a/images/create-net.jpg b/images/create-net.jpg new file mode 100644 index 00000000..94eeecb8 Binary files /dev/null and b/images/create-net.jpg differ diff --git a/images/create-net.png b/images/create-net.png deleted file mode 100644 index ffdfb5ed..00000000 Binary files a/images/create-net.png and /dev/null differ diff --git a/images/disconnect.jpg b/images/disconnect.jpg new file mode 100644 index 00000000..933dde1b Binary files /dev/null and b/images/disconnect.jpg differ diff --git a/images/disconnect.png b/images/disconnect.png deleted file mode 100644 index 8c907c3c..00000000 Binary files a/images/disconnect.png and /dev/null differ diff --git a/images/enrollmentkeycreate.jpg b/images/enrollmentkeycreate.jpg new file mode 100644 index 00000000..32469daa Binary files /dev/null and b/images/enrollmentkeycreate.jpg differ diff --git a/images/enrollmentkeycreate.png b/images/enrollmentkeycreate.png deleted file mode 100644 index bb3b9456..00000000 Binary files a/images/enrollmentkeycreate.png and /dev/null differ diff --git a/images/enrollmentkeyinvalid.jpg b/images/enrollmentkeyinvalid.jpg new file mode 100644 index 00000000..6f4457ef Binary files /dev/null and b/images/enrollmentkeyinvalid.jpg differ diff --git a/images/enrollmentkeyinvalid.png b/images/enrollmentkeyinvalid.png deleted file mode 100644 index 0ca0c4be..00000000 Binary files a/images/enrollmentkeyinvalid.png and /dev/null differ diff --git a/images/enrollmentkeytoken.jpg b/images/enrollmentkeytoken.jpg new file mode 100644 index 00000000..3bd7e6fd Binary files /dev/null and b/images/enrollmentkeytoken.jpg differ diff --git a/images/enrollmentkeytoken.png b/images/enrollmentkeytoken.png deleted file mode 100644 index 4d2f9c73..00000000 Binary files a/images/enrollmentkeytoken.png and /dev/null differ diff --git a/images/extclient1.png b/images/extclient1.png index 59b84763..fe779d11 100644 Binary files a/images/extclient1.png and b/images/extclient1.png differ diff --git a/images/extclient2.png b/images/extclient2.png index db53382a..4e710d14 100644 Binary files a/images/extclient2.png and b/images/extclient2.png differ diff --git a/images/extclient3.png b/images/extclient3.png index 702dbf71..4c07ed9a 100644 Binary files a/images/extclient3.png and b/images/extclient3.png differ diff --git a/images/hostdetails.jpg b/images/hostdetails.jpg new file mode 100644 index 00000000..5494d7f7 Binary files /dev/null and b/images/hostdetails.jpg differ diff --git a/images/hostdetails.png b/images/hostdetails.png deleted file mode 100644 index 68ccfa65..00000000 Binary files a/images/hostdetails.png and /dev/null differ diff --git a/images/hostedit.jpg b/images/hostedit.jpg new file mode 100644 index 00000000..02d10805 Binary files /dev/null and b/images/hostedit.jpg differ diff --git a/images/hostedit.png b/images/hostedit.png deleted file mode 100644 index 3789031e..00000000 Binary files a/images/hostedit.png and /dev/null differ diff --git a/images/internet-gateway.png b/images/internet-gateway.png index 81dabb8a..82a5ebb2 100644 Binary files a/images/internet-gateway.png and b/images/internet-gateway.png differ diff --git a/images/nc-install-output.jpg b/images/nc-install-output.jpg new file mode 100644 index 00000000..10c5347f Binary files /dev/null and b/images/nc-install-output.jpg differ diff --git a/images/nc-install-output.png b/images/nc-install-output.png deleted file mode 100644 index 303c7e9e..00000000 Binary files a/images/nc-install-output.png and /dev/null differ diff --git a/images/netclientcli.jpg b/images/netclientcli.jpg new file mode 100644 index 00000000..85a23b8a Binary files /dev/null and b/images/netclientcli.jpg differ diff --git a/images/netclientcli.png b/images/netclientcli.png deleted file mode 100644 index 6e906d04..00000000 Binary files a/images/netclientcli.png and /dev/null differ diff --git a/images/netclientconnectedGUI.jpg b/images/netclientconnectedGUI.jpg new file mode 100644 index 00000000..b1e83cdb Binary files /dev/null and b/images/netclientconnectedGUI.jpg differ diff --git a/images/netclientconnectedGUI.png b/images/netclientconnectedGUI.png deleted file mode 100644 index b40b9e94..00000000 Binary files a/images/netclientconnectedGUI.png and /dev/null differ diff --git a/images/netclientdetailsGUI.jpg b/images/netclientdetailsGUI.jpg new file mode 100644 index 00000000..50736824 Binary files /dev/null and b/images/netclientdetailsGUI.jpg differ diff --git a/images/netclientdetailsGUI.png b/images/netclientdetailsGUI.png deleted file mode 100644 index 3608bae8..00000000 Binary files a/images/netclientdetailsGUI.png and /dev/null differ diff --git a/images/netclientjoinGUI.jpg b/images/netclientjoinGUI.jpg new file mode 100644 index 00000000..d1ee7ada Binary files /dev/null and b/images/netclientjoinGUI.jpg differ diff --git a/images/netclientjoinGUI.png b/images/netclientjoinGUI.png deleted file mode 100644 index 7d809bbd..00000000 Binary files a/images/netclientjoinGUI.png and /dev/null differ diff --git a/images/netclientjoincli.jpg b/images/netclientjoincli.jpg new file mode 100644 index 00000000..cd19ff4b Binary files /dev/null and b/images/netclientjoincli.jpg differ diff --git a/images/netclientjoincli.png b/images/netclientjoincli.png deleted file mode 100644 index 0e1d977a..00000000 Binary files a/images/netclientjoincli.png and /dev/null differ diff --git a/images/netclienttokenGUI.jpg b/images/netclienttokenGUI.jpg new file mode 100644 index 00000000..9d4bed09 Binary files /dev/null and b/images/netclienttokenGUI.jpg differ diff --git a/images/netclienttokenGUI.png b/images/netclienttokenGUI.png deleted file mode 100644 index 2133cb3d..00000000 Binary files a/images/netclienttokenGUI.png and /dev/null differ diff --git a/images/netmaker-github/readme.gif b/images/netmaker-github/readme.gif index 650b9034..6d9b18c8 100644 Binary files a/images/netmaker-github/readme.gif and b/images/netmaker-github/readme.gif differ diff --git a/images/netmaker-node.jpg b/images/netmaker-node.jpg new file mode 100644 index 00000000..529c72df Binary files /dev/null and b/images/netmaker-node.jpg differ diff --git a/images/netmaker-node.png b/images/netmaker-node.png deleted file mode 100644 index 88068785..00000000 Binary files a/images/netmaker-node.png and /dev/null differ diff --git a/images/netmakerhostpage.jpg b/images/netmakerhostpage.jpg new file mode 100644 index 00000000..9e111a5c Binary files /dev/null and b/images/netmakerhostpage.jpg differ diff --git a/images/netmakerhostpage.png b/images/netmakerhostpage.png deleted file mode 100644 index 817b8ae4..00000000 Binary files a/images/netmakerhostpage.png and /dev/null differ diff --git a/images/network-created.jpg b/images/network-created.jpg new file mode 100644 index 00000000..173455a1 Binary files /dev/null and b/images/network-created.jpg differ diff --git a/images/network-created.png b/images/network-created.png deleted file mode 100644 index 5c46cb92..00000000 Binary files a/images/network-created.png and /dev/null differ diff --git a/images/networkjoinui.jpg b/images/networkjoinui.jpg new file mode 100644 index 00000000..ce90a258 Binary files /dev/null and b/images/networkjoinui.jpg differ diff --git a/images/networkjoinui.png b/images/networkjoinui.png deleted file mode 100644 index d127b860..00000000 Binary files a/images/networkjoinui.png and /dev/null differ diff --git a/images/node-details.jpg b/images/node-details.jpg new file mode 100644 index 00000000..41dc8b10 Binary files /dev/null and b/images/node-details.jpg differ diff --git a/images/node-details.png b/images/node-details.png deleted file mode 100644 index 7b8852f3..00000000 Binary files a/images/node-details.png and /dev/null differ diff --git a/images/nodes.jpg b/images/nodes.jpg new file mode 100644 index 00000000..b1b3739d Binary files /dev/null and b/images/nodes.jpg differ diff --git a/images/nodes.png b/images/nodes.png deleted file mode 100644 index af4b295e..00000000 Binary files a/images/nodes.png and /dev/null differ diff --git a/images/oauth1.jpg b/images/oauth1.jpg new file mode 100644 index 00000000..6313ea40 Binary files /dev/null and b/images/oauth1.jpg differ diff --git a/images/oauth1.png b/images/oauth1.png deleted file mode 100644 index aa6fbfeb..00000000 Binary files a/images/oauth1.png and /dev/null differ diff --git a/images/oauth2.jpg b/images/oauth2.jpg new file mode 100644 index 00000000..5213be87 Binary files /dev/null and b/images/oauth2.jpg differ diff --git a/images/oauth2.png b/images/oauth2.png deleted file mode 100644 index 83baae2c..00000000 Binary files a/images/oauth2.png and /dev/null differ diff --git a/images/oauth3.jpg b/images/oauth3.jpg new file mode 100644 index 00000000..d8814dfc Binary files /dev/null and b/images/oauth3.jpg differ diff --git a/images/oauth3.png b/images/oauth3.png deleted file mode 100644 index 35a12ce7..00000000 Binary files a/images/oauth3.png and /dev/null differ diff --git a/images/ping-node.jpg b/images/ping-node.jpg new file mode 100644 index 00000000..48153aa1 Binary files /dev/null and b/images/ping-node.jpg differ diff --git a/images/ping-node.png b/images/ping-node.png deleted file mode 100644 index 0638740f..00000000 Binary files a/images/ping-node.png and /dev/null differ diff --git a/index.rst b/index.rst index 6a9b0116..ebd926d8 100644 --- a/index.rst +++ b/index.rst @@ -20,232 +20,38 @@ This documentation covers Netmaker's :doc:`installation <./server-installation>` **For Kubernetes-specific guidance, please see the** `Netmaker Kubernetes Documentation. `_ -About --------- -High-level information about what Netmaker is and how it works. .. toctree:: - :maxdepth: 2 + :maxdepth: 3 about - - architecture - -Getting Started ------------------------------------- - -How to install Netmaker and set up your first network. - -.. toctree:: - :maxdepth: 2 - - install - - quick-start - getting-started - -Netclient ------------------------------------- - -Client-side instructions for joining a network and managing a machine locally. - -.. toctree:: - :maxdepth: 2 - - netclient - -Ingress, Egress, and Relays ------------------------------- - -How to give machines outside of the Netmaker network access to network resources via an Ingress Gateway: - -.. toctree:: - :maxdepth: 2 - - external-clients - -How to give machines inside the Netmaker network access to external network resources via an Egress Gateway: - - -.. toctree:: - :maxdepth: 2 - - egress-gateway - -How to make machines inside the network reachable if they are blocked by NAT/Firewall: - - - -.. toctree:: - :maxdepth: 2 - - turn-server - -Access Control and Zero Trust ------------------------------- - -Fine-grained control of your networks. Enable or disable any peer-to-peer connection to decide which machines can talk to which other machines. - -.. toctree:: - :maxdepth: 2 - - acls - -Kubernetes Documentation ---------------------------- - -.. toctree:: - - Kubernetes - -`Netmaker Kubernetes Documentation `_ - - -Professional Documentation ---------------------------- - -.. toctree:: - :maxdepth: 2 - - pro/index - -Users in Netmaker Professional ------------------------------- - -.. toctree:: - :maxdepth: 2 - - pro/pro-users - -Advanced Server Installation -------------------------------- - -A detailed guide to installing the Netmaker server (API, DB, UI, DNS), and configuration options. - -.. toctree:: - :maxdepth: 2 - - server-installation - -Advanced Client Installation --------------------------------- - -A detailed guide to installing the Netmaker agent (netclient) on devices and configuration options. - -.. toctree:: - :maxdepth: 2 - - advanced-client-install - - -Oauth Configuration --------------------- - -A simple guide to configuring OAuth for Netmaker. - -.. toctree:: - :maxdepth: 2 - - oauth - - -External Guides ----------------- - -A handful of guides for use cases including site-to-site, Kubernetes, private DNS, and more. - -.. toctree:: - :maxdepth: 2 - - usage - -UI Reference ---------------- - -A reference document for the Netmaker Server UI, with annotated screenshot detailing each field. - -.. toctree:: - :maxdepth: 2 - - ui-reference - -API Reference ---------------- - -A reference document for the Netmaker Server API, and example API calls for various use cases. - -.. toctree:: - :maxdepth: 1 - - api - -Upgrades ----------------- - -Upgrading the Netmaker server and clients. - -.. toctree:: - :maxdepth: 1 - + features upgrades + how-to-guides + references + license + conduct -NMCTL ----------------- - -A reference document for the Netmaker CLI tool nmctl. - -.. toctree:: - :maxdepth: 1 - nmctl.rst -NMCTL - Standalone --------------------- -A reference document for using Netmaker without a UI. -.. toctree:: - :maxdepth: 1 - nmctl-standalone.rst -Troubleshooting ----------------- -Help with common Netmaker/netclient issues. -.. toctree:: - :maxdepth: 2 - troubleshoot -Support ----------------- -Where to go for help, and a FAQ. - -.. toctree:: - :maxdepth: 2 - support -Code of Conduct ------------------ -A statement on our expectations and pledge to the community. -.. toctree:: - conduct.rst -Licensing ---------------- -A link to the Netmaker license. -.. toctree:: - license.rst diff --git a/license.rst b/license.rst index 3e81c466..dd9d3de1 100644 --- a/license.rst +++ b/license.rst @@ -2,5 +2,5 @@ License ======= -Netmaker's source code and all artifacts in this repository are freely available. All versions are published under the Server Side Public License (SSPL), version 1, which can be found `here `_. +Netmaker's source code and all artifacts in this repository are freely available. All versions are published under the Aache License, which can be found `here `_. diff --git a/netclient.rst b/netclient.rst index cb1f0f4f..80c3fe46 100644 --- a/netclient.rst +++ b/netclient.rst @@ -1,6 +1,6 @@ -================================ -Netclient Setup -================================ +========== +Netclient +========== As of v0.18.0 Netclient is now in its own standalone repo seperate from netmaker. @@ -13,8 +13,7 @@ The UI has been updated for Mac and Windows, And the CLI has been updated. -.. image:: images/netclientcli.png - :width: 80% +.. image:: images/netclientcli.jpg :alt: netclient CLI :align: center @@ -29,7 +28,7 @@ The Netclient is supported on the following operating systems: * macOS * FreeBSD -For unsupported devices, please use the external client, which is just a static, vanilla, WireGuard configuration file, which can be added to any device that supports WireGuard. +For unsupported devices, please use the Remote Access Client config, which is just a static, vanilla, WireGuard configuration file, which can be added to any device that supports WireGuard. ****************** Installation @@ -54,8 +53,8 @@ Debian Distros (debian/ubuntu/mint/pop-os) .. code-block:: - curl -sL 'https://apt.netmaker.org/gpg.key' | sudo tee /etc/apt/trusted.gpg.d/netclient.asc - curl -sL 'https://apt.netmaker.org/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/netclient.list + curl -sL 'https://apt.netmaker.org/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/netmaker-keyring.gpg + echo "deb [signed-by=/usr/share/keyrings/netmaker-keyring.gpg] https://apt.netmaker.org stable main" | sudo tee /etc/apt/sources.list.d/netclient.list sudo apt update sudo apt install netclient @@ -85,6 +84,17 @@ OpenWRT Distros (mips/mipsle) refer to Advanced Client Installation :ref:`advanced-client-install:Notes on OpenWRT` +OpenSUSE (tumbleweed/leap) +--------------------------------------------------------------------- + +.. code-block:: shell + + sudo rpm --import https://rpm.netmaker.org/gpg.key + curl -sL 'https://rpm.netmaker.org/netclient-repo' | sudo tee /etc/zypp/repos.d/netclient.repo + sudo zypper refresh + sudo zypper install netclient + + Windows =============== @@ -155,14 +165,14 @@ If you prefer (e.g., when specifying a lot of environment variables), you can us environment: - TOKEN= - PORT= - - ENPOINT= + - ENDPOINT= - MTU= - HOST_NAME= - IS_STATIC= volumes: - '/etc/netclient:/etc/netclient' container_name: netclient - image: 'gravitl/netclient:v0.18.0' + image: 'gravitl/netclient:latest' where is the Access Token available from the "Viewing your Access Key Details" window in the Netmaker UI. @@ -179,16 +189,22 @@ Your compose would look more like this: services: netclient: privileged: true + network_mode: host restart: always environment: - TOKEN= - - VERBOSITY=<0-4> + - PORT= + - ENDPOINT= + - MTU= + - HOST_NAME=nc-docker-2 + - IS_STATIC= + - IFACE_NAME=netmaker-2 volumes: - '/etc/netclient2:/etc/netclient' container_name: netclient2 - image: 'gravitl/new-netclient:v0.20.5' + image: 'gravitl/netclient:latest' -By using this method, you can run many netclients on the same host and just incrementing up (netclient3, netclient4 ..... netclientN). +By using this method, you can run many netclients on the same host and just incrementing up the volumes (netclient3, netclient4 ..... netclientN) and make sure to set the interface name, so that it won't conflict with existing netclients running on same host. **IMPORTANT:** @@ -205,7 +221,7 @@ Joining a Network The join command provides the following flags with short descriptions on what each one does. -.. image:: images/netclientjoincli.png +.. image:: images/netclientjoincli.jpg :width: 80% :alt: netclient CLI :align: center @@ -239,22 +255,22 @@ Again, if you are making a docker container on an already existing baremetal net .. code-block:: - docker run -d --privileged -e TOKEN= -v /etc/netclient2:/etc/netclient --name netclient2 gravitl/new-netclient: + docker run -d --network host --privileged -e TOKEN= -e HOST_NAME=nc-docker-2 -e IFACE_NAME="netmaker-2" -v /etc/netclient2:/etc/netclient --name netclient2 gravitl/new-netclient: -And again host networking will be turned off in this case and will not have the private address of the contianer and it will be segmented. +Make sure interface name you pass when running multiple netclient containers on same host doesn't conflict with each other. These commands will be available to copy and paste in the access keys section of your netmaker UI. You can set the verbosity to a level 0-4 with the flag ``-v `` in the join command if you need more info about the join. To join on the GUI with Windows or Mac, just click the ADD NEW button and you will be given a choice of token or Username/Password. -.. image:: images/netclientjoinGUI.png +.. image:: images/netclientjoinGUI.jpg :width: 80% :alt: netclient join through GUI :align: center Choose token and you will be taken to a screen where you will enter the Access Token found in the access keys tab of the netmaker UI. -.. image:: images/netclienttokenGUI.png +.. image:: images/netclienttokenGUI.jpg :width: 80% :alt: netclient token screen :align: center @@ -277,14 +293,14 @@ The Server name will be in the and the network will be in If the join was successful, you should see the network on the GUI. -.. image:: images/netclientconnectedGUI.png +.. image:: images/netclientconnectedGUI.jpg :width: 80% :alt: netclient GUI showing a connected network :align: center You should be able to click on that network and see the details page on that network. -.. image:: images/netclientdetailsGUI.png +.. image:: images/netclientdetailsGUI.jpg :width: 80% :alt: netclient GUI network details :align: center @@ -309,7 +325,7 @@ You can also disconnect and reconnect from the UI. Click on the node you want to On the bottom, you should see a switch labeled connected like this one. toggle the switch and hit submit. That client will connect or disconnect accordingly. -.. image:: images/disconnect.png +.. image:: images/disconnect.jpg :width: 80% :alt: connect/disconnect button :align: center diff --git a/nmctl-standalone.rst b/nmctl-standalone.rst index 06eae227..3740af22 100644 --- a/nmctl-standalone.rst +++ b/nmctl-standalone.rst @@ -9,12 +9,12 @@ Assumptions ****************** 1. using bash shell -2. netclient, nmctl and jq have been installed -3. netmaker server has been set up at example.com without UI (netmaker-ui section of docker-compose.yml has been deleted) +2. nmctl and jq have been installed +3. netmaker server has been set up at example.com. This can be a SaaS (managed) tenant as well. -*********************** -Setup superadmin user -*********************** +********************* +Setup superadmin user +********************* Set base domain ================ @@ -22,8 +22,10 @@ Set base domain export NN_DOMAIN=example.com + Create SuperAdmin User -======================= +====================== + .. code-block:: curl --location 'https://api.$NM_DOMAIN/api/users/adm/createsuperadmin' \ @@ -52,10 +54,10 @@ Create Normal User nmctl user create --name --password ************************* -Normal Operations by user +Normal Operations by user ************************* -*assume that users have been created by superAdmin* +*assume that users have been created by superadmin* *********************** Set username/password @@ -66,13 +68,14 @@ Set username/password export PASSWORD= - ****************** Set User Context ****************** .. code-block:: nmctl context set commandline --endpoint https://api.$NM_DOMAIN --username $USER --password $PASSWORD + nmctl context use commandline + ****************** Create Network diff --git a/nmctl.rst b/nmctl.rst index 2a01efff..80327205 100644 --- a/nmctl.rst +++ b/nmctl.rst @@ -31,7 +31,7 @@ If everything is setup ok, you should be able to type ``nmctl`` and see the foll context Manage various netmaker server configurations dns Manage DNS entries associated with a network enrollment_key Manage Enrollment Keys - ext_client Manage External Clients + ext_client Manage Remote Access Clients help Help about any command host Manage hosts logs Retrieve server logs @@ -51,22 +51,79 @@ If everything is setup ok, you should be able to type ``nmctl`` and see the foll Your CLI should be ready to go at this point. -Before running any commands, a context has to be set which stores the API endpoint information. +Context +============= + +Before running any commands, a context has to be set which stores the API endpoint information. This allows the CLI to know which server to communicate with, and the user account to use. + +NMCLI supports connecting to both standalone (self-hosted) and SaaS(managed) tenants. This is specified with a flag. More details below. + + +Connecting to standalone (self-hosted) tenants +---------------------------------------------- + +Assuming your tenant is hosted at `https://api.netmaker.example.com` You can use your `username` and `password` that you use to sign in to the dashboard UI to set the context. Then you can set the CLI to use that context. .. code-block:: - nmctl context set dev --endpoint=https://api.netmaker.domain.com --username=admin --password=YOUR_PASSWORD - nmctl context use dev # this sets any defined context as the current context + nmctl context set --endpoint=https://api.netmaker.example.com --username= --password= # create the context + nmctl context use # apply the created context -You can see a list of all your networks that you have set with the following. +You can also authenticate via OAuth with the following: .. code-block:: - nmctl context list + nmctl context set --endpoint=https://api.netmaker.example.com --sso # create the context for OAuth (Social Sign On) + nmctl context use # apply the created context + + +Connecting to SaaS (managed) tenants +------------------------------------ + +You can also authenticate with a managed (SaaS) tenant with the following commands: + +.. code-block:: + + nmctl context set --saas --tenant_id= --username= --password= # create the context + nmctl context use # apply the created context + +You can also authenticate via OAuth with the following: + +.. code-block:: + + nmctl context set --saas --sso --tenant_id= # create the context for OAuth (Social Sign On) + nmctl context use # apply the created context + + +List and switch between contexts +-------------------------------- + +You can see a list of all your contexts that you have created with the following: + +.. code-block:: + + nmctl context list + +That list also tells you what context/tenant is currently selected. + +You can switch to a different context by using the `use` subcommand: + +.. code-block:: + + nmctl context use + + +Delete contexts +--------------- + +You can delete a context with the following: + +.. code-block:: + + nmctl context delete -That list also tells you what network is currently set. Network ============= @@ -142,17 +199,17 @@ Fetching the node list once again we can see that our node has been turned into +--------------+---------------------------+---------+----------+--------+---------+-------+--------------------------------------+ -External Clients -================== +Remote Access Clients +===================== -Adding an :doc:`external client <./external-clients>` to the network is just as easy. Requires the `network name` and `node id` as input parameters. +Adding a :doc:`Remote Access Client <./external-clients>` to the network is just as easy. Requires the `network name` and `node id` as input parameters. .. code-block:: nmctl ext_client create test_net 938d7861-55fc-40a9-970d-6d70acfc3a80 Success -List all available external clients. +List all available Remote Access Clients. .. code-block:: @@ -163,7 +220,7 @@ List all available external clients. | limp-chicken |test_net | 10.11.13.2 | | true | 2022-11-23 18:28:57 +0530 IST | +--------------+---------+--------------+--------------+---------+-------------------------------+ -The wireguard config of an external client can also be fetched with the `network name` and `external client id`. +The wireguard config of an Remote Access Client can also be fetched with the `network name` and `client id`. .. code-block:: @@ -181,6 +238,41 @@ The wireguard config of an external client can also be fetched with the `network Endpoint = 138.209.145.214:51824 PersistentKeepalive = 20 + +ACLs +===== + +Access Control between hosts can be managed via the NMCTL CLI. These settings allow the network admin to specify which hosts are allowed to communicate between each other. + +List +---- + +To list all access control settings for a network: + +.. code-block:: + + nmctl acl list + +Allow/Deny +---------- + +To allow communication between two hosts on a network: + +.. code-block:: + + nmctl acl allow + +To deny communication between two hosts: + +.. code-block:: + + nmctl acl deny + +Host IDs can be retrieved with the `nmctl node list` command. + +The global `--output` flag can be used to format how a network's ACLs are outputted. + + Help ======= diff --git a/oauth.rst b/oauth.rst index 183ce9aa..6ea87d33 100644 --- a/oauth.rst +++ b/oauth.rst @@ -59,8 +59,7 @@ After restarting your server, the Netmaker logs will indicate if the OAuth provi Once successful, users can click the key symbol on the login page to sign-in with your configured OAuth provider. -.. image:: images/oauth1.png - :width: 80% +.. image:: images/oauth1.jpg :alt: Login Oauth :align: center @@ -73,12 +72,11 @@ Admins must navigate to the "Users" screen to configure permissions. For each user, an admin must specify which networks that user has access to configure. Additionally, an Admin can elevate a user to Admin permissions. -.. image:: images/oauth3.png - :width: 80% +.. image:: images/oauth3.jpg :alt: Edit User 2 :align: center -.. image:: images/oauth2.png +.. image:: images/oauth2.jpg :width: 80% :alt: Edit User :align: center diff --git a/pro/images/failOverselect.jpg b/pro/images/failOverselect.jpg new file mode 100644 index 00000000..85047518 Binary files /dev/null and b/pro/images/failOverselect.jpg differ diff --git a/pro/images/failOvertab.jpg b/pro/images/failOvertab.jpg new file mode 100644 index 00000000..05f61b90 Binary files /dev/null and b/pro/images/failOvertab.jpg differ diff --git a/pro/images/users/remote-access-client-2.png b/pro/images/users/remote-access-client-2.png index 6822537b..f7f80d37 100644 Binary files a/pro/images/users/remote-access-client-2.png and b/pro/images/users/remote-access-client-2.png differ diff --git a/pro/images/users/remote-access-client-3.png b/pro/images/users/remote-access-client-3.png index 82c0379e..83b9acb2 100644 Binary files a/pro/images/users/remote-access-client-3.png and b/pro/images/users/remote-access-client-3.png differ diff --git a/pro/images/users/remote-access-client.png b/pro/images/users/remote-access-client.png index a0f4a48a..c941f5f5 100644 Binary files a/pro/images/users/remote-access-client.png and b/pro/images/users/remote-access-client.png differ diff --git a/pro/index.rst b/pro/index.rst index 8cf3594e..987e40c8 100644 --- a/pro/index.rst +++ b/pro/index.rst @@ -9,19 +9,6 @@ :alt: Netmaker WireGuard :align: center -=================================================== -Netmaker Professional Documentation -=================================================== - -Netmaker Professional is our advanced Netmaker offering for business use cases. It offers all the features of community edition plus: - -- **Metrics:** Nodes collect networking metrics such as latency, transfer, and connectivity status. These are displayed in the Netmaker UI, and also exported to Grafana via Prometheus. - -- **Users:** Community netmaker has rudimentary users, but Professional gives you the ability to create access levels to control network access, and even create groups to organize users. This allows users to log into the dashboard who can only manage ext clients for themselves, or nodes. - -- **Remote Access Client:** Netmaker Professional comes with a remote access client that allows you to connect to your network from anywhere. This is a great way to connect to your network from a laptop or mobile device (soon). - - Setup -------- @@ -32,6 +19,14 @@ How to set up Netmaker Professional pro-setup +Users +--------------- + +.. toctree:: + :maxdepth: 2 + + pro-users + Relays --------------- @@ -66,3 +61,11 @@ Remote Access Client :maxdepth: 2 rac + +FailOvers +----------------------- + +.. toctree:: + :maxdepth: 2 + + pro-failovers diff --git a/pro/pro-failovers.rst b/pro/pro-failovers.rst new file mode 100644 index 00000000..3cca7004 --- /dev/null +++ b/pro/pro-failovers.rst @@ -0,0 +1,34 @@ +===================================== +FailOver Servers +===================================== + +Introduction +=============== + +Sometimes nodes are in hard-to-reach places. Typically this will be due to a CGNAT, Double NAT, or a restrictive firewall. In such scenarios, a direct peer-to-peer connection with all other nodes might be impossible. + +For this reason, Netmaker has a FailOver functionality. At any time you may designate a publicly reachable node (such as the Netmaker Server) as a FailOver, and netmaker will identify if any peers in the network are not able to +communicate directly then their connection will automatically fallback through the failOver node in the network + +Configuring a FailOver node +================================== + +To create a failover, you can use any host in your network, but it should have a public IP address (not behind a NAT). + +Navigate to the network tab and click on the hosts tab + +.. image:: images/failOvertab.jpg + :width: 80% + :alt: FailOver + :align: center + +You can choose any public node in the network to be a failover, Once chosen any peers facing difficulties to communicate directly with each other, will have connection go over the failover node. + +To reset the network connections, you can remove the failover node, and network will go back to original state from if any connections are getting failed over. + +.. image:: images/failOverselect.jpg + :width: 80% + :alt: FailOver + :align: center + + diff --git a/pro/pro-metrics.rst b/pro/pro-metrics.rst index 6178a348..9eb48745 100644 --- a/pro/pro-metrics.rst +++ b/pro/pro-metrics.rst @@ -37,8 +37,14 @@ Grafana Dashboard ================================= If your Netmaker instance includes the Prometheus/Grafana setup and is configured with the `METRICS_EXPORTER="on"`, you -can also view your metrics via Grafana. Simply navigate to the `dashboards` section of your Grafana instance. There, -you will be presented with two out-of-the-box Netmaker options of the following: +can also view your metrics via Grafana. Simply navigate to the `dashboards` section of your Grafana instance. +.. code-block:: + + URL: "https://grafana." + Username: "admin" + Password: "admin" + +There, you will be presented with two out-of-the-box Netmaker options of the following: - `Netmaker Metrics Dashboard` - `Netmaker Network Graph` @@ -64,8 +70,9 @@ Or hover an edge to view information about the connection between two nodes. The :alt: Netmaker Grafana View 2 :align: center -Also you can view your metrics on `prometheus dashboard`,for the first time you will be prompted for credentials in your brower when you visit your prometheus dashboard. +Also you can view your metrics on `prometheus dashboard`, for the first time you will be prompted for credentials in your brower when you visit your prometheus dashboard. .. code-block:: - UserName: "Netmaker-Prometheus" + URL: "https://prometheus." + Username: "Netmaker-Prometheus" Password: "" \ No newline at end of file diff --git a/pro/pro-setup.rst b/pro/pro-setup.rst index 3cc97a04..c0129ccd 100644 --- a/pro/pro-setup.rst +++ b/pro/pro-setup.rst @@ -67,14 +67,14 @@ Upgrade to Pro from Community Edition You can upgrade from an existing community server to a pro server with this script. Follow the prompts to setup a pro server and the script will make the necessary changes to your netmaker.env file and grab the pro docker-compose.override.yml file. -If you prefer to upgrade manually, go to your netmaker server and add the following to your netmaker.env file. +If you prefer to upgrade manually, go to your netmaker server and add the following to your netmaker.env file: -.. code-block:: yaml +.. code-block:: - LICENSE_KEY: “” - NETMAKER_TENANT_ID: "" + LICENSE_KEY= + NETMAKER_TENANT_ID= -Also change ``SERVER_IMAGE_TAG`` in netmaker.env to ``-ee``. For example: ``SERVER_IMAGE_TAG=v0.20.3-ee`` +Also change ``SERVER_IMAGE_TAG`` in netmaker.env to ``-ee``. For example: ``SERVER_IMAGE_TAG=v0.21.2-ee`` Also change the ``INSTALL_TYPE`` from ce to pro. @@ -82,13 +82,17 @@ Then you will need to get the docker-compose pro file from here .. code-block:: - wget -O docker-compose.override.yml https://github.com/gravitl/netmaker/blob/master/compose/docker-compose.pro.yml + wget -o /root/docker-compose.override.yml https://raw.githubusercontent.com/gravitl/netmaker/master/compose/docker-compose.pro.yml No changes will need to be made to that file. It will use the configs listed in your netmaker.env file. -After that ``docker kill netmaker netmaker-ui && docker-compose up -d`` and you should see the professional UI on dashboard. +After that run the following command: + +.. code-block:: + + docker kill netmaker netmaker-ui && docker-compose up -d -You should see a new Dashboard. The top menu bar will have relays and metrics added. +When you browse to your self-hosted Netmaker via dashboard., you should see the professional UI and a new Dashboard. The top menu bar will have relays and metrics added. .. image:: images/pro-new-dashboard.png :width: 80% diff --git a/pro/pro-users.rst b/pro/pro-users.rst index f08f5e8d..58f8c328 100644 --- a/pro/pro-users.rst +++ b/pro/pro-users.rst @@ -4,7 +4,7 @@ Users in Netmaker Professional ================================= Netmaker Professional offers advanced user management features. The super admin can create users with either a user or admin role. Only Admins can access the dashboard, the normal users can use remote access client to join the network through a gateway. -Admins can add users and assign them to client gateways, which includes managing the user's access to different client gateways. +Admins can add users and assign them to remote access gateways, which includes managing the user's access to different remote access gateways. Here is a breakdown of the different user types and their permissions: @@ -28,10 +28,10 @@ To add a user, go to the Users section and click the Add User button. Fill in th The credentials will need to be shared with the added user. -Attaching or removing user from a client gateway -================================================ -To attach users to a client gateway or remove users from a gateway, you will need to have the client gateway set up. -Once the client gateway is set up, you will see an option to remove users from the dropdown menu. +Attaching or removing user from a remote access gateway +======================================================== +To attach users to a remote access gateway or remove users from a gateway, you will need to have the gateway set up. +Once the remote access gateway is set up, you will see an option to attach or remove users from the gateway's dropdown menu on the table row. .. image:: images/users/gateway-dropdown.png :width: 80% diff --git a/pro/rac.rst b/pro/rac.rst index 400de702..5594a641 100644 --- a/pro/rac.rst +++ b/pro/rac.rst @@ -28,34 +28,48 @@ For Linux (Debian/Ubuntu), you can also use the following command to download th sudo apt search remote-client # to see available versions sudo apt install remote-client + +Red Hat Distros (Fedora/RedHat/CentOSRocky) + +.. code-block:: + + curl -sL 'https://rpm.netmaker.org/remote-client/gpg.key' | sudo tee /tmp/gpg.key + curl -sL 'https://rpm.netmaker.org/remote-client/remote-client-repo' | sudo tee /etc/yum.repos.d/remote-client.repo + sudo rpm --import /tmp/gpg.key + sudo dnf check-update + sudo dnf install remote-client + + Following the above instructions, you can run RAC from your Linux desktop environment launcher or from the command line using the `remote-client` command. -For Mac, You can download the mac installer from the fileserver link above and run it. Because the app needs to be run as root, open a teminal. Enter the command ``sudo /Applications/NetmakerRemoteClient.app/Contents/MacOS/remote-client``. +For Mac, You can download the mac installer from the fileserver link above and run it. Because the app needs to be run as root, open a teminal and enter the command ``sudo /Applications/NetmakerRemoteClient.app/Contents/MacOS/remote-client``. For Windows, you can download the remote-access-client_86.msi installer and run it to install on your windows machine. The app will need to be run as administrator. Right click on the desktop icon after installation and click on ``run as administrator``. + ****************** Quick Start ****************** **NOTE**: OpenGL is a requirement for Netmaker RAC to run. If you are running RAC on a virtual machine (especially with Windows as guest OS), you may need to enable 3D acceleration in your virtual machine settings. -To use RAC, you will need to have a Netmaker server running and have a user account on that server. You will also need to have a client gateway set up on the server that you have access to. +To use RAC, you will need to have a Netmaker server running and have a user account on that server. You will also need to have a remote access gateway set up on the server. Client devices connect to the network through the remote access gateway (ingress host). Check :ref:`this section ` on how to create a non-admin user. -RAC is for non-admin users who want to gain remote access to the network, this also provides admins fine-grained control over users in the network by attaching/removing them from a client gateway. +RAC is best suited for non-admin users who want to gain remote access to the network, this also provides admins fine-grained control over users in the network by attaching/removing them from a remote access gateway. Admins can also use RAC to gain remote access to the network with a different machine. Using the Remote Access Client (RAC) ==================================== -Once a user has been added to a client gateway, they can connect to a network using the remote access client. To do this, they will first need to log in using the credentials that were provided to them. +Once a user has been attached to a remote access gateway, they can connect to a network using the remote access client. To do this, they will first need to log in using the credentials that were provided to them. Social login is also supported. .. image:: images/users/remote-access-client.png :width: 80% :alt: Remote access login :align: center -After successful login you will be shown all the networks and gateways you have given access to, so now you will be able to connect/disconnect/refresh your connection to a gateway +After successful login you will be shown all the networks and gateways you have given access to, so now you will be able to connect/disconnect/refresh your connection to a gateway. Internet gateways are depicted with a globe icon. +An internet gateway can be used to route all your traffic through the gateway, this is useful if you want to access the internet without exposing your public IP address. This behaves like a traditional VPN. .. image:: images/users/remote-access-client-2.png :width: 80% @@ -64,7 +78,7 @@ After successful login you will be shown all the networks and gateways you have The remote access client also has the following options: -* Refresh connection: This disconnects the current connection to the client gateway and then reconnects to it. +* Refresh connection: This basically disconnects the current connection to the remote access gateway and then reconnects to it. * Reload clients: This reloads the client data on the page, which can be useful if the data has changed since the page was last loaded. .. image:: images/users/remote-access-client-3.png @@ -72,6 +86,14 @@ The remote access client also has the following options: :alt: Reload clients :align: center +* Reset: This resets all connections to remote access gateways across all Netmaker servers and networks known to the client. This can be useful if you end up with a bad wireguard or network interface configuration or are having trouble connecting to a gateway. you should only use this option if Refresh connection does not work. + + +Using Netmaker like a traditional VPN +====================================== + +Some remote access gateways, specifically internet gateways (depicted by globe icon) can route all your traffic through the them. This can be useful if you want to access the internet without exposing your public IP address. This behaves like a traditional VPN. Internet gateways is a Pro-only feature. + Controlling RAC user sessions ============================= @@ -83,3 +105,16 @@ With `RAC_AUTO_DISABLE` set to true, a non-admin user's remote sessions will be The user will have to relogin to enable their remote session again. NOTE: The `JWT_VALIDITY_DURATION` environment variable also configures all the JWT token validity duration for all users, regardless of whether `RAC_AUTO_DISABLE` is set to `true` or not. + + +FAQs and Known Issues +===================== + +**Q: I am getting an error when trying to connect to a gateway.** + +A: Make sure that the gateway is running healthily and that you have access to it. Also try to "Refresh" and see if that fixes the issue. Otherwise "Reset" all connections and try again. + + +**Q: Other WireGuard-based VPNs interfere with Netmaker RAC.** + +A: This is a known issue. If you have other WireGuard-based VPNs running on your machine, they may interfere with Netmaker RAC. You can try to disable them and see if that fixes the issue. Pro-tip: Netmaker Pro offers internet gateway functionality, so you can use it just as a traditional VPN. For more information, explore the `Remote Access gateway feature `_. diff --git a/quick-start.rst b/quick-start.rst index c1f20efb..6a46387f 100644 --- a/quick-start.rst +++ b/quick-start.rst @@ -21,27 +21,37 @@ Important Notes 0. Prerequisites ================== -- **Virtual Machine** - - - Preferably from a cloud provider (e.x: DigitalOcean, Linode, AWS, GCP, etc.) - - - We **highly recommend** that Netmaker be deployed in a dedicated networking environment. It should not share a local network with the clients which it will be managing. This can cause routing issues. - - We do not recommend Oracle Cloud, as VM's here have been known to cause network interference. +Server +----------------- - - The machine should have a public, static IP address - - - The machine should have at least 1GB RAM and 1 CPU (2GB RAM preferred for production installs) - - - 2GB+ of storage - - - Ubuntu 21.04 Installed +All components of Netmaker can be run on a single server (Virtual Machine or Bare Metal). Here some recommendations for setting up the server: -- **Domain** +- We **highly recommend** that Netmaker be deployed in a dedicated networking environment. It should not share a local network with the clients which it will be managing. This can cause routing issues. +- The machine should have a public, static IP address +- The machine should have at least 1GB RAM and 1 CPU (2GB RAM preferred for production installs) +- 2GB+ of storage +- Ubuntu 21.04 Installed + +If you do not have a host for this server, here are some recommendations: + +- `DigitalOcean (preferred) `_ +- `Linode `_ +- `KeepSec `_ +- `AWS `_ +- `Azure `_ +- `GCP `_ +- We **do not** recommend Oracle Cloud. There are known issues with their network configuration. + +Domain +-------- + +Your server will host several services (netmaker server, UI, etc.) each of which requires a dedicated, public subdomain. Here are some recommendations: - - A publicly owned domain (e.x. example.com, mysite.biz) - - Permission and access to modify DNS records via DNS service (e.x: Route53) - - **Note on Cloudflare:** Many of our users use Cloudflare for DNS. Cloudflare has limitations on subdomains you must be aware of, which can cause issues once Netmaker is deployed. Cloudflare will also proxy connections, which MQ does not like. This can be disabled in the Cloudflare dashboard. If setting up your Netmaker server using Cloudflare for DNS, be aware that the configuration of Cloudflare may cause problems with Netmaker which must be resolved, and at this point, Netmaker is not providing guidance on this setup. +- Use a publicly owned domain (e.x. example.com, mysite.biz) +- Designate a subdomain (e.g. netmaker.example.com) for netmaker's services (e.g. dashboard.netmaker.example.com) +- Make sure you have permission and access to modify DNS records for your domain (e.x: Route53) +- **Note on Cloudflare:** Many of our users use Cloudflare for DNS. Cloudflare has limitations on subdomains you must be aware of, which can cause issues once Netmaker is deployed. Cloudflare will also proxy connections, which MQ does not like. This can be disabled in the Cloudflare dashboard. If setting up your Netmaker server using Cloudflare for DNS, be aware that the configuration of Cloudflare may cause problems with Netmaker which must be resolved, and at this point, Netmaker is not providing guidance on this setup. 1. Prepare DNS ================ @@ -54,10 +64,6 @@ Create a wildcard A record pointing to the public IP of your VM. As an example, - broker.domain -- turn.domain - -- turnapi.domain - If deploying Pro, you will also need records for the following:IsStatic - grafana.domain @@ -86,7 +92,6 @@ Make sure firewall settings are set for Netmaker both on the VM and with your cl Make sure the following ports are open both on the VM and in the cloud security groups: - **443, 80 (tcp):** for Caddy, which proxies the Dashboard (UI), REST API (Netmaker Server), and Broker (MQTT) -- **3479, 8089 (TURN, TURN api):** Port 3479 is commonly used for UDP traffic related to TURN. Similar to STUN, TURN servers need to work effectively with firewalls and NAT devices. By using the reserved port 3479, TURN servers can better handle communication across various network configurations. Port 8089 is not reserved specifically for TURN but is commonly associated with TURN server deployments. - **51821-518XX (udp):** for WireGuard - Netmaker needs one port per network, starting with 51821, so open up a range depending on the number of networks you plan on having. For instance, 51821-51830. - **8085 (exporter Pro):** If you are building a Pro server, you need this port open. - **1883, 8883 8083, 18083 (if using EMQX):** We use two different types of brokers. There is Mosquitto or EMQX. if you are setting up EMQX, these four need to be open for MQTT, SSL MQTT, web sockets, and the EMQX dashbaord/REST api. @@ -155,7 +160,7 @@ You can grab the netmaker.env file here. wget https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/netmaker.default.env cp netmaker.default.env netmaker.env -You can then use a text editor like vim or nano to go in there and fill out the fields. There is an example below to reference. You can get your ip with the command ``ip route get 1 | sed -n 's/^.*src \([0-9.]*\) .*$/\1/p'``. You can also generate random strings for the master key and TURN and MQ passwords with the command ``tr -dc A-Za-z0-9 .nip.io``. +You can then use a text editor like vim or nano to go in there and fill out the fields. There is an example below to reference. You can get your ip with the command ``ip route get 1 | sed -n 's/^.*src \([0-9.]*\) .*$/\1/p'``. You can also generate random strings for the master key and MQ passwords with the command ``tr -dc A-Za-z0-9 .nip.io``. .. code-block:: cfg @@ -167,10 +172,6 @@ You can then use a text editor like vim or nano to go in there and fill out the SERVER_HOST= # The admin master key for accessing the API. Change this in any production installation. MASTER_KEY= - # The username to set for turn api access - TURN_USERNAME= - # The password to set for turn api access - TURN_PASSWORD= # The username to set for MQ access MQ_USERNAME= # The password to set for MQ access @@ -215,12 +216,7 @@ You can then use a text editor like vim or nano to go in there and fill out the # If AUTO, stick with the existing logic for NAT detection # This setting is no longer available from v0.20.5 DEFAULT_PROXY_MODE="off" - # Port to access turn server - TURN_PORT="3479" - # Config for using turn, accepts either true/false - USE_TURN="true" DEBUG_MODE="off" - TURN_API_PORT="8089" # Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST). # Change to "off" to turn off. REST_BACKEND="on" diff --git a/references.rst b/references.rst new file mode 100644 index 00000000..a65cbdb8 --- /dev/null +++ b/references.rst @@ -0,0 +1,59 @@ +============== +References +============== + +UI +==== + +Annotated screenshots of most UI components, detailing the configuration options of each field across Nodes, Networks, DNS, Ext Clients, Users, and more. + +.. toctree:: + :maxdepth: 2 + + ui-reference + +API +==== + +Netmaker can be run without the UI, and all functions can be achieved via API calls + +.. toctree:: + :maxdepth: 2 + + api + +Netclient +=========== +Netclient manages WireGuard on client devices (nodes) + +.. toctree:: + :maxdepth: 2 + + netclient + +NMCTL +====== +nmctl is a CLI tool for interacting with the Netmaker API + +.. toctree:: + :maxdepth: 2 + + nmctl + nmctl-standalone + +FAQ +===== +Frequently Asked Questions + +.. toctree:: + :maxdepth: 2 + + support + +Troubleshooting +================ + +.. toctree:: + :maxdepth: 2 + + troubleshoot diff --git a/server-installation.rst b/server-installation.rst index 0d34dc4b..0944a833 100644 --- a/server-installation.rst +++ b/server-installation.rst @@ -157,7 +157,7 @@ MANAGE_IPTABLES: PORT_FORWARD_SERVICES: **Default:** "" - **Description:** Comma-separated list of services for which to configure port forwarding on the machine. Options include "mq,dns,ssh". MQ IS DEPRECIATED, DO NOT SET THIS.'ssh' forwards port 22 over WireGuard, enabling ssh to server over WireGuard. However, if you set the Netmaker server as an ingress gateway, this will break SSH on external clients, so be careful. DNS enables private DNS over WireGuard. If you would like to use private DNS with ext clients, turn this on. + **Description:** Comma-separated list of services for which to configure port forwarding on the machine. Options include "mq,dns,ssh". MQ IS DEPRECIATED, DO NOT SET THIS.'ssh' forwards port 22 over WireGuard, enabling ssh to server over WireGuard. However, if you set the Netmaker server as an Remote Access Gateway (ingress), this will break SSH on Remote Access Clients, so be careful. DNS enables private DNS over WireGuard. If you would like to use private DNS with ext clients, turn this on. VERBOSITY: **Default:** 0 @@ -192,7 +192,7 @@ There are also some environment variables that have been changed, or removed. Yo .. literalinclude:: ./examplecode/netmaker.default.env :language: YAML -Our Caddy file has gone through some minor changes as well. There needs to be a block for the TURN server. The file should look like this. +Your Caddyfile should look like this. .. code-block:: cfg @@ -226,16 +226,6 @@ Our Caddy file has gone through some minor changes as well. There needs to be a https://api.NETMAKER_BASE_DOMAIN { reverse_proxy http://netmaker:8081 } - - # TURN - https://turn.NETMAKER_BASE_DOMAIN { - reverse_proxy host.docker.internal:3479 - } - - #TURN API - https://turnapi.NETMAKER_BASE_DOMAIN { - reverse_proxy http://host.docker.internal:8089 - } # MQ wss://broker.NETMAKER_BASE_DOMAIN { @@ -251,13 +241,9 @@ The following is a brief description of each: - `docker-compose.yml `_ -= This maintains the most recommended setup at the moment, using the caddy proxy. -- `docker-compose.pro.yml `_ -= This is the compose file needed for Netmaker Professional. You will need a licence and user id from `Netmaker's licence dashboard `_ . - +- `docker-compose.pro.yml `_ -= This is the compose file needed for Netmaker Professional. You will need a licence and tenant id from `Netmaker's licence dashboard `_ . -No DNS - CoreDNS Disabled ----------------------------------------------- -CoreDNS is no longer required for most installs. You can simply remove the CoreDNS section from your docker-compose. DNS will still function because it is added directly to nodes' hosts files (ex: /etc/hosts). If you would like to disable DNS propagation entirely, in your netmaker.env for netmaker, set DNS_MODE="off" .. _Emqx: @@ -280,7 +266,6 @@ In your Caddyfile, the only change you need to make is in the mq block. # MQ wss://broker.{$NM_DOMAIN} { - tls /root/certs/fullchain.pem /root/certs/privkey.pem reverse_proxy ws://mq:8083 } @@ -363,17 +348,11 @@ Server Setup (using sqlite) masterkey: "" mqpassword: "" mqusername: "" - turn_username: "" - turn_password: "" - turn_server: "turn." - turn_api_server: "https://turnapi." - turn_port: "3479" - use_turn: "true" serverbrokerendpoint: "ws://mq:1883" -4. Update YOUR_BASE_DOMAIN and SECRET_KEY as well as username and passwords for mq and turn. +4. Update YOUR_BASE_DOMAIN and SECRET_KEY as well as username and passwords for mq. 5. create your netmaker.service file /etc/systemd/system/netmaker.service .. code-block:: cfg diff --git a/support.rst b/support.rst index d889c956..9c485569 100644 --- a/support.rst +++ b/support.rst @@ -1,7 +1,4 @@ -========= -Support -========= - +====== FAQ ====== @@ -27,17 +24,7 @@ Please see the :doc:`Egress Gateway <./egress-gateway>` documentation. Do you offer any business or professional support? --------------------------------------------------- -Yes, please contact info@gravitl.com or visit https://gravitl.com/plans. - - -Why the SSPL License? ----------------------- - -As of now, we think the SSPL is the best way to ensure the long-term viability of the project, but we are regularly evaluating this to see if an OSI-approved license makes more sense. - -We believe the SSPL lets most people run the project the way they want, for both private use and business use, while giving us a path to maintain viability. We are working to make sure the guidelines clear, and do not want the license to impact the community's ability to use and modify the project. - -If you believe the SSPL will negatively impact your ability to use the project, please do not hesitate to reach out. +Yes, please contact help@netmaker.io or visit https://gravitl.com/plans. Telemetry ============== @@ -51,7 +38,7 @@ The following is the full list of telemetry data we collect. Besides "Server Ver - Randomized server ID - Count of nodes - Count of "non-server" nodes -- Count of external clients +- Count of Remote Access Clients - Count of networks - Count of users - Count of linux nodes diff --git a/turn-server.rst b/turn-server.rst deleted file mode 100644 index f97082c6..00000000 --- a/turn-server.rst +++ /dev/null @@ -1,105 +0,0 @@ -===================================== -Turn Servers -===================================== - -Introduction -=============== - - - -A TURN (Traversal Using Relays around NAT) server is a type of server used in peer-to-peer communication protocols to facilitate communication between devices that are located behind a network address translator (NAT). - -NAT is commonly used in home and office networks to allow multiple devices to share a single public IP address. While this can be an effective way to conserve IP addresses, it can cause problems for certain types of communication protocols, including peer-to-peer communication protocols such as Voice over IP (VoIP) and video conferencing. - -When two devices behind different NATs want to communicate directly, they often cannot establish a direct connection due to the NATs blocking incoming connections. A TURN server can act as a relay between the two devices, allowing them to establish a communication channel through the server. - -TURN servers work by relaying data between two devices. When a device behind a NAT wants to communicate with a device on the public Internet, it sends its data to the TURN server. The TURN server then relays the data to the other device, and the other device sends its response back through the TURN server to the first device. This allows the two devices to communicate without needing to establish a direct connection. - -While TURN servers can be useful for facilitating peer-to-peer communication between devices behind NATs, they can also introduce latency and increase bandwidth usage. It's important to carefully consider the use of TURN servers in any communication protocol to ensure that they are used effectively and efficiently. - -Implementing the Netmaker TURN server -===================================== - -If you are starting out making a new netmaker server, you can just folow the installation instructions. :doc:`Quick Install<./quick-start>` - -If You have an existing installation and would like to add a TURN server, You will need to make some changes to your docker-compose.yml and Caddyfile. These changes work with both Community edition and Professional edition. There is also an option to turn the TURN server on and off, so if you decide not to use it anymore, you can just switch it off. - -You should probably backup your docker-compose file at this point. That way, if you need to start over or want to revert the changes, you can just copy the backup. - -Start with your docker-compose.yml file. In the netmaker section you will need to add the following to the environment variables. - -.. code-block:: yaml - - TURN_SERVER_HOST: "turn.NETMAKER_BASE_DOMAIN" - TURN_SERVER_API_HOST: "https://turnapi.NETMAKER_BASE_DOMAIN" - TURN_PORT: "3479" - TURN_USERNAME: "REPLACE_TURN_USERNAME" - TURN_PASSWORD: "REPLACE_TURN_PASSWORD" - USE_TURN: "true" - -In the caddy section of the docker-compose.yml file, add the following below ``restart: unless-stopped`` - -.. code-block:: yaml - - extra_hosts: - - "host.docker.internal:host-gateway" - -You will also need to add a turn section to your compose file. place the following above the volumes: - -.. code-block:: yaml - - turn: - container_name: turn - image: gravitl/turnserver:v1.0.0 - network_mode: "host" - volumes: - - turn_server:/etc/config - environment: - DEBUG_MODE: "off" - VERBOSITY: "1" - TURN_PORT: "3479" - TURN_API_PORT: "8089" - CORS_ALLOWED_ORIGIN: "*" - TURN_SERVER_HOST: "turn.NETMAKER_BASE_DOMAIN" - USERNAME: "REPLACE_TURN_USERNAME" - PASSWORD: "REPLACE_TURN_PASSWORD" - -Replace the ``NETMAKER_BASE_DOMAIN`` with your domain and ``REPLACE_TURN_USERNAME`` and ``REPLACE_TURN_PASSWORD`` with your desired username and password. make sure that they match in the netmaker section and the turn section. - -The final part in your docker-compose.yml file will be adding a volume. in the volumes section at the bottom of the file, add the following: - -.. code-block:: yaml - - turn_server: {} - - -You will then need to make the following additions to your Caddyfile: - -.. code-block:: cfg - - # TURN - https://turn.NETMAKER_BASE_DOMAIN { - reverse_proxy host.docker.internal:3479 - } - - #TURN API - https://turnapi.NETMAKER_BASE_DOMAIN { - reverse_proxy http://host.docker.internal:8089 - } - -You can then ``docker-compose down && docker-compose up -d`` - -You can verify the working turn server with ``docker logs turn``. You should see an output similar to this: - -.. code-block:: cfg - - [turnserver] 2023-05-07 20:19:03 Netmaker Turn Version (v1.0.0) - [turnserver] 2023-05-07 20:19:03 REST Server (Version: v1.0.0) successfully started on port (8089) - 2023/05/07 20:19:03 Server 0 listening on [::]:3479 - 2023/05/07 20:19:03 Server 1 listening on [::]:3479 - 2023/05/07 20:19:03 Server 2 listening on [::]:3479 - 2023/05/07 20:19:03 Server 3 listening on [::]:3479 - 2023/05/07 20:19:03 Server 4 listening on [::]:3479 - -Your turn server should be up and running at this point. You should be able to see a connection in difficult setups like a double NAT or asymetrical NAT. As mentioned before You should expect a bit of latency with the extra hop from peer to TURN to peer. - diff --git a/ui-reference.rst b/ui-reference.rst index a17185ac..9aa38b99 100644 --- a/ui-reference.rst +++ b/ui-reference.rst @@ -1,7 +1,3 @@ -================= -UI Reference -================= - This page contains annotated screenshots of most UI components, detailing the configuration options of each field across Nodes, Networks, DNS, Ext Clients, Users, and more. @@ -138,14 +134,12 @@ Node List :alt: nodes list :align: center -(1) **Search Nodes:** Look up a node by name. -(2) **Node Name:** Name of node. By default set to hostname of machine. -(3) **IP Addresses:** Private IPs of node within network. -(4) **Network:** Network the node is in. -(5) **Egress:** Indicates if node is an egress gateway. Click to convert into egress gateway. Egress gateways route traffic from the network into a specific subnet or subnets. Egress gateways should be servers in a static location with a reliable IP. -(6) **Ingress:** Indicates if the node is an ingress. Click to convert into ingress gateway. Ingress gateways route traffic into the network over the WireGuard interface using "ext clients," which are static WireGuard config files. Ingress gateways should be servers in a static location with a reliable IP. -(7) **Status:** Indicates how recently the node checked into the server. Displays "Warning" after 5 minutes and "Error" after 30 minutes without a check in. Does **not** indicate the health of the node's virtual network connections. -(8) **Delete:** Delete the node. +(1) **Search Hosts:** Look up a host by name. +(2) **Host Name:** Name of host. By default set to hostname of machine. +(3) **Private Addresses:** Private IPs of host within network. +(4) **Public Address:** Public IP of host. +(5) **Status:** Indicates how recently the host checked into the server. Displays "Warning" after 5 minutes and "Error" after 30 minutes without a check in. Does **not** explicitly indicate the health of the node's virtual network connections; however a healthy host will check-in regularly. +(6) **Actions:** Dropdown list of actions that can be performed on a host, including disconnecting and deleting the host. A node pending deletion will be grayed out. @@ -185,43 +179,40 @@ Edit Node / Node Details (3) **Metrics** View the node's metrics (4) **Host** View the node's associated host (5) **Delete** Delete the node - (6) **Endpoint:** The (typically public) IP of the machine, which peers will use to reach it, in combination with the port. If changing this value, make sure Roaming is turned off, since otherwise, the node will check to see if there is a change in the public IP regularly and update it. -(7) **Dynamic Endpoint:** The endpoint may be changed automatically. Switching this off (indicating static endpoint) means the endpoint will stay the same until you change it. This can be good to set if the machine is a server sitting in a location that is not expected to change. It is also good to have this switched off for Ingress, Egress, and Relay Servers, since they should be in a reliable location. +(7) **Dynamic Endpoint:** The endpoint may be changed automatically. Switching this off (indicating static endpoint) means the endpoint will stay the same until you change it. This can be good to set if the machine is a server sitting in a location that is not expected to change. It is also good to have this switched off for Remote Access gateway, Egress, and Relay Servers, since they should be in a reliable location. (8) **Listen Port:** The port used by the node locally. **This value is ignored if UDP Hole Punching is on,** because port is set dynamically every time interface is created. If UDP Hole Punching is off, the port can be set to any reasonable (and available) value you'd like for the local machine. (9) **IP Address:** The primary private IP address of the node. Assigned automatically by Netmaker but can be changed to whatever you want within the Network CIDR. (10) **IPv6 Address:** (Only if running dual stack) the primary private IPv6 address of the node. Assigned automatically by Netmaker but can be changed to whatever you want within the Network CIDR. (11) **Local Address:** The "locally reachable" address of the node. Other nodes will take note of this to see if this node is on the same network. If so, they will use this address instead of the public "Endpoint." If running a few nodes inside of a VPC, home network, or similar, make sure the local address is populated correctly for faster and more secure inter-node communication. (12) **Node Name:** The name of the node within the network. Hostname by default but can be anything (within the character limits). (13) **Public Key:** (Uneditable) The public key of the node, distributed to other peers in the network. -(14) **PostUp:** Uneditable by default to disable RCE. Commands to run after the interface is created. If an ingress or egress gateway are created, this field will populate automatically with appropriate iptables commands. -(15) **PostDown:** Uneditable by default to disable RCE. Commands to run after the interface is brought down. If an ingress or egress gateway are created, this field will populate automatically with appropriate iptables commands. -(16) **Persistent Keepalive:** How often packets are sent to keep connections open with other peers. -(17) **Last Modified:** Timestamp of the last time the node config was changed. -(18) **Node Expiration Datetime:** If a node should become invalid after a length of time, you can set it in this field, after which time, it will lose access to the network and will not populate to other nodes. Useful for scenarios where temporary access is granted to 3rd parties. -(19) **Last Checkin:** Unix timestamp of the last time the node checked in with the server. Used to determine generic health of node. -(20) **MAC Address:** The hardware Media Access Control (MAC) address of the machine. Used to be used as the unique ID, but is being depreciated. -(21) **Egress Gateway Ranges:** If Egress is enabled, the gateway ranges that this machine routes to. -(22) **Local Range:** If IsLocal has been enabled on the network, this is the local range in which the node will look for a private address from it's local interfaces, to use as an endpoint. -(23) **Node Operating System:** The OS of the machine. -(24) **MTU:** The MTU that the node will use on the interface. If "wg show" displays a valid handshake but pings are not working, many times the issue is MTU. Making this value lower can solve this issue. Some typical values are 1024, 1280, and 1420. -(25) **Network:** The network this node belongs to. -(26) **Node ACL Rule** The current ACL rule for this node in the network -(27) **Is DNS On:** DNS is solely handled by resolvectl at the moment, which is on many Linux distributions. For anything else, this value should remain off. If you wish to configure DNS for non-compatible systems, you must do so manually. -(28) **Is Local:** If on, will only communicate over the local address (Assumes IsLocal tuned to 'yes' on the network level.) -(29) **Connected** Indicates whether the node has is connected to the network - - -Ext Clients -================ +(14) **Persistent Keepalive:** How often packets are sent to keep connections open with other peers. +(15) **Last Modified:** Timestamp of the last time the node config was changed. +(16) **Node Expiration Datetime:** If a node should become invalid after a length of time, you can set it in this field, after which time, it will lose access to the network and will not populate to other nodes. Useful for scenarios where temporary access is granted to 3rd parties. +(17) **Last Checkin:** Unix timestamp of the last time the node checked in with the server. Used to determine generic health of node. +(18) **MAC Address:** The hardware Media Access Control (MAC) address of the machine. Used to be used as the unique ID, but is being depreciated. +(19) **Egress Gateway Ranges:** If Egress is enabled, the gateway ranges that this machine routes to. +(20) **Local Range:** If IsLocal has been enabled on the network, this is the local range in which the node will look for a private address from it's local interfaces, to use as an endpoint. +(21) **Node Operating System:** The OS of the machine. +(22) **MTU:** The MTU that the node will use on the interface. If "wg show" displays a valid handshake but pings are not working, many times the issue is MTU. Making this value lower can solve this issue. Some typical values are 1024, 1280, and 1420. +(23) **Network:** The network this node belongs to. +(24) **Node ACL Rule** The current ACL rule for this node in the network +(25) **Is DNS On:** DNS is solely handled by resolvectl at the moment, which is on many Linux distributions. For anything else, this value should remain off. If you wish to configure DNS for non-compatible systems, you must do so manually. +(26) **Is Local:** If on, will only communicate over the local address (Assumes IsLocal tuned to 'yes' on the network level.) +(27) **Connected** Indicates whether the node has is connected to the network + + +Remote Access +============= .. image:: images/ui-8.jpg :width: 80% :alt: dashboard :align: center -(1) **Gateway Name / IP Address:** Information about which Node is the Ingress Gateway. -(2) **Add External Client:** Button to generate a new ext client. +(1) **Gateway Name / IP Address:** Information about which Node is the Remote Access Gateway. +(2) **Add Client Config:** Button to generate a new Remote Access Client configuration file. (3) **Client ID:** The randomly-generated name of the client. Click on the ID to change the name to something sensible. (4) **IP Address:** The private ip address of the ext client. (5) **QR Code:** If joining form iOS or Android, open the WireGuard app and scan the QR code to join the network.