gravitl/netmaker
1
1
Fork 0
mirror of https://github.com/gravitl/netmaker.git synced 2024-09-24 01:06:05 +08:00
Code Issues Packages Projects Releases Wiki Activity
netmaker/docs/_build/html/getting-started.html
afeiszli 3996d48380 auto generate clientid
2021-05-25 17:57:06 -04:00

504 lines
23 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<meta name="lang:clipboard.copy" content="Copy to clipboard">
<meta name="lang:clipboard.copied" content="Copied to clipboard">
<meta name="lang:search.language" content="en">
<meta name="lang:search.pipeline.stopwords" content="True">
<meta name="lang:search.pipeline.trimmer" content="True">
<meta name="lang:search.result.none" content="No matching documents">
<meta name="lang:search.result.one" content="1 matching document">
<meta name="lang:search.result.other" content="# matching documents">
<meta name="lang:search.tokenizer" content="[\s\-]+">
<link href="https://fonts.gstatic.com/" rel="preconnect" crossorigin>
<link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,500,700|Roboto:300,400,400i,700&display=fallback" rel="stylesheet">
<style>
body,
input {
font-family: "Roboto", "Helvetica Neue", Helvetica, Arial, sans-serif
}
code,
kbd,
pre {
font-family: "Roboto Mono", "Courier New", Courier, monospace
}
</style>
<link rel="stylesheet" href="_static/stylesheets/application.css"/>
<link rel="stylesheet" href="_static/stylesheets/application-palette.css"/>
<link rel="stylesheet" href="_static/stylesheets/application-fixes.css"/>
<link rel="stylesheet" href="_static/fonts/material-icons.css"/>
<meta name="theme-color" content="#3f51b5">
<script src="_static/javascripts/modernizr.js"></script>
<title>Getting Started &#8212; Netmaker 0.3.5 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/material.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Welcome to Netmaker’s documentation!" href="index.html" />
</head>
<body dir=ltr
data-md-color-primary=indigo data-md-color-accent=light-blue>
<svg class="md-svg">
<defs data-children-count="0">
<svg xmlns="http://www.w3.org/2000/svg" width="416" height="448" viewBox="0 0 416 448" id="__github"><path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19T128 352t-18.125-8.5-10.75-19T96 304t3.125-20.5 10.75-19T128 256t18.125 8.5 10.75 19T160 304zm160 0q0 10-3.125 20.5t-10.75 19T288 352t-18.125-8.5-10.75-19T256 304t3.125-20.5 10.75-19T288 256t18.125 8.5 10.75 19T320 304zm40 0q0-30-17.25-51T296 232q-10.25 0-48.75 5.25Q229.5 240 208 240t-39.25-2.75Q130.75 232 120 232q-29.5 0-46.75 21T56 304q0 22 8 38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0 37.25-1.75t35-7.375 30.5-15 20.25-25.75T360 304zm56-44q0 51.75-15.25 82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5T212 416q-19.5 0-35.5-.75t-36.875-3.125-38.125-7.5-34.25-12.875T37 371.5t-21.5-28.75Q0 312 0 260q0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25 30.875Q171.5 96 212 96q37 0 70 8 26.25-20.5 46.75-30.25T376 64q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34 99.5z"/></svg>
</defs>
</svg>
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search">
<label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
<a href="#getting-started" tabindex="1" class="md-skip"> Skip to content </a>
<header class="md-header" data-md-component="header">
<nav class="md-header-nav md-grid">
<div class="md-flex navheader">
<div class="md-flex__cell md-flex__cell--shrink">
<a href="index.html" title="Netmaker 0.3.5 documentation"
class="md-header-nav__button md-logo">
<i class="md-icon">&#xe869</i>
</a>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
</div>
<div class="md-flex__cell md-flex__cell--stretch">
<div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
<span class="md-header-nav__topic">Netmaker Docs</span>
<span class="md-header-nav__topic"> Getting Started </span>
</div>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" action="search.html" method="GET" name="search">
<input type="text" class="md-search__input" name="q" placeholder="Search"
autocapitalize="off" autocomplete="off" spellcheck="false"
data-md-component="query" data-md-state="active">
<label class="md-icon md-search__icon" for="__search"></label>
<button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
&#xE5CD;
</button>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" data-md-scrollfix>
<div class="md-search-result" data-md-component="result">
<div class="md-search-result__meta">
Type to start searching
</div>
<ol class="md-search-result__list"></ol>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<div class="md-header-nav__source">
<a href="https://github.com/bashtage/sphinx-material/" title="Go to repository" class="md-source" data-md-source="github">
<div class="md-source__icon">
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24" width="28" height="28">
<use xlink:href="#__github" width="24" height="24"></use>
</svg>
</div>
<div class="md-source__repository">
Material for Sphinx
</div>
</a>
</div>
</div>
<script src="_static/javascripts/version_dropdown.js"></script>
<script>
var json_loc = ""versions.json"",
target_loc = "../",
text = "Versions";
$( document ).ready( add_version_dropdown(json_loc, target_loc, text));
</script>
</div>
</nav>
</header>
<div class="md-container">
<nav class="md-tabs" data-md-component="tabs">
<div class="md-tabs__inner md-grid">
<ul class="md-tabs__list">
<li class="md-tabs__item"><a href="index.html" class="md-tabs__link">Netmaker 0.3.5 documentation</a></li>
</ul>
</div>
</nav>
<main class="md-main">
<div class="md-main__inner md-grid" data-md-component="container">
<div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" data-md-level="0">
<label class="md-nav__title md-nav__title--site" for="__drawer">
<a href="index.html" title="Netmaker 0.3.5 documentation" class="md-nav__button md-logo">
<i class="md-icon">&#xe869</i>
</a>
<a href="index.html"
title="Netmaker 0.3.5 documentation">Netmaker Docs</a>
</label>
<div class="md-nav__source">
<a href="https://github.com/bashtage/sphinx-material/" title="Go to repository" class="md-source" data-md-source="github">
<div class="md-source__icon">
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 24 24" width="28" height="28">
<use xlink:href="#__github" width="24" height="24"></use>
</svg>
</div>
<div class="md-source__repository">
Material for Sphinx
</div>
</a>
</div>
<ul class="md-nav__list">
<li class="md-nav__item">
<input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc"> Getting Started </label>
<a href="#" class="md-nav__link md-nav__link--active">Getting Started</a>
<nav class="md-nav md-nav--secondary">
<label class="md-nav__title" for="__toc">Contents</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item"><a href="#getting-started--page-root" class="md-nav__link">Getting Started</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#use-cases" class="md-nav__link">Use Cases</a>
</li>
<li class="md-nav__item"><a href="#compatible-systems" class="md-nav__link">Compatible Systems</a>
</li>
<li class="md-nav__item"><a href="#quick-start" class="md-nav__link">Quick Start</a>
</li></ul>
</nav>
</li>
<li class="md-nav__item"><a class="md-nav__extra_link" href="_sources/getting-started.rst.txt">Show Source</a> </li>
</ul>
</nav>
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#use-cases" class="md-nav__link">Use Cases</a>
</li>
<li class="md-nav__item">
<a href="#compatible-systems" class="md-nav__link">Compatible Systems</a>
</li>
<li class="md-nav__item">
<a href="#quick-start" class="md-nav__link">Quick Start</a>
</li></ul>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary">
<label class="md-nav__title" for="__toc">Contents</label>
<ul class="md-nav__list" data-md-scrollfix="">
<li class="md-nav__item"><a href="#getting-started--page-root" class="md-nav__link">Getting Started</a><nav class="md-nav">
<ul class="md-nav__list">
<li class="md-nav__item"><a href="#use-cases" class="md-nav__link">Use Cases</a>
</li>
<li class="md-nav__item"><a href="#compatible-systems" class="md-nav__link">Compatible Systems</a>
</li>
<li class="md-nav__item"><a href="#quick-start" class="md-nav__link">Quick Start</a>
</li></ul>
</nav>
</li>
<li class="md-nav__item"><a class="md-nav__extra_link" href="_sources/getting-started.rst.txt">Show Source</a> </li>
<li id="searchbox" class="md-nav__item"></li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content">
<article class="md-content__inner md-typeset" role="main">
<h1 id="getting-started--page-root">Getting Started<a class="headerlink" href="#getting-started--page-root" title="Permalink to this headline"></a></h1>
<p>Netmaker is a tool for creating and managing virtual overlay networks. If you have servers spread across multiple locations, data centers, or clouds, this platform can make life easier. Netmaker takes all those machines and puts them on a single, secure, flat network so that they can all talk to each other easily and securely. It’s like a VPC but of arbitrary computers.</p>
<p>Netmaker can be compared to and covers use cases similar to Tailscale, ZeroTier, or Nebula, but Netmaker does more than that, while being faster, more dynamic and more flexible.</p>
<p>Netmaker uses kernel WireGuard to create encrypted tunnels between every node in your virtual network. Netmaker’s <cite>netclient</cite> agent is self-updating and pulls any necessary changes (such as new peers) from the main server.</p>
<h2 id="use-cases">Use Cases<a class="headerlink" href="#use-cases" title="Permalink to this headline"></a></h2>
<blockquote>
<div><ol class="arabic simple">
<li><p>Create a flat, secure network between multiple/hybrid cloud environments</p></li>
<li><p>Integrate central and edge services</p></li>
<li><p>Secure a home or office network while providing remote connectivity</p></li>
</ol>
<p>4. Manage cryptocurrency proof-of-stake machines
6. Provide an additional layer of security on an existing network
7. Encrypt Kubernetes inter-node communications
8. Secure site-to-site connections</p>
</div></blockquote>
<h2 id="compatible-systems">Compatible Systems<a class="headerlink" href="#compatible-systems" title="Permalink to this headline"></a></h2>
<dl class="simple">
<dt>To manage a server automatically, Netmaker requires <strong>systemd-based linux.</strong> Compatible systems include:</dt><dd><ul class="simple">
<li><p>Fedora</p></li>
<li><p>Ubuntu</p></li>
<li><p>Debian</p></li>
<li><p>Mint</p></li>
<li><p>SUSE</p></li>
<li><p>RHEL</p></li>
<li><p>Raspian.</p></li>
<li><p>Arch</p></li>
<li><p>CentOS</p></li>
<li><p>CoreOS</p></li>
</ul>
</dd>
<dt>To manage DNS (optional), the server must have systemd-resolved. Systems that have this enabled include:</dt><dd><ul class="simple">
<li><p>Arch</p></li>
<li><p>Debian</p></li>
<li><p>Ubuntu</p></li>
<li><p>SUSE</p></li>
</ul>
</dd>
</dl>
<p>In future releases, we will support other platforms such as Windows, MacOS, iOS, Android, and more.</p>
<p>Video Tutorials and Articles:</p>
<h2 id="quick-start">Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this headline"></a></h2>
<p>[Intro/Overview Video Tutorial](<a class="reference external" href="https://youtu.be/PWLPT320Ybo">https://youtu.be/PWLPT320Ybo</a>)
[Site-to-Site Video Tutorial](<a class="reference external" href="https://youtu.be/krCKBJhwwDk">https://youtu.be/krCKBJhwwDk</a>)</p>
<p>### Note about permissions
The default installation requires special privileges on the server side, because Netmaker will control the local kernel Wireguard. This can be turned off and run in non-privileged mode if necessary (but disables some features). For more details, see the <strong>Usage</strong> docs.</p>
<dl class="simple">
<dt>### Prereqs</dt><dd><ol class="arabic simple">
<li><p>A running linux server to host Netmaker, with an IP reachable by your computers (Debian-based preferred but not required).</p></li>
<li><p>Linux installed on the above server (Debian-based preferred but not required).</p></li>
<li><p>Install Docker and Docker Compose if running in Docker Mode (see below).</p></li>
<li><dl class="simple">
<dt>System dependencies installed:</dt><dd><ul class="simple">
<li><p>Docker (if running in default Docker mode. DO NOT use snap install for docker.)</p></li>
<li><p>Docker Compose</p></li>
<li><p>Wireguard + Resolvectl (if running in default Client mode)</p></li>
</ul>
</dd>
</dl>
</li>
</ol>
</dd>
</dl>
<p>#### CoreDNS Preparation
v0.3 introduces CoreDNS as a private nameserver. To run CoreDNS on your server host, you must disable systemd-resolved to open port 53:
1. systemctl stop systemd-resolved
2. systemctl disable systemd-resolved
3. vim /etc/systemd/resolved.conf</p>
<blockquote>
<div><blockquote>
<div><ul class="simple">
<li><p>uncomment <strong>DNS=</strong> and add 8.8.8.8 or whatever is your preference</p></li>
<li><p>uncomment <strong>DNSStubListener=</strong> and set to <strong>“no”</strong></p></li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="4">
<li><p>sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf</p></li>
</ol>
</div></blockquote>
<p>### Launch Netmaker
Note, this installs Netmaker with CoreDNS and a Netclient (privileged). If you want to run the server non-privileged or without CoreDNS, see the advanced usage docs.</p>
<ol class="arabic simple">
<li><p>Clone this repo or just copy contents of “docker-compose.yml” to your Netmaker server (from prereqs).</p></li>
<li><p>In docker-compose.yml, change BACKEND_URL to the public IP of your server.</p></li>
<li><p>Run <cite>sudo docker-compose up -d</cite></p></li>
<li><p>Navigate to your server’s IP in the browser and you should see the Netmaker UI asking to create a new admin user.</p></li>
<li><p>Create a new admin user</p></li>
<li><p>You are now ready to begin using Netmaker.</p></li>
</ol>
<p>### Create a Network
You can also just use the “default” network.
1. Click “CREATE NETWORK” in the upper left of your console
2. Enter a valid address range, e.g. 10.11.12.0/24
3. Enter a name such as “homenet”
4. Additional options:</p>
<blockquote>
<div><ul class="simple">
<li><p><strong>Dual Stack</strong>: Machines will recieve a private IPv6 address in addition to their IPv4 address.</p></li>
<li><p><strong>Local:</strong> Will use local address range for endpoints instead of public. Use Case: Home or Office network where most devices do not have public IP’s. In this case you can create a gateway into the network after creating the Local Network.</p></li>
</ul>
</div></blockquote>
<p>After Network creation, you can edit the network in the NETWORK DETAILS pane, modifying the address range and default options. You can also toggle on <strong>Allow Node Signup Without Keys</strong>, which makes the next step unnecessary, but allows anyone to create a node in your network, which will be cordoned in pending state.</p>
<p>### Create Keys
1. Click the “ACCESS KEYS” tab
2. Click “ADD NEW ACCESSS KEY”
3. Give your key a name and number of uses
4. Several values will be displayed. Save these somewhere, as they will only be displayed once:</p>
<blockquote>
<div><ul class="simple">
<li><p><strong>Access Key:</strong> Use only in special edge cases where server connection string must be modified</p></li>
<li><p><strong>Access Token:</strong> Use on machines that already have the netclient utility</p></li>
<li><p><strong>Install Command:</strong> Use on machines that do not have the netclient utility</p></li>
</ul>
</div></blockquote>
<p>### Install Agent:
For machines <strong>without</strong> netclient, run the install command (from above): <cite>curl -sfL https://raw.githubusercontent.com/gravitl/netmaker/v0.3/netclient-install.sh | KEY=&lt;your access key&gt; sh -</cite>
For machines <strong>with</strong> netclient run the following (with access token from above): <cite>sudo netclient -c install -t &lt;access token&gt;</cite>
For networks with <strong>manual signup</strong> enabled (see above), install using the network name: <cite>sudo netclient -c install -n &lt;network name&gt;</cite></p>
<p>### Manage Nodes
Your machines should now be visible in the control pane.
<strong>Modify nodes:</strong> Click the pencil icon in the NODES pane to modify details like WireGuard port, address, and node name. You can also <strong>DELETE</strong> nodes here and they will lose network access.
<strong>Approve nodes:</strong> If a node is in pending state (signed up without key), you can approve it. An icon will appear for pending nodes that need approval.</p>
<p><strong>Gateway Mode:</strong> Click the Gateway icon to enable gateway mode on a given node. A popup will allow you to choose an existing network, or enter a custom address range.
<em>Example: You create a network in netmaker called Homenet. It has several machines on your home server. You create another network called Cloudnet. It has several machines in AWS. You have one server (server X) which is added to both networks. On Cloudnet, you make Server X a gateway to Homenet. Now, the cloudnet machines have access to your homenet machines. via Server X.</em></p>
<p><em>On Homenet, you add Server Y, a machine in AWS, and make it a gateway to a custom address range 172.16.0.0/16. The machines on your home network now have access to any AWS machines in that address range via Server Y</em></p>
<p>### Manage DNS
On the DNS tab you can create custom DNS entries for a given network.</p>
<blockquote>
<div><ol class="arabic simple">
<li><p>All dns entries will be <em>postfixed</em> with a private TLD of the network name, for example, “.mynet”</p></li>
<li><p>Default DNS is created for node name + TLD, for instance, node-c42wt.mynet. This is not editable.</p></li>
<li><dl class="simple">
<dt>Click ADD ENTRY to add custom DNS</dt><dd><ul class="simple">
<li><p>You can click CHOOSE NODE to direct DNS to a specific node in the network</p></li>
<li><p>You can also specify any custom address you would like, which can be outside the network (for instance, the IP for google.com)</p></li>
<li><p>Add a dns entry name, which will be postfixed with the network TLD. E.g. if you enter “privateapi.com”, it will become “privateapi.com.networkname”</p></li>
</ul>
</dd>
</dl>
</li>
</ol>
</div></blockquote>
<p>### Uninstalling Client
To uninstall the client from a network: <cite>sudo netclient -c remove -n &lt; networkname &gt;</cite>
To uninstall entirely, run the above for each network, and then run <cite>sudo rm -rf /etc/netclient</cite></p>
<p>### Uninstralling Netmaker
To uninstall the netmaker server, simply run <cite>docker-compose down</cite></p>
<p>#### LICENSE</p>
<p>Netmaker’s source code and all artifacts in this repository are freely available. All versions are published under the Server Side Public License (SSPL), version 1, which can be found here: [LICENSE.txt](./LICENSE.txt).</p>
<p>#### CONTACT</p>
<p>Email: <a class="reference external" href="mailto:alex%40gravitl.com">alex<span>@</span>gravitl<span>.</span>com</a>
Discord: <a class="reference external" href="https://discord.gg/zRb9Vfhk8A">https://discord.gg/zRb9Vfhk8A</a></p>
</article>
</div>
</div>
</main>
</div>
<footer class="md-footer">
<div class="md-footer-nav">
<nav class="md-footer-nav__inner md-grid">
<a href="index.html" title="Welcome to Netmaker’s documentation!"
class="md-flex md-footer-nav__link md-footer-nav__link--prev"
rel="prev">
<div class="md-flex__cell md-flex__cell--shrink">
<i class="md-icon md-icon--arrow-back md-footer-nav__button"></i>
</div>
<div class="md-flex__cell md-flex__cell--stretch md-footer-nav__title">
<span class="md-flex__ellipsis">
<span
class="md-footer-nav__direction"> Previous </span> Welcome to Netmaker’s documentation! </span>
</div>
</a>
</a>
</nav>
</div>
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-footer-copyright">
<div class="md-footer-copyright__highlight">
&#169; Copyright 2021, Alex Feiszli.
</div>
Created using
<a href="http://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
and
<a href="https://github.com/bashtage/sphinx-material/">Material for
Sphinx</a>
</div>
</div>
</div>
</footer>
<script src="_static/javascripts/application.js"></script>
<script>app.initialize({version: "1.0.4", url: {base: ".."}})</script>
</body>
</html>
Reference in a new issue View git blame Copy permalink