You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: advanced-client-install.rst
+19-16
Original file line number
Diff line number
Diff line change
@@ -9,9 +9,9 @@ These steps should be run after the Netmaker server has been created and a netwo
9
9
Introduction to Netclient
10
10
===============================
11
11
12
-
At its heart, the netclient is a simple CLI for managing access to various WireGuard-based networks. It manages WireGuard on the host system, so that you don't have to. Why is this necessary?
12
+
At its heart, the netclient is a simple CLI for managing access to various WireGuard-based networks. It manages WireGuard on the host system so that you don't have to. Why is this necessary?
13
13
14
-
If you are setting up a WireGuard-based virtual network, you must configure each machine with very specific settings, so that every machine can reach it, and it can reach every other machine. Any changes to the settings of any one of these machines can break those connections. Any machine that is added, removed, or modified on the network requires reconfiguring of every peer in the network. This can be very timeconsuming.
14
+
If you are setting up a WireGuard-based virtual network, you must configure each machine with very specific settings, so that every machine can reach it, and it can reach every other machine. Any changes to the settings of any one of these machines can break those connections. Any machine that is added, removed, or modified on the network requires reconfiguring of every peer in the network. This can be very time-consuming.
15
15
16
16
The netmaker server holds configuration details about every machine in your network and how other machines should connect to it.
17
17
@@ -27,13 +27,13 @@ IPv6 requires a minimum MTU of 1280. A lot of router configurations expect a sta
27
27
Notes on Windows
28
28
==================================
29
29
30
-
If running the netclient on windows, you must download the netclient.exe binary and run it from Powershell as an Administrator.
30
+
If running the netclient on Windows, you must download the netclient.exe binary and run it from Powershell as an Administrator.
31
31
32
32
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:
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(Professional Edition Feature) from Netmaker GUI. In order to achieve this, netmaker pro edition is required.
36
+
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(Professional Edition Feature) from Netmaker GUI. To achieve this, a netmaker pro edition is required.
37
37
38
38
Running netclient commands
39
39
----------------------------
@@ -53,27 +53,27 @@ With some versions of WireGuard on Windows, high CPU utilization has been found
53
53
Changing network profile to private
54
54
------------------------------------
55
55
56
-
By default the netmaker network profile is added as a public network. This is the default behavior on Windows. For changing it to private, please run Powershell command,
56
+
By default, the netmaker network profile is added as a public network. This is the default behaviour on Windows. To change it to private, please run the Powershell command,
Sometimes the netclient does not work after the Windows wake up from sleep/hibernate. The root cause is not identified. Restarting netclient service can fix the issue.
63
+
Sometimes the netclient does not work after the Windows wake up from sleep/hibernation. The root cause is not identified. Restarting the netclient service can fix the issue.
64
64
65
65
Irregular netclient restart on Windows 2016 server
There is one issue reported on Windows 2016 server. The netclient restarted irregularly. The root cause is not identified. But as the feedback from the client, the issue can be fixed by disabling ISATAP adapter and 6to4 feature.
68
+
There is one issue reported on the Windows 2016 server. The netclient restarted irregularly. The root cause is not identified. However, as per the feedback from the client, the issue can be fixed by disabling the ISATAP adapter and 6to4 feature.
69
69
70
70
- `Set-Net6to4configuration -state disabled`
71
71
- `Set-Netisatapconfiguration -state disabled`
72
72
- `Set-NetTeredoConfiguration -type disabled`
73
73
74
74
Event id 0 in Windows Event logs
75
75
---------------------------------
76
-
netclient service is delegated to Winsw on Windows. An issue is reported that the stop/start/restart events in Event logs show event id as 0 always. It does not impact any netclient functions.
76
+
netclient service is delegated to Winsw on Windows. An issue is reported that the stop/start/restart events in Event logs show the event ID as 0 always. It does not impact any netclient functions.
77
77
78
78
Modes and System Compatibility
79
79
==================================
@@ -85,23 +85,23 @@ The netclient can be run in a few "modes". System compatibility depends on which
85
85
CLI
86
86
------------
87
87
88
-
In its simplest form, the netclient can be treated as just a simple, manual, CLI tool, which a user can call to configure the machine. The cli can be compiled from source code to run on most systems, and has already been compiled for x86 and ARM architectures.
88
+
In its simplest form, the netclient can be treated as just a simple, manual, CLI tool, which a user can call to configure the machine. The CLI can be compiled from source code to run on most systems and has already been compiled for x86 and ARM architectures.
89
89
90
-
As a CLI, the netclient should function on any Linux or Unixbased system that has the wireguard utility (callable with **wg**) installed.
90
+
As a CLI, the netclient should function on any Linux or Unix-based system that has the wireguard utility (callable with **wg**) installed.
91
91
92
92
Daemon
93
93
----------
94
94
95
95
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.
96
96
97
-
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.
97
+
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.
98
98
99
99
Private DNS Management
100
100
-----------------------
101
101
102
102
To manage private DNS, the netclient relies on systemd-resolved (resolvectl). Absent this, it cannot set private DNS for the machine.
103
103
104
-
A user may choose to manually set a private DNS nameserver of <netmaker server>:53. However, beware, as netmaker sets split dns, and the system must be configured properly. Otherwise, this nameserver may break your local DNS.
104
+
A user may choose to manually set a private DNS nameserver of <netmaker server>:53. However, beware, as netmaker sets split DNS, the system must be configured properly. Otherwise, this nameserver may break your local DNS.
105
105
106
106
Prerequisites
107
107
=============
@@ -114,10 +114,13 @@ To obtain the netclient, go to the GitHub releases: https://github.com/gravitl/n
114
114
115
115
**For Private DNS management:** Resolvectl (systemd-resolved)
116
116
117
+
Please refer to the `Firewall Rules for Machines Running Netclient <https://docs.netmaker.io/install.html#firewall-rules-for-machines-running-netclient>`_ for more information.
118
+
119
+
117
120
Configuration
118
121
===============
119
122
120
-
The CLI has information about all commands and variables. This section shows the "help" output for these commands as well as some additional reference.
123
+
The CLI has information about all commands and variables. This section shows the "help" output for these commands as well as some additional references.
121
124
122
125
CLI Reference
123
126
--------------------
@@ -144,19 +147,19 @@ Installation
144
147
145
148
To install netclient and join a network, you need to use ``netclient install`` command and get an enrollment key for a particular network from netmaker.
146
149
147
-
An admin creates an enrollment key in the "Enrollment Keys" section of the UI. Upon creating a key, it can be viewed by clicking onto the key from UI. Some details regarding the key will be visible:
150
+
An admin creates an enrollment key in the "Enrollment Keys" section of the UI. Upon creating a key, it can be viewed by clicking on the key from UI. Some details regarding the key will be visible:
148
151
149
152
**Key:** The enrollment key to join and authenticate to a netmaker network
150
153
151
-
**Type:** Type of key determines the usage limitation of a particular key. Possible values are: Unlimited, Time Bound, Limited Number of Uses
154
+
**Type:** The Type of key determines the usage limitation of a particular key. Possible values are: Unlimited, Time Bound, Limited Number of Uses
152
155
153
156
**Expires at:** Shows the expiration date of the particular enrollment key
154
157
155
158
**Networks:** Shows which netmaker networks can be joined by using the particular enrollment key
156
159
157
160
**Install Command:** The CLI command to register with the server using the enrollment key, and join the networks
158
161
159
-
For firsttime installations, you can run the Install Command. For additional networks, simply run ``netclient join -t <enrollment key>``.
162
+
For first-time installations, you can run the Install Command. For additional networks, simply run ``netclient join -t <enrollment key>``.
Copy file name to clipboardexpand all lines: install.rst
+82-9
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ Prerequisites
11
11
Server
12
12
-----------------
13
13
14
-
All components of Netmaker can be run on a single server (Virtual Machine or Bare Metal). Here some recommendations for setting up the server:
14
+
All components of Netmaker can be run on a single server (Virtual Machine or Bare Metal). Here are some recommendations for setting up the server:
15
15
16
16
- We **highly recommend** that Netmaker be deployed in a dedicated networking environment.
17
17
- The machine should have a public, static IP address
@@ -40,6 +40,80 @@ Your server will host several services (netmaker server, UI, etc.) each of which
40
40
- **Note on Cloudflare:** Many of our users use Cloudflare. Cloudflare will proxy connections, which MQ does not like. This can be disabled in the Cloudflare DNS dashboard. If setting up your Netmaker server using Cloudflare for DNS, be aware that the configuration of Cloudflare proxy may cause problems with Netmaker which must be resolved, and at this point, Netmaker is not providing guidance on this setup.
41
41
42
42
43
+
44
+
Firewall Rules for Netmaker Server
45
+
-------------------------------------
46
+
47
+
Make sure firewall settings are set for Netmaker both on the VM and with your cloud security groups (AWS, GCP, etc) or with your router/FWA.
48
+
49
+
Make sure the following ports are open both on the VM and in the cloud security groups:
50
+
51
+
- **443, 80 (tcp):** for Caddy, which proxies the Dashboard (UI), REST API (Netmaker Server), and Broker (MQTT)
52
+
- **51821 (udp and tcp):** for WireGuard - Install script automatically setups a netclient on the server machine with default port as 51821.
53
+
- **8085 (exporter Pro):** If you are building a Pro server, you need this port open.
54
+
- **1883, 8883 8083, 18083 (if using EMQX):** We use two different types of brokers. There is Mosquitto or EMQX. Mosquitto is our default offering which uses ports 8883 and 1883. If you are setting up EMQX, all four ports mentioned need to be opened for MQTT, SSL MQTT, web sockets, and the EMQX dashboard/REST API.
55
+
- **53 (tcp and udp):** If you set the CoreDNS container, that comes with the Netmaker installation, to 'host' your domain name resolution needs
56
+
57
+
58
+
.. code-block::
59
+
60
+
sudo ufw allow proto tcp from any to any port 443
61
+
sudo ufw allow proto tcp from any to any port 80
62
+
sudo ufw allow 51821/udp (based on your netclient listen port on server machine)
63
+
sudo ufw allow 51821/tcp (based on your netclient listen port on server machine)
64
+
65
+
#optional: only when hosting DNS on the Netmaker server
66
+
sudo ufw allow 53
67
+
68
+
69
+
It is also important to make sure the server does not block forwarding traffic (it will do this by default on some providers). To ensure traffic will be forwarded:
70
+
71
+
.. code-block::
72
+
73
+
iptables --policy FORWARD ACCEPT
74
+
75
+
76
+
**Again, based on your cloud provider, you may additionally need to set inbound security rules for your server (for instance, on AWS). This will be dependent on your cloud provider. Be sure to check before moving on:**
77
+
- allow 443/tcp from all
78
+
- allow 80/tcp from all
79
+
- allow 51821-51830/udp from all
80
+
- allow 51821-51830/tcp from all
81
+
- allow 53 from all (optional)
82
+
83
+
84
+
Firewall Rules for Machines Running Netclient
85
+
-------------------------------------------------
86
+
87
+
As we already know, Netclient manages WireGuard on client devices (nodes). As its name suggests, Netclient is a client in a mesh topology, thus it needs to communicate with the server and with the other clients as well. Netclient will detect local changes and send them to the server when necessary. A change in IP address or port will lead to a network update to keep everything in sync.
88
+
It goes without saying that in almost all cases a firewall must be up and running on any device that is connected to a network, especially the Internet. Firewalls are inherently restrictive for good reasons. And by default, it might not allow traffic that Netclient would use to function properly.
89
+
90
+
On Windows machines, it is possible to allow programs or applications through the firewall. Thus you might want to allow Netclient and, depending on your setup, WireGuard.
91
+
92
+
On Linux, these necessary ports are needed to be opened:
93
+
94
+
- UDP and TCP ports 51821-51830 for inbound and outbound (based on your client's listen port running on the machine)
95
+
- TCP port 443 for outbound
96
+
- UDP ports 19302 & 3478 for STUN outbound requests
97
+
98
+
For advanced use cases, you might need to view your device's firewall logs, or in the case of Netclients behind a NAT, your Firewall-Appliance/Router's firewall logs. Look for blocked traffic coming in and out having origin/destination IPs of your devices.
- Due to the high volume of installations, the auto-generated domain has been rate-limited by the certificate provider. For this reason, we **strongly recommend** using your own domain. Using the auto-generated domain may lead to a failed installation due to rate limiting.
128
+
- Due to the high volume of installations, the auto-generated domain has been rate-limited by the certificate provider. For this reason, we **strongly recommend** using your domain. Using the auto-generated domain may lead to a failed installation due to rate limiting.
55
129
56
130
**IMPORTANT:** From v0.22.0 the install script will install PRO version of netmaker with a 14-day free trial, for you to try out full capabilities of netmaker.
57
131
58
132
Integrating OAuth
59
133
====================
60
134
61
-
Users are also allowed to join a Netmaker server via OAuth. They can do this by clicking the "Login with SSO" button on the dashboard's login page. Check out the :doc:`integrating oauth docs <./oauth>`.
62
-
63
-
After trial period ends:
64
-
=========================
135
+
Users are also allowed to join a Netmaker server via OAuth. They can do this by clicking the "Login with SSO" button on the dashboard's login page. Check out the:doc:`integrating oauth docs <./oauth>`.
65
136
66
-
a. if you wish to continue using PRO :-
137
+
After the trial period ends:
138
+
==============================
67
139
140
+
a. if you wish to continue using PRO:-
68
141
i. check these steps to obtain pro license `<https://docs.netmaker.io/pro/pro-setup.html>`_
69
142
ii. Run `/root/nm-quick.sh -u`
70
143
71
-
b. if you wish to downgrade to community version
144
+
b. if you wish to downgrade to the community version
72
145
73
146
i. Run `/root/nm-quick.sh -d`
74
147
75
148
76
149
1. **To get started the easiest way, visit our SaaS platform to set up a netmaker server with just a few clicks** `<https://app.netmaker.io>`_
77
150
78
-
2. :doc:`check out these steps for manual installation process for on-prem, although we don't recommend this path, instead use the install script mentioned above<./manual-install>`
151
+
2. :doc:`check out these steps for the manual installation process for on-prem, although we don't recommend this path, instead use the install script mentioned above<./manual-install>`
79
152
80
153
3. :ref:`Highly Available Installation <HAInstall>`
Copy file name to clipboardexpand all lines: manual-install.rst
+1-31
Original file line number
Diff line number
Diff line change
@@ -87,39 +87,9 @@ At this point you should have all the system dependencies you need.
87
87
3. Open Firewall
88
88
===============================
89
89
90
-
Make sure firewall settings are set for Netmaker both on the VM and with your cloud security groups (AWS, GCP, etc).
91
-
92
-
Make sure the following ports are open both on the VM and in the cloud security groups:
93
-
94
-
- **443, 80 (tcp):** for Caddy, which proxies the Dashboard (UI), REST API (Netmaker Server), and Broker (MQTT)
95
-
- **51821-518XX (udp):** for WireGuard - Netmaker needs one port per network, starting with 51821, so open up a range depending on the number of networks you plan on having. For instance, 51821-51830.
96
-
- **8085 (exporter Pro):** If you are building a Pro server, you need this port open.
97
-
- **1883, 8883 8083, 18083 (if using EMQX):** We use two different types of brokers. There is Mosquitto or EMQX. if you are setting up EMQX, these four need to be open for MQTT, SSL MQTT, web sockets, and the EMQX dashbaord/REST api.
98
-
99
-
100
-
.. code-block::
101
-
102
-
sudo ufw allow proto tcp from any to any port 443
103
-
sudo ufw allow proto tcp from any to any port 80
104
-
sudo ufw allow proto tcp from any to any port 3479
105
-
sudo ufw allow proto tcp from any to any port 8089
106
-
sudo ufw allow 51821:51830/udp
90
+
Please refer to the `Firewall Rules for Netmaker Server <https://docs.netmaker.io/install.html#firewall-rules-for-netmaker-server>`_ for more information.
107
91
108
92
109
-
It is also important to make sure the server does not block forwarding traffic (it will do this by default on some providers). To ensure traffic will be forwarded:
110
-
111
-
.. code-block::
112
-
113
-
iptables --policy FORWARD ACCEPT
114
-
115
-
116
-
**Again, based on your cloud provider, you may additionally need to set inbound security rules for your server (for instance, on AWS). This will be dependent on your cloud provider. Be sure to check before moving on:**
0 commit comments