mirror of
https://github.com/gravitl/netmaker.git
synced 2026-01-06 10:55:21 +08:00
docs update
This commit is contained in:
afeiszli
parent
85d363b1ad
commit
3960482cf5
9 changed files with 261 additions and 67 deletions
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.
|
|
@ -52,6 +52,8 @@ A user may choose to manually set a private DNS nameserver of <netmaker server>:
|
|||
Prerequisites
|
||||
=============
|
||||
|
||||
To obtain the netclient, go to the GitHub releases: https://github.com/gravitl/netmaker/releases
|
||||
|
||||
**For netclient cli:** Linux/Unix with WireGuard installed (wg command available)
|
||||
|
||||
**For netclient daemon:** Systemd Linux + WireGuard
|
||||
|
|
@ -61,29 +63,48 @@ Prerequisites
|
|||
Configuration
|
||||
===============
|
||||
|
||||
Variable Reference
|
||||
The CLI has information about all commands and variables. This section shows the "help" output for these commands as well as some additional reference.
|
||||
|
||||
CLI Reference
|
||||
--------------------
|
||||
``sudo netclient --help``
|
||||
|
||||
.. literalinclude:: ./examplecode/netclient-help.txt
|
||||
:language: YAML
|
||||
|
||||
|
||||
``sudo netclient join --help``
|
||||
|
||||
.. literalinclude:: ./examplecode/netclient-join.txt
|
||||
:language: YAML
|
||||
|
||||
|
||||
Config File Reference
|
||||
------------------------
|
||||
|
||||
CLI Reference
|
||||
------------------------
|
||||
There is a config file for each node under /etc/netconfig-<network name>. You can change these values and then set "postchanges" to "true", or go to the CLI and run ``netclient push -n <network>``
|
||||
|
||||
|
||||
.. literalinclude:: ./examplecode/netconfig-example.yml
|
||||
:language: YAML
|
||||
|
||||
|
||||
Installation
|
||||
======================
|
||||
|
||||
Token
|
||||
-------
|
||||
|
||||
Access Key
|
||||
------------
|
||||
To install netmaker, you need a server token for a particular network, unless you're joining a network that allows manual signup, in which case you can join without a token, but the server will quarantine the machine until the admin approves it.
|
||||
|
||||
Manual
|
||||
---------
|
||||
An admin creates a token in the ACCESS KEYS section of the UI. Upon creating a token, it generates 3 values:
|
||||
|
||||
**Access Key:** The secret key to authenticate as a node in the network
|
||||
|
||||
**Access Token:** The secret key plus information about how to access the server (addresses, ports), all decoded by the netclient to register with the server
|
||||
|
||||
**Install Command:** A short script that will obtain the netclient binary, register with the server, and join the network, all in one
|
||||
|
||||
For first time installations, you can run the Install Command. For additional networks, simply run ``netclient join -t <access token>``. The raw access key will not be needed unless there are special circumstances, mostly troubleshooting incorrect information in the token (you can instead manually specify the server location).
|
||||
|
||||
Config File
|
||||
------------
|
||||
|
||||
Managing Netclient
|
||||
=====================
|
||||
|
|
|
|||
153
docs/_build/html/client-installation.html
vendored
153
docs/_build/html/client-installation.html
vendored
|
|
@ -425,25 +425,13 @@
|
|||
</li>
|
||||
<li class="md-nav__item"><a href="#configuration" class="md-nav__link">Configuration</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#variable-reference" class="md-nav__link">Variable Reference</a>
|
||||
<li class="md-nav__item"><a href="#cli-reference" class="md-nav__link">CLI Reference</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#config-file-reference" class="md-nav__link">Config File Reference</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#cli-reference" class="md-nav__link">CLI Reference</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#installation" class="md-nav__link">Installation</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#token" class="md-nav__link">Token</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#access-key" class="md-nav__link">Access Key</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#manual" class="md-nav__link">Manual</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#config-file" class="md-nav__link">Config File</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
<li class="md-nav__item"><a href="#installation" class="md-nav__link">Installation</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#managing-netclient" class="md-nav__link">Managing Netclient</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
|
|
@ -792,25 +780,13 @@
|
|||
</li>
|
||||
<li class="md-nav__item"><a href="#configuration" class="md-nav__link">Configuration</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#variable-reference" class="md-nav__link">Variable Reference</a>
|
||||
<li class="md-nav__item"><a href="#cli-reference" class="md-nav__link">CLI Reference</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#config-file-reference" class="md-nav__link">Config File Reference</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#cli-reference" class="md-nav__link">CLI Reference</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#installation" class="md-nav__link">Installation</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
<li class="md-nav__item"><a href="#token" class="md-nav__link">Token</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#access-key" class="md-nav__link">Access Key</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#manual" class="md-nav__link">Manual</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#config-file" class="md-nav__link">Config File</a>
|
||||
</li></ul>
|
||||
</nav>
|
||||
<li class="md-nav__item"><a href="#installation" class="md-nav__link">Installation</a>
|
||||
</li>
|
||||
<li class="md-nav__item"><a href="#managing-netclient" class="md-nav__link">Managing Netclient</a><nav class="md-nav">
|
||||
<ul class="md-nav__list">
|
||||
|
|
@ -872,36 +848,125 @@
|
|||
|
||||
|
||||
<h2 id="prerequisites">Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
|
||||
<p>To obtain the netclient, go to the GitHub releases: <a class="reference external" href="https://github.com/gravitl/netmaker/releases">https://github.com/gravitl/netmaker/releases</a></p>
|
||||
<p><strong>For netclient cli:</strong> Linux/Unix with WireGuard installed (wg command available)</p>
|
||||
<p><strong>For netclient daemon:</strong> Systemd Linux + WireGuard</p>
|
||||
<p><strong>For Private DNS management:</strong> Resolvectl (systemd-resolved)</p>
|
||||
|
||||
|
||||
<h2 id="configuration">Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The CLI has information about all commands and variables. This section shows the “help” output for these commands as well as some additional reference.</p>
|
||||
|
||||
<h3 id="variable-reference">Variable Reference<a class="headerlink" href="#variable-reference" title="Permalink to this headline">¶</a></h3>
|
||||
<h3 id="cli-reference">CLI Reference<a class="headerlink" href="#cli-reference" title="Permalink to this headline">¶</a></h3>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">netclient</span> <span class="pre">--help</span></code></p>
|
||||
<div class="highlight-YAML notranslate"><div class="highlight"><pre><span></span><span class="nt">NAME</span><span class="p">:</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">Netclient CLI - Netmaker's netclient agent and CLI. Used to perform interactions with Netmaker server and set local WireGuard config.</span>
|
||||
|
||||
<span class="nt">USAGE</span><span class="p">:</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">netclient [global options] command [command options] [arguments...]</span>
|
||||
|
||||
<span class="nt">COMMANDS</span><span class="p">:</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">register Register with Netmaker Server for secure GRPC communications.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">join Join a Netmaker network.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">leave Leave a Netmaker network.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">checkin Checks for local changes and then checks into the specified Netmaker network to ask about remote changes.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">push Push configuration changes to server.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">pull Pull latest configuration and peers from server.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">list Get list of networks.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">uninstall Uninstall the netclient system service.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">unregister Unregister the netclient from secure server GRPC.</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">help, h Shows a list of commands or help for one command</span>
|
||||
|
||||
<span class="nt">GLOBAL OPTIONS</span><span class="p">:</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--help, -h show help (default</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">false)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">sudo</span> <span class="pre">netclient</span> <span class="pre">join</span> <span class="pre">--help</span></code></p>
|
||||
<div class="highlight-YAML notranslate"><div class="highlight"><pre><span></span><span class="nt">NAME</span><span class="p">:</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">netclient join - Join a Netmaker network.</span>
|
||||
|
||||
<span class="nt">USAGE</span><span class="p">:</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">netclient join [command options] [arguments...]</span>
|
||||
|
||||
<span class="nt">OPTIONS</span><span class="p">:</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--network value, -n value Network to perform specified action against. (default</span><span class="p p-Indicator">:</span> <span class="s">"all"</span><span class="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_NETWORK]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--password value, -p value Password for authenticating with netmaker. (default</span><span class="p p-Indicator">:</span> <span class="s">"badpassword"</span><span class="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_PASSWORD]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--endpoint value, -e value Reachable (usually public) address for WireGuard (not the private WG address). [$NETCLIENT_ENDPOINT]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--macaddress value, -m value Mac Address for this machine. Used as a unique identifier within Netmaker network. [$NETCLIENT_MACADDRESS]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--publickey value, --pubkey value Public Key for WireGuard Interface. [$NETCLIENT_PUBLICKEY]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--privatekey value, --privkey value Private Key for WireGuard Interface. [$NETCLIENT_PRIVATEKEY]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--port value Port for WireGuard Interface. [$NETCLIENT_PORT]</span>
|
||||
<span class="nt">--keepalive value Default PersistentKeepAlive for Peers in WireGuard Interface. (default</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">0) [$NETCLIENT_KEEPALIVE]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--operatingsystem value, --os value Identifiable name for machine within Netmaker network. [$NETCLIENT_OS]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--name value Identifiable name for machine within Netmaker network. [$NETCLIENT_NAME]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--localaddress value Local address for machine. Can be used in place of Endpoint for machines on the same LAN. [$NETCLIENT_LOCALADDRESS]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--address value, -a value WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESS]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--addressIPv6 value, --a6 value WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESSIPV6]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--interface value, -i value WireGuard local network interface name. [$NETCLIENT_INTERFACE]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--apiserver value Address + GRPC Port (e.g. 1.2.3.4:50051) of Netmaker server. [$NETCLIENT_API_SERVER]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--grpcserver value Address + API Port (e.g. 1.2.3.4:8081) of Netmaker server. [$NETCLIENT_GRPC_SERVER]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--key value, -k value Access Key for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSKEY]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--token value, -t value Access Token for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSTOKEN]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--localrange value Local Range if network is local, for instance 192.168.1.0/24. [$NETCLIENT_LOCALRANGE]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--dns value Sets private dns if 'on'. Ignores if 'off'. Will retrieve from network if unset. [$NETCLIENT_DNS]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--islocal value Sets endpoint to local address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_LOCAL]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--isdualstack value Sets ipv6 address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_DUALSTACK]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--ipforwarding value Sets ip forwarding on if 'on'. Ignores if 'off'. On by default. (default</span><span class="p p-Indicator">:</span> <span class="s">"on"</span><span class="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_IPFORWARDING]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--postup value Sets PostUp command for WireGuard. [$NETCLIENT_POSTUP]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--postdown value Sets PostDown command for WireGuard. [$NETCLIENT_POSTDOWN]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--daemon value Installs daemon if 'on'. Ignores if 'off'. On by default. (default</span><span class="p p-Indicator">:</span> <span class="s">"on"</span><span class="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_DAEMON]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--roaming value Checks for IP changes if 'on'. Ignores if 'off'. On by default. (default</span><span class="p p-Indicator">:</span> <span class="s">"on"</span><span class="l l-Scalar l-Scalar-Plain">) [$NETCLIENT_ROAMING]</span>
|
||||
<span class="l l-Scalar l-Scalar-Plain">--help, -h show help (default</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">false)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
|
||||
|
||||
<h3 id="config-file-reference">Config File Reference<a class="headerlink" href="#config-file-reference" title="Permalink to this headline">¶</a></h3>
|
||||
|
||||
|
||||
<h3 id="cli-reference">CLI Reference<a class="headerlink" href="#cli-reference" title="Permalink to this headline">¶</a></h3>
|
||||
<p>There is a config file for each node under /etc/netconfig-<network name>. You can change these values and then set “postchanges” to “true”, or go to the CLI and run <code class="docutils literal notranslate"><span class="pre">netclient</span> <span class="pre">push</span> <span class="pre">-n</span> <span class="pre"><network></span></code></p>
|
||||
<div class="highlight-YAML notranslate"><div class="highlight"><pre><span></span><span class="nt">server</span><span class="p">:</span>
|
||||
<span class="nt">grpcaddress</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">10.101.0.1:50051</span> <span class="c1"># Address of GRPC Server (used for all interaction with server after registration)</span>
|
||||
<span class="nt">apiaddress</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">1.2.3.4:8081</span> <span class="c1"># Address of API Server (used only for registration/unregistration)</span>
|
||||
<span class="nt">accesskey</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">5qKTbTgsvb45y3qyRmWft</span> <span class="c1"># Key used to sign up with server. Used only during registration</span>
|
||||
<span class="nt">node</span><span class="p">:</span>
|
||||
<span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">my-computer</span> <span class="c1"># name of this node</span>
|
||||
<span class="nt">interface</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">nm-example</span> <span class="c1"># name of interface to create/use for WG</span>
|
||||
<span class="nt">network</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">example</span> <span class="c1"># name of network this ode is a part of</span>
|
||||
<span class="nt">password</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">$2a$0afehuytviN/thMpVlCYkonxy.Ws2.rNCJjBSAa3HZuhrK5hpYxme</span> <span class="c1"># encrypted node password, used to retrieve JWT. Can be changed to new pass in plaintext and CLI will update/replace with encrypted pass</span>
|
||||
<span class="nt">macaddress</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">6c:4b:91:0g:68:7b</span> <span class="c1"># MAC of node. Used as a Unique ID</span>
|
||||
<span class="nt">localaddress</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">192.168.1.32</span> <span class="c1"># Address on local network, used as endpoint for other local nodes for faster comms</span>
|
||||
<span class="nt">wgaddress</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">10.7.11.2</span> <span class="c1"># Private WG addres on network</span>
|
||||
<span class="nt">wgaddress6</span><span class="p">:</span> <span class="s">"f8:34:41:77:5c:15"</span> <span class="c1"># Private ipv6 address if network is dual stack</span>
|
||||
<span class="nt">roaming</span><span class="p">:</span> <span class="s">"on"</span> <span class="c1"># Whether or not to grab new endpoint value automatically</span>
|
||||
<span class="nt">dns</span><span class="p">:</span> <span class="s">"off"</span> <span class="c1"># Whether or not to set local DNS based on Netmaker's Private DNS server</span>
|
||||
<span class="nt">islocal</span><span class="p">:</span> <span class="s">"no"</span> <span class="c1"># Based on network. If yes, will use local IP as endpoint.</span>
|
||||
<span class="nt">isdualstack</span><span class="p">:</span> <span class="s">"yes"</span> <span class="c1"># Use IPv6 in addition to IPv4</span>
|
||||
<span class="nt">isingressgateway</span><span class="p">:</span> <span class="s">"no"</span> <span class="c1"># whether or not node is an ingress gateway (will set iptables forwarding rules)</span>
|
||||
<span class="nt">allowedips</span><span class="p">:</span> <span class="s">""</span> <span class="c1"># not currently used</span>
|
||||
<span class="nt">localrange</span><span class="p">:</span> <span class="s">""</span> <span class="c1"># local range if it's a local network. For instance, 192.168.1.0/24</span>
|
||||
<span class="nt">postup</span><span class="p">:</span> <span class="s">""</span> <span class="c1"># postup command, used by ingress/egress gateways to set iptables</span>
|
||||
<span class="nt">postdown</span><span class="p">:</span> <span class="s">""</span> <span class="c1"># postdown command, used by ingress/egress gateways to set iptables</span>
|
||||
<span class="nt">port</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">51821</span> <span class="c1"># WG port to use</span>
|
||||
<span class="nt">keepalive</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">20</span> <span class="c1"># default keepalive with nodes</span>
|
||||
<span class="nt">publickey</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">8/q9cOg7c9QjnoXygVrY/VNE197VMRadJodkb1ZsujA=</span> <span class="c1"># public key of node to show to other nodes</span>
|
||||
<span class="nt">privatekey</span><span class="p">:</span> <span class="s">""</span> <span class="c1"># private key, set only for changing and then will revert to blank in config</span>
|
||||
<span class="nt">endpoint</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">78.170.22.168</span> <span class="c1"># public endpoint for reaching node </span>
|
||||
<span class="nt">postchanges</span><span class="p">:</span> <span class="s">"false"</span> <span class="c1"># if true, will post and config file changes on next checkin and then revert to false</span>
|
||||
<span class="nt">ipforwarding</span><span class="p">:</span> <span class="s">"on"</span> <span class="c1"># set ip forwarding; highly recommended to leave on</span>
|
||||
<span class="nt">network</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">home</span> <span class="c1"># the network (duplicate of node.network)</span>
|
||||
<span class="nt">daemon</span><span class="p">:</span> <span class="s">"on"</span> <span class="c1"># whether or not to manage systemd</span>
|
||||
<span class="nt">operatingsystem</span><span class="p">:</span> <span class="s">""</span> <span class="c1"># not currently in use</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
|
||||
|
||||
|
||||
<h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
|
||||
|
||||
<h3 id="token">Token<a class="headerlink" href="#token" title="Permalink to this headline">¶</a></h3>
|
||||
|
||||
|
||||
<h3 id="access-key">Access Key<a class="headerlink" href="#access-key" title="Permalink to this headline">¶</a></h3>
|
||||
|
||||
|
||||
<h3 id="manual">Manual<a class="headerlink" href="#manual" title="Permalink to this headline">¶</a></h3>
|
||||
|
||||
|
||||
<h3 id="config-file">Config File<a class="headerlink" href="#config-file" title="Permalink to this headline">¶</a></h3>
|
||||
|
||||
<p>To install netmaker, you need a server token for a particular network, unless you’re joining a network that allows manual signup, in which case you can join without a token, but the server will quarantine the machine until the admin approves it.</p>
|
||||
<p>An admin creates a token in the ACCESS KEYS section of the UI. Upon creating a token, it generates 3 values:</p>
|
||||
<p><strong>Access Key:</strong> The secret key to authenticate as a node in the network</p>
|
||||
<p><strong>Access Token:</strong> The secret key plus information about how to access the server (addresses, ports), all decoded by the netclient to register with the server</p>
|
||||
<p><strong>Install Command:</strong> A short script that will obtain the netclient binary, register with the server, and join the network, all in one</p>
|
||||
<p>For first time installations, you can run the Install Command. For additional networks, simply run <code class="docutils literal notranslate"><span class="pre">netclient</span> <span class="pre">join</span> <span class="pre">-t</span> <span class="pre"><access</span> <span class="pre">token></span></code>. The raw access key will not be needed unless there are special circumstances, mostly troubleshooting incorrect information in the token (you can instead manually specify the server location).</p>
|
||||
|
||||
|
||||
<h2 id="managing-netclient">Managing Netclient<a class="headerlink" href="#managing-netclient" title="Permalink to this headline">¶</a></h2>
|
||||
|
|
|
|||
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
|
|
@ -52,6 +52,8 @@ A user may choose to manually set a private DNS nameserver of <netmaker server>:
|
|||
Prerequisites
|
||||
=============
|
||||
|
||||
To obtain the netclient, go to the GitHub releases: https://github.com/gravitl/netmaker/releases
|
||||
|
||||
**For netclient cli:** Linux/Unix with WireGuard installed (wg command available)
|
||||
|
||||
**For netclient daemon:** Systemd Linux + WireGuard
|
||||
|
|
@ -61,29 +63,48 @@ Prerequisites
|
|||
Configuration
|
||||
===============
|
||||
|
||||
Variable Reference
|
||||
The CLI has information about all commands and variables. This section shows the "help" output for these commands as well as some additional reference.
|
||||
|
||||
CLI Reference
|
||||
--------------------
|
||||
``sudo netclient --help``
|
||||
|
||||
.. literalinclude:: ./examplecode/netclient-help.txt
|
||||
:language: YAML
|
||||
|
||||
|
||||
``sudo netclient join --help``
|
||||
|
||||
.. literalinclude:: ./examplecode/netclient-join.txt
|
||||
:language: YAML
|
||||
|
||||
|
||||
Config File Reference
|
||||
------------------------
|
||||
|
||||
CLI Reference
|
||||
------------------------
|
||||
There is a config file for each node under /etc/netconfig-<network name>. You can change these values and then set "postchanges" to "true", or go to the CLI and run ``netclient push -n <network>``
|
||||
|
||||
|
||||
.. literalinclude:: ./examplecode/netconfig-example.yml
|
||||
:language: YAML
|
||||
|
||||
|
||||
Installation
|
||||
======================
|
||||
|
||||
Token
|
||||
-------
|
||||
|
||||
Access Key
|
||||
------------
|
||||
To install netmaker, you need a server token for a particular network, unless you're joining a network that allows manual signup, in which case you can join without a token, but the server will quarantine the machine until the admin approves it.
|
||||
|
||||
Manual
|
||||
---------
|
||||
An admin creates a token in the ACCESS KEYS section of the UI. Upon creating a token, it generates 3 values:
|
||||
|
||||
**Access Key:** The secret key to authenticate as a node in the network
|
||||
|
||||
**Access Token:** The secret key plus information about how to access the server (addresses, ports), all decoded by the netclient to register with the server
|
||||
|
||||
**Install Command:** A short script that will obtain the netclient binary, register with the server, and join the network, all in one
|
||||
|
||||
For first time installations, you can run the Install Command. For additional networks, simply run ``netclient join -t <access token>``. The raw access key will not be needed unless there are special circumstances, mostly troubleshooting incorrect information in the token (you can instead manually specify the server location).
|
||||
|
||||
Config File
|
||||
------------
|
||||
|
||||
Managing Netclient
|
||||
=====================
|
||||
|
|
|
|||
20
docs/examplecode/netclient-help.txt
Normal file
20
docs/examplecode/netclient-help.txt
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
NAME:
|
||||
Netclient CLI - Netmaker's netclient agent and CLI. Used to perform interactions with Netmaker server and set local WireGuard config.
|
||||
|
||||
USAGE:
|
||||
netclient [global options] command [command options] [arguments...]
|
||||
|
||||
COMMANDS:
|
||||
register Register with Netmaker Server for secure GRPC communications.
|
||||
join Join a Netmaker network.
|
||||
leave Leave a Netmaker network.
|
||||
checkin Checks for local changes and then checks into the specified Netmaker network to ask about remote changes.
|
||||
push Push configuration changes to server.
|
||||
pull Pull latest configuration and peers from server.
|
||||
list Get list of networks.
|
||||
uninstall Uninstall the netclient system service.
|
||||
unregister Unregister the netclient from secure server GRPC.
|
||||
help, h Shows a list of commands or help for one command
|
||||
|
||||
GLOBAL OPTIONS:
|
||||
--help, -h show help (default: false)
|
||||
35
docs/examplecode/netclient-join.txt
Normal file
35
docs/examplecode/netclient-join.txt
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
NAME:
|
||||
netclient join - Join a Netmaker network.
|
||||
|
||||
USAGE:
|
||||
netclient join [command options] [arguments...]
|
||||
|
||||
OPTIONS:
|
||||
--network value, -n value Network to perform specified action against. (default: "all") [$NETCLIENT_NETWORK]
|
||||
--password value, -p value Password for authenticating with netmaker. (default: "badpassword") [$NETCLIENT_PASSWORD]
|
||||
--endpoint value, -e value Reachable (usually public) address for WireGuard (not the private WG address). [$NETCLIENT_ENDPOINT]
|
||||
--macaddress value, -m value Mac Address for this machine. Used as a unique identifier within Netmaker network. [$NETCLIENT_MACADDRESS]
|
||||
--publickey value, --pubkey value Public Key for WireGuard Interface. [$NETCLIENT_PUBLICKEY]
|
||||
--privatekey value, --privkey value Private Key for WireGuard Interface. [$NETCLIENT_PRIVATEKEY]
|
||||
--port value Port for WireGuard Interface. [$NETCLIENT_PORT]
|
||||
--keepalive value Default PersistentKeepAlive for Peers in WireGuard Interface. (default: 0) [$NETCLIENT_KEEPALIVE]
|
||||
--operatingsystem value, --os value Identifiable name for machine within Netmaker network. [$NETCLIENT_OS]
|
||||
--name value Identifiable name for machine within Netmaker network. [$NETCLIENT_NAME]
|
||||
--localaddress value Local address for machine. Can be used in place of Endpoint for machines on the same LAN. [$NETCLIENT_LOCALADDRESS]
|
||||
--address value, -a value WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESS]
|
||||
--addressIPv6 value, --a6 value WireGuard address for machine within Netmaker network. [$NETCLIENT_ADDRESSIPV6]
|
||||
--interface value, -i value WireGuard local network interface name. [$NETCLIENT_INTERFACE]
|
||||
--apiserver value Address + GRPC Port (e.g. 1.2.3.4:50051) of Netmaker server. [$NETCLIENT_API_SERVER]
|
||||
--grpcserver value Address + API Port (e.g. 1.2.3.4:8081) of Netmaker server. [$NETCLIENT_GRPC_SERVER]
|
||||
--key value, -k value Access Key for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSKEY]
|
||||
--token value, -t value Access Token for signing up machine with Netmaker server during initial 'add'. [$NETCLIENT_ACCESSTOKEN]
|
||||
--localrange value Local Range if network is local, for instance 192.168.1.0/24. [$NETCLIENT_LOCALRANGE]
|
||||
--dns value Sets private dns if 'on'. Ignores if 'off'. Will retrieve from network if unset. [$NETCLIENT_DNS]
|
||||
--islocal value Sets endpoint to local address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_LOCAL]
|
||||
--isdualstack value Sets ipv6 address if 'yes'. Ignores if 'no'. Will retrieve from network if unset. [$NETCLIENT_IS_DUALSTACK]
|
||||
--ipforwarding value Sets ip forwarding on if 'on'. Ignores if 'off'. On by default. (default: "on") [$NETCLIENT_IPFORWARDING]
|
||||
--postup value Sets PostUp command for WireGuard. [$NETCLIENT_POSTUP]
|
||||
--postdown value Sets PostDown command for WireGuard. [$NETCLIENT_POSTDOWN]
|
||||
--daemon value Installs daemon if 'on'. Ignores if 'off'. On by default. (default: "on") [$NETCLIENT_DAEMON]
|
||||
--roaming value Checks for IP changes if 'on'. Ignores if 'off'. On by default. (default: "on") [$NETCLIENT_ROAMING]
|
||||
--help, -h show help (default: false)
|
||||
32
docs/examplecode/netconfig-example.yml
Normal file
32
docs/examplecode/netconfig-example.yml
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
server:
|
||||
grpcaddress: 10.101.0.1:50051 # Address of GRPC Server (used for all interaction with server after registration)
|
||||
apiaddress: 1.2.3.4:8081 # Address of API Server (used only for registration/unregistration)
|
||||
accesskey: 5qKTbTgsvb45y3qyRmWft # Key used to sign up with server. Used only during registration
|
||||
node:
|
||||
name: my-computer # name of this node
|
||||
interface: nm-example # name of interface to create/use for WG
|
||||
network: example # name of network this ode is a part of
|
||||
password: $2a$0afehuytviN/thMpVlCYkonxy.Ws2.rNCJjBSAa3HZuhrK5hpYxme # encrypted node password, used to retrieve JWT. Can be changed to new pass in plaintext and CLI will update/replace with encrypted pass
|
||||
macaddress: 6c:4b:91:0g:68:7b # MAC of node. Used as a Unique ID
|
||||
localaddress: 192.168.1.32 # Address on local network, used as endpoint for other local nodes for faster comms
|
||||
wgaddress: 10.7.11.2 # Private WG addres on network
|
||||
wgaddress6: "f8:34:41:77:5c:15" # Private ipv6 address if network is dual stack
|
||||
roaming: "on" # Whether or not to grab new endpoint value automatically
|
||||
dns: "off" # Whether or not to set local DNS based on Netmaker's Private DNS server
|
||||
islocal: "no" # Based on network. If yes, will use local IP as endpoint.
|
||||
isdualstack: "yes" # Use IPv6 in addition to IPv4
|
||||
isingressgateway: "no" # whether or not node is an ingress gateway (will set iptables forwarding rules)
|
||||
allowedips: "" # not currently used
|
||||
localrange: "" # local range if it's a local network. For instance, 192.168.1.0/24
|
||||
postup: "" # postup command, used by ingress/egress gateways to set iptables
|
||||
postdown: "" # postdown command, used by ingress/egress gateways to set iptables
|
||||
port: 51821 # WG port to use
|
||||
keepalive: 20 # default keepalive with nodes
|
||||
publickey: 8/q9cOg7c9QjnoXygVrY/VNE197VMRadJodkb1ZsujA= # public key of node to show to other nodes
|
||||
privatekey: "" # private key, set only for changing and then will revert to blank in config
|
||||
endpoint: 78.170.22.168 # public endpoint for reaching node
|
||||
postchanges: "false" # if true, will post and config file changes on next checkin and then revert to false
|
||||
ipforwarding: "on" # set ip forwarding; highly recommended to leave on
|
||||
network: home # the network (duplicate of node.network)
|
||||
daemon: "on" # whether or not to manage systemd
|
||||
operatingsystem: "" # not currently in use
|
||||
Loading…
Add table
Reference in a new issue