From 43d4a3097adba281784923ffd3b0d8ad1ba8036c Mon Sep 17 00:00:00 2001 From: Christopher Blaha Date: Wed, 17 Jul 2024 07:01:19 -0400 Subject: [PATCH] Net 1317 (#310) * updates * update server config vars * remove node_id * fix warning * fix windows link * fix apple install instructions * warning fix --- advanced-client-install.rst | 39 ------ netclient.rst | 15 +-- pro/pro-users.rst | 2 +- pro/rac.rst | 2 +- server-installation.rst | 232 +++++++++++++++++++++++------------- 5 files changed, 157 insertions(+), 133 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..c80c49b7 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) --------------------------------------------------------------------- @@ -99,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 ============ @@ -113,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/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. Docker 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 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..9d8f62fe 100644 --- a/server-installation.rst +++ b/server-installation.rst @@ -33,144 +33,214 @@ In most situations, if you wish to modify a server setting, set it in the netmak Variable Description ---------------------- -SERVER_NAME +NM_EMAIL + **Default** "" + + **Description** Email used for SSL certificates + +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. + +SERVER_IMAGE_TAG + + **Default** -CORS_ALLOWED_ORIGIN: - **Default:** "*" + **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:** The "allowed origin" for API requests. Change to restrict where API requests can come from. +UI_IMAGE_TAG -REST_BACKEND: - **Default:** "on" + **Default** "" - **Description:** Enables the REST backend (API running on API_PORT at SERVER_HTTP_HOST). Change to "off" to turn off. + **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. -DNS_MODE: - **Default:** "off" +METRICS_EXPORTER - **Description:** Enables DNS Mode, meaning config files will be generated for CoreDNS. + **Default** off -DATABASE: - **Default:** "sqlite" + **Description** This is a pro feature that exports metrics to the netmaker server. - **Description:** Specify db type to connect with. Currently, options include "sqlite", "rqlite", and "postgres". +PROMETHEUS -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. Prometheus is an open-source systems monitoring and alerting toolkit originally built at SoundCloud. It is used in out metrics collection -SQL_HOST: - **Default:** "localhost" +DNS_MODE - **Description:** Host where postgres is running. + **Default** on -SQL_PORT: - **Default:** "5432" + **Description** Enables DNS Mode, meaning all nodes will set hosts file for private dns settings - **Description:** port postgres is running. +NETCLIENT_AUTO_UPDATE -SQL_DB: - **Default:** "netmaker" + **Default** enabled - **Description:** DB to use in postgres. + **Description** Enable/Disable auto update of netclient -SQL_USER: - **Default:** "postgres" +API_PORT - **Description:** User for postgres. + **Default** 8081 -SQL_PASS: - **Default:** "nopass" + **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. - **Description:** Password for postgres. +EXPORTER_API_PORT -RCE: - **Default:** "off" + **Default** 8085 - **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 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 + + **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 -NODE_ID - **Default:** +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 - **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. +CLIENT_ID -VERBOSITY: - **Default:** 0 + **Default** "" - **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. + **Description** The client id of your oauth provider. +CLIENT_SECRET -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. + **Default** "" -.. literalinclude:: ./examplecode/dev.yaml - :language: YAML + **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** if turned on data will be cached on to improve performance significantly (IMPORTANT: If HA set to `false` ) + +ENDPOINT_DETECTION + + **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 -------------------------------------- @@ -334,7 +404,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 +450,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