From 515f427c2ce21368419879ed20c436ca9f81a0a8 Mon Sep 17 00:00:00 2001 From: theguy951357 Date: Mon, 17 Jun 2024 14:20:06 -0400 Subject: [PATCH 1/7] updates --- advanced-client-install.rst | 39 ------------------------------------- netclient.rst | 4 ++-- pro/rac.rst | 2 +- server-installation.rst | 16 +++++++-------- 4 files changed, 10 insertions(+), 51 deletions(-) diff --git a/advanced-client-install.rst b/advanced-client-install.rst index f35311e6..23f900e6 100644 --- a/advanced-client-install.rst +++ b/advanced-client-install.rst @@ -75,35 +75,6 @@ Event id 0 in Windows Event logs --------------------------------- 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. -Notes on OpenWRT -=========================== - -Deploying on OpenWRT depends a lot on the version of OpenWRT and the hardware being used. - -1. Ensure you download the appropriate binary for your architecture. replace ${VERSION} with the version you want to download - -a. https://github.com/gravitl/netclient/releases/download/${VERSION}/netclient-linux-amd64 -b. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-arm64 -c. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-armv5 -d. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-armv6 -e. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-armv7 -f. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mips-hardfloat -g. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mips-softfloat -h. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mipsle-hardfloat -i. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mipsle-softfloat - -2. run netclient install (note: all netclient commands must be run as root) will install the netclient binary to /usr/bin/netclient and service file to /etc/init.d/netclient - -3. to start/stop the netclient daemon run - -.. code-block:: - - /sbin/rc-service netclient start/stop - -4. run other netclient commands (join, list, connect, disconnect, pull etc ) as required - - - Modes and System Compatibility ================================== @@ -222,16 +193,6 @@ If the daemon is not running correctly, try restarting the daemon, or pulling ch ``sudo netclient pull`` -Making Updates ----------------- - -``vim /etc/netclient/config/netconfig-`` - -Change any of the variables in this file, and changes will be pushed to the server and processed locally on the next checkin. - -For instance, change the private address, endpoint, or name. See above example config file for details - - Adding/Removing Networks --------------------------- diff --git a/netclient.rst b/netclient.rst index 925fedda..1f728fa6 100644 --- a/netclient.rst +++ b/netclient.rst @@ -116,9 +116,9 @@ Brew Install GUI Installer (for v0.22.0 and below) ------------------------------------- -Download Link for Apple silicon: https://fileserver.netmaker.org/releases/download/v0.22.0/Netclient-M1.pkg +Download Link for Apple silicon: https://fileserver.netmaker.org/releases/download/latest/Netclient-M1.pkg -Download Link for Apple Intel: https://fileserver.netmaker.org/releases/download/v0.22.0/Netclient-Intel.pkg +Download Link for Apple Intel: https://fileserver.netmaker.org/releases/download/latest/Netclient-Intel.pkg Replace version number in URL with the version you want to install. diff --git a/pro/rac.rst b/pro/rac.rst index d308ad3c..29d34966 100644 --- a/pro/rac.rst +++ b/pro/rac.rst @@ -21,7 +21,7 @@ You can download the M1 or Intel Mac installer from our fileserver link (https:/ **For Windows:** You can download the `remoteclientbundle.exe` bundle (recommended as this install wireguard and other dependencies) or `remote-access-client_86.msi` installer (MSI doesnt install any dependencies) and run it to install on your windows machine. You can then open the GUI to start using RAC! -Download link: https://fileserver.netmaker.io/latest/remoteclientbundle.exe +Download link: https://fileserver.netmaker.io/releases/download/latest/remoteclientbundle.exe ----------------------------- diff --git a/server-installation.rst b/server-installation.rst index 4e7b769d..5843c5df 100644 --- a/server-installation.rst +++ b/server-installation.rst @@ -33,6 +33,11 @@ In most situations, if you wish to modify a server setting, set it in the netmak Variable Description ---------------------- +NM_EMAIL + **Default** "" + + **Description** Email used for SSL certificates + SERVER_NAME **Default:** "" @@ -165,13 +170,6 @@ VERBOSITY: **Description:** Specify the level of logging you would like on the server. Goes up to 3 for debugging. If you run into issues, up the verbosity. -Config File Reference ------------------------ -A config file may be placed under config/environments/.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. - -.. literalinclude:: ./examplecode/dev.yaml - :language: YAML - Compose File - Annotated -------------------------------------- @@ -334,7 +332,7 @@ If using rqlite or postgres, you must change the DATABASE environment/config var Server Setup (using sqlite) --------------------------- -1. Get the binary. ``wget -O /etc/netmaker/netmaker https://github.com/gravitl/netmaker/releases/download/$VERSION/netmaker`` +1. Get the binary. ``wget -O /etc/netmaker/netmaker https://github.com/gravitl/netmaker/releases/latest/download/netmaker-linux-amd64`` 2. Move the binary to /usr/sbin and make it executable. 3. create a config file. /etc/netmaker/netmaker.yml @@ -380,7 +378,7 @@ UI Setup The following uses Caddy as a file server/proxy. 1. Download and Unzip UI asset files from https://github.com/gravitl/netmaker-ui/releases and put them in /var/www/netmaker - ``sudo wget -O /tmp/netmaker-ui.zip https://github.com/gravitl/netmaker-ui/releases/download/latest/netmaker-ui.zip`` + ``sudo wget -O /tmp/netmaker-ui.zip https://github.com/gravitl/netmaker-ui/releases/latest/download/netmaker-ui.zip`` ``sudo unzip /tmp/netmaker-ui.zip -d /var/www/netmaker`` 2. Create config.js in /var/www/netmaker From c8f997647e7d5b943e6c8973f8a919153d6058a5 Mon Sep 17 00:00:00 2001 From: theguy951357 Date: Tue, 18 Jun 2024 16:52:11 -0400 Subject: [PATCH 2/7] update server config vars --- server-installation.rst | 226 +++++++++++++++++++++++++++------------- 1 file changed, 152 insertions(+), 74 deletions(-) diff --git a/server-installation.rst b/server-installation.rst index 5843c5df..d952b20a 100644 --- a/server-installation.rst +++ b/server-installation.rst @@ -38,137 +38,215 @@ NM_EMAIL **Description** Email used for SSL certificates -SERVER_NAME +NM_DOMAIN **Default:** "" - **Description:** MUST SET THIS VALUE. This is the public, resolvable DNS name of the MQ Broker. For instance: broker.netmaker.example.com. + **Description:** Public IP of machine SERVER_HOST **Default:** (Server detects the public IP address of machine) - **Description:** The public IP of the server where the machine is running. + **Description:** The public IP of the server where the machine is running. -SERVER_API_CONN_STRING - **Default:** "" +MASTER_KEY + **Default:** "secretkey" - **Description:** MUST SET THIS VALUE. This is the public, resolvable address of the API, including the port. For instance: api.netmaker.example.com:443. + **Description:** The admin master key for accessing the API. Change this in any production installation. + +MQ_USERNAME + **Default** "" -COREDNS_ADDR - **Default:** "" + **Description** The username to set for MQ access - **Description:** The public IP of the CoreDNS server. Will typically be the same as the server where Netmaker is running (same as SERVER_HOST). +MQ_PASSWORD + **Default** "" + **Description** The password to set for MQ access -SERVER_HTTP_HOST - **Default:** Equals SERVER_HOST if set, "127.0.0.1" if SERVER_HOST is unset. - - **Description:** Should be the same as SERVER_API_CONN_STRING minus the port. +INSTALL_TYPE + **Default** ce -API_PORT: - **Default:** 8081 + **Description** The installation type to run on the server. "ce" will run community edition. "pro" will run professional edition if you have an on-prem tenant. - **Description:** Should be the same as the port on SERVER_API_CONN_STRING in most cases. Sets the port for the API on the server. +LICENSE_KEY -MASTER_KEY: - **Default:** "secretkey" + **Default** "" - **Description:** The admin master key for accessing the API. Change this in any production installation. + **Description** The license key from your on-prem tenent needed to validate your professional installation. + +NETMAKER_TENANT_ID + + **Default** "" + + **Description** The ID of your on-prem tenant used to validate your professional installation. -CORS_ALLOWED_ORIGIN: - **Default:** "*" +SERVER_IMAGE_TAG - **Description:** The "allowed origin" for API requests. Change to restrict where API requests can come from. + **Default** -REST_BACKEND: - **Default:** "on" + **Description** The tag used for the server docker image. You can set it to "latest" to get the most up to date version. To stay on a certain version set the tag to the version you would like. ex: v0.24.2. if using a pro image, add "-ee" after the version. ex: v0.24.2-ee. - **Description:** Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST). Change to "off" to turn off. +UI_IMAGE_TAG -DNS_MODE: - **Default:** "off" + **Default** "" + + **Description** The tag used for the netmaker ui docker image. You can set it to "latest" to get the most up to date version. To stay on a certain version set the tag to the version you would like. ex: v0.24.2. + +NODE_ID - **Description:** Enables DNS Mode, meaning config files will be generated for CoreDNS. + **Default** netmaker-server-1 -DATABASE: - **Default:** "sqlite" + **Description** used for HA - identifies this server vs other servers - **Description:** Specify db type to connect with. Currently, options include "sqlite", "rqlite", and "postgres". +METRICS_EXPORTER -SQL_CONN: - **Default:** "http://" + **Default** off - **Description:** Specify the necessary string to connect with your local or remote sql database. + **Description** This is a pro feature that exports metrics to the netmaker server. -SQL_HOST: - **Default:** "localhost" +PROMETHEUS - **Description:** Host where postgres is running. + **Default** off -SQL_PORT: - **Default:** "5432" + **Description** This is a pro feature. Prometheus is an open-source systems monitoring and alerting toolkit originally built at SoundCloud. It is used in out metrics collection - **Description:** port postgres is running. +DNS_MODE -SQL_DB: - **Default:** "netmaker" + **Default** on - **Description:** DB to use in postgres. + **Description** Enables DNS Mode, meaning all nodes will set hosts file for private dns settings -SQL_USER: - **Default:** "postgres" +NETCLIENT_AUTO_UPDATE - **Description:** User for postgres. + **Default** enabled -SQL_PASS: - **Default:** "nopass" + **Description** Enable/Disable auto update of netclient - **Description:** Password for postgres. +API_PORT -RCE: - **Default:** "off" + **Default** 8081 - **Description:** The server enables you to set PostUp and PostDown commands for nodes, which is standard for WireGuard with wg-quick, but is also **Remote Code Execution**, which is a critical vulnerability if the server is exploited. Because of this, it's turned off by default, but if turned on, PostUp and PostDown become editable. + **Description** The HTTP API port for Netmaker. Used for API calls / communication from front end. If changed, need to change port of BACKEND_URL for netmaker-ui. + +EXPORTER_API_PORT + + **Default** 8085 + + **Description** the API port to set for the metrics exporter. + +CORS_ALLOWED_ORIGIN + + **Default** "*" + + **Description** The "allowed origin" for API requests. Change to restrict where API requests can come from with comma-separated URLs. ex:- https://dashboard.netmaker.domain1.com,https://dashboard.netmaker.domain2.com DISPLAY_KEYS - **Default:** "on" - **Description:** If "on", will allow you to always show the key values of "access keys". This could be considered a vulnerability, so if turned "off", will only display key values once, and it is up to the users to store the key values locally. + **Default** on -NODE_ID - **Default:** + **Description** Show keys permanently in UI (until deleted) as opposed to 1-time display. + +DATABASE + + **Default** sqlite + + **Description** Database to use - sqlite, postgres, or rqlite + +SERVER_BROKER_ENDPOINT + + **Default** ws://mq:1883 + + **Description** The address of the mq server. If running from docker compose it will be "mq". Otherwise, need to input address. If using "host networking", it will find and detect the IP of the mq container. For EMQX websockets use `SERVER_BROKER_ENDPOINT=ws://mq:8083/mqtt` + +VERBOSITY + + **Default** 1 + + **Description** Logging verbosity level - 1, 2, 3, or 4 + +REST_BACKEND - **Description:** This setting is used for HA configurations of the server, to identify between different servers. Nodes are given ID's like netmaker-1, netmaker-2, and netmaker-3. If the server is not HA, there is no reason to set this field. + **Default** on + + **Description** Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST). + +DISABLE_REMOTE_IP_CHECK + + **Default** off + + **Description** If turned "on", Server will not set Host based on remote IP check. This is already overridden if SERVER_HOST is set. TELEMETRY - **Default:** "on" - **Description:** If "on", the server will send anonymous telemetry data once daily, which is used to improve the product. Data sent includes counts (integer values) for the number of nodes, types of nodes, users, and networks. It also sends the version of the server. + **Default** on -MQ_HOST - **Default:** (public IP of server) + **Description** Whether or not to send telemetry data to help improve Netmaker. Switch to "off" to opt out of sending telemetry. - **Description:** The address of the mq server. If running from docker compose it will be "mq". If using "host networking", it will find and detect the IP of the mq container. Otherwise, need to input address. If not set, it will use the public IP of the server. The port 1883 will be appended automatically. This is the expected reachable port for MQ and cannot be changed at this time. +ALLOWED_EMAIL_DOMAINS -HOST_NETWORK: - **Default:** "off" + **Default** "*" - **Description:** Whether or not host networking is turned on. Only turn on if configured for host networking (see docker-compose.hostnetwork.yml). Will set host-level settings like iptables and forwarding for MQ. + **Description** only mentioned domains will be allowded to signup using oauth, by default all domains are allowed -MANAGE_IPTABLES: - **Default:** "on" +AUTH_PROVIDER - **Description:** # Allows netmaker to manage iptables locally to set forwarding rules. Largely for DNS or SSH forwarding (see below). It will also set a default "allow forwarding" policy on the host. It's better to leave this on unless you know what you're doing. + **Default** "" -PORT_FORWARD_SERVICES: - **Default:** "" + **Description** You can use azure-ad, github, google, oidc + +CLIENT_ID + + **Default** "" + + **Description** The client id of your oauth provider. + +CLIENT_SECRET + + **Default** "" + + **Description** The client secret of your oauth provider. + +FRONTEND_URL + + **Default** "" + + **Description** https://dashboard. + +AZURE_TENANT + + **Default** "" + + **Description** only for azure, you may optionally specify the tenant for the OAuth + +OIDC_ISSUER + + **Default** "" + + **Description** https://oidc.yourprovider.com - URL of oidc provider + +JWT_VALIDITY_DURATION + + **Default** 43200 + + **Description** Duration of JWT token validity in seconds + +RAC_AUTO_DISABLE + + **Default** false + + **Description** Auto disable a user's connected clients based on JWT token expiration + +CACHING_ENABLED + + **Default** true - **Description:** Comma-separated list of services for which to configure port forwarding on the machine. Options include "mq,dns,ssh". MQ IS DEPRECIATED, DO NOT SET THIS.'ssh' forwards port 22 over WireGuard, enabling ssh to server over WireGuard. However, if you set the Netmaker server as an Remote Access Gateway (ingress), this will break SSH on Remote Access Clients, so be careful. DNS enables private DNS over WireGuard. If you would like to use private DNS with ext clients, turn this on. + **Description** if turned on data will be cached on to improve performance significantly (IMPORTANT: If HA set to `false` ) -VERBOSITY: - **Default:** 0 +ENDPOINT_DETECTION - **Description:** Specify the level of logging you would like on the server. Goes up to 3 for debugging. If you run into issues, up the verbosity. + **Default** true + **Description** if turned on netclient checks if peers are reachable over private/LAN address, and choose that as peer endpoint Compose File - Annotated -------------------------------------- From ee0b5fec36f9ed367da8a0c5e0de16d872954ac8 Mon Sep 17 00:00:00 2001 From: theguy951357 Date: Mon, 24 Jun 2024 07:39:56 -0400 Subject: [PATCH 3/7] remove node_id --- server-installation.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/server-installation.rst b/server-installation.rst index d952b20a..9d8f62fe 100644 --- a/server-installation.rst +++ b/server-installation.rst @@ -92,12 +92,6 @@ UI_IMAGE_TAG **Description** The tag used for the netmaker ui docker image. You can set it to "latest" to get the most up to date version. To stay on a certain version set the tag to the version you would like. ex: v0.24.2. -NODE_ID - - **Default** netmaker-server-1 - - **Description** used for HA - identifies this server vs other servers - METRICS_EXPORTER **Default** off From 4ce730ba1ffe877e476ab9977f2e412b43fad19d Mon Sep 17 00:00:00 2001 From: theguy951357 Date: Mon, 24 Jun 2024 07:43:36 -0400 Subject: [PATCH 4/7] fix warning --- netclient.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/netclient.rst b/netclient.rst index 1f728fa6..a9ae44f6 100644 --- a/netclient.rst +++ b/netclient.rst @@ -74,12 +74,6 @@ Arch Distros (arch/manjaro/endeavouros) yay -S netclient -OpenWRT Distros (mips/mipsle) ------------------------------------------------- - -.. code-block:: - -refer to Advanced Client Installation :ref:`advanced-client-install:Notes on OpenWRT` OpenSUSE (tumbleweed/leap) --------------------------------------------------------------------- From 9d4d2c58e5e2c59f8c21980e50374b56b49f9b75 Mon Sep 17 00:00:00 2001 From: theguy951357 Date: Mon, 24 Jun 2024 07:46:26 -0400 Subject: [PATCH 5/7] fix windows link --- netclient.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netclient.rst b/netclient.rst index a9ae44f6..70b85acd 100644 --- a/netclient.rst +++ b/netclient.rst @@ -93,7 +93,7 @@ Windows Bundled Installer ----------------- -Download Link: https://fileserver.netmaker.org/latest/netclientbundle.exe +Download Link: https://fileserver.netmaker.org/releases/download/latest/netclientbundle.exe Mac ============ From bb0fd783747c283cc35667829f8ecc4f669a337b Mon Sep 17 00:00:00 2001 From: theguy951357 Date: Mon, 24 Jun 2024 07:47:51 -0400 Subject: [PATCH 6/7] fix apple install instructions --- netclient.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/netclient.rst b/netclient.rst index 70b85acd..c80c49b7 100644 --- a/netclient.rst +++ b/netclient.rst @@ -107,14 +107,13 @@ Brew Install (optional) brew audit netclient brew install netclient -GUI Installer (for v0.22.0 and below) +Installer ------------------------------------- Download Link for Apple silicon: https://fileserver.netmaker.org/releases/download/latest/Netclient-M1.pkg Download Link for Apple Intel: https://fileserver.netmaker.org/releases/download/latest/Netclient-Intel.pkg -Replace version number in URL with the version you want to install. Docker From 635baf85940d680966ebb1768c5f8bafab666306 Mon Sep 17 00:00:00 2001 From: theguy951357 Date: Mon, 24 Jun 2024 07:53:15 -0400 Subject: [PATCH 7/7] warning fix --- pro/pro-users.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pro/pro-users.rst b/pro/pro-users.rst index b671f54b..3e69f6b3 100644 --- a/pro/pro-users.rst +++ b/pro/pro-users.rst @@ -1,4 +1,4 @@ -.. _pro-users: + ================================= Users in Netmaker Professional