mirror of
https://github.com/gravitl/netmaker.git
synced 2024-09-20 23:36:18 +08:00
updating docs for 0.8
This commit is contained in:
afeiszli
parent
ad5372f5f3
commit
683d9e61e9
BIN
docs/_build/doctrees/architecture.doctree
vendored
BIN
docs/_build/doctrees/architecture.doctree
vendored
Binary file not shown.
BIN
docs/_build/doctrees/client-installation.doctree
vendored
BIN
docs/_build/doctrees/client-installation.doctree
vendored
Binary file not shown.
BIN
docs/_build/doctrees/environment.pickle
vendored
BIN
docs/_build/doctrees/environment.pickle
vendored
Binary file not shown.
BIN
docs/_build/doctrees/external-clients.doctree
vendored
BIN
docs/_build/doctrees/external-clients.doctree
vendored
Binary file not shown.
BIN
docs/_build/doctrees/getting-started.doctree
vendored
BIN
docs/_build/doctrees/getting-started.doctree
vendored
Binary file not shown.
BIN
docs/_build/doctrees/quick-start.doctree
vendored
BIN
docs/_build/doctrees/quick-start.doctree
vendored
Binary file not shown.
BIN
docs/_build/doctrees/server-installation.doctree
vendored
BIN
docs/_build/doctrees/server-installation.doctree
vendored
Binary file not shown.
BIN
docs/_build/doctrees/troubleshoot.doctree
vendored
BIN
docs/_build/doctrees/troubleshoot.doctree
vendored
Binary file not shown.
40
docs/_build/html/_sources/architecture.rst.txt
vendored
40
docs/_build/html/_sources/architecture.rst.txt
vendored
|
|
@ -63,7 +63,9 @@ SystemD
|
|||
|
||||
SystemD is a system service manager for a wide array of Linux operating systems. Not all Linux distributions have adopted systemd, but, for better or worse, it has become a fairly common standard in the Linux world. That said, any non-Linux operating system will not have systemd, and many Linux/Unix distributionshave alternative system service managers.
|
||||
|
||||
Netmaker's netclient, the agent which controls networking on all nodes, can be run as a CLI or as a system daemon. It runs as a daemon by default, and this requires systemd. As Netmaker evolves, systemd will become just one of the possible service management options, allowing the netclient to be run on a wider array of devices. However, for the time being, the netclient should be run "unmanaged" (netclient join -daemon=off) on systems that do not run systemd, and some other method can be used like a cron job or custom script.
|
||||
Netmaker's netclient, the agent which controls networking on all nodes, can be run as a CLI or as a system daemon. On Linux, it runs as a daemon by default, and this requires systemd. As Netmaker evolves, systemd will become just one of the possible service management options, allowing the netclient to be run on a wider array of devices. However, for the time being, the netclient should be run "unmanaged" (netclient join -daemon=off) on systems that do not run systemd, and some other method can be used like a cron job or custom script.
|
||||
|
||||
As of 0.8, Mac and Windows are supported. On these operating systems, netclient launches the daemon using LaunchD and Windows Service, respectively, as opposed to SystemD.
|
||||
|
||||
Components
|
||||
===========
|
||||
|
|
@ -81,13 +83,13 @@ Most server settings are configurable via a config file, or by environment varia
|
|||
|
||||
These modes include client mode and dns mode. Either of these can be disabled but are enabled by default. Client mode allows you to treat the Netmaker host machine (operating system) as a network Node, installing the netclient and controlling the host network. DNS mode has the server write config settings for CoreDNS, a separate component and nameserver, which picks up the config settings to manage node DNS.
|
||||
|
||||
The Netmaker server interacts with rqlite, a distributed version of sqlite, which holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration.
|
||||
The Netmaker server interacts with either sqlit (default) or rqlite, a distributed version of sqlite, as its database. This DB holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration.
|
||||
|
||||
|
||||
Netclient
|
||||
----------------
|
||||
|
||||
The netclient is, at its core, a golang binary. Source code can be found in the netclient folder of the Netmaker `GitHub Repository <https://github.com/gravitl/netmaker/tree/master/netclient>`_. The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems. As of version 0.5, the netclient can be run as a system daemon on linux distributions with systemd, or as an "unmanaged" client on distributions without systemd.
|
||||
The netclient is, at its core, a golang binary. Source code can be found in the netclient folder of the Netmaker `GitHub Repository <https://github.com/gravitl/netmaker/tree/master/netclient>`_. The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems. As of version 0.8, the netclient can be run as a system daemon on linux distributions with systemd, or as an "unmanaged" client on distributions without systemd. The netclient for Windows and Mac will run as a Windows Service or LaunchDaemon, respectively.
|
||||
|
||||
The netclient is installed via a simple bash script, which pulls the latest binary and runs 'register' and 'join' commands.
|
||||
|
||||
|
|
@ -95,17 +97,19 @@ The 'register' command adds a WireGuard tunnel directly to the netmaker server,
|
|||
|
||||
The 'join' command attempts to add the machine to the Netmaker network using sensible defaults, which can be overridden with a config file or environment variables. Assuming the netclient has a valid key (or the network allows manual node signup), it will be registered into the Netmaker network, and will be returned necessary configuration details for how to set up its local network.
|
||||
|
||||
The netclient then sets up the systemd daemon (if running in daemon mode), and configures WireGuard. At this point it should be part of the network.
|
||||
The netclient then sets up the system daemon (if running in daemon mode), and configures WireGuard. At this point it should be part of the network.
|
||||
|
||||
If running in daemon mode, on a periodic basis (systemd timer), the netclient performs a "check in." It will authenticate with the server, and check to see if anything has changed in the network. It will also post changes about its own local configuration if there. If there has been a change, the server will return new configurations and the netclient will reconfigure the network. If not running in daemon mode, it is up to the operator to perform check ins (netclient checkin -n < network name >).
|
||||
|
||||
The check in process is what allows Netmaker to create dynamic mesh networks. As nodes are added to, removed from, and modified on the network, other nodes are notified, and make appropriate changes.
|
||||
|
||||
|
||||
rqlite
|
||||
--------
|
||||
sqlite and rqlite
|
||||
---------------------
|
||||
|
||||
As of v0.7, Netmaker uses rqlite, a distributed (RAFT consensus) database, and interacts with this database to store and retrieve information about nodes, networks, and users. With the 0.7 refactor, additional database support is very easy to implement. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file.
|
||||
As of v0.8, Netmaker uses sqlite by default as a database. It can also use rqlite, a distributed (RAFT consensus) databaseand. Netmaker interacts with this database to store and retrieve information about nodes, networks, and users.
|
||||
|
||||
Additional database support (besides sqlite and rqlite) is very easy to implement for special use cases. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file.
|
||||
|
||||
Netmaker UI
|
||||
---------------
|
||||
|
|
@ -120,8 +124,6 @@ CoreDNS
|
|||
|
||||
Netmaker allows users to provide and manage Private DNS for their nodes. This requires a nameserver, and CoreDNS is the chosen nameserver. CoreDNS is lightweight and extensible. CoreDNS loads dns settings from a simple file, managed by Netmaker, and serves out DNS info for managed nodes. DNS can be tricky, and DNS management is currently only supported on a small set of devices, specifically those running systemd-resolved. However, the Netmaker CoreDNS instance can be added manually as a nameserver to other devices. DNS mode can also be turned off.
|
||||
|
||||
Worth considering is that CoreDNS requires port 53 on the Netmaker host system, which may cause conflicts depending on your operating system. This is explained in the :doc:`Server Installation <./server-installation>` guide.
|
||||
|
||||
External Client
|
||||
----------------
|
||||
|
||||
|
|
@ -129,7 +131,9 @@ The external client is simply a manually configured WireGuard connection to your
|
|||
|
||||
Most machines can run WireGuard. It is fairly simple to set up a WireGuard connection to a single endpoint. It is setting up mesh networks and other topologies like site-to-site which becomes complicated.
|
||||
|
||||
Netmaker v0.5 introduces the "external client" to handle any devices which are not currently compatible with the netclient, including Windows, iPhone, Android, and Mac. Over time, this list will be eliminated and there may not even be a need for the external client.
|
||||
Mac, Windows, and Linux are handled natively by the Netclient.
|
||||
|
||||
Netmaker can issue "external clients" to handle any devices which are not currently compatible with the netclient, including iPhone, Android, and some Unix distributions. Over time, this list will be eliminated and there may not even be a need for the external 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.
|
||||
|
||||
|
|
@ -160,9 +164,13 @@ Below is a high level, step-by-step overview of the flow of communications withi
|
|||
Compatible Systems for Netclient
|
||||
==================================
|
||||
|
||||
To manage a node manually, the Netclient can be compiled and run for most linux distibutions, with a prerequisite of WireGuard.
|
||||
To manage a node manually, the Netclient can be compiled and run for most linux distibutions, with a prerequisite of WireGuard with kernel headers. If the netclient from the release pages does not run natively on your system, you may need to compile the netclient binary directly on the machine from the source code. This may be true for some installations of SUSE, Fedora, and some Debian-based systems. However, if the dependencies are installed on the machine, the netclient should run correctly after being compiled.
|
||||
|
||||
To manage a node automatically, the Netmaker client (netclient) requires **systemd-based linux.** Compatible systems include:
|
||||
Simply clone the repo, cd to netmaker/netclient and run "go build" (Golang must be installed).
|
||||
|
||||
The following systems should be operable natively with Netclient in daemon mode:
|
||||
- Windows
|
||||
- Mac
|
||||
- Fedora
|
||||
- Ubuntu
|
||||
- Debian
|
||||
|
|
@ -173,7 +181,7 @@ To manage a node automatically, the Netmaker client (netclient) requires **syste
|
|||
- Arch
|
||||
- CentOS
|
||||
- CoreOS
|
||||
|
||||
|
||||
To manage DNS (optional), the node must have systemd-resolved. Systems that have this enabled include:
|
||||
- Arch
|
||||
- Debian
|
||||
|
|
@ -181,8 +189,6 @@ To manage DNS (optional), the node must have systemd-resolved. Systems that have
|
|||
- SUSE
|
||||
|
||||
Limitations
|
||||
===========
|
||||
=============
|
||||
|
||||
Install limitations mostly include platform-specific limitations, such as needing systemd or systemd-resolved (see above).
|
||||
|
||||
In addition the Netmaker is currently unable to route traffic for for devices behind a "carrier-grade NAT". This will be solved in a future release with the introduction of relay servers.
|
||||
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 <https://stackoverflow.com/questions/62356581/wireguard-vpn-how-to-fix-operation-not-supported-if-it-worked-before>`_)
|
||||
|
|
@ -19,6 +19,17 @@ The netclient agent connects to the server, pushing and pulling information when
|
|||
|
||||
The netclient agent then configures WireGuard (and other network properties) locally, so that the network stays intact.
|
||||
|
||||
Notes on Windows
|
||||
==================================
|
||||
|
||||
If running the netclient on windows, you must download the netclient.exe binary and run it from Powershell as an Administrator.
|
||||
|
||||
Windows will by default have firewall rules that prevent inbound connections. If you wish to allow inbound connections from particular peers, use the following command:
|
||||
|
||||
``netsh advfirewall firewall add rule name="Allow from <peer private addr>" dir=in action=allow protocol=ANY remoteip=<peer private addr>``
|
||||
|
||||
If you want to allow all peers access, but do not want to configure firewall rules for all peers, you can configure access for one peer, and set it as a Relay Server.
|
||||
|
||||
Modes and System Compatibility
|
||||
==================================
|
||||
|
||||
|
|
@ -36,11 +47,9 @@ As a CLI, the netclient should function on any Linux or Unix based system that h
|
|||
Daemon
|
||||
----------
|
||||
|
||||
The netclient is intended to be run as a system daemon. This allows it to automatically retrieve and send updates. To do this, the netclient can install itself as a systemd service.
|
||||
The netclient is intended to be run as a system daemon. This allows it to automatically retrieve and send updates. To do this, the netclient can install itself as a systemd service, or launchd/windows service for Mac or Windows.
|
||||
|
||||
This requires a systemd-based linux operating system.
|
||||
|
||||
If running the netclient on a non-systemd system, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.
|
||||
If running the netclient on non-systemd linux, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.
|
||||
|
||||
Private DNS Management
|
||||
-----------------------
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ By using this method, you can hook any machine into a netmaker network that can
|
|||
|
||||
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, 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 resource runnin on the virtual network, and **not** for use cases where one wishes to make a resource accessible on the network. For that, use netclient.
|
||||
Important to note, 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 resource 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
|
||||
==================================
|
||||
|
|
@ -57,3 +57,16 @@ Example config file:
|
|||
.. literalinclude:: ./examplecode/myclient.conf
|
||||
|
||||
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.
|
||||
|
||||
Configuring DNS for Ext Clients (OPTIONAL)
|
||||
============================================
|
||||
|
||||
If you wish to have a DNS field on your ext clients conf, simply edit the network field as shown below to 1.1.1.1 or 8.8.8.8 for example.
|
||||
If you do not want DNS on your ext client conf files, simply leave it blank.
|
||||
|
||||
.. image:: images/exclient5.png
|
||||
:width: 80%
|
||||
:alt: Gateway
|
||||
:align: center
|
||||
|
||||
Important to note, your client automatically adds egress gateway ranges (if any on the same network) to it's allowed IPs.
|
||||
|
|
|
|||
|
|
@ -66,7 +66,8 @@ Deploy Nodes
|
|||
1. SSH to each machine
|
||||
2. ``sudo su -``
|
||||
3. **Prerequisite Check:** Every Linux machine on which you run the netclient must have WireGuard and systemd installed
|
||||
4. Run the install command, Ex: ``curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/develop/scripts/netclient-install.sh | KEY=vm3ow4thatogiwnsla3thsl3894ths sh -``
|
||||
4. For linux machines with SystemD and WireGuard installed, Run the install command, Ex: ``curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/develop/scripts/netclient-install.sh | KEY=vm3ow4thatogiwnsla3thsl3894ths sh -``
|
||||
5. For Mac, Windows, and arch-specific linux distributions (e.g. ARM), `download the appropriate netclient for your system <https://github.com/gravitl/netmaker/releases/tag/latest/>`_ . Then, run "netclient join -t <your token>".
|
||||
|
||||
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 <./client-installation>` documentation. If this process failed and you do not see your node in the console (see below), then reference the :doc:`troubleshooting <./troubleshoot>` documentation.
|
||||
|
||||
|
|
|
|||
53
docs/_build/html/_sources/quick-start.rst.txt
vendored
53
docs/_build/html/_sources/quick-start.rst.txt
vendored
|
|
@ -7,16 +7,15 @@ This quick start guide is an **opinionated** guide for getting up and running wi
|
|||
0. Introduction
|
||||
==================
|
||||
|
||||
We assume for this installation that you want all of the Netmaker features enabled, want your server to be secure, and want it to be accessible from anywhere.
|
||||
We assume for this installation that you want all of the Netmaker features enabled, you want your server to be secure, and you want your server to be accessible from anywhere.
|
||||
|
||||
This instance will not be HA. However, it should comfortably handle around one hundred concurrent clients and support most use cases.
|
||||
This instance will not be HA. However, it should comfortably handle around one hundred concurrent clients and support the most common use cases.
|
||||
|
||||
If you are deploying for an enterprise use case, please contact info@gravitl.com for support.
|
||||
If you are deploying for a business or enterprise use case and this setup will not fit your needs, please contact info@gravitl.com, or check out the business subscription plans at https://gravitl.com/plans/business.
|
||||
|
||||
By the end of this guide, you will have Netmaker installed on a public VM linked to your custom domain, secured behind an Nginx reverse proxy.
|
||||
|
||||
If this configuration does not fit your use case, see the :doc:`Advanced Installation <./server-installation>` docs.
|
||||
|
||||
For information about deploying more advanced configurations, see the :doc:`Advanced Installation <./server-installation>` docs.
|
||||
|
||||
|
||||
1. Prerequisites
|
||||
|
|
@ -24,9 +23,11 @@ If this configuration does not fit your use case, see the :doc:`Advanced Install
|
|||
- **Virtual Machine**
|
||||
|
||||
- Preferably from a cloud provider (e.x: DigitalOcean, Linode, AWS, GCP, etc.)
|
||||
- We do not recommend Oracle Cloud, as VM's here have been known to cause network interference.
|
||||
- Public, static IP
|
||||
- Min 2GB RAM, 1 CPU (4GB RAM, 2CPU preferred)
|
||||
- 5GB+ of storage
|
||||
- Min 1GB RAM, 1 CPU (4GB RAM, 2CPU preferred)
|
||||
- Nginx may have performance issues if using a cloud VPS with a single, shared CPU
|
||||
- 2GB+ of storage
|
||||
- Ubuntu 20.04 Installed
|
||||
|
||||
- **Domain**
|
||||
|
|
@ -47,11 +48,11 @@ Begin by installing the community version of Docker and docker-compose (there ar
|
|||
|
||||
sudo apt-get remove docker docker-engine docker.io containerd runc
|
||||
sudo apt-get update
|
||||
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
|
||||
sudo apt-get -y install apt-transport-https ca-certificates curl gnupg lsb-release
|
||||
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
|
||||
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
sudo apt-get update
|
||||
sudo apt-get install docker-ce docker-ce-cli containerd.io
|
||||
sudo apt-get -y install docker-ce docker-ce-cli containerd.io
|
||||
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
|
||||
sudo chmod +x /usr/local/bin/docker-compose
|
||||
docker --version
|
||||
|
|
@ -64,7 +65,7 @@ Install Dependencies
|
|||
|
||||
In addition to Docker, this installation requires WireGuard, Nginx, and Certbot.
|
||||
|
||||
``sudo apt install wireguard wireguard-tools nginx certbot python3-certbot-nginx net-tools``
|
||||
``sudo apt -y install wireguard wireguard-tools nginx certbot python3-certbot-nginx net-tools``
|
||||
|
||||
|
||||
3. Prepare VM
|
||||
|
|
@ -109,20 +110,9 @@ Make sure firewall settings are appropriate for Netmaker. You need ports 53 and
|
|||
- allow 443/tcp from all
|
||||
- allow 53/udp and 53/tcp from all
|
||||
|
||||
Prepare for DNS
|
||||
----------------------------------------------------------------
|
||||
|
||||
On Ubuntu 20.04, by default there is a service consuming port 53 related to DNS resolution. We need port 53 open in order to run our own DNS server. The below steps will disable systemd-resolved, and insert a generic DNS nameserver for local resolution.
|
||||
|
||||
.. code-block::
|
||||
|
||||
systemctl stop systemd-resolved
|
||||
systemctl disable systemd-resolved
|
||||
vim /etc/systemd/resolved.conf
|
||||
* uncomment DNS and add 8.8.8.8 or whatever reachable nameserver is your preference *
|
||||
* uncomment DNSStubListener and set to "no" *
|
||||
ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
|
||||
In addition to the above ports, you will need to make sure that your cloud's firewall or security groups are opened for the range of ports that Netmaker's WireGuard interfaces consume.
|
||||
|
||||
Netmaker will create one interface per network, starting from 51821. So, if you plan on having 5 networks, you will want to have at least 51821-51825 open (udp).
|
||||
|
||||
Prepare Nginx
|
||||
-----------------
|
||||
|
|
@ -148,23 +138,28 @@ Insert your domain in the configuration file and add to nginx:
|
|||
Prepare Templates
|
||||
------------------
|
||||
|
||||
**Note on COREDNS_IP:** Depending on your cloud provider, the public IP may not be bound directly to the VM on which you are running. In such cases, CoreDNS cannot bind to this IP, and you should use the IP of the default interface on your machine in place of COREDNS_IP. If the public IP **is** bound to the VM, you can simply use the same IP as SERVER_PUBLIC_IP.
|
||||
|
||||
.. code-block::
|
||||
|
||||
wget https://raw.githubusercontent.com/gravitl/netmaker/develop/compose/docker-compose.quickstart.yml
|
||||
sed -i 's/NETMAKER_BASE_DOMAIN/<your base domain>/g' docker-compose.quickstart.yml
|
||||
sed -i 's/SERVER_PUBLIC_IP/<your server ip>/g' docker-compose.quickstart.yml
|
||||
wget https://raw.githubusercontent.com/gravitl/netmaker/develop/compose/docker-compose.yml
|
||||
sed -i 's/NETMAKER_BASE_DOMAIN/<your base domain>/g' docker-compose.yml
|
||||
sed -i 's/SERVER_PUBLIC_IP/<your server ip>/g' docker-compose.yml
|
||||
sed -i 's/COREDNS_IP/<your server ip>/g' docker-compose.yml
|
||||
|
||||
Generate a unique master key and insert it:
|
||||
|
||||
.. code-block::
|
||||
|
||||
tr -dc A-Za-z0-9 </dev/urandom | head -c 30 ; echo ''
|
||||
sed -i 's/REPLACE_MASTER_KEY/<your generated key>/g' docker-compose.quickstart.yml
|
||||
sed -i 's/REPLACE_MASTER_KEY/<your generated key>/g' docker-compose.yml
|
||||
|
||||
You may want to save this key for future use with the API.
|
||||
|
||||
Start Netmaker
|
||||
----------------
|
||||
|
||||
``sudo docker-compose -f docker-compose.quickstart.yml up -d``
|
||||
``sudo docker-compose -f docker-compose.yml up -d``
|
||||
|
||||
navigate to dashboard.<your base domain> to see your nginx instance.
|
||||
|
||||
|
|
@ -172,4 +167,4 @@ To troubleshoot issues, start with:
|
|||
|
||||
``docker logs netmaker``
|
||||
|
||||
Or check out the :doc:`troubleshoooting docs <./troubleshoot>`.
|
||||
Or check out the :doc:`troubleshoooting docs <./troubleshoot>`.
|
||||
|
|
|
|||
|
|
@ -98,6 +98,21 @@ DNS_MODE:
|
|||
|
||||
**Description:** Enables DNS Mode, meaning config files will be generated for CoreDNS.
|
||||
|
||||
DATABASE:
|
||||
**Default:** "sqlite"
|
||||
|
||||
**Description:** Specify db type to connect with. Currently, options include "sqlite" and "rqlite".
|
||||
|
||||
SQL_CONN:
|
||||
**Default:** "http://"
|
||||
|
||||
**Description:** Specify the necessary string to connect with your local or remote sql database.
|
||||
|
||||
CLIENT_MODE:
|
||||
**Default:** "on"
|
||||
|
||||
**Description:** Specifies if server should deploy itself as a node (client) in each network. May be turned to "off" for more restricted servers.
|
||||
|
||||
Config File Reference
|
||||
----------------------
|
||||
A config file may be placed under config/environments/<env-name>.yml. To read this file at runtime, provide the environment variable NETMAKER_ENV at runtime. For instance, dev.yml paired with ENV=dev. Netmaker will load the specified Config file. This allows you to store and manage configurations for different environments. Below is a reference Config File you may use.
|
||||
|
|
|
|||
17
docs/_build/html/_sources/troubleshoot.rst.txt
vendored
17
docs/_build/html/_sources/troubleshoot.rst.txt
vendored
|
|
@ -4,9 +4,9 @@ Troubleshooting
|
|||
|
||||
Common Issues
|
||||
--------------
|
||||
**How can I connect my Android, IOS, MacOS or Windows device to my Netmaker VPN?**
|
||||
**How can I connect my Android or IOS device to my Netmaker VPN?**
|
||||
Currently meshing one of these devices is not supported, however it will be soon.
|
||||
For now you can connect to your VPN by making one of the nodes an Ingressgateway, then
|
||||
For now you can connect to your VPN by making one of the nodes an Ingress Gateway, then
|
||||
create an Ext Client for each device. Finally, use the official WG app or another
|
||||
WG configuration app to connect via QR or downloading the device's WireGuard configuration.
|
||||
|
||||
|
|
@ -22,8 +22,16 @@ Common Issues
|
|||
Yes, we have an active `discord <https://discord.gg/Pt4T9y9XK8>`_ community and issues on our `github <https://github.com/gravitl/netmaker/issues>`_ are answered frequently!
|
||||
You can also sign-up for updates at our `gravitl site <https://gravitl.com/>`_!
|
||||
|
||||
**How can I get additional support for my business?**
|
||||
Check out our business support subscriptions at https://gravitl.com/plans. Subscription holders can also purchase consulting credits via the site.
|
||||
|
||||
|
||||
Server
|
||||
-------
|
||||
|
||||
**I upgraded from 0.7 to 0.8 and now I dont have any data in my server!**
|
||||
In 0.8, sqlite becomes the default database. If you were running with rqlite, you must set the DATABASE environment variable to rqlite in order to continue using rqlite.
|
||||
|
||||
**Can I secure/encrypt all the traffic to my server and UI?**
|
||||
This can fairly simple to achieve assuming you have access to a domain and are familiar with Nginx.
|
||||
Please refer to the quick-start guide to see!
|
||||
|
|
@ -63,7 +71,7 @@ UI
|
|||
Yes, nodes can share names without issue. It may just be harder on you to know which is which.
|
||||
|
||||
Netclient
|
||||
-------
|
||||
-----------
|
||||
**How do I connect a node to my Netmaker network with Netclient?**
|
||||
First get your access token (not just access key), then run ``sudo netclient join -t <access token>``.
|
||||
**NOTE:** netclient may be under /etc/netclient/, i.e run ``sudo /etc/netclient/netclient join -t <access token>``
|
||||
|
|
@ -91,6 +99,9 @@ Netclient
|
|||
sudo chcon -Rv -u system_u -t bin_t '/etc/netclient/netclient'
|
||||
sudo restorecon -R -v /etc/netclient/netclient
|
||||
|
||||
**I have a handshake with a peer but can't ping it, what gives?**
|
||||
This is commonly due to incorrect MTU settings. Typically, it will be because MTU is too high. Try setting MTU lower on the node. This can be done via netconfig, or by editing the node in the UI.
|
||||
|
||||
CoreDNS
|
||||
--------
|
||||
**Is CoreDNS required to use Netmaker?**
|
||||
|
|
|
|||
39
docs/_build/html/architecture.html
vendored
39
docs/_build/html/architecture.html
vendored
|
|
@ -268,7 +268,7 @@
|
|||
</li>
|
||||
<li class="md-nav__item"><a href="#netclient" class="md-nav__link">Netclient</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#rqlite" class="md-nav__link">rqlite</a>
|
||||
<li class="md-nav__item"><a href="#sqlite-and-rqlite" class="md-nav__link">sqlite and rqlite</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#netmaker-ui" class="md-nav__link">Netmaker UI</a>
|
||||
</li>
|
||||
|
|
@ -540,6 +540,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -747,7 +754,7 @@
|
|||
</li>
|
||||
<li class="md-nav__item"><a href="#netclient" class="md-nav__link">Netclient</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#rqlite" class="md-nav__link">rqlite</a>
|
||||
<li class="md-nav__item"><a href="#sqlite-and-rqlite" class="md-nav__link">sqlite and rqlite</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#netmaker-ui" class="md-nav__link">Netmaker UI</a>
|
||||
</li>
|
||||
|
|
@ -809,7 +816,8 @@
|
|||
|
||||
<h3 id="systemd">SystemD<a class="headerlink" href="#systemd" title="Permalink to this headline">¶</a></h3>
|
||||
<p>SystemD is a system service manager for a wide array of Linux operating systems. Not all Linux distributions have adopted systemd, but, for better or worse, it has become a fairly common standard in the Linux world. That said, any non-Linux operating system will not have systemd, and many Linux/Unix distributionshave alternative system service managers.</p>
|
||||
<p>Netmaker’s netclient, the agent which controls networking on all nodes, can be run as a CLI or as a system daemon. It runs as a daemon by default, and this requires systemd. As Netmaker evolves, systemd will become just one of the possible service management options, allowing the netclient to be run on a wider array of devices. However, for the time being, the netclient should be run “unmanaged” (netclient join -daemon=off) on systems that do not run systemd, and some other method can be used like a cron job or custom script.</p>
|
||||
<p>Netmaker’s netclient, the agent which controls networking on all nodes, can be run as a CLI or as a system daemon. On Linux, it runs as a daemon by default, and this requires systemd. As Netmaker evolves, systemd will become just one of the possible service management options, allowing the netclient to be run on a wider array of devices. However, for the time being, the netclient should be run “unmanaged” (netclient join -daemon=off) on systems that do not run systemd, and some other method can be used like a cron job or custom script.</p>
|
||||
<p>As of 0.8, Mac and Windows are supported. On these operating systems, netclient launches the daemon using LaunchD and Windows Service, respectively, as opposed to SystemD.</p>
|
||||
|
||||
|
||||
|
||||
|
|
@ -821,21 +829,22 @@
|
|||
<p>The Netmaker server acts as an API to the front end, and as a GRPC server to the machines in the network. GRPC is much faster and more efficient than standard API calls, which increases the speed of transactions. For this reason, the Netmaker server exposes two ports: The default for the API is 8081, and the default for GRPC is 50051. Either the API or the GRPC server can be disabled on any given Netmaker instance can be disabled, allowing you to deploy two different servers for managing the API (which is largely for the admin’s use) and GRPC (which is largely for the nodes’ use).</p>
|
||||
<p>Most server settings are configurable via a config file, or by environment variables (which take precedence). If the server finds neither of these, it sets sensible defaults, including things like the server’s reachable IP, ports, and which “modes” to run in.</p>
|
||||
<p>These modes include client mode and dns mode. Either of these can be disabled but are enabled by default. Client mode allows you to treat the Netmaker host machine (operating system) as a network Node, installing the netclient and controlling the host network. DNS mode has the server write config settings for CoreDNS, a separate component and nameserver, which picks up the config settings to manage node DNS.</p>
|
||||
<p>The Netmaker server interacts with rqlite, a distributed version of sqlite, which holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration.</p>
|
||||
<p>The Netmaker server interacts with either sqlit (default) or rqlite, a distributed version of sqlite, as its database. This DB holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration.</p>
|
||||
|
||||
|
||||
<h3 id="netclient">Netclient<a class="headerlink" href="#netclient" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The netclient is, at its core, a golang binary. Source code can be found in the netclient folder of the Netmaker <a class="reference external" href="https://github.com/gravitl/netmaker/tree/master/netclient">GitHub Repository</a>. The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems. As of version 0.5, the netclient can be run as a system daemon on linux distributions with systemd, or as an “unmanaged” client on distributions without systemd.</p>
|
||||
<p>The netclient is, at its core, a golang binary. Source code can be found in the netclient folder of the Netmaker <a class="reference external" href="https://github.com/gravitl/netmaker/tree/master/netclient">GitHub Repository</a>. The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems. As of version 0.8, the netclient can be run as a system daemon on linux distributions with systemd, or as an “unmanaged” client on distributions without systemd. The netclient for Windows and Mac will run as a Windows Service or LaunchDaemon, respectively.</p>
|
||||
<p>The netclient is installed via a simple bash script, which pulls the latest binary and runs ‘register’ and ‘join’ commands.</p>
|
||||
<p>The ‘register’ command adds a WireGuard tunnel directly to the netmaker server, for all subsequent communication.</p>
|
||||
<p>The ‘join’ command attempts to add the machine to the Netmaker network using sensible defaults, which can be overridden with a config file or environment variables. Assuming the netclient has a valid key (or the network allows manual node signup), it will be registered into the Netmaker network, and will be returned necessary configuration details for how to set up its local network.</p>
|
||||
<p>The netclient then sets up the systemd daemon (if running in daemon mode), and configures WireGuard. At this point it should be part of the network.</p>
|
||||
<p>The netclient then sets up the system daemon (if running in daemon mode), and configures WireGuard. At this point it should be part of the network.</p>
|
||||
<p>If running in daemon mode, on a periodic basis (systemd timer), the netclient performs a “check in.” It will authenticate with the server, and check to see if anything has changed in the network. It will also post changes about its own local configuration if there. If there has been a change, the server will return new configurations and the netclient will reconfigure the network. If not running in daemon mode, it is up to the operator to perform check ins (netclient checkin -n < network name >).</p>
|
||||
<p>The check in process is what allows Netmaker to create dynamic mesh networks. As nodes are added to, removed from, and modified on the network, other nodes are notified, and make appropriate changes.</p>
|
||||
|
||||
|
||||
<h3 id="rqlite">rqlite<a class="headerlink" href="#rqlite" title="Permalink to this headline">¶</a></h3>
|
||||
<p>As of v0.7, Netmaker uses rqlite, a distributed (RAFT consensus) database, and interacts with this database to store and retrieve information about nodes, networks, and users. With the 0.7 refactor, additional database support is very easy to implement. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file.</p>
|
||||
<h3 id="sqlite-and-rqlite">sqlite and rqlite<a class="headerlink" href="#sqlite-and-rqlite" title="Permalink to this headline">¶</a></h3>
|
||||
<p>As of v0.8, Netmaker uses sqlite by default as a database. It can also use rqlite, a distributed (RAFT consensus) databaseand. Netmaker interacts with this database to store and retrieve information about nodes, networks, and users.</p>
|
||||
<p>Additional database support (besides sqlite and rqlite) is very easy to implement for special use cases. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file.</p>
|
||||
|
||||
|
||||
<h3 id="netmaker-ui">Netmaker UI<a class="headerlink" href="#netmaker-ui" title="Permalink to this headline">¶</a></h3>
|
||||
|
|
@ -845,13 +854,13 @@
|
|||
|
||||
<h3 id="coredns">CoreDNS<a class="headerlink" href="#coredns" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Netmaker allows users to provide and manage Private DNS for their nodes. This requires a nameserver, and CoreDNS is the chosen nameserver. CoreDNS is lightweight and extensible. CoreDNS loads dns settings from a simple file, managed by Netmaker, and serves out DNS info for managed nodes. DNS can be tricky, and DNS management is currently only supported on a small set of devices, specifically those running systemd-resolved. However, the Netmaker CoreDNS instance can be added manually as a nameserver to other devices. DNS mode can also be turned off.</p>
|
||||
<p>Worth considering is that CoreDNS requires port 53 on the Netmaker host system, which may cause conflicts depending on your operating system. This is explained in the <a class="reference internal" href="server-installation.html"><span class="doc">Server Installation</span></a> guide.</p>
|
||||
|
||||
|
||||
<h3 id="external-client">External Client<a class="headerlink" href="#external-client" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The external client is simply a manually configured WireGuard connection to your network, which Netmaker helps to manage.</p>
|
||||
<p>Most machines can run WireGuard. It is fairly simple to set up a WireGuard connection to a single endpoint. It is setting up mesh networks and other topologies like site-to-site which becomes complicated.</p>
|
||||
<p>Netmaker v0.5 introduces the “external client” to handle any devices which are not currently compatible with the netclient, including Windows, iPhone, Android, and Mac. Over time, this list will be eliminated and there may not even be a need for the external client.</p>
|
||||
<p>Mac, Windows, and Linux are handled natively by the Netclient.</p>
|
||||
<p>Netmaker can issue “external clients” to handle any devices which are not currently compatible with the netclient, including iPhone, Android, and some Unix distributions. Over time, this list will be eliminated and there may not even be a need for the external client.</p>
|
||||
<p>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.</p>
|
||||
|
||||
|
||||
|
|
@ -880,9 +889,12 @@
|
|||
|
||||
|
||||
<h2 id="compatible-systems-for-netclient">Compatible Systems for Netclient<a class="headerlink" href="#compatible-systems-for-netclient" title="Permalink to this headline">¶</a></h2>
|
||||
<p>To manage a node manually, the Netclient can be compiled and run for most linux distibutions, with a prerequisite of WireGuard.</p>
|
||||
<p>To manage a node manually, the Netclient can be compiled and run for most linux distibutions, with a prerequisite of WireGuard with kernel headers. If the netclient from the release pages does not run natively on your system, you may need to compile the netclient binary directly on the machine from the source code. This may be true for some installations of SUSE, Fedora, and some Debian-based systems. However, if the dependencies are installed on the machine, the netclient should run correctly after being compiled.</p>
|
||||
<p>Simply clone the repo, cd to netmaker/netclient and run “go build” (Golang must be installed).</p>
|
||||
<dl class="simple">
|
||||
<dt>To manage a node automatically, the Netmaker client (netclient) requires <strong>systemd-based linux.</strong> Compatible systems include:</dt><dd><ul class="simple">
|
||||
<dt>The following systems should be operable natively with Netclient in daemon mode:</dt><dd><ul class="simple">
|
||||
<li><p>Windows</p></li>
|
||||
<li><p>Mac</p></li>
|
||||
<li><p>Fedora</p></li>
|
||||
<li><p>Ubuntu</p></li>
|
||||
<li><p>Debian</p></li>
|
||||
|
|
@ -906,8 +918,7 @@
|
|||
|
||||
|
||||
<h2 id="limitations">Limitations<a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Install limitations mostly include platform-specific limitations, such as needing systemd or systemd-resolved (see above).</p>
|
||||
<p>In addition the Netmaker is currently unable to route traffic for for devices behind a “carrier-grade NAT”. This will be solved in a future release with the introduction of relay servers.</p>
|
||||
<p>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.: <a class="reference external" href="https://stackoverflow.com/questions/62356581/wireguard-vpn-how-to-fix-operation-not-supported-if-it-worked-before">Installing Kernel Headers on Debian</a>)</p>
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
30
docs/_build/html/client-installation.html
vendored
30
docs/_build/html/client-installation.html
vendored
|
|
@ -432,6 +432,8 @@
|
|||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#modes-and-system-compatibility" class="md-nav__link">Modes and System Compatibility</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#cli" class="md-nav__link">CLI</a>
|
||||
|
|
@ -477,6 +479,13 @@
|
|||
<a href="#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
|
@ -540,6 +549,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -729,6 +745,8 @@
|
|||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#modes-and-system-compatibility" class="md-nav__link">Modes and System Compatibility</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#cli" class="md-nav__link">CLI</a>
|
||||
|
|
@ -787,6 +805,13 @@
|
|||
<p>The netclient agent then configures WireGuard (and other network properties) locally, so that the network stays intact.</p>
|
||||
|
||||
|
||||
<h2 id="notes-on-windows">Notes on Windows<a class="headerlink" href="#notes-on-windows" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If running the netclient on windows, you must download the netclient.exe binary and run it from Powershell as an Administrator.</p>
|
||||
<p>Windows will by default have firewall rules that prevent inbound connections. If you wish to allow inbound connections from particular peers, use the following command:</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">netsh</span> <span class="pre">advfirewall</span> <span class="pre">firewall</span> <span class="pre">add</span> <span class="pre">rule</span> <span class="pre">name="Allow</span> <span class="pre">from</span> <span class="pre"><peer</span> <span class="pre">private</span> <span class="pre">addr>"</span> <span class="pre">dir=in</span> <span class="pre">action=allow</span> <span class="pre">protocol=ANY</span> <span class="pre">remoteip=<peer</span> <span class="pre">private</span> <span class="pre">addr></span></code></p>
|
||||
<p>If you want to allow all peers access, but do not want to configure firewall rules for all peers, you can configure access for one peer, and set it as a Relay Server.</p>
|
||||
|
||||
|
||||
<h2 id="modes-and-system-compatibility">Modes and System Compatibility<a class="headerlink" href="#modes-and-system-compatibility" title="Permalink to this headline">¶</a></h2>
|
||||
<p><strong>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</strong></p>
|
||||
<p>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.”</p>
|
||||
|
|
@ -797,9 +822,8 @@
|
|||
|
||||
|
||||
<h3 id="daemon">Daemon<a class="headerlink" href="#daemon" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The netclient is intended to be run as a system daemon. This allows it to automatically retrieve and send updates. To do this, the netclient can install itself as a systemd service.</p>
|
||||
<p>This requires a systemd-based linux operating system.</p>
|
||||
<p>If running the netclient on a non-systemd system, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.</p>
|
||||
<p>The netclient is intended to be run as a system daemon. This allows it to automatically retrieve and send updates. To do this, the netclient can install itself as a systemd service, or launchd/windows service for Mac or Windows.</p>
|
||||
<p>If running the netclient on non-systemd linux, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.</p>
|
||||
|
||||
|
||||
<h3 id="private-dns-management">Private DNS Management<a class="headerlink" href="#private-dns-management" title="Permalink to this headline">¶</a></h3>
|
||||
|
|
|
|||
27
docs/_build/html/external-clients.html
vendored
27
docs/_build/html/external-clients.html
vendored
|
|
@ -427,6 +427,13 @@
|
|||
<a href="client-installation.html#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="client-installation.html#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
|
@ -484,6 +491,8 @@
|
|||
<li class="md-nav__item"><a href="#configuring-an-ingress-gateway" class="md-nav__link">Configuring an Ingress Gateway</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
</li>
|
||||
|
|
@ -510,6 +519,13 @@
|
|||
<a href="#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -702,6 +718,8 @@
|
|||
<li class="md-nav__item"><a href="#configuring-an-ingress-gateway" class="md-nav__link">Configuring an Ingress Gateway</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
</li>
|
||||
|
|
@ -729,7 +747,7 @@
|
|||
<p>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 <strong>Ingress Gateway</strong>, which <strong>is</strong> a managed server (running netclient). This server then forwards traffic to the appropriate endpoint, acting as a middle-man/relay.</p>
|
||||
<p>By using this method, you can hook any machine into a netmaker network that can run WireGuard.</p>
|
||||
<p>It is recommended to run the netclient where compatible, but for all other cases, a machine can be configured as an external client.</p>
|
||||
<p>Important to note, an external client is not <strong>reachable</strong> 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 resource runnin on the virtual network, and <strong>not</strong> for use cases where one wishes to make a resource accessible on the network. For that, use netclient.</p>
|
||||
<p>Important to note, an external client is not <strong>reachable</strong> 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 resource running on the virtual network, and <strong>not</strong> for use cases where one wishes to make a resource accessible on the network. For that, use netclient.</p>
|
||||
|
||||
|
||||
<h2 id="configuring-an-ingress-gateway">Configuring an Ingress Gateway<a class="headerlink" href="#configuring-an-ingress-gateway" title="Permalink to this headline">¶</a></h2>
|
||||
|
|
@ -760,6 +778,13 @@
|
|||
<p>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.</p>
|
||||
|
||||
|
||||
<h2 id="configuring-dns-for-ext-clients-optional">Configuring DNS for Ext Clients (OPTIONAL)<a class="headerlink" href="#configuring-dns-for-ext-clients-optional" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you wish to have a DNS field on your ext clients conf, simply edit the network field as shown below to 1.1.1.1 or 8.8.8.8 for example.
|
||||
If you do not want DNS on your ext client conf files, simply leave it blank.</p>
|
||||
<a class="reference internal image-reference" href="images/exclient5.png"><img alt="Gateway" class="align-center" src="images/exclient5.png" style="width: 80%;"/></a>
|
||||
<p>Important to note, your client automatically adds egress gateway ranges (if any on the same network) to it’s allowed IPs.</p>
|
||||
|
||||
|
||||
|
||||
|
||||
</article>
|
||||
|
|
|
|||
14
docs/_build/html/genindex.html
vendored
14
docs/_build/html/genindex.html
vendored
|
|
@ -425,6 +425,13 @@
|
|||
<a href="client-installation.html#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="client-installation.html#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
|
@ -488,6 +495,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
|
|||
10
docs/_build/html/getting-started.html
vendored
10
docs/_build/html/getting-started.html
vendored
|
|
@ -518,6 +518,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -778,7 +785,8 @@
|
|||
<li><p>SSH to each machine</p></li>
|
||||
<li><p><code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">su</span> <span class="pre">-</span></code></p></li>
|
||||
<li><p><strong>Prerequisite Check:</strong> Every Linux machine on which you run the netclient must have WireGuard and systemd installed</p></li>
|
||||
<li><p>Run the install command, Ex: <code class="docutils literal notranslate"><span class="pre">curl</span> <span class="pre">-sfL</span> <span class="pre">https://raw.githubusercontent.com/gravitl/netmaker/develop/scripts/netclient-install.sh</span> <span class="pre">|</span> <span class="pre">KEY=vm3ow4thatogiwnsla3thsl3894ths</span> <span class="pre">sh</span> <span class="pre">-</span></code></p></li>
|
||||
<li><p>For linux machines with SystemD and WireGuard installed, Run the install command, Ex: <code class="docutils literal notranslate"><span class="pre">curl</span> <span class="pre">-sfL</span> <span class="pre">https://raw.githubusercontent.com/gravitl/netmaker/develop/scripts/netclient-install.sh</span> <span class="pre">|</span> <span class="pre">KEY=vm3ow4thatogiwnsla3thsl3894ths</span> <span class="pre">sh</span> <span class="pre">-</span></code></p></li>
|
||||
<li><p>For Mac, Windows, and arch-specific linux distributions (e.g. ARM), <a class="reference external" href="https://github.com/gravitl/netmaker/releases/tag/latest/">download the appropriate netclient for your system</a> . Then, run “netclient join -t <your token>”.</p></li>
|
||||
</ol>
|
||||
<p>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 <a class="reference internal" href="client-installation.html"><span class="doc">client installation</span></a> documentation. If this process failed and you do not see your node in the console (see below), then reference the <a class="reference internal" href="troubleshoot.html"><span class="doc">troubleshooting</span></a> documentation.</p>
|
||||
<a class="reference internal image-reference" href="_images/nc-install-output.png"><img alt="Output from Netclient Install" class="align-center" src="_images/nc-install-output.png" style="width: 80%;"/></a>
|
||||
|
|
|
|||
16
docs/_build/html/index.html
vendored
16
docs/_build/html/index.html
vendored
|
|
@ -426,6 +426,13 @@
|
|||
<a href="client-installation.html#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="client-installation.html#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
|
@ -489,6 +496,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -800,6 +814,7 @@
|
|||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="client-installation.html">Client Installation</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="client-installation.html#introduction-to-netclient">Introduction to Netclient</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="client-installation.html#notes-on-windows">Notes on Windows</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="client-installation.html#modes-and-system-compatibility">Modes and System Compatibility</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="client-installation.html#prerequisites">Prerequisites</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="client-installation.html#configuration">Configuration</a></li>
|
||||
|
|
@ -819,6 +834,7 @@
|
|||
<li class="toctree-l2"><a class="reference internal" href="external-clients.html#introduction">Introduction</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="external-clients.html#configuring-an-ingress-gateway">Configuring an Ingress Gateway</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="external-clients.html#adding-clients-to-a-gateway">Adding Clients to a Gateway</a></li>
|
||||
<li class="toctree-l2"><a class="reference internal" href="external-clients.html#configuring-dns-for-ext-clients-optional">Configuring DNS for Ext Clients (OPTIONAL)</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
|
|
|||
77
docs/_build/html/quick-start.html
vendored
77
docs/_build/html/quick-start.html
vendored
|
|
@ -308,8 +308,6 @@
|
|||
</li>
|
||||
<li class="md-nav__item"><a href="#prepare-firewall" class="md-nav__link">Prepare Firewall</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#prepare-for-dns" class="md-nav__link">Prepare for DNS</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#prepare-nginx" class="md-nav__link">Prepare Nginx</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
|
|
@ -473,6 +471,13 @@
|
|||
<a href="client-installation.html#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="client-installation.html#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
|
@ -536,6 +541,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -741,8 +753,6 @@
|
|||
</li>
|
||||
<li class="md-nav__item"><a href="#prepare-firewall" class="md-nav__link">Prepare Firewall</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#prepare-for-dns" class="md-nav__link">Prepare for DNS</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#prepare-nginx" class="md-nav__link">Prepare Nginx</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
|
|
@ -771,21 +781,33 @@
|
|||
<p>This quick start guide is an <strong>opinionated</strong> guide for getting up and running with Netmaker as quickly as possible.</p>
|
||||
|
||||
<h2 id="introduction">0. Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
|
||||
<p>We assume for this installation that you want all of the Netmaker features enabled, want your server to be secure, and want it to be accessible from anywhere.</p>
|
||||
<p>This instance will not be HA. However, it should comfortably handle around one hundred concurrent clients and support most use cases.</p>
|
||||
<p>If you are deploying for an enterprise use case, please contact <a class="reference external" href="mailto:info%40gravitl.com">info<span>@</span>gravitl<span>.</span>com</a> for support.</p>
|
||||
<p>We assume for this installation that you want all of the Netmaker features enabled, you want your server to be secure, and you want your server to be accessible from anywhere.</p>
|
||||
<p>This instance will not be HA. However, it should comfortably handle around one hundred concurrent clients and support the most common use cases.</p>
|
||||
<p>If you are deploying for a business or enterprise use case and this setup will not fit your needs, please contact <a class="reference external" href="mailto:info%40gravitl.com">info<span>@</span>gravitl<span>.</span>com</a>, or check out the business subscription plans at <a class="reference external" href="https://gravitl.com/plans/business">https://gravitl.com/plans/business</a>.</p>
|
||||
<p>By the end of this guide, you will have Netmaker installed on a public VM linked to your custom domain, secured behind an Nginx reverse proxy.</p>
|
||||
<p>If this configuration does not fit your use case, see the <a class="reference internal" href="server-installation.html"><span class="doc">Advanced Installation</span></a> docs.</p>
|
||||
<p>For information about deploying more advanced configurations, see the <a class="reference internal" href="server-installation.html"><span class="doc">Advanced Installation</span></a> docs.</p>
|
||||
|
||||
|
||||
<h2 id="prerequisites">1. Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p><strong>Virtual Machine</strong></p>
|
||||
<ul>
|
||||
<li><p>Preferably from a cloud provider (e.x: DigitalOcean, Linode, AWS, GCP, etc.)</p></li>
|
||||
<li><dl class="simple">
|
||||
<dt>Preferably from a cloud provider (e.x: DigitalOcean, Linode, AWS, GCP, etc.)</dt><dd><ul>
|
||||
<li><p>We do not recommend Oracle Cloud, as VM’s here have been known to cause network interference.</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
</li>
|
||||
<li><p>Public, static IP</p></li>
|
||||
<li><p>Min 2GB RAM, 1 CPU (4GB RAM, 2CPU preferred)</p></li>
|
||||
<li><p>5GB+ of storage</p></li>
|
||||
<li><dl class="simple">
|
||||
<dt>Min 1GB RAM, 1 CPU (4GB RAM, 2CPU preferred)</dt><dd><ul>
|
||||
<li><p>Nginx may have performance issues if using a cloud VPS with a single, shared CPU</p></li>
|
||||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
</li>
|
||||
<li><p>2GB+ of storage</p></li>
|
||||
<li><p>Ubuntu 20.04 Installed</p></li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -805,11 +827,11 @@
|
|||
<p>Begin by installing the community version of Docker and docker-compose (there are issues with the snap version). You can follow the official <a class="reference external" href="https://docs.docker.com/engine/install/">Docker instructions here</a>. Or, you can use the below series of commands which should work on Ubuntu 20.04.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">remove</span> <span class="n">docker</span> <span class="n">docker</span><span class="o">-</span><span class="n">engine</span> <span class="n">docker</span><span class="o">.</span><span class="n">io</span> <span class="n">containerd</span> <span class="n">runc</span>
|
||||
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">update</span>
|
||||
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">apt</span><span class="o">-</span><span class="n">transport</span><span class="o">-</span><span class="n">https</span> <span class="n">ca</span><span class="o">-</span><span class="n">certificates</span> <span class="n">curl</span> <span class="n">gnupg</span> <span class="n">lsb</span><span class="o">-</span><span class="n">release</span>
|
||||
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="o">-</span><span class="n">y</span> <span class="n">install</span> <span class="n">apt</span><span class="o">-</span><span class="n">transport</span><span class="o">-</span><span class="n">https</span> <span class="n">ca</span><span class="o">-</span><span class="n">certificates</span> <span class="n">curl</span> <span class="n">gnupg</span> <span class="n">lsb</span><span class="o">-</span><span class="n">release</span>
|
||||
<span class="n">curl</span> <span class="o">-</span><span class="n">fsSL</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">download</span><span class="o">.</span><span class="n">docker</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">linux</span><span class="o">/</span><span class="n">ubuntu</span><span class="o">/</span><span class="n">gpg</span> <span class="o">|</span> <span class="n">sudo</span> <span class="n">gpg</span> <span class="o">--</span><span class="n">dearmor</span> <span class="o">-</span><span class="n">o</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">share</span><span class="o">/</span><span class="n">keyrings</span><span class="o">/</span><span class="n">docker</span><span class="o">-</span><span class="n">archive</span><span class="o">-</span><span class="n">keyring</span><span class="o">.</span><span class="n">gpg</span>
|
||||
<span class="n">echo</span> <span class="s2">"deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"</span> <span class="o">|</span> <span class="n">sudo</span> <span class="n">tee</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">apt</span><span class="o">/</span><span class="n">sources</span><span class="o">.</span><span class="n">list</span><span class="o">.</span><span class="n">d</span><span class="o">/</span><span class="n">docker</span><span class="o">.</span><span class="n">list</span> <span class="o">></span> <span class="o">/</span><span class="n">dev</span><span class="o">/</span><span class="n">null</span>
|
||||
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">update</span>
|
||||
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">docker</span><span class="o">-</span><span class="n">ce</span> <span class="n">docker</span><span class="o">-</span><span class="n">ce</span><span class="o">-</span><span class="n">cli</span> <span class="n">containerd</span><span class="o">.</span><span class="n">io</span>
|
||||
<span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="o">-</span><span class="n">y</span> <span class="n">install</span> <span class="n">docker</span><span class="o">-</span><span class="n">ce</span> <span class="n">docker</span><span class="o">-</span><span class="n">ce</span><span class="o">-</span><span class="n">cli</span> <span class="n">containerd</span><span class="o">.</span><span class="n">io</span>
|
||||
<span class="n">sudo</span> <span class="n">curl</span> <span class="o">-</span><span class="n">L</span> <span class="s2">"https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)"</span> <span class="o">-</span><span class="n">o</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">docker</span><span class="o">-</span><span class="n">compose</span>
|
||||
<span class="n">sudo</span> <span class="n">chmod</span> <span class="o">+</span><span class="n">x</span> <span class="o">/</span><span class="n">usr</span><span class="o">/</span><span class="n">local</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">docker</span><span class="o">-</span><span class="n">compose</span>
|
||||
<span class="n">docker</span> <span class="o">--</span><span class="n">version</span>
|
||||
|
|
@ -821,7 +843,7 @@
|
|||
|
||||
<h3 id="id1">Install Dependencies<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
|
||||
<p>In addition to Docker, this installation requires WireGuard, Nginx, and Certbot.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">install</span> <span class="pre">wireguard</span> <span class="pre">wireguard-tools</span> <span class="pre">nginx</span> <span class="pre">certbot</span> <span class="pre">python3-certbot-nginx</span> <span class="pre">net-tools</span></code></p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">apt</span> <span class="pre">-y</span> <span class="pre">install</span> <span class="pre">wireguard</span> <span class="pre">wireguard-tools</span> <span class="pre">nginx</span> <span class="pre">certbot</span> <span class="pre">python3-certbot-nginx</span> <span class="pre">net-tools</span></code></p>
|
||||
|
||||
|
||||
|
||||
|
|
@ -864,18 +886,8 @@
|
|||
</ul>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
<h3 id="prepare-for-dns">Prepare for DNS<a class="headerlink" href="#prepare-for-dns" title="Permalink to this headline">¶</a></h3>
|
||||
<p>On Ubuntu 20.04, by default there is a service consuming port 53 related to DNS resolution. We need port 53 open in order to run our own DNS server. The below steps will disable systemd-resolved, and insert a generic DNS nameserver for local resolution.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">systemctl</span> <span class="n">stop</span> <span class="n">systemd</span><span class="o">-</span><span class="n">resolved</span>
|
||||
<span class="n">systemctl</span> <span class="n">disable</span> <span class="n">systemd</span><span class="o">-</span><span class="n">resolved</span>
|
||||
<span class="n">vim</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">systemd</span><span class="o">/</span><span class="n">resolved</span><span class="o">.</span><span class="n">conf</span>
|
||||
<span class="o">*</span> <span class="n">uncomment</span> <span class="n">DNS</span> <span class="ow">and</span> <span class="n">add</span> <span class="mf">8.8.8.8</span> <span class="ow">or</span> <span class="n">whatever</span> <span class="n">reachable</span> <span class="n">nameserver</span> <span class="ow">is</span> <span class="n">your</span> <span class="n">preference</span> <span class="o">*</span>
|
||||
<span class="o">*</span> <span class="n">uncomment</span> <span class="n">DNSStubListener</span> <span class="ow">and</span> <span class="nb">set</span> <span class="n">to</span> <span class="s2">"no"</span> <span class="o">*</span>
|
||||
<span class="n">ln</span> <span class="o">-</span><span class="n">sf</span> <span class="o">/</span><span class="n">run</span><span class="o">/</span><span class="n">systemd</span><span class="o">/</span><span class="n">resolve</span><span class="o">/</span><span class="n">resolv</span><span class="o">.</span><span class="n">conf</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">resolv</span><span class="o">.</span><span class="n">conf</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>In addition to the above ports, you will need to make sure that your cloud’s firewall or security groups are opened for the range of ports that Netmaker’s WireGuard interfaces consume.</p>
|
||||
<p>Netmaker will create one interface per network, starting from 51821. So, if you plan on having 5 networks, you will want to have at least 51821-51825 open (udp).</p>
|
||||
|
||||
|
||||
<h3 id="prepare-nginx">Prepare Nginx<a class="headerlink" href="#prepare-nginx" title="Permalink to this headline">¶</a></h3>
|
||||
|
|
@ -895,20 +907,23 @@
|
|||
<h2 id="install-netmaker">4. Install Netmaker<a class="headerlink" href="#install-netmaker" title="Permalink to this headline">¶</a></h2>
|
||||
|
||||
<h3 id="prepare-templates">Prepare Templates<a class="headerlink" href="#prepare-templates" title="Permalink to this headline">¶</a></h3>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">wget</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">raw</span><span class="o">.</span><span class="n">githubusercontent</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">gravitl</span><span class="o">/</span><span class="n">netmaker</span><span class="o">/</span><span class="n">develop</span><span class="o">/</span><span class="n">compose</span><span class="o">/</span><span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">quickstart</span><span class="o">.</span><span class="n">yml</span>
|
||||
<span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="s1">'s/NETMAKER_BASE_DOMAIN/<your base domain>/g'</span> <span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">quickstart</span><span class="o">.</span><span class="n">yml</span>
|
||||
<span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="s1">'s/SERVER_PUBLIC_IP/<your server ip>/g'</span> <span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">quickstart</span><span class="o">.</span><span class="n">yml</span>
|
||||
<p><strong>Note on COREDNS_IP:</strong> Depending on your cloud provider, the public IP may not be bound directly to the VM on which you are running. In such cases, CoreDNS cannot bind to this IP, and you should use the IP of the default interface on your machine in place of COREDNS_IP. If the public IP <strong>is</strong> bound to the VM, you can simply use the same IP as SERVER_PUBLIC_IP.</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">wget</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">raw</span><span class="o">.</span><span class="n">githubusercontent</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">gravitl</span><span class="o">/</span><span class="n">netmaker</span><span class="o">/</span><span class="n">develop</span><span class="o">/</span><span class="n">compose</span><span class="o">/</span><span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">yml</span>
|
||||
<span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="s1">'s/NETMAKER_BASE_DOMAIN/<your base domain>/g'</span> <span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">yml</span>
|
||||
<span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="s1">'s/SERVER_PUBLIC_IP/<your server ip>/g'</span> <span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">yml</span>
|
||||
<span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="s1">'s/COREDNS_IP/<your server ip>/g'</span> <span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">yml</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Generate a unique master key and insert it:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">tr</span> <span class="o">-</span><span class="n">dc</span> <span class="n">A</span><span class="o">-</span><span class="n">Za</span><span class="o">-</span><span class="n">z0</span><span class="o">-</span><span class="mi">9</span> <span class="o"></</span><span class="n">dev</span><span class="o">/</span><span class="n">urandom</span> <span class="o">|</span> <span class="n">head</span> <span class="o">-</span><span class="n">c</span> <span class="mi">30</span> <span class="p">;</span> <span class="n">echo</span> <span class="s1">''</span>
|
||||
<span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="s1">'s/REPLACE_MASTER_KEY/<your generated key>/g'</span> <span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">quickstart</span><span class="o">.</span><span class="n">yml</span>
|
||||
<span class="n">sed</span> <span class="o">-</span><span class="n">i</span> <span class="s1">'s/REPLACE_MASTER_KEY/<your generated key>/g'</span> <span class="n">docker</span><span class="o">-</span><span class="n">compose</span><span class="o">.</span><span class="n">yml</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You may want to save this key for future use with the API.</p>
|
||||
|
||||
|
||||
<h3 id="start-netmaker">Start Netmaker<a class="headerlink" href="#start-netmaker" title="Permalink to this headline">¶</a></h3>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">docker-compose</span> <span class="pre">-f</span> <span class="pre">docker-compose.quickstart.yml</span> <span class="pre">up</span> <span class="pre">-d</span></code></p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">docker-compose</span> <span class="pre">-f</span> <span class="pre">docker-compose.yml</span> <span class="pre">up</span> <span class="pre">-d</span></code></p>
|
||||
<p>navigate to dashboard.<your base domain> to see your nginx instance.</p>
|
||||
<p>To troubleshoot issues, start with:</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">docker</span> <span class="pre">logs</span> <span class="pre">netmaker</span></code></p>
|
||||
|
|
|
|||
14
docs/_build/html/search.html
vendored
14
docs/_build/html/search.html
vendored
|
|
@ -431,6 +431,13 @@
|
|||
<a href="client-installation.html#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="client-installation.html#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
|
@ -494,6 +501,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
|
|||
2
docs/_build/html/searchindex.js
vendored
2
docs/_build/html/searchindex.js
vendored
File diff suppressed because one or more lines are too long
16
docs/_build/html/server-installation.html
vendored
16
docs/_build/html/server-installation.html
vendored
|
|
@ -548,6 +548,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -853,6 +860,15 @@
|
|||
<dt>DNS_MODE:</dt><dd><p><strong>Default:</strong> “off”</p>
|
||||
<p><strong>Description:</strong> Enables DNS Mode, meaning config files will be generated for CoreDNS.</p>
|
||||
</dd>
|
||||
<dt>DATABASE:</dt><dd><p><strong>Default:</strong> “sqlite”</p>
|
||||
<p><strong>Description:</strong> Specify db type to connect with. Currently, options include “sqlite” and “rqlite”.</p>
|
||||
</dd>
|
||||
<dt>SQL_CONN:</dt><dd><p><strong>Default:</strong> “<a class="reference external" href="http://">http://</a>”</p>
|
||||
<p><strong>Description:</strong> Specify the necessary string to connect with your local or remote sql database.</p>
|
||||
</dd>
|
||||
<dt>CLIENT_MODE:</dt><dd><p><strong>Default:</strong> “on”</p>
|
||||
<p><strong>Description:</strong> Specifies if server should deploy itself as a node (client) in each network. May be turned to “off” for more restricted servers.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
|
|
|
|||
24
docs/_build/html/troubleshoot.html
vendored
24
docs/_build/html/troubleshoot.html
vendored
|
|
@ -427,6 +427,13 @@
|
|||
<a href="client-installation.html#introduction-to-netclient" class="md-nav__link">Introduction to Netclient</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="client-installation.html#notes-on-windows" class="md-nav__link">Notes on Windows</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
|
@ -490,6 +497,13 @@
|
|||
<a href="external-clients.html#adding-clients-to-a-gateway" class="md-nav__link">Adding Clients to a Gateway</a>
|
||||
|
||||
|
||||
</li>
|
||||
<li class="md-nav__item">
|
||||
|
||||
|
||||
<a href="external-clients.html#configuring-dns-for-ext-clients-optional" class="md-nav__link">Configuring DNS for Ext Clients (OPTIONAL)</a>
|
||||
|
||||
|
||||
</li></ul>
|
||||
|
||||
</li>
|
||||
|
|
@ -727,8 +741,8 @@
|
|||
|
||||
<h2 id="common-issues">Common Issues<a class="headerlink" href="#common-issues" title="Permalink to this headline">¶</a></h2>
|
||||
<dl class="simple">
|
||||
<dt><strong>How can I connect my Android, IOS, MacOS or Windows device to my Netmaker VPN?</strong></dt><dd><p>Currently meshing one of these devices is not supported, however it will be soon.
|
||||
For now you can connect to your VPN by making one of the nodes an Ingressgateway, then
|
||||
<dt><strong>How can I connect my Android or IOS device to my Netmaker VPN?</strong></dt><dd><p>Currently meshing one of these devices is not supported, however it will be soon.
|
||||
For now you can connect to your VPN by making one of the nodes an Ingress Gateway, then
|
||||
create an Ext Client for each device. Finally, use the official WG app or another
|
||||
WG configuration app to connect via QR or downloading the device’s WireGuard configuration.</p>
|
||||
</dd>
|
||||
|
|
@ -741,11 +755,15 @@ Simply turn on “allow manual signups” on your network and nodes will not con
|
|||
<dt><strong>Is there a community or forum to ask questions about Netmaker?</strong></dt><dd><p>Yes, we have an active <a class="reference external" href="https://discord.gg/Pt4T9y9XK8">discord</a> community and issues on our <a class="reference external" href="https://github.com/gravitl/netmaker/issues">github</a> are answered frequently!
|
||||
You can also sign-up for updates at our <a class="reference external" href="https://gravitl.com/">gravitl site</a>!</p>
|
||||
</dd>
|
||||
<dt><strong>How can I get additional support for my business?</strong></dt><dd><p>Check out our business support subscriptions at <a class="reference external" href="https://gravitl.com/plans">https://gravitl.com/plans</a>. Subscription holders can also purchase consulting credits via the site.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
<h2 id="server">Server<a class="headerlink" href="#server" title="Permalink to this headline">¶</a></h2>
|
||||
<dl class="simple">
|
||||
<dt><strong>I upgraded from 0.7 to 0.8 and now I dont have any data in my server!</strong></dt><dd><p>In 0.8, sqlite becomes the default database. If you were running with rqlite, you must set the DATABASE environment variable to rqlite in order to continue using rqlite.</p>
|
||||
</dd>
|
||||
<dt><strong>Can I secure/encrypt all the traffic to my server and UI?</strong></dt><dd><p>This can fairly simple to achieve assuming you have access to a domain and are familiar with Nginx.
|
||||
Please refer to the quick-start guide to see!</p>
|
||||
</dd>
|
||||
|
|
@ -804,6 +822,8 @@ You can also see the current WireGuard configuration with <code class="docutils
|
|||
</pre></div>
|
||||
</div>
|
||||
</dd>
|
||||
<dt><strong>I have a handshake with a peer but can’t ping it, what gives?</strong></dt><dd><p>This is commonly due to incorrect MTU settings. Typically, it will be because MTU is too high. Try setting MTU lower on the node. This can be done via netconfig, or by editing the node in the UI.</p>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -63,7 +63,9 @@ SystemD
|
|||
|
||||
SystemD is a system service manager for a wide array of Linux operating systems. Not all Linux distributions have adopted systemd, but, for better or worse, it has become a fairly common standard in the Linux world. That said, any non-Linux operating system will not have systemd, and many Linux/Unix distributionshave alternative system service managers.
|
||||
|
||||
Netmaker's netclient, the agent which controls networking on all nodes, can be run as a CLI or as a system daemon. It runs as a daemon by default, and this requires systemd. As Netmaker evolves, systemd will become just one of the possible service management options, allowing the netclient to be run on a wider array of devices. However, for the time being, the netclient should be run "unmanaged" (netclient join -daemon=off) on systems that do not run systemd, and some other method can be used like a cron job or custom script.
|
||||
Netmaker's netclient, the agent which controls networking on all nodes, can be run as a CLI or as a system daemon. On Linux, it runs as a daemon by default, and this requires systemd. As Netmaker evolves, systemd will become just one of the possible service management options, allowing the netclient to be run on a wider array of devices. However, for the time being, the netclient should be run "unmanaged" (netclient join -daemon=off) on systems that do not run systemd, and some other method can be used like a cron job or custom script.
|
||||
|
||||
As of 0.8, Mac and Windows are supported. On these operating systems, netclient launches the daemon using LaunchD and Windows Service, respectively, as opposed to SystemD.
|
||||
|
||||
Components
|
||||
===========
|
||||
|
|
@ -81,13 +83,13 @@ Most server settings are configurable via a config file, or by environment varia
|
|||
|
||||
These modes include client mode and dns mode. Either of these can be disabled but are enabled by default. Client mode allows you to treat the Netmaker host machine (operating system) as a network Node, installing the netclient and controlling the host network. DNS mode has the server write config settings for CoreDNS, a separate component and nameserver, which picks up the config settings to manage node DNS.
|
||||
|
||||
The Netmaker server interacts with rqlite, a distributed version of sqlite, which holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration.
|
||||
The Netmaker server interacts with either sqlit (default) or rqlite, a distributed version of sqlite, as its database. This DB holds information about nodes, networks, users, and other important data. This data is configuration data. For the most part, Netmaker serves configuration data to Nodes, telling them how they should configure themselves. The Netclient is the agent that actually does that configuration.
|
||||
|
||||
|
||||
Netclient
|
||||
----------------
|
||||
|
||||
The netclient is, at its core, a golang binary. Source code can be found in the netclient folder of the Netmaker `GitHub Repository <https://github.com/gravitl/netmaker/tree/master/netclient>`_. The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems. As of version 0.5, the netclient can be run as a system daemon on linux distributions with systemd, or as an "unmanaged" client on distributions without systemd.
|
||||
The netclient is, at its core, a golang binary. Source code can be found in the netclient folder of the Netmaker `GitHub Repository <https://github.com/gravitl/netmaker/tree/master/netclient>`_. The binary, by itself, can be compiled for most systems. However, this binary is designed to manage a certain number of Operating Systems. As of version 0.8, the netclient can be run as a system daemon on linux distributions with systemd, or as an "unmanaged" client on distributions without systemd. The netclient for Windows and Mac will run as a Windows Service or LaunchDaemon, respectively.
|
||||
|
||||
The netclient is installed via a simple bash script, which pulls the latest binary and runs 'register' and 'join' commands.
|
||||
|
||||
|
|
@ -95,17 +97,19 @@ The 'register' command adds a WireGuard tunnel directly to the netmaker server,
|
|||
|
||||
The 'join' command attempts to add the machine to the Netmaker network using sensible defaults, which can be overridden with a config file or environment variables. Assuming the netclient has a valid key (or the network allows manual node signup), it will be registered into the Netmaker network, and will be returned necessary configuration details for how to set up its local network.
|
||||
|
||||
The netclient then sets up the systemd daemon (if running in daemon mode), and configures WireGuard. At this point it should be part of the network.
|
||||
The netclient then sets up the system daemon (if running in daemon mode), and configures WireGuard. At this point it should be part of the network.
|
||||
|
||||
If running in daemon mode, on a periodic basis (systemd timer), the netclient performs a "check in." It will authenticate with the server, and check to see if anything has changed in the network. It will also post changes about its own local configuration if there. If there has been a change, the server will return new configurations and the netclient will reconfigure the network. If not running in daemon mode, it is up to the operator to perform check ins (netclient checkin -n < network name >).
|
||||
|
||||
The check in process is what allows Netmaker to create dynamic mesh networks. As nodes are added to, removed from, and modified on the network, other nodes are notified, and make appropriate changes.
|
||||
|
||||
|
||||
rqlite
|
||||
--------
|
||||
sqlite and rqlite
|
||||
---------------------
|
||||
|
||||
As of v0.7, Netmaker uses rqlite, a distributed (RAFT consensus) database, and interacts with this database to store and retrieve information about nodes, networks, and users. With the 0.7 refactor, additional database support is very easy to implement. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file.
|
||||
As of v0.8, Netmaker uses sqlite by default as a database. It can also use rqlite, a distributed (RAFT consensus) databaseand. Netmaker interacts with this database to store and retrieve information about nodes, networks, and users.
|
||||
|
||||
Additional database support (besides sqlite and rqlite) is very easy to implement for special use cases. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file.
|
||||
|
||||
Netmaker UI
|
||||
---------------
|
||||
|
|
@ -120,8 +124,6 @@ CoreDNS
|
|||
|
||||
Netmaker allows users to provide and manage Private DNS for their nodes. This requires a nameserver, and CoreDNS is the chosen nameserver. CoreDNS is lightweight and extensible. CoreDNS loads dns settings from a simple file, managed by Netmaker, and serves out DNS info for managed nodes. DNS can be tricky, and DNS management is currently only supported on a small set of devices, specifically those running systemd-resolved. However, the Netmaker CoreDNS instance can be added manually as a nameserver to other devices. DNS mode can also be turned off.
|
||||
|
||||
Worth considering is that CoreDNS requires port 53 on the Netmaker host system, which may cause conflicts depending on your operating system. This is explained in the :doc:`Server Installation <./server-installation>` guide.
|
||||
|
||||
External Client
|
||||
----------------
|
||||
|
||||
|
|
@ -129,7 +131,9 @@ The external client is simply a manually configured WireGuard connection to your
|
|||
|
||||
Most machines can run WireGuard. It is fairly simple to set up a WireGuard connection to a single endpoint. It is setting up mesh networks and other topologies like site-to-site which becomes complicated.
|
||||
|
||||
Netmaker v0.5 introduces the "external client" to handle any devices which are not currently compatible with the netclient, including Windows, iPhone, Android, and Mac. Over time, this list will be eliminated and there may not even be a need for the external client.
|
||||
Mac, Windows, and Linux are handled natively by the Netclient.
|
||||
|
||||
Netmaker can issue "external clients" to handle any devices which are not currently compatible with the netclient, including iPhone, Android, and some Unix distributions. Over time, this list will be eliminated and there may not even be a need for the external 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.
|
||||
|
||||
|
|
@ -160,9 +164,13 @@ Below is a high level, step-by-step overview of the flow of communications withi
|
|||
Compatible Systems for Netclient
|
||||
==================================
|
||||
|
||||
To manage a node manually, the Netclient can be compiled and run for most linux distibutions, with a prerequisite of WireGuard.
|
||||
To manage a node manually, the Netclient can be compiled and run for most linux distibutions, with a prerequisite of WireGuard with kernel headers. If the netclient from the release pages does not run natively on your system, you may need to compile the netclient binary directly on the machine from the source code. This may be true for some installations of SUSE, Fedora, and some Debian-based systems. However, if the dependencies are installed on the machine, the netclient should run correctly after being compiled.
|
||||
|
||||
To manage a node automatically, the Netmaker client (netclient) requires **systemd-based linux.** Compatible systems include:
|
||||
Simply clone the repo, cd to netmaker/netclient and run "go build" (Golang must be installed).
|
||||
|
||||
The following systems should be operable natively with Netclient in daemon mode:
|
||||
- Windows
|
||||
- Mac
|
||||
- Fedora
|
||||
- Ubuntu
|
||||
- Debian
|
||||
|
|
@ -173,7 +181,7 @@ To manage a node automatically, the Netmaker client (netclient) requires **syste
|
|||
- Arch
|
||||
- CentOS
|
||||
- CoreOS
|
||||
|
||||
|
||||
To manage DNS (optional), the node must have systemd-resolved. Systems that have this enabled include:
|
||||
- Arch
|
||||
- Debian
|
||||
|
|
@ -181,8 +189,6 @@ To manage DNS (optional), the node must have systemd-resolved. Systems that have
|
|||
- SUSE
|
||||
|
||||
Limitations
|
||||
===========
|
||||
=============
|
||||
|
||||
Install limitations mostly include platform-specific limitations, such as needing systemd or systemd-resolved (see above).
|
||||
|
||||
In addition the Netmaker is currently unable to route traffic for for devices behind a "carrier-grade NAT". This will be solved in a future release with the introduction of relay servers.
|
||||
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 <https://stackoverflow.com/questions/62356581/wireguard-vpn-how-to-fix-operation-not-supported-if-it-worked-before>`_)
|
||||
|
|
@ -19,6 +19,17 @@ The netclient agent connects to the server, pushing and pulling information when
|
|||
|
||||
The netclient agent then configures WireGuard (and other network properties) locally, so that the network stays intact.
|
||||
|
||||
Notes on Windows
|
||||
==================================
|
||||
|
||||
If running the netclient on windows, you must download the netclient.exe binary and run it from Powershell as an Administrator.
|
||||
|
||||
Windows will by default have firewall rules that prevent inbound connections. If you wish to allow inbound connections from particular peers, use the following command:
|
||||
|
||||
``netsh advfirewall firewall add rule name="Allow from <peer private addr>" dir=in action=allow protocol=ANY remoteip=<peer private addr>``
|
||||
|
||||
If you want to allow all peers access, but do not want to configure firewall rules for all peers, you can configure access for one peer, and set it as a Relay Server.
|
||||
|
||||
Modes and System Compatibility
|
||||
==================================
|
||||
|
||||
|
|
@ -36,11 +47,9 @@ As a CLI, the netclient should function on any Linux or Unix based system that h
|
|||
Daemon
|
||||
----------
|
||||
|
||||
The netclient is intended to be run as a system daemon. This allows it to automatically retrieve and send updates. To do this, the netclient can install itself as a systemd service.
|
||||
The netclient is intended to be run as a system daemon. This allows it to automatically retrieve and send updates. To do this, the netclient can install itself as a systemd service, or launchd/windows service for Mac or Windows.
|
||||
|
||||
This requires a systemd-based linux operating system.
|
||||
|
||||
If running the netclient on a non-systemd system, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.
|
||||
If running the netclient on non-systemd linux, it is recommended to manually configure the netclient as a daemon using whatever method is acceptable on the chosen operating system.
|
||||
|
||||
Private DNS Management
|
||||
-----------------------
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ By using this method, you can hook any machine into a netmaker network that can
|
|||
|
||||
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, 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 resource runnin on the virtual network, and **not** for use cases where one wishes to make a resource accessible on the network. For that, use netclient.
|
||||
Important to note, 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 resource 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
|
||||
==================================
|
||||
|
|
|
|||
|
|
@ -66,7 +66,8 @@ Deploy Nodes
|
|||
1. SSH to each machine
|
||||
2. ``sudo su -``
|
||||
3. **Prerequisite Check:** Every Linux machine on which you run the netclient must have WireGuard and systemd installed
|
||||
4. Run the install command, Ex: ``curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/develop/scripts/netclient-install.sh | KEY=vm3ow4thatogiwnsla3thsl3894ths sh -``
|
||||
4. For linux machines with SystemD and WireGuard installed, Run the install command, Ex: ``curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/develop/scripts/netclient-install.sh | KEY=vm3ow4thatogiwnsla3thsl3894ths sh -``
|
||||
5. For Mac, Windows, and arch-specific linux distributions (e.g. ARM), `download the appropriate netclient for your system <https://github.com/gravitl/netmaker/releases/tag/latest/>`_ . Then, run "netclient join -t <your token>".
|
||||
|
||||
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 <./client-installation>` documentation. If this process failed and you do not see your node in the console (see below), then reference the :doc:`troubleshooting <./troubleshoot>` documentation.
|
||||
|
||||
|
|
|
|||
|
|
@ -7,15 +7,15 @@ This quick start guide is an **opinionated** guide for getting up and running wi
|
|||
0. Introduction
|
||||
==================
|
||||
|
||||
We assume for this installation that you want all of the Netmaker features enabled, want your server to be secure, and want it to be accessible from anywhere.
|
||||
We assume for this installation that you want all of the Netmaker features enabled, you want your server to be secure, and you want your server to be accessible from anywhere.
|
||||
|
||||
This instance will not be HA. However, it should comfortably handle around one hundred concurrent clients and support most use cases.
|
||||
This instance will not be HA. However, it should comfortably handle around one hundred concurrent clients and support the most common use cases.
|
||||
|
||||
If you are deploying for a business or enterprise use case and this setup will not fit your needs, please contact info@gravitl.com, or check out the business subscription plans at gravitl.com/plans.
|
||||
If you are deploying for a business or enterprise use case and this setup will not fit your needs, please contact info@gravitl.com, or check out the business subscription plans at https://gravitl.com/plans/business.
|
||||
|
||||
By the end of this guide, you will have Netmaker installed on a public VM linked to your custom domain, secured behind an Nginx reverse proxy.
|
||||
|
||||
If this configuration does not fit your use case, see the :doc:`Advanced Installation <./server-installation>` docs.
|
||||
For information about deploying more advanced configurations, see the :doc:`Advanced Installation <./server-installation>` docs.
|
||||
|
||||
|
||||
1. Prerequisites
|
||||
|
|
@ -26,6 +26,7 @@ If this configuration does not fit your use case, see the :doc:`Advanced Install
|
|||
- We do not recommend Oracle Cloud, as VM's here have been known to cause network interference.
|
||||
- Public, static IP
|
||||
- Min 1GB RAM, 1 CPU (4GB RAM, 2CPU preferred)
|
||||
- Nginx may have performance issues if using a cloud VPS with a single, shared CPU
|
||||
- 2GB+ of storage
|
||||
- Ubuntu 20.04 Installed
|
||||
|
||||
|
|
@ -47,11 +48,11 @@ Begin by installing the community version of Docker and docker-compose (there ar
|
|||
|
||||
sudo apt-get remove docker docker-engine docker.io containerd runc
|
||||
sudo apt-get update
|
||||
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
|
||||
sudo apt-get -y install apt-transport-https ca-certificates curl gnupg lsb-release
|
||||
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
|
||||
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
sudo apt-get update
|
||||
sudo apt-get install docker-ce docker-ce-cli containerd.io
|
||||
sudo apt-get -y install docker-ce docker-ce-cli containerd.io
|
||||
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
|
||||
sudo chmod +x /usr/local/bin/docker-compose
|
||||
docker --version
|
||||
|
|
@ -64,7 +65,7 @@ Install Dependencies
|
|||
|
||||
In addition to Docker, this installation requires WireGuard, Nginx, and Certbot.
|
||||
|
||||
``sudo apt install wireguard wireguard-tools nginx certbot python3-certbot-nginx net-tools``
|
||||
``sudo apt -y install wireguard wireguard-tools nginx certbot python3-certbot-nginx net-tools``
|
||||
|
||||
|
||||
3. Prepare VM
|
||||
|
|
@ -109,6 +110,10 @@ Make sure firewall settings are appropriate for Netmaker. You need ports 53 and
|
|||
- allow 443/tcp from all
|
||||
- allow 53/udp and 53/tcp from all
|
||||
|
||||
In addition to the above ports, you will need to make sure that your cloud's firewall or security groups are opened for the range of ports that Netmaker's WireGuard interfaces consume.
|
||||
|
||||
Netmaker will create one interface per network, starting from 51821. So, if you plan on having 5 networks, you will want to have at least 51821-51825 open (udp).
|
||||
|
||||
Prepare Nginx
|
||||
-----------------
|
||||
|
||||
|
|
@ -122,10 +127,8 @@ Insert your domain in the configuration file and add to nginx:
|
|||
|
||||
.. code-block::
|
||||
|
||||
NETMAKER_BASE_DOMAIN=<your base domain>
|
||||
sed -i 's/NETMAKER_BASE_DOMAIN/$NETMAKER_BASE_DOMAIN/g' netmaker-nginx-template.conf
|
||||
sudo cp netmaker-nginx-template.conf /etc/nginx/sites-available/netmaker-nginx.conf
|
||||
sudo ln -s /etc/nginx/sites-available/netmaker-nginx.conf /etc/nginx/sites-enabled/netmaker.nginx.conf
|
||||
sed -i 's/NETMAKER_BASE_DOMAIN/<your base domain>/g' netmaker-nginx-template.conf
|
||||
sudo cp netmaker-nginx-template.conf /etc/nginx/conf.d/<your base domain>.conf
|
||||
nginx -t && nginx -s reload
|
||||
systemctl restart nginx
|
||||
|
||||
|
|
@ -135,23 +138,28 @@ Insert your domain in the configuration file and add to nginx:
|
|||
Prepare Templates
|
||||
------------------
|
||||
|
||||
**Note on COREDNS_IP:** Depending on your cloud provider, the public IP may not be bound directly to the VM on which you are running. In such cases, CoreDNS cannot bind to this IP, and you should use the IP of the default interface on your machine in place of COREDNS_IP. If the public IP **is** bound to the VM, you can simply use the same IP as SERVER_PUBLIC_IP.
|
||||
|
||||
.. code-block::
|
||||
|
||||
wget https://raw.githubusercontent.com/gravitl/netmaker/develop/compose/docker-compose.quickstart.yml
|
||||
sed -i 's/NETMAKER_BASE_DOMAIN/$NETMAKER_BASE_DOMAIN/g' docker-compose.quickstart.yml
|
||||
sed -i 's/SERVER_PUBLIC_IP/<your server ip>/g' docker-compose.quickstart.yml
|
||||
wget https://raw.githubusercontent.com/gravitl/netmaker/develop/compose/docker-compose.yml
|
||||
sed -i 's/NETMAKER_BASE_DOMAIN/<your base domain>/g' docker-compose.yml
|
||||
sed -i 's/SERVER_PUBLIC_IP/<your server ip>/g' docker-compose.yml
|
||||
sed -i 's/COREDNS_IP/<your server ip>/g' docker-compose.yml
|
||||
|
||||
Generate a unique master key and insert it:
|
||||
|
||||
.. code-block::
|
||||
|
||||
tr -dc A-Za-z0-9 </dev/urandom | head -c 30 ; echo ''
|
||||
sed -i 's/REPLACE_MASTER_KEY/<your generated key>/g' docker-compose.quickstart.yml
|
||||
sed -i 's/REPLACE_MASTER_KEY/<your generated key>/g' docker-compose.yml
|
||||
|
||||
You may want to save this key for future use with the API.
|
||||
|
||||
Start Netmaker
|
||||
----------------
|
||||
|
||||
``sudo docker-compose -f docker-compose.quickstart.yml up -d``
|
||||
``sudo docker-compose -f docker-compose.yml up -d``
|
||||
|
||||
navigate to dashboard.<your base domain> to see your nginx instance.
|
||||
|
||||
|
|
|
|||
|
|
@ -98,6 +98,21 @@ DNS_MODE:
|
|||
|
||||
**Description:** Enables DNS Mode, meaning config files will be generated for CoreDNS.
|
||||
|
||||
DATABASE:
|
||||
**Default:** "sqlite"
|
||||
|
||||
**Description:** Specify db type to connect with. Currently, options include "sqlite" and "rqlite".
|
||||
|
||||
SQL_CONN:
|
||||
**Default:** "http://"
|
||||
|
||||
**Description:** Specify the necessary string to connect with your local or remote sql database.
|
||||
|
||||
CLIENT_MODE:
|
||||
**Default:** "on"
|
||||
|
||||
**Description:** Specifies if server should deploy itself as a node (client) in each network. May be turned to "off" for more restricted servers.
|
||||
|
||||
Config File Reference
|
||||
----------------------
|
||||
A config file may be placed under config/environments/<env-name>.yml. To read this file at runtime, provide the environment variable NETMAKER_ENV at runtime. For instance, dev.yml paired with ENV=dev. Netmaker will load the specified Config file. This allows you to store and manage configurations for different environments. Below is a reference Config File you may use.
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@ Troubleshooting
|
|||
|
||||
Common Issues
|
||||
--------------
|
||||
**How can I connect my Android, IOS, MacOS or Windows device to my Netmaker VPN?**
|
||||
**How can I connect my Android or IOS device to my Netmaker VPN?**
|
||||
Currently meshing one of these devices is not supported, however it will be soon.
|
||||
For now you can connect to your VPN by making one of the nodes an Ingressgateway, then
|
||||
For now you can connect to your VPN by making one of the nodes an Ingress Gateway, then
|
||||
create an Ext Client for each device. Finally, use the official WG app or another
|
||||
WG configuration app to connect via QR or downloading the device's WireGuard configuration.
|
||||
|
||||
|
|
@ -22,8 +22,16 @@ Common Issues
|
|||
Yes, we have an active `discord <https://discord.gg/Pt4T9y9XK8>`_ community and issues on our `github <https://github.com/gravitl/netmaker/issues>`_ are answered frequently!
|
||||
You can also sign-up for updates at our `gravitl site <https://gravitl.com/>`_!
|
||||
|
||||
**How can I get additional support for my business?**
|
||||
Check out our business support subscriptions at https://gravitl.com/plans. Subscription holders can also purchase consulting credits via the site.
|
||||
|
||||
|
||||
Server
|
||||
-------
|
||||
|
||||
**I upgraded from 0.7 to 0.8 and now I dont have any data in my server!**
|
||||
In 0.8, sqlite becomes the default database. If you were running with rqlite, you must set the DATABASE environment variable to rqlite in order to continue using rqlite.
|
||||
|
||||
**Can I secure/encrypt all the traffic to my server and UI?**
|
||||
This can fairly simple to achieve assuming you have access to a domain and are familiar with Nginx.
|
||||
Please refer to the quick-start guide to see!
|
||||
|
|
@ -63,7 +71,7 @@ UI
|
|||
Yes, nodes can share names without issue. It may just be harder on you to know which is which.
|
||||
|
||||
Netclient
|
||||
-------
|
||||
-----------
|
||||
**How do I connect a node to my Netmaker network with Netclient?**
|
||||
First get your access token (not just access key), then run ``sudo netclient join -t <access token>``.
|
||||
**NOTE:** netclient may be under /etc/netclient/, i.e run ``sudo /etc/netclient/netclient join -t <access token>``
|
||||
|
|
@ -91,6 +99,9 @@ Netclient
|
|||
sudo chcon -Rv -u system_u -t bin_t '/etc/netclient/netclient'
|
||||
sudo restorecon -R -v /etc/netclient/netclient
|
||||
|
||||
**I have a handshake with a peer but can't ping it, what gives?**
|
||||
This is commonly due to incorrect MTU settings. Typically, it will be because MTU is too high. Try setting MTU lower on the node. This can be done via netconfig, or by editing the node in the UI.
|
||||
|
||||
CoreDNS
|
||||
--------
|
||||
**Is CoreDNS required to use Netmaker?**
|
||||
|
|
|
|||
Loading…
Reference in a new issue