diff --git a/README.md b/README.md index 04f7d0ee..a553a05d 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@

- + diff --git a/compose/docker-compose.caddy.yml b/compose/docker-compose.caddy.yml index 1fcb9445..789de2d9 100644 --- a/compose/docker-compose.caddy.yml +++ b/compose/docker-compose.caddy.yml @@ -3,7 +3,7 @@ version: "3.4" services: netmaker: container_name: netmaker - image: gravitl/netmaker:v0.9.3 + image: gravitl/netmaker:v0.9.4 volumes: - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket - /run/systemd/system:/run/systemd/system diff --git a/compose/docker-compose.contained.yml b/compose/docker-compose.contained.yml index 5d36e2c4..e8124158 100644 --- a/compose/docker-compose.contained.yml +++ b/compose/docker-compose.contained.yml @@ -3,7 +3,7 @@ version: "3.4" services: netmaker: container_name: netmaker - image: gravitl/netmaker:v0.9.3 + image: gravitl/netmaker:v0.9.4 volumes: - dnsconfig:/root/config/dnsconfig - /usr/bin/wg:/usr/bin/wg diff --git a/compose/docker-compose.nodns.yml b/compose/docker-compose.nodns.yml index bde0977f..9a3ee3cf 100644 --- a/compose/docker-compose.nodns.yml +++ b/compose/docker-compose.nodns.yml @@ -3,7 +3,7 @@ version: "3.4" services: netmaker: container_name: netmaker - image: gravitl/netmaker:v0.9.3 + image: gravitl/netmaker:v0.9.4 volumes: - /usr/bin/wg:/usr/bin/wg - sqldata:/root/data diff --git a/compose/docker-compose.reference.yml b/compose/docker-compose.reference.yml index b6ecfa41..6cd3fb3b 100644 --- a/compose/docker-compose.reference.yml +++ b/compose/docker-compose.reference.yml @@ -11,7 +11,7 @@ services: container_name: netmaker depends_on: - rqlite - image: gravitl/netmaker:v0.9.3 + image: gravitl/netmaker:v0.9.4 volumes: # Volume mounts necessary for CLIENT_MODE to control wireguard networking on host (except dnsconfig, which is where dns config files are stored for use by CoreDNS) - dnsconfig:/root/config/dnsconfig # Netmaker writes Corefile to this location, which gets mounted by CoreDNS for DNS configuration. - /usr/bin/wg:/usr/bin/wg diff --git a/compose/docker-compose.yml b/compose/docker-compose.yml index 047a7671..413f0af3 100644 --- a/compose/docker-compose.yml +++ b/compose/docker-compose.yml @@ -3,7 +3,7 @@ version: "3.4" services: netmaker: container_name: netmaker - image: gravitl/netmaker:v0.9.3 + image: gravitl/netmaker:v0.9.4 volumes: - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket - /run/systemd/system:/run/systemd/system diff --git a/controllers/network.go b/controllers/network.go index 840c06c7..e3e84071 100644 --- a/controllers/network.go +++ b/controllers/network.go @@ -227,7 +227,7 @@ func createNetwork(w http.ResponseWriter, r *http.Request) { if servercfg.IsClientMode() != "off" { var success bool - success, err = serverctl.AddNetwork(network.NetID) + success, err = serverctl.AddNetwork(&network) if err != nil || !success { logic.DeleteNetwork(network.NetID) if err == nil { diff --git a/controllers/server.go b/controllers/server.go index fc94b41d..8735fadf 100644 --- a/controllers/server.go +++ b/controllers/server.go @@ -13,7 +13,7 @@ import ( ) func serverHandlers(r *mux.Router) { - r.HandleFunc("/api/server/addnetwork/{network}", securityCheckServer(true, http.HandlerFunc(addNetwork))).Methods("POST") + // r.HandleFunc("/api/server/addnetwork/{network}", securityCheckServer(true, http.HandlerFunc(addNetwork))).Methods("POST") r.HandleFunc("/api/server/getconfig", securityCheckServer(false, http.HandlerFunc(getConfig))).Methods("GET") r.HandleFunc("/api/server/removenetwork/{network}", securityCheckServer(true, http.HandlerFunc(removeNetwork))).Methods("DELETE") } @@ -91,19 +91,21 @@ func getConfig(w http.ResponseWriter, r *http.Request) { //w.WriteHeader(http.StatusOK) } -func addNetwork(w http.ResponseWriter, r *http.Request) { - // Set header - w.Header().Set("Content-Type", "application/json") +// func addNetwork(w http.ResponseWriter, r *http.Request) { +// // Set header +// w.Header().Set("Content-Type", "application/json") - // get params - var params = mux.Vars(r) +// // get params +// var params = mux.Vars(r) +// var networkName = params["network"] +// var networkSettings, err := logic.GetNetwork(netwnetworkName) - success, err := serverctl.AddNetwork(params["network"]) +// success, err := serverctl.AddNetwork(params["network"]) - if err != nil || !success { - json.NewEncoder(w).Encode("Could not add server to network " + params["network"]) - return - } +// if err != nil || !success { +// json.NewEncoder(w).Encode("Could not add server to network " + params["network"]) +// return +// } - json.NewEncoder(w).Encode("Server added to network " + params["network"]) -} +// json.NewEncoder(w).Encode("Server added to network " + params["network"]) +// } diff --git a/docker/Caddyfile b/docker/Caddyfile index 646a0e98..a43bf3e7 100644 --- a/docker/Caddyfile +++ b/docker/Caddyfile @@ -1,19 +1,33 @@ { - # LetsEncrypt account - email YOUR_EMAIL + # LetsEncrypt account + email YOUR_EMAIL } # Dashboard https://dashboard.NETMAKER_BASE_DOMAIN { - reverse_proxy http://127.0.0.1:8082 + # Apply basic security headers + header { + # Enable HTTP Strict Transport Security (HSTS) + Strict-Transport-Security "max-age=31536000;" + # Enable cross-site filter (XSS) and tell browser to block detected attacks + X-XSS-Protection "1; mode=block" + # Disallow the site to be rendered within a frame on a foreign domain (clickjacking protection) + X-Frame-Options "SAMEORIGIN" + # Prevent search engines from indexing + X-Robots-Tag "none" + # Remove the server name + -Server + } + + reverse_proxy http://127.0.0.1:8082 } # API https://api.NETMAKER_BASE_DOMAIN { - reverse_proxy http://127.0.0.1:8081 + reverse_proxy http://127.0.0.1:8081 } # gRPC https://grpc.NETMAKER_BASE_DOMAIN { - reverse_proxy h2c://127.0.0.1:50051 -} \ No newline at end of file + reverse_proxy h2c://127.0.0.1:50051 +} diff --git a/docker/Dockerfile-netclient-kernel b/docker/Dockerfile-netclient-kernel new file mode 100644 index 00000000..f562fb68 --- /dev/null +++ b/docker/Dockerfile-netclient-kernel @@ -0,0 +1,39 @@ +FROM debian:buster as builder +# add glib support daemon manager + +RUN apt update -y && apt install -y wget bash gcc musl-dev openssl golang git build-essential libmnl-dev iptables + +RUN wget -O go.tgz https://dl.google.com/go/go1.17.1.linux-amd64.tar.gz + +RUN tar -C /usr/local -xzf go.tgz + +WORKDIR /usr/local/go/src + +RUN chmod +x make.bash + +RUN ./make.bash + +ENV PATH="/usr/local/go/bin:$PATH" + +ENV GOPATH=/opt/go/ + +ENV PATH=$PATH:$GOPATH/bin + +WORKDIR /app + +COPY . . + +ENV GO111MODULE=auto + +RUN GOOS=linux GOARCH=amd64 CGO_ENABLED=0 /usr/local/go/bin/go build -ldflags="-w -s" -o netclient-app netclient/main.go + +FROM debian:buster + +WORKDIR /root/ + +RUN apt update -y && apt install -y bash curl wget traceroute procps dnsutils iptables openresolv iproute2 +COPY --from=builder /app/netclient-app ./netclient +COPY --from=builder /app/scripts/netclient.sh . +RUN chmod 0755 netclient && chmod 0755 netclient.sh + +ENTRYPOINT ["/bin/sh", "./netclient.sh"] diff --git a/docs/_build/doctrees/api.doctree b/docs/_build/doctrees/api.doctree index 634ad548..c8cec0f3 100644 Binary files a/docs/_build/doctrees/api.doctree and b/docs/_build/doctrees/api.doctree differ diff --git a/docs/_build/doctrees/architecture.doctree b/docs/_build/doctrees/architecture.doctree index 95215812..f19b177e 100644 Binary files a/docs/_build/doctrees/architecture.doctree and b/docs/_build/doctrees/architecture.doctree differ diff --git a/docs/_build/doctrees/client-installation.doctree b/docs/_build/doctrees/client-installation.doctree index 437bc4a1..f853a520 100644 Binary files a/docs/_build/doctrees/client-installation.doctree and b/docs/_build/doctrees/client-installation.doctree differ diff --git a/docs/_build/doctrees/egress-gateway.doctree b/docs/_build/doctrees/egress-gateway.doctree new file mode 100644 index 00000000..acba8c15 Binary files /dev/null and b/docs/_build/doctrees/egress-gateway.doctree differ diff --git a/docs/_build/doctrees/environment.pickle b/docs/_build/doctrees/environment.pickle index 91da36c1..2142dc41 100644 Binary files a/docs/_build/doctrees/environment.pickle and b/docs/_build/doctrees/environment.pickle differ diff --git a/docs/_build/doctrees/external-clients.doctree b/docs/_build/doctrees/external-clients.doctree index 1b5e7885..a2fc3604 100644 Binary files a/docs/_build/doctrees/external-clients.doctree and b/docs/_build/doctrees/external-clients.doctree differ diff --git a/docs/_build/doctrees/index.doctree b/docs/_build/doctrees/index.doctree index b7c4bf44..bd45a34e 100644 Binary files a/docs/_build/doctrees/index.doctree and b/docs/_build/doctrees/index.doctree differ diff --git a/docs/_build/doctrees/oauth.doctree b/docs/_build/doctrees/oauth.doctree index a82021b7..8df3380b 100644 Binary files a/docs/_build/doctrees/oauth.doctree and b/docs/_build/doctrees/oauth.doctree differ diff --git a/docs/_build/doctrees/relay-server.doctree b/docs/_build/doctrees/relay-server.doctree new file mode 100644 index 00000000..9b659a3c Binary files /dev/null and b/docs/_build/doctrees/relay-server.doctree differ diff --git a/docs/_build/doctrees/server-installation.doctree b/docs/_build/doctrees/server-installation.doctree index 15f32364..54d48949 100644 Binary files a/docs/_build/doctrees/server-installation.doctree and b/docs/_build/doctrees/server-installation.doctree differ diff --git a/docs/_build/doctrees/support.doctree b/docs/_build/doctrees/support.doctree index 5b93c530..5df82e86 100644 Binary files a/docs/_build/doctrees/support.doctree and b/docs/_build/doctrees/support.doctree differ diff --git a/docs/_build/doctrees/ui-reference.doctree b/docs/_build/doctrees/ui-reference.doctree new file mode 100644 index 00000000..fc9c6b41 Binary files /dev/null and b/docs/_build/doctrees/ui-reference.doctree differ diff --git a/docs/_build/doctrees/upgrades.doctree b/docs/_build/doctrees/upgrades.doctree new file mode 100644 index 00000000..10830c9e Binary files /dev/null and b/docs/_build/doctrees/upgrades.doctree differ diff --git a/docs/_build/doctrees/usage.doctree b/docs/_build/doctrees/usage.doctree index a32ce475..2c515f98 100644 Binary files a/docs/_build/doctrees/usage.doctree and b/docs/_build/doctrees/usage.doctree differ diff --git a/docs/_build/html/.buildinfo b/docs/_build/html/.buildinfo index 65439e79..857575e0 100644 --- a/docs/_build/html/.buildinfo +++ b/docs/_build/html/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: 7d73735f557dbf90d3004bb9dfde743b +config: cabfca75dd75f057ab5b5002a892c622 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/_build/html/_images/egress1.png b/docs/_build/html/_images/egress1.png new file mode 100644 index 00000000..e639629d Binary files /dev/null and b/docs/_build/html/_images/egress1.png differ diff --git a/docs/_build/html/_images/egress2.png b/docs/_build/html/_images/egress2.png new file mode 100644 index 00000000..74fb8ae0 Binary files /dev/null and b/docs/_build/html/_images/egress2.png differ diff --git a/docs/_build/html/_images/egress3.png b/docs/_build/html/_images/egress3.png new file mode 100644 index 00000000..b5e67d59 Binary files /dev/null and b/docs/_build/html/_images/egress3.png differ diff --git a/docs/_build/html/_images/egress4.png b/docs/_build/html/_images/egress4.png new file mode 100644 index 00000000..b5e67d59 Binary files /dev/null and b/docs/_build/html/_images/egress4.png differ diff --git a/docs/_build/html/_images/egress5.png b/docs/_build/html/_images/egress5.png new file mode 100644 index 00000000..3f8b4e60 Binary files /dev/null and b/docs/_build/html/_images/egress5.png differ diff --git a/docs/_build/html/_images/egress7.png b/docs/_build/html/_images/egress7.png new file mode 100644 index 00000000..f0f97c76 Binary files /dev/null and b/docs/_build/html/_images/egress7.png differ diff --git a/docs/_build/html/_images/ingress1.png b/docs/_build/html/_images/ingress1.png new file mode 100644 index 00000000..25b8919a Binary files /dev/null and b/docs/_build/html/_images/ingress1.png differ diff --git a/docs/_build/html/_images/relay1.png b/docs/_build/html/_images/relay1.png new file mode 100644 index 00000000..3810cdba Binary files /dev/null and b/docs/_build/html/_images/relay1.png differ diff --git a/docs/_build/html/_images/ui-1.jpg b/docs/_build/html/_images/ui-1.jpg new file mode 100644 index 00000000..1b599981 Binary files /dev/null and b/docs/_build/html/_images/ui-1.jpg differ diff --git a/docs/_build/html/_images/ui-10.jpg b/docs/_build/html/_images/ui-10.jpg new file mode 100644 index 00000000..6222d0a9 Binary files /dev/null and b/docs/_build/html/_images/ui-10.jpg differ diff --git a/docs/_build/html/_images/ui-11.jpg b/docs/_build/html/_images/ui-11.jpg new file mode 100644 index 00000000..994fc856 Binary files /dev/null and b/docs/_build/html/_images/ui-11.jpg differ diff --git a/docs/_build/html/_images/ui-2.jpg b/docs/_build/html/_images/ui-2.jpg new file mode 100644 index 00000000..9f8c5bfa Binary files /dev/null and b/docs/_build/html/_images/ui-2.jpg differ diff --git a/docs/_build/html/_images/ui-3.jpg b/docs/_build/html/_images/ui-3.jpg new file mode 100644 index 00000000..6f52dd0d Binary files /dev/null and b/docs/_build/html/_images/ui-3.jpg differ diff --git a/docs/_build/html/_images/ui-4.jpg b/docs/_build/html/_images/ui-4.jpg new file mode 100644 index 00000000..47d532bb Binary files /dev/null and b/docs/_build/html/_images/ui-4.jpg differ diff --git a/docs/_build/html/_images/ui-5.jpg b/docs/_build/html/_images/ui-5.jpg new file mode 100644 index 00000000..cfdc82e9 Binary files /dev/null and b/docs/_build/html/_images/ui-5.jpg differ diff --git a/docs/_build/html/_images/ui-6.jpg b/docs/_build/html/_images/ui-6.jpg new file mode 100644 index 00000000..850e525e Binary files /dev/null and b/docs/_build/html/_images/ui-6.jpg differ diff --git a/docs/_build/html/_images/ui-7.jpg b/docs/_build/html/_images/ui-7.jpg new file mode 100644 index 00000000..8f4ef726 Binary files /dev/null and b/docs/_build/html/_images/ui-7.jpg differ diff --git a/docs/_build/html/_images/ui-8.jpg b/docs/_build/html/_images/ui-8.jpg new file mode 100644 index 00000000..52487c9d Binary files /dev/null and b/docs/_build/html/_images/ui-8.jpg differ diff --git a/docs/_build/html/_sources/about.rst.txt b/docs/_build/html/_sources/about.rst.txt index eecfd1f3..fd6e0bd9 100644 --- a/docs/_build/html/_sources/about.rst.txt +++ b/docs/_build/html/_sources/about.rst.txt @@ -1,6 +1,6 @@ -=============== +========== About -=============== +========== What is Netmaker? ================== diff --git a/docs/_build/html/_sources/api.rst.txt b/docs/_build/html/_sources/api.rst.txt index 4231815e..f219890d 100644 --- a/docs/_build/html/_sources/api.rst.txt +++ b/docs/_build/html/_sources/api.rst.txt @@ -12,7 +12,7 @@ Authentication ============== API calls must be authenticated via a header of the format `-H "Authorization: Bearer "` There are two methods to obtain YOUR_SECRET_KEY: 1. Using the masterkey. By default, this value is "secret key," but you should change this on your instance and keep it secure. This value can be set via env var at startup or in a config file (config/environments/< env >.yaml). See the [general usage](./USAGE.md) documentation for more details. -2. Using a JWT recieved for a node. This can be retrieved by calling the `/api/nodes//authenticate` endpoint, as documented below. +2. Using a JWT received for a node. This can be retrieved by calling the `/api/nodes//authenticate` endpoint, as documented below. Format of Calls for Curl diff --git a/docs/_build/html/_sources/architecture.rst.txt b/docs/_build/html/_sources/architecture.rst.txt index e760597a..8b8f9bde 100644 --- a/docs/_build/html/_sources/architecture.rst.txt +++ b/docs/_build/html/_sources/architecture.rst.txt @@ -21,7 +21,7 @@ WireGuard WireGuard is a relatively new but very important technology which was recently added to the Linux kernel. WireGuard creates very fast but simple encrypted tunnels between devices. From the `WireGuard `_ website, "it might be regarded as the most secure, easiest to use, and simplest VPN solution in the industry." -Previous solutions like OpenVPN and IPSec are considerably more heavy and complex, while being less performant. All existing VPN tunnelling solutions will cause a significant increase in your network latency. WireGuard is the first to achieve near over-the-line network speeds, meaning you see no signigifant performance impact. With the release of WireGuard, there is little reason to use any other existing tunnel encryption technology. +Previous solutions like OpenVPN and IPSec are considerably more heavy and complex, while being less performant. All existing VPN tunneling solutions will cause a significant increase in your network latency. WireGuard is the first to achieve near over-the-line network speeds, meaning you see no significant performance impact. With the release of WireGuard, there is little reason to use any other existing tunnel encryption technology. Mesh Network ------------- @@ -56,7 +56,7 @@ Netmaker does a lot of work to set configurations for you, so that you don't hav Node ------ -A machine in a Netmaker network, which is managed by the Netclient, is referred to as a Node, as you will see in the UI. A Node can be a VM, a bare metal server, a desktop computer, an IoT device, or any other number of internet-connected machines on which the netclient is installed. A node is simply an endpoint in the network, which can send traffic to all the other nodes, and recieve traffic from all of the other nodes. +A machine in a Netmaker network, which is managed by the Netclient, is referred to as a Node, as you will see in the UI. A Node can be a VM, a bare metal server, a desktop computer, an IoT device, or any other number of internet-connected machines on which the netclient is installed. A node is simply an endpoint in the network, which can send traffic to all the other nodes, and receive traffic from all of the other nodes. SystemD ------- @@ -107,7 +107,7 @@ The check in process is what allows Netmaker to create dynamic mesh networks. As Database (sqlite, rqlite, postgres) ------------------------------------- -As of v0.8, Netmaker uses sqlite by default as a database. It can also use PostgreSQL, or rqlite, a distributed (RAFT consensus) databaseand. Netmaker interacts with this database to store and retrieve information about nodes, networks, and users. +As of v0.8, Netmaker uses sqlite by default as a database. It can also use PostgreSQL, or rqlite, a distributed (RAFT consensus) database. Netmaker interacts with this database to store and retrieve information about nodes, networks, and users. Additional database support (besides sqlite and rqlite) is very easy to implement for special use cases. Netmaker uses simple key value lookups to run the networks, and the database was designed to be extensible, so support for key-value stores and other SQL-based databases can be achieved by changing a single file. @@ -153,7 +153,7 @@ Below is a high level, step-by-step overview of the flow of communications withi 9. Netmaker server verifies information and creates the node, setting default values for any missing information. 10. Timestamp is set for the network (see #16). 11. Netmaker returns settings as response to netclient. Some settings may be added or modified based on the network. -12. Netclient recieves response. If successful, it takes any additional info returned from Netmaker and configures the local system/WireGuard +12. Netclient receives response. If successful, it takes any additional info returned from Netmaker and configures the local system/WireGuard 13. Netclient sends another request to Netmaker's GRPC server, this time to retrieve the peers list (all other clients in the network). 14. Netmaker sends back peers list, including current known configurations of all nodes in network. 15. Netclient configures WireGuard with this information. At this point, the node is fully configured as a part of the network and should be able to reach the other nodes via private address. diff --git a/docs/_build/html/_sources/client-installation.rst.txt b/docs/_build/html/_sources/client-installation.rst.txt index 772cd715..75bced67 100644 --- a/docs/_build/html/_sources/client-installation.rst.txt +++ b/docs/_build/html/_sources/client-installation.rst.txt @@ -1,6 +1,6 @@ -==================== -Client Installation -==================== +================================ +Advanced Client Installation +================================ This document tells you how to install the netclient on machines that will be a part of your Netmaker network, as well as non-compatible systems. diff --git a/docs/_build/html/_sources/egress-gateway.rst.txt b/docs/_build/html/_sources/egress-gateway.rst.txt new file mode 100644 index 00000000..3df2aa20 --- /dev/null +++ b/docs/_build/html/_sources/egress-gateway.rst.txt @@ -0,0 +1,96 @@ +===================================== +Egress Gateway +===================================== + +Introduction +=============== + +.. image:: images/egress1.png + :width: 80% + :alt: Gateway + :align: center + +Netmaker allows your clients to reach external networks via an Egress Gateway. The Egress Gateway is a netclient which has been deployed to a server or router with access to a given subnet. + +In the netmaker UI, that node is set as an "egress gateway." Range(s) are specified which this node has access to. Once created, all clients (and all new ext clients) in the network will be able to reach those ranges via the gateway. + +Configuring an Egress Gateway +================================== + +Configuring an Egress Gateway is very straight forward. As a prerequisite, you must know what you are trying to access remotely. For instance: + +- a VPC +- a Kubernetes network +- a home network +- an office network +- a data center + +After you have determined this, you must next deploy a netclient in a compatible location where the network is accessible. For instance, a Linux server or router in the office, or a Kubernetes worker node. This machine should be stable and relatively static (not expected to change its IP frequently or shut down unexpectedly). + +Next, you must determine which interface to use in order to reach the internal network. As an example, lets say there is a machine in the network at 10.10.10.2, and you have deployed the netclient on a different machine. You can run + +.. code-block:: + + ip route get 10.10.10.2 + +This should return the interface used to reach that address (e.x. "eth2") + +Finally, once you have determined the interface, the subnet, and deployed your netclient, you can go to your Netmaker UI and set the node as a gateway. + +.. image:: images/egress7.png + :width: 80% + :alt: Gateway + :align: center + +At this point simply insert the range(s) into the first field, and the interface name into the second field, and click "create". + +.. image:: images/ui-6.jpg + :width: 80% + :alt: Gateway + :align: center + +Netmaker will set iptables rules on the node, which will then implement these rules, allowing it to route traffic from the network to the specified range(s). + +Use Cases +============ + +1) Remote Access +------------------- + +A common scenario would be to combine this with an "Ingress Gateway" to create a simple method for accessing a home or office network. Such a setup would typically have only two nodes: the ingress and egress gateways. The Ingress Gateway should usually be globally accessible, which makes the Netmaker server itself a good candidate. This means you need only the netmaker server as the Ingress, and one additional machine (in the private network you wish to reach), as the Egress. + +.. image:: images/egress2.png + :width: 80% + :alt: Gateway + :align: center + +In some scenarios, a single node will act as both ingress and egress! For instance, you can enable acess to a VPC using your Netmaker server, deployed with a public IP. Traffic comes in over the public IP (encrypted of course) and then routes to the VPC subnet via the egress gateway. + +.. image:: images/egress3.png + :width: 50% + :alt: Gateway + :align: center + +2) VPN / NAT Gateway +----------------------- + +Most people think of a VPN as a remote server that keeps your internet traffic secure while you browse the web, or as a tool for accessing internet services in another country,using a VPN server based in that country. + +These are not typical use cases for Netmaker, but can be easily enabled. + +**The most important note is this: Do not use 0.0.0.0/0 as your egress gateway.** This is how you typically set up a "standard" VPN with WireGuard, however, it will not work with Netmaker. The Netclient specifically ignores gateways that overlap with local ranges (for efficiency ranges). 0.0.0.0 overlaps with everything, so it is always ignored. + +Instead, use the following list of ranges: + +.. code-block:: + + 0.0.0.0/5,8.0.0.0/7,11.0.0.0/8,12.0.0.0/6,16.0.0.0/4,32.0.0.0/3,64.0.0.0/2,128.0.0.0/3,160.0.0.0/5,168.0.0.0/6,172.0.0.0/12,172.32.0.0/11,172.64.0.0/10,172.128.0.0/9,173.0.0.0/8,174.0.0.0/7,176.0.0.0/4,192.0.0.0/9,192.128.0.0/11,192.160.0.0/13,192.169.0.0/16,192.170.0.0/15,192.172.0.0/14,192.176.0.0/12,192.192.0.0/10,193.0.0.0/8,194.0.0.0/7,196.0.0.0/6,200.0.0.0/5,208.0.0.0/4 + +This list encompasses the standard "public" network ranges, and ignores the standard "private" network ranges. + +Simply paste this list into your "egress gateway ranges" and your clients should begin routing public-facing traffic over the gateway. + +.. image:: images/egress5.png + :width: 50% + :alt: Gateway + :align: center diff --git a/docs/_build/html/_sources/external-clients.rst.txt b/docs/_build/html/_sources/external-clients.rst.txt index 0337c52a..aad6d456 100644 --- a/docs/_build/html/_sources/external-clients.rst.txt +++ b/docs/_build/html/_sources/external-clients.rst.txt @@ -1,10 +1,15 @@ -================ -External Clients -================ +===================================== +Ingress + External Clients +===================================== Introduction =============== +.. image:: images/ingress1.png + :width: 50% + :alt: Gateway + :align: center + Netmaker allows for "external clients" to reach into a network and access services via an Ingress Gateway. So what is an "external client"? An external client is any machine which cannot or should not be meshed. This can include: - Phones - Laptops diff --git a/docs/_build/html/_sources/index.rst.txt b/docs/_build/html/_sources/index.rst.txt index ec1607a8..9b8a5f55 100644 --- a/docs/_build/html/_sources/index.rst.txt +++ b/docs/_build/html/_sources/index.rst.txt @@ -23,68 +23,71 @@ Netmaker is a platform for creating and managing fast, secure, and dynamic virtu This documentation covers Netmaker's :doc:`installation <./server-installation>`, :doc:`usage <./usage>`, :doc:`troubleshooting <./support>`, and customization, as well as reference documents for the :doc:`API <./api>`, UI and Agent configuration. All of the `source code `_ for Netmaker is on GitHub. - -.. :raw-html:`
` - -.. .. raw:: html -.. :file: youtube-1.html +**For Kubernetes-specific guidance, please see the** `Netmaker Kubernetes Documentation. `_ About ------- -A quick overview of Netmaker, explaining what it is, how it works, and why you should be using it. +-------- + +High-level information about what Netmaker is and how it works. .. toctree:: :maxdepth: 2 - + about - -Architecture ---------------- - -A technical overview of Netmaker, including design decisions and limitations. - -.. toctree:: - :maxdepth: 2 architecture -Install +Getting Started ------------------------------------ -Choose the right install method for you. +How to install Netmaker and set up your first network. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 install -Quick Start ---------------- - -A quick start guide to getting up and running with Netmaker and WireGuard as quickly as possible. - -.. toctree:: - :maxdepth: 2 - quick-start -.. toctree:: - :maxdepth: 2 - getting-started -Quick Start Nginx (depreciated) ------------------------------------- +Ingress, Egress, and Relays +------------------------------ -An older guide to getting up and running with Netmaker using Nginx as quickly as possible. +How to give machines outside of the Netmaker network access to network resources via an Ingress Gateway: .. toctree:: - :maxdepth: 1 + :maxdepth: 2 + + external-clients - quick-start-nginx +How to give machines inside the Netmaker network access to external network resources via an Egress Gateway: -Server Installation --------------------- + +.. toctree:: + :maxdepth: 2 + + egress-gateway + +How to make machines inside the network reachable if they are blocked by NAT/Firewall: + +.. toctree:: + :maxdepth: 2 + + relay-server + +Kubernetes Documentation +--------------------------- + +.. toctree:: + + Kubernetes + +`Netmaker Kubernetes Documentation `_ + + +Advanced Server Installation +------------------------------- A detailed guide to installing the Netmaker server (API, DB, UI, DNS), and configuration options. @@ -93,6 +96,17 @@ A detailed guide to installing the Netmaker server (API, DB, UI, DNS), and confi server-installation +Advanced Client Installation +-------------------------------- + +A detailed guide to installing the Netmaker agent (netclient) on devices and configuration options. + +.. toctree:: + :maxdepth: 2 + + client-installation + + Oauth Configuration -------------------- @@ -104,27 +118,7 @@ A simple guide to configuring OAuth for Netmaker. oauth -Client Installation --------------------- - -A detailed guide to installing the Netmaker agent (netclient) on devices and configuration options. - -.. toctree:: - :maxdepth: 2 - - client-installation - -External Clients --------------------- - -A detailed guide to give clients outside of the Netmaker network access to network resources. - -.. toctree:: - :maxdepth: 2 - - external-clients - -Guides +External Guides ---------------- A handful of guides for use cases including site-to-site, Kubernetes, private DNS, and more. @@ -134,18 +128,37 @@ A handful of guides for use cases including site-to-site, Kubernetes, private DN usage +UI Reference +--------------- + +A reference document for the Netmaker Server UI, with annotated screenshot detailing each field. + +.. toctree:: + :maxdepth: 2 + + ui-reference + API Reference --------------- A reference document for the Netmaker Server API, and example API calls for various use cases. -**Coming Soon:** Swagger Documentation - .. toctree:: :maxdepth: 1 api +Upgrades +---------------- + +Upgrading the Netmaker server and clients. + +.. toctree:: + :maxdepth: 1 + + upgrades + + Troubleshooting ---------------- diff --git a/docs/_build/html/_sources/oauth.rst.txt b/docs/_build/html/_sources/oauth.rst.txt index 9b094b70..2af20f55 100644 --- a/docs/_build/html/_sources/oauth.rst.txt +++ b/docs/_build/html/_sources/oauth.rst.txt @@ -35,7 +35,7 @@ Instructions for Microsoft Azure AD: https://oauth2-proxy.github.io/oauth2-proxy Configuring Netmaker ====================== -After you have configured your OAuth provider, take note of the CLIENT_ID and CLIENT_SECRET. +After you have configured your OAuth provider, take note of the CLIENT_ID and CLIENT_SECRET. If you are using Azure for oauth, you may also want to note down the Azure tenant ID you wish to use. Next, Configure Netmaker with the following environment variables. If any are left blank, OAuth will fail. @@ -46,7 +46,7 @@ Next, Configure Netmaker with the following environment variables. If any are le CLIENT_SECRET: "" SERVER_HTTP_HOST: "api." FRONTEND_URL: "https://dashboard." - + AZURE_TENANT: "" After restarting your server, the Netmaker logs will indicate if the OAuth provider was successfully initialized: diff --git a/docs/_build/html/_sources/relay-server.rst.txt b/docs/_build/html/_sources/relay-server.rst.txt new file mode 100644 index 00000000..1364fa64 --- /dev/null +++ b/docs/_build/html/_sources/relay-server.rst.txt @@ -0,0 +1,36 @@ +===================================== +Relay Servers +===================================== + +Introduction +=============== + +.. image:: images/relay1.png + :width: 80% + :alt: Relay + :align: center + +Sometimes nodes are in hard-to-reach places. Typically this will be due to a CGNAT, Double NAT, or restrictive firewall. In such scenarios, a direct peer-to-peer connection with all other nodes might be impossible. + +For this reason, Netmaker has a Relay Server functionality. At any time you may designate a publicly reachable node (such as the Netmaker Server) as a Relay, and tell it which machines it should relay. Then, all traffic routing to and from that machine will go through the relay. This allows you to circumvent the above issues and ensure connectivity when direct measures do not work. + +Configuring a Relay +================================== + +To create a relay, you can use any node in your network, but it should have a public IP address (not behind a NAT). Your Netmaker server can be a relay server and makes for a good default choice if you are unsure of which node to select. + +Simply click the relay button in the nodes list. Then, specify the nodes which it should relay. You can either enter the IP's directly, select from a list, or click "Select All." + +.. image:: images/ui-7.jpg + :width: 80% + :alt: Relay + :align: center + +If you choose "select all" this essentially turns your network into a hub-and-spoke network. All traffic now routes over the relay node. This can create a bottleneck and slow down your network, but in some scenarios may simplify network operations. + +After creation, you can change the list of relayed nodes by clicking "edit node" and editing the list (Field #12 below). + +.. image:: images/ui-5.jpg + :width: 40% + :alt: Relay + :align: center diff --git a/docs/_build/html/_sources/support.rst.txt b/docs/_build/html/_sources/support.rst.txt index d1c2329f..2054aac6 100644 --- a/docs/_build/html/_sources/support.rst.txt +++ b/docs/_build/html/_sources/support.rst.txt @@ -5,25 +5,10 @@ Support FAQ ====== -Does/Will Netmaker Support X Operating System? --------------------------------------------------- - -Netmaker is initially available on a limited number of operating systems for good reason: Every operating system is designed differently. With a small team, we can either focus on making Netmaker do a lot on a few number of operating systems, or a little on a bunch of operating systems. We chose the first option. You can view the System Compatibility docs for more info, but in general, you should only be using Netmaker on systemd linux right now. - -However, via "external clients", any device that supports WireGuard can be added to the network. - -In future iterations will expand the operating system support for Netclient, and devices that must use the "external client" feature can switch to Netclient. - -How do I install the Netclient on X? ---------------------------------------- - -As per the above, there are many unsupported operating systems. You are still welcome to try, it is just an executable binary file after all. If the system is unix-based and has kernel WireGuard installed, netclient may very well mesh the device into the network. However, the service likely will encounter problems retrieving updates. - - Is Netmaker a VPN like NordNPN? -------------------------------- -No. Netmaker makes Virtual Networks, which are technically VPNs, but different. It's more like a corporate VPN, or a VPC (if you're familiar with AWS). +No. Netmaker makes Virtual Networks, which are technically VPNs, but different. It's more like a corporate VPN, or a VPC (if you're familiar with AWS). Netmaker is often compared to OpenVPN, Tailscale, or Nebula. If you're looking to achieve self-hosted web browsing, with functionality similar to NordVPN, ExpressVPN, Surfshark, Tunnelbear, or Private Internet Access, this is probably not the project for you. Technically, you can accomplish this with Netmaker, but it would be a little like using a all-terrain vehicle for stock car racing. @@ -34,23 +19,25 @@ https://github.com/pivpn/pivpn https://github.com/subspacecloud/subspace https://github.com/mullvad/mullvadvpn-app -Do you offer any enterprise support? --------------------------------------- +Do you have an 'Exit Nodes' feature? +--------------------------------------- -If you are interested in enterprise support for your project, please contact info@gravitl.com. +Please see the :doc:`Egress Gateway <./egress-gateway>` documentation. + +Do you offer any business or enterprise support? +--------------------------------------------------- + +Yes, please contact info@gravitl.com or visit https://gravitl.com/plans. Why the SSPL License? ---------------------- -We thought long and hard about the license. Ultimately, we think this is the best way to support and ensure the health of the project long term. The community deserves something that is well-maintained, and in order to do that, eventually we need some financial support. We won't do that by limiting the project, but we will offer some additional support, and hosted options for things people would end up paying for anyway (relay servers, load balancing support, backups). +As of now, we think the SSPL is the best way to ensure the long-term viability of the project, but we are regularly evaluating this to see if an OSI-approved license makes more sense. -While SSPL is not an OSI-approved open source license, it let's people generally run the project however they want, both for private use and business use, without running into the issue of someone else monetizing the project and making it financially untenable. We are working on making the guidelines clear, and will make sure that the license does not impact the communities ability to use and modify the project. - -If you have concerns about the license leading to project restrictions down the road, just know that there are other paid, closed-source/closed-core options out there, so beyond not wanting to follow that path, we also don't think it's a good idea economically either. We firmly believe that having the project open is not only right, but the best option. - -All that said, we will re-evaluate the license on a regular basis and determine if an OSI-approved license makes more sense. It's just easier to move from SSPL to another license than vice-versa. +We believe the SSPL lets most people run the project the way they want, for both for private use and business use, while giving us a path to maintain viability. We are working to make sure the guidelines clear, and do not want the license to impact the community's ability to use and modify the project. +If you believe the SSPL will negatively impact your ability to use the project, please do not hesitate to reach out. Contact =========== diff --git a/docs/_build/html/_sources/ui-reference.rst.txt b/docs/_build/html/_sources/ui-reference.rst.txt new file mode 100644 index 00000000..d241cbce --- /dev/null +++ b/docs/_build/html/_sources/ui-reference.rst.txt @@ -0,0 +1,184 @@ +================= +UI Reference +================= + +This page contains annotated screenshots of most UI components, detailing the configuration options of each field across Nodes, Networks, DNS, Ext Clients, Users, and more. + +Dashboard +================= + +.. image:: images/ui-1.jpg + :width: 80% + :alt: dashboard + :align: center + +Networks +================= + +Create +-------- + +.. image:: images/ui-2.jpg + :width: 80% + :alt: create network + :align: center + +.. code-block:: + +(1) **Autofill:** Provides sensible defaults for network details and makes up a name. +(2) **Network Name:** The name of the network. Character limited, as this translates to the interface name on hosts (nm-) +(3) **Address Range:** The CIDR of the network. Must be a valid IPv4 Subnet and should be a private address range. +(4) **Udp Hole Punching:** Enables or disables "UDP Hole Punching" on the network. When on, clients will first reach out to the server. The server will keep track of public addresses / ports and send these to all other clients in the network. This increases NAT traversibility, but can also cause issues depending on the server environment (if server is in a private network, for example). Typically good to enable if clients will "roam" frequently or are user devices. Typically better to disable if most clients will be servers with well-defined endpoints / ports. If enabled, you can also disable UDP Hole Punching on any individual machine via the UI (see Node section) but it will be enabled by default. +(5) **Is Local Network:** Turn on if all clients in the network will be in the same "local" network. This is a very rare situation and depends on the use case. Almost always leave this off. Turn on if you are in a large data center with a large private address space over which clients should communicate. Can also enable if using a VPC and are treating a single client as "egress" for the VPC. If enabled, fill out the address range of the local network which should determine endpoints. +(6) **Is Dual Stack:** Turn on to add private ipv6 addresses to all clients in addition to their ipv4 addresses. Not typically necessary. If on, enter a private ipv6 address range to pull from. + +Edit +-------- + +.. image:: images/ui-3.jpg + :width: 80% + :alt: edit network + :align: center + +**NOTE:** With the exception of Address Ranges (1-2) any setting that affects nodes will not take effect on existing nodes. It will only set the settings on any **new** node, after the setting has been changed. + +(1) **Address Range (ipv4):** The ipv4 private network CIDR. If edited, Netmaker will go through all nodes and update private addresses based on the new range.** +(2) **Address Range (ipv6):** The ipv6 private network CIDR. If edited, Netmaker will go through all nodes and update private addresses based on the new range.** +(3) **Local Range:** Only relevant if "Is Local" was switched on during creation. Specifies the local range that nodes will base their Endpoint off of (note: if a node cannot find an enpoint within the range it will fallback to public ip). +(4) **Display Name:** The display name of the network. Network Name cannot be changed (acts as a unique ID) but display name can be changed. Only effects appearance in UI. +(5) **Default Interface:** The default network interface name configured on each node. This defaults to "nm-". +(6) **Default Port:** The default WireGuard port each node will attempt to use. Nodes will iterate up from this port until they find a free port. +(7) **Default PostUp:** A default post-up command to run on each node (after interface has been configured). Disabled by default to prevent RCE vulnerabilities. +(8) **Default PostDown:** A default post-down command to run on each node (after interface has been removed). Disabled by default to prevent RCE vulnerabilities. +(9) **Default Keepalive:** How often nodes should send packets to keep connection alive with all peers (in seconds). +(10) **Default Ext Client DNS:** If set, adds a "DNS=" line to each ext client config. Set this to add DNS to clients. Typically will set this to the server's public IP. +(11) **Default MTU:** Default MTU for interfaces of all clients in network. Can be useful to set lower in certain difficult environments such as Kubernetes. +(12) **Allow Node Signup Without Keys:** Allows nodes to join the network without a valid Access Key. Nodes will be put in "pending" status until approved via UI by an admin. Useful if an arbitrary number of people need to join the network and there is no easy way to distribute keys to users. +(13) **Is Dual Stack:** Enable the Dual Stack feature of networks and add ipv6 addresses to nodes. +(14) **Default Saveconfig:** Typically ignore this. Sets the SaveConfig field on wireguard config. +(15) **UDP Hole Punching:** Whether or not UDP Hole Punching is turned on (see Network Create notes). Only effects new nodes. Enables or disables "UDP Hole Punching" on the network. When on, clients will first reach out to the server. The server will keep track of public addresses / ports and send these to all other clients in the network. This increases NAT traversibility, but can also cause issues depending on the server environment (if server is in a private network, for example). Typically good to enable if clients will "roam" frequently or are user devices. Typically better to disable if most clients will be servers with well-defined endpoints / ports. If enabled, you can also disable UDP Hole Punching on any individual machine via the UI (see Node section) but it will be enabled by default. + +Nodes +======== + +Node List +------------- + +.. image:: images/ui-4.jpg + :width: 80% + :alt: dashboard + :align: center + +(1) **Search Nodes:** Look up a node by name. +(2) **Select Network:** Filter nodes by network. +(3) **Node Name:** Name of node. By default set to hostname of machine. +(4) **IP Address:** Private IP of node within network. +(5) **Network:** Network the node is in. +(6) **Egress:** Indicates if node is an egress gateway. Click to convert into egress gateway. Egress gateways route traffic from the network into a specific subnet or subnets. Egress gateways should be servers in a static location with a reliable IP. +(7) **Ingress:** Indicates if the node is an ingress. Click to convert into ingress gateway. Ingress gateways route traffic into the network over the WireGuard interface using "ext clients," which are static WireGuard config files. Ingress gateways should be servers in a static location with a reliable IP. +(8) **Relay:** Indicates if the node is a relay. Click to convert into relay. Relays route traffic to specified nodes for the network (typically hard to reach / CGNAT'ted nodes. Relays should be servers in a static location with a reliable IP. +(9) **Status:** Indicates how recently the node checked into the server. Displays "Warning" after 5 minutes and "Error" after 30 minutes without a check in. Does **not** indicate the health of the node's virtual network connections. +(10) **Delete:** Delete the node. + +Create Egress +--------------- + +.. image:: images/ui-6.jpg + :width: 80% + :alt: dashboard + :align: center + +(1) **Egress Gateway Ranges:** A comma-separated list of the subnets for which the gateway will route traffic. For instance, with Kubernetes this could be both the Service Network and Pod Network. For a standard VPN, Netmaker can use a list of the public CIDR's (see the docs). Typically, this will be something like a data center network, VPC, or home network. +(2) **Interface:** The interface on the machine used to access the provided egress gateway ranges. For instance, on a typical linux machine, the interface for public traffic would be "eth0". Usually you will need to check on the machine first to find the right interface. For instance, on Linux, you can find the interface by running this: ip route get

. + + +Create Relay +------------- + +.. image:: images/ui-7.jpg + :width: 80% + :alt: dashboard + :align: center + +(1) **Relay Addresses:** Specify which private addresses (of nodes) that this node should relay for. +(2) **Select Nodes:** Rather than specify by IP, you can just select from a list of node names instead. +(3) **Select All:** Rather than select a list, you can "select all", which converts the network from "pure mesh" into "hub-and-spoke", meaning there are no p2p connections, everything goes through this relay first. + +Edit Node / Node Details +-------------------------- + +.. image:: images/ui-5.jpg + :width: 80% + :alt: dashboard + :align: center + +(1) **IP Address:** The primary private IP address of the node. Assigned automatically by Netmaker but can be changed to whatever you want within the Network CIDR. +(2) **IPv6 Address:** (Only if running dual stack) the primary private IPv6 address of the node. Assigned automatically by Netmaker but can be changed to whatever you want within the Network CIDR. +(3) **Local Address:** The "locally reachable" address of the node. Other nodes will take note of this to see if this node is on the same network. If so, they will use this address instead of the public "Endpoint." If running a few nodes inside of a VPC, home network, or similar, make sure the local address is populated correctly for faster and more secure inter-node communication. +(4) **Node Name:** The name of the node within the network. Hostname by default but can be anything (within the character limits). +(5) **Port:** The port used by the node locally. **This value is ignored if UDP Hole Punching is on,** because port is set dynamically every time interface is created. If UDP Hole Punching is off, the port can be set to any reasonable (and available) value you'd like for the local machine. Typi +(6) **Public Key:** (Uneditable) The public key of the node, distributed to other peers in the network. +(7) **Endpoint:** The (typically public) IP of the machine, which peers will use to reach it, in combination with the port. If changing this value, make sure Roaming is turned off, since otherwise, the node will check to see if there is a change in the public IP regularly and update it. +(8) **PostUp:** Uneditable by default to disable RCE. Commands to run after the interface is created. If an ingress or egress gateway are created, this field will populate automatically with appropriate iptables commands. +(9) **PostDown:** Uneditable by default to disable RCE. Commands to run after the interface is brought down. If an ingress or egress gateway are created, this field will populate automatically with appropriate iptables commands. +(10) **Allowed IPs:** Additional private addresses given to the node (in addition to the IPAddress and IPv6Address). Useful in some scenarios where there is a known address a server should have. Any IPs added here will be tacked onto the AllowedIPs of other peers, so this node will be shown to have multiple reachable private addresses. +(11) **Persistent Keepalive:** How often packets are sent to keep connections open with other peers. +(12) **Relay Addresses:** If "Relay" is enabled on this node, this field can be edited to add and remove nodes from the relay. So if you are currently relaying just one node but wish to relay an additional node, just add it's private IP here. +(13) **Node Expiration Datetime:** If a node should become invalid after a length of time, you can set it in this field, after which time, it will lose access to the network and will not populate to other nodes. Useful for scenarios where temporary access is granted to 3rd parties. +(14) **Last Checkin:** Unix timestamp of the last time the node checked in with the server. Used to determine generic health of node. +(15) **Mac Address:** The hardware mac address of the machine. Used to be used as the unique ID, but is being depreciated. +(16) **Network:** The network this 1node belongs to. +(17) **Egress Gateway Ranges:** If Egress is enabled, the gateway ranges that this machine routes to. +(18) **Local Range:** If IsLocal has been enabled on the network, this is the local range in which the node will look for a private address from it's local interfaces, to use as an endpoint. +(19) **Node Operating System:** The OS of the machine. +(20) **MTU:** The MTU that the node will use on the interface. If "wg show" displays a valid handshake but pings are not working, many times the issue is MTU. Making this value lower can solve this issue. Some typical values are 1024, 1280, and 1420. +(21) **Saveconfig:** Usually best to ignore this. Sets the "SaveConfig" value on wireguard config files. +(22) **Is Static:** Ports and Endpoints can be changed automatically by the netclient. Switching on "Is Static" means the port and endpoint will stay the same until you change it. This can be good to set if the machine is a server sitting in a location that is not expected to change. It is also good to have Is Static switched on for Ingress, Egress, and Relay Servers, since they should be in a reliable location. +(23) **UDP Hole Punching:** If on, the node's port will be randomized. The port and endpoint distributed to other nodes are no longer determined by the settings in this file. Instead, the node will "check in" with the server regularly. The server will track the IP and port used to open a connection, and store these values. These values then get distributed to nodes. This is helpful for getting around NAT's which may obscure the node's location. +(24) **Is DNS On:** DNS is solely handled by resolvectl at the moment, which is on many Linux distributions. For anything else, this value should remain off. If you wish to configure DNS for non-compatible systems, you must do so manually. +(25) **Dualstack:** Whether or not this machine should have both a private ipv4 address and ipv6 address. +(26) **Is Local:** If on, will only communicate over the local address (Assumes IsLocal tuned to 'yes' on the network level.) +(27) **Roaming:** If on, will check regularly for changes in the Endpoint and modify the Endpoint value appropriately. This allows a client to "roam" between wifi networks and maintain a connection. Good to keep on for machines where the public address may change. +(28) **IPforwarding:** If on, ipforwarding is enabled on the machine. Should almost always be kept on. + +Ext Clients +================ + +.. image:: images/ui-8.jpg + :width: 80% + :alt: dashboard + :align: center + +(1) **Gateway Name / IP Address:** Information about which Node is the Ingress Gateway. +(2) **Add External Client:** Button to generate a new ext client. +(3) **Client ID:** The randomly-generated name of the client. Click on the ID to change the name to something sensible. +(4) **IP Address:** The private ip address of the ext client. +(5) **QR Code:** If joining form iOS or Android, open the WireGuard app and scan the QR code to join the network. +(6) **Download Client Configuration:** If joining from a laptop/desktop, download the config file and run "wg-quick up /path/to/config" +(7) **Delete:** Delete the ext client and remove its network access. + +DNS +=========== + +.. image:: images/ui-10.jpg + :width: 80% + :alt: dashboard + :align: center + +(1) **DNS Name:** The private DNS entry. Must end in "." (added automatically). This avoids conflicts between networks. +(2) **IP Address:** The IP address of the entry. Can be anything (public addresses too!) but typically a node IP. +(3) **Select Node Address:** Select a node name to populate its IP address automatically. + +Create / Edit Users +===================== + +.. image:: images/ui-11.jpg + :width: 80% + :alt: dashboard + :align: center + +(1) **Username:** Specify Username. +(2) **Password:** Specify password. +(3) **Confirm Password:** Confirm password. +(4) **Make Admin:** Make into a server admin or "super admin", which has access to all networks and server-level settings. +(5) **Networks:** If not made into an "admin", select the networks which this user has access to. The user will be a "network admin" of these networks, but other networks will be invisible/unaccessible. diff --git a/docs/_build/html/_sources/upgrades.rst.txt b/docs/_build/html/_sources/upgrades.rst.txt new file mode 100644 index 00000000..d01cff51 --- /dev/null +++ b/docs/_build/html/_sources/upgrades.rst.txt @@ -0,0 +1,40 @@ +===================================== +Upgrades +===================================== + +Introduction +=============== + +As of 0.9.4, upgrading Netmaker is a manual process. This is expected to be automated in the future, but for now is still a relatively straightforward process. + +Upgrade the Server (netmaker) +================================== + +To upgrade the server, you only need to change the docker image versions: + +1. `ssh root@my-server-ip` +2. `docker compose down` +3. `vi docker-compose.yml` +4. Change gravitl/netmaker: and gravitl/netmaker-ui: to the new version. +5. Save and close the file +6. `docker-compose up -d` + +Upgrade the Clients (netclient) +================================== + +To upgrade the client, you must get the new client binary and place it in /etc/netclient. Depending on the new vs. old version, there may be minor incompatibilities (discussed below). + +1. Vists https://github.com/gravitl/netmaker/releases/ +2. Find the appropriate binary for your machine. +3. Download. E.x.: `wget https://github.com/gravitl/netmaker/releases/download/vX.X.X/netclient-myversion` +4. Rename binary to `netclient` and move to folder. E.x.: `mv netclient-myversion /etc/netclient/netclient` +5. `netclient --version` (confirm it's the correct version) +6. `netclient pull` + +This last step helps ensure any newly added fields are now present. You may run into a "panic" based on missing fields and your version mismatch. In such cases, you can either: + +1. Add the missing field to /etc/netclient/config/netconfig-yournetwork and then run "netclient checkin" + +or + +2. Leave and rejoin the network \ No newline at end of file diff --git a/docs/_build/html/_sources/usage.rst.txt b/docs/_build/html/_sources/usage.rst.txt index 7abdfca8..a81e4e0c 100644 --- a/docs/_build/html/_sources/usage.rst.txt +++ b/docs/_build/html/_sources/usage.rst.txt @@ -1,16 +1,12 @@ -============== -Using Netmaker -============== +================= +External Guides +================= -Netmaker has many different use cases, from a basic virtual network to an office gateway VPN to a Kubernetes underlay. It can be a bit overwhelming to figure out where to start. If you don't find your use case here, but think Netmaker is a good fit, let us know! - -External Tutorials -================== - -Members of the community have created helpful tutorials for getting started with Netmaker. Below are some selected tutorials on different topics. +Netmaker has many use cases, from a basic virtual network to an office gateway VPN to a Kubernetes underlay. It can be a bit overwhelming to figure out where to start. If you don't find your use case here, but think Netmaker is a good fit, let us know! Video Tutorials ---------------- +================== + * `Intro/Overview `_: Tutorial on first-time usage, setting up a mesh network. * `Site-to-Site Gateway `_: Tutorial on setting up site-to-site connections, allowing peers to access external networks via gateways. * `IPv6 and Private DNS `_: Tutorial on dual-stack IPv6 in Netmaker and Private DNS management (separate topics). @@ -18,7 +14,8 @@ Video Tutorials Written Tutorials ------------------ +================== + * `K3s Cross-cloud cluster `_: Tutorial on setting up cross-cloud K3s clusters using Netmaker. * `MicroK8s Cross-cloud cluster `_: Tutorial on setting up cross-cloud MicroK8s clusters using Netmaker. * `Secure access to private services `_: Tutorial on setting up secure Nextcloud with Netmaker. \ No newline at end of file diff --git a/docs/_build/html/_static/documentation_options.js b/docs/_build/html/_static/documentation_options.js index a3a901a7..2fd011ef 100644 --- a/docs/_build/html/_static/documentation_options.js +++ b/docs/_build/html/_static/documentation_options.js @@ -1,6 +1,6 @@ var DOCUMENTATION_OPTIONS = { URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), - VERSION: '0.9.0', + VERSION: '0.9.4', LANGUAGE: 'None', COLLAPSE_INDEX: false, BUILDER: 'html', diff --git a/docs/_build/html/about.html b/docs/_build/html/about.html index 3cf6607f..cbe7d207 100644 --- a/docs/_build/html/about.html +++ b/docs/_build/html/about.html @@ -46,7 +46,7 @@ - About — Netmaker 0.9.0 documentation + About — Netmaker 0.9.4 documentation @@ -81,7 +81,7 @@