<p>By default, Netmaker ships with DNS Mode, Client Mode, and Secure GRPC enabled. However, these features require special permissions and are not necessary for a simple setup, so we are going to deploy without them. To learn more about enabling these features, check out the <aclass="reference internal"href="server-installation.html"><spanclass="doc">installation docs</span></a>.</p>
<h2id="prerequisites">Prerequisites<aclass="headerlink"href="#prerequisites"title="Permalink to this headline">¶</a></h2>
<blockquote>
<div><olclass="arabic simple">
<li><p>A Linux server to host Netmaker, with an external IP reachable by your nodes (will be referred to as <strong>your-host</strong> in document).</p></li>
<li><p>Docker and Docker Compose installed on the above server. Follow the official <aclass="reference external"href="https://docs.docker.com/engine/install/">Docker instructions</a> for installing Docker and Docker Compose on your system.</p></li>
<li><p>All network nodes should be systemd-based (see Compatibility under <aclass="reference internal"href="architecture.html"><spanclass="doc">Architecture</span></a> docs)</p></li>
</ol>
</div></blockquote>
<h2id="install">Install<aclass="headerlink"href="#install"title="Permalink to this headline">¶</a></h2>
<p>Navigate to the IP address of your host in the browser. You should see the below screen. If not, please see the Quick Start section of the <aclass="reference internal"href="support.html"><spanclass="doc">troubleshooting</span></a> docs.</p>
<aclass="reference internal image-reference"href="_images/create-user.png"><imgalt="Create User Screen"class="align-center"src="_images/create-user.png"style="width: 80%;"/></a>
<h2id="setup">Setup<aclass="headerlink"href="#setup"title="Permalink to this headline">¶</a></h2>
<olclass="arabic simple">
<li><p>Create your admin user, with a username and password.</p></li>
<li><p>Login with your new user</p></li>
<li><p>Examine the <strong>default</strong> network. Click on DEFAULT under NETWORK DETAILS</p></li>
</ol>
<aclass="reference internal image-reference"href="_images/default-net.png"><imgalt="Create User Screen"class="align-center"src="_images/default-net.png"style="width: 80%;"/></a>
<p>This displays information about the <strong>default</strong> network, which is created on server startup. You can delete this network if you do not need it, but for standard use cases this network should be enough to get started. Nodes will get an address from the network address range (ADDRESSRANGE). If the range conflicts with a pre-existing private network on your devices, you may want to change this, or make a new network instead. Nodes will also get default settings from here for unset configurations. For instance, the DEFAULTKEEPALIVE field will set the PersistenKeepAlive for nodes.</p>
<p>To get started quickly, we can just use the existing default network.</p>
<h3id="create-key">Create Key<aclass="headerlink"href="#create-key"title="Permalink to this headline">¶</a></h3>
<olclass="arabic simple">
<li><p>Click on the ACCESS KEYS tab and select the DEFAULT network.</p></li>
<li><p>Click ADD NEW ACCESS KEY</p></li>
<li><p>Give it a name (ex: “mykey”) and a number of uses (ex: 25)</p></li>
<li><p>Click CREATE KEY (<strong>Important:</strong> Do not click out of the following screen until you have saved your key details. It will appear only once.)</p></li>
<li><p>Copy the bottom command under “Your agent install command with access token” and save it somewhere locally. E.x: <codeclass="docutils literal notranslate"><spanclass="pre">curl</span><spanclass="pre">-sfL</span><spanclass="pre">https://raw.githubusercontent.com/gravitl/netmaker/v0.5/scripts/netclient-install.sh</span><spanclass="pre">|</span><spanclass="pre">KEY=vm3ow4thatogiwnsla3thsl3894ths</span><spanclass="pre">sh</span><spanclass="pre">-</span></code>. <strong>A change is required here. Change netclient-install.sh in this command to netclient-install.slim.sh, EX:</strong></p></li>
<p>You will use this command to install the netclient on your nodes. There are three different values for three different scenarios:</p>
<ulclass="simple">
<li><p>The <strong>Access Key</strong> value is the secret string that will allow your node to authenticate with the Netmaker network. This can be used with existing netclient installations where additional configurations (such as setting the server IP manually) may be required. This is not typical. E.g. <codeclass="docutils literal notranslate"><spanclass="pre">netclient</span><spanclass="pre">-c</span><spanclass="pre">install</span><spanclass="pre">-k</span><spanclass="pre"><access</span><spanclass="pre">key></span><spanclass="pre">-s</span><spanclass="pre">1.2.3.4</span><spanclass="pre">-p</span><spanclass="pre">50052</span></code></p></li>
<li><p>The <strong>Access Token</strong> value is a base64 encoded string that contains the server IP and grpc port, as well as the access key. This is decoded by the netclient and can be used with existing netclient installations like this: <codeclass="docutils literal notranslate"><spanclass="pre">netclient</span><spanclass="pre">-c</span><spanclass="pre">install</span><spanclass="pre">-t</span><spanclass="pre"><access</span><spanclass="pre">token></span></code>. You should use this method for adding a network to a node that is already on a network. For instance, Node A is in the <strong>mynet</strong> network and now you are adding it to <strong>default</strong>.</p></li>
<li><p>The <strong>install command</strong> value is a curl command that can be run on Linux systems. It is a simple script that downloads the netclient binary and runs the install command all in one. However, this script is tailored for Secure GRPC Mode and contains an additional (unnecessary) command: <strong>netclient register -k keyvalue</strong>. This command will not work without secure GRPC enabled and will return a 500 error.</p></li>
<p>Networks can also be enabled to allow nodes to sign up without keys at all. In this scenario, nodes enter a “pending state” and are not permitted to join the network until an admin approves them.</p>
<h2id="deploy-nodes">Deploy Nodes<aclass="headerlink"href="#deploy-nodes"title="Permalink to this headline">¶</a></h2>
<li><p><strong>Prerequisite Check:</strong> Every Linux machine on which you run the netclient must have WireGuard and systemd installed</p></li>
</ol>
<blockquote>
<div><ulclass="simple">
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">which</span><spanclass="pre">wg</span></code> (should show wg binary present)</p></li>
<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 <aclass="reference internal"href="client-installation.html"><spanclass="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 <aclass="reference internal"href="troubleshoot.html"><spanclass="doc">troubleshooting</span></a> documentation.</p>
<aclass="reference internal image-reference"href="_images/nc-install-output.png"><imgalt="Output from Netclient Install"class="align-center"src="_images/nc-install-output.png"style="width: 80%;"/></a>
<p>Repeat the above steps for every machine you would like to add to your network. You can re-use the same install command so long as you do not run out of uses on your access key (after which it will be invalidated and deleted).</p>
<p>Once installed on all nodes, you can test the connection by pinging the private address of any node from any other node.</p>
<p>You can view/modify/delete any node by selecting it in the NODES tab. For instance, you can change the name to something more sensible like “workstation” or “api server”. You can also modify network settings here, such as keys or the WireGuard port. These settings will be picked up by the node on its next check in. For more information, see Advanced Configuration in the <aclass="reference internal"href="usage.html"><spanclass="doc">Using Netmaker</span></a> docs.</p>
<p>Nodes can be added/removed/modified on the network at any time. Nodes can also be added to multiple Netmaker networks. Any changes will get picked up by any nodes on a given network, and will take aboue ~30 seconds to take effect.</p>
<h2id="uninstalling-the-netclient">Uninstalling the netclient<aclass="headerlink"href="#uninstalling-the-netclient"title="Permalink to this headline">¶</a></h2>
<li><p>To remove your nodes from the default network, run the following on each node: <codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">netclient</span><spanclass="pre">leave</span><spanclass="pre">-n</span><spanclass="pre">default</span></code></p></li>
<li><p>To remove the netclient entirely from each node, run <codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">rm</span><spanclass="pre">-rf</span><spanclass="pre">/etc/netclient</span></code> (after running the first step)</p></li>
<p>To uninstall Netmaker from the server, simply run <codeclass="docutils literal notranslate"><spanclass="pre">docker-compose</span><spanclass="pre">down</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">docker-compose</span><spanclass="pre">down</span><spanclass="pre">--volumes</span></code> to remove the docker volumes for a future installation.</p>