Skip to content

Commit

Permalink
Merge pull request #317 from gravitl/develop
Browse files Browse the repository at this point in the history
Develop
  • Loading branch information
abhishek9686 authored Jul 22, 2024
2 parents 8981a72 + 06c43c4 commit 3cc1c35
Show file tree
Hide file tree
Showing 27 changed files with 371 additions and 431 deletions.
39 changes: 0 additions & 39 deletions advanced-client-install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -75,35 +75,6 @@ Event id 0 in Windows Event logs
---------------------------------
netclient service is delegated to Winsw on Windows. An issue is reported that the stop/start/restart events in Event logs show event id as 0 always. It does not impact any netclient functions.

Notes on OpenWRT
===========================

Deploying on OpenWRT depends a lot on the version of OpenWRT and the hardware being used.

1. Ensure you download the appropriate binary for your architecture. replace ${VERSION} with the version you want to download

a. https://github.com/gravitl/netclient/releases/download/${VERSION}/netclient-linux-amd64
b. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-arm64
c. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-armv5
d. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-armv6
e. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-armv7
f. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mips-hardfloat
g. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mips-softfloat
h. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mipsle-hardfloat
i. https://github.com/gravitl/netclient/releases/download/v0.20.5/netclient-linux-mipsle-softfloat

2. run netclient install (note: all netclient commands must be run as root) will install the netclient binary to /usr/bin/netclient and service file to /etc/init.d/netclient

3. to start/stop the netclient daemon run

.. code-block::
/sbin/rc-service netclient start/stop
4. run other netclient commands (join, list, connect, disconnect, pull etc ) as required



Modes and System Compatibility
==================================

Expand Down Expand Up @@ -222,16 +193,6 @@ If the daemon is not running correctly, try restarting the daemon, or pulling ch
``sudo netclient pull``


Making Updates
----------------

``vim /etc/netclient/config/netconfig-<network>``

Change any of the variables in this file, and changes will be pushed to the server and processed locally on the next checkin.

For instance, change the private address, endpoint, or name. See above example config file for details


Adding/Removing Networks
---------------------------

Expand Down
2 changes: 0 additions & 2 deletions getting-started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ Getting Started
netclient
advanced-client-install
server-installation
oauth

Setup
=================
Expand Down Expand Up @@ -189,4 +188,3 @@ Uninstalling Netmaker
===========================

To uninstall Netmaker from the server, simply run ``docker-compose down`` or ``docker-compose down --volumes`` to remove the docker volumes for a future installation.

56 changes: 47 additions & 9 deletions install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,44 @@ Install
Choose the install method that makes sense for you.


Prerequisites
==================

Server
-----------------

All components of Netmaker can be run on a single server (Virtual Machine or Bare Metal). Here some recommendations for setting up the server:

- We **highly recommend** that Netmaker be deployed in a dedicated networking environment.
- The machine should have a public, static IP address
- The machine should have at least 1GB RAM and 1 CPU (2GB RAM preferred for production installs)
- 2GB+ of storage
- Ubuntu 24.04 Installed

If you do not have a host for this server, here are some recommendations:

- `DigitalOcean (preferred) <https://www.digitalocean.com>`_
- `Linode <https://www.linode.com>`_
- `KeepSec <https://www.keepsec.ca>`_
- `AWS <https://aws.amazon.com>`_
- `Azure <https://azure.microsoft.com>`_
- `GCP <https://cloud.google.com>`_
- We **do not** recommend Oracle Cloud. There are known issues with their network configuration.

Domain
--------

Your server will host several services (netmaker server, UI, etc.) each of which requires a dedicated, public subdomain. Here are some recommendations:

- Use a publicly owned domain (e.x. example.com, mysite.biz)
- Designate a subdomain (e.g. netmaker.example.com) for netmaker's services (e.g. dashboard.netmaker.example.com)
- Make sure you have permission and access to modify DNS records for your domain (e.x: Route53)
- **Note on Cloudflare:** Many of our users use Cloudflare. Cloudflare will proxy connections, which MQ does not like. This can be disabled in the Cloudflare DNS dashboard. If setting up your Netmaker server using Cloudflare for DNS, be aware that the configuration of Cloudflare proxy may cause problems with Netmaker which must be resolved, and at this point, Netmaker is not providing guidance on this setup.


Quick Install
==================

1. **We recommend using the nm-quick script for self-hosted/On-Prem setup.**

.. code-block::
Expand All @@ -17,6 +55,11 @@ Choose the install method that makes sense for you.

**IMPORTANT:** From v0.22.0 the install script will install PRO version of netmaker with a 14-day free trial, for you to try out full capabilities of netmaker.

Integrating OAuth
====================

Users are also allowed to join a Netmaker server via OAuth. They can do this by clicking the "Login with SSO" button on the dashboard's login page. Check out the :doc:`integrating oauth docs <./oauth>`.

After trial period ends:
=========================

Expand All @@ -29,16 +72,11 @@ After trial period ends:

i. Run `/root/nm-quick.sh -d`

2. **To get started the easiest way, visit our SaaS platform to set up a netmaker server with just a few clicks** `<https://app.netmaker.io>`_


3. :doc:`check out these steps for manual installation process for on-prem, although we don't recommend this path, instead use the install script mentioned above<./manual-install>`

4. :ref:`Kubernetes Installation <KubeInstall>`

5. :ref:`Non-Docker (from binary) Install <NoDocker>`
1. **To get started the easiest way, visit our SaaS platform to set up a netmaker server with just a few clicks** `<https://app.netmaker.io>`_

6. :ref:`Highly Available Installation <HAInstall>`
2. :doc:`check out these steps for manual installation process for on-prem, although we don't recommend this path, instead use the install script mentioned above<./manual-install>`

7. :doc:`Advanced Install Resources <./server-installation>`
3. :ref:`Highly Available Installation <HAInstall>`

4. :doc:`Advanced Install Resources <./server-installation>`
2 changes: 1 addition & 1 deletion license.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@
License
=======

Netmaker's source code and all artifacts in this repository are freely available. All versions are published under the Aache License, which can be found `here <https://raw.githubusercontent.com/gravitl/netmaker/master/LICENSE.md>`_.
Netmaker's source code and all artifacts are available in this GitHub Organization `Gravitl <https://github.com/gravitl>`_. All versions of netmaker are published under a License, which can be found `here <https://raw.githubusercontent.com/gravitl/netmaker/master/LICENSE.md>`_.

7 changes: 6 additions & 1 deletion manual-install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Server

All components of Netmaker can be run on a single server (Virtual Machine or Bare Metal). Here some recommendations for setting up the server:

- We **highly recommend** that Netmaker be deployed in a dedicated networking environment. It should not share a local network with the clients which it will be managing. This can cause routing issues.
- We **highly recommend** that Netmaker be deployed in a dedicated networking environment.
- The machine should have a public, static IP address
- The machine should have at least 1GB RAM and 1 CPU (2GB RAM preferred for production installs)
- 2GB+ of storage
Expand Down Expand Up @@ -267,6 +267,11 @@ Then run
ln -fs /root/netmaker.env /root/.env
Integrating OAuth
--------------------

Users are also allowed to join a Netmaker server via OAuth. They can do this by clicking the "Login with SSO" button on the dashboard's login page. Check out the :doc:`integrating oauth docs <./oauth>`.

6. Start Netmaker
==================

Expand Down
15 changes: 4 additions & 11 deletions netclient.rst
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,6 @@ Arch Distros (arch/manjaro/endeavouros)
yay -S netclient
OpenWRT Distros (mips/mipsle)
------------------------------------------------

.. code-block::
refer to Advanced Client Installation :ref:`advanced-client-install:Notes on OpenWRT`
OpenSUSE (tumbleweed/leap)
---------------------------------------------------------------------
Expand All @@ -99,7 +93,7 @@ Windows
Bundled Installer
-----------------

Download Link: https://fileserver.netmaker.org/latest/netclientbundle.exe
Download Link: https://fileserver.netmaker.org/releases/download/latest/netclientbundle.exe

Mac
============
Expand All @@ -113,14 +107,13 @@ Brew Install
(optional) brew audit netclient
brew install netclient
GUI Installer (for v0.22.0 and below)
Installer
-------------------------------------

Download Link for Apple silicon: https://fileserver.netmaker.org/releases/download/v0.22.0/Netclient-M1.pkg
Download Link for Apple silicon: https://fileserver.netmaker.org/releases/download/latest/Netclient-M1.pkg

Download Link for Apple Intel: https://fileserver.netmaker.org/releases/download/v0.22.0/Netclient-Intel.pkg
Download Link for Apple Intel: https://fileserver.netmaker.org/releases/download/latest/Netclient-Intel.pkg

Replace version number in URL with the version you want to install.


Docker
Expand Down
36 changes: 5 additions & 31 deletions oauth.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,11 +18,11 @@ Configuring your provider

In order to use OAuth, configure your OAuth provider (GitHub, Google, Azure AD).

You must configure your provider (except for Azure AD) to use the Netmaker Dashboard URI dashboard.<netmaker.base.domain> as the origin URL.
You must configure your provider (except for Azure AD) to use the Netmaker Dashboard URI: dashboard.<netmaker.base.domain> as the origin URL.

For example: `https://dashboard.netmaker.mydomain.com`

You must configure your provider to use the Netmaker API URI redirect route with the following format: https://api.<netmaker base domain>/api/oauth/callback.
You must configure your provider to use the Netmaker API URI redirect route with the following format: api.<netmaker base domain>/api/oauth/callback

For example: `https://api.netmaker.mydomain.com/api/oauth/callback`

Expand All @@ -48,46 +48,20 @@ Next, Configure Netmaker with the following environment variables. If any are le
SERVER_HTTP_HOST: "api.<netmaker base domain>"
FRONTEND_URL: "https://dashboard.<netmaker base domain>"
AZURE_TENANT: "<only for azure, you may optionally specify the tenant for the OAuth>"
OIDC_ISSUER: "<only for oidc, your issuer endpoint for OIDC ie. http://127.0.0.1:5556/dex"
OIDC_ISSUER: "<only for oidc, your issuer endpoint for OIDC> ie. http://127.0.0.1:5556/dex"
After restarting your server, the Netmaker logs will indicate if the OAuth provider was successfully initialized:

.. code-block::
sudo docker logs netmaker
Once successful, users can click the key symbol on the login page to sign-in with your configured OAuth provider.
Once successful, users can click on the "Login with SSO" button in the login page to sign-in with your configured OAuth provider.

.. image:: images/oauth1.jpg
:alt: Login Oauth
:align: center


Configuring User Permissions
===============================

User management is done through the Netmaker dashboard, under the Users (or Manage Account, for SaaS) section from the left navigation bar.
Only server admins have access to this section and can promote users to admin status. The superadmin/tenant owner can both promote and demote users to admin status.

.. image:: images/user-mgmt.png
:width: 80%
:alt: Users
:align: center

Normal users do not have access to the dashboard and are recommended to use our Remote Access Client to connect to the network.
An admin must aforehand grant such users permission to certain networks by assigning them to remote access gateways however. View the "Remote Access" section for more information on this.

User creation
-------------

To create a new user, click the "Add a User" button on the Users page. Fill in the user's details and click "Create User".

.. image:: images/oauth3.jpg
:alt: Edit User 2
:align: center

.. include_after_this_label
Oauth Users
-----------

Expand All @@ -98,5 +72,5 @@ Users are also allowed to join a Netmaker server via OAuth. They can do this by
:alt: Pending Users
:align: center

From v0.23.1, new accounts would be added to a pending list and would require approval from an admin before they can access any resource. This version also allows whielisting of email domains for OAuth users.
From v0.23.1, new accounts would be added to a pending list and would require approval from an admin before they can access any resource. This version also allows whitelisting of email domains for OAuth users.
Server admins can do that by adding a comma-separated list of domains to the `ALLOWED_EMAIL_DOMAINS` environment variable. eg: `ALLOWED_EMAIL_DOMAINS=example.net,example.com`
Binary file added pro/images/14-day-trial.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/billing-info-form.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/missed-profile-info.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/payment-method-form.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/pricing-and-limits.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/pro-aftersignup.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified pro/images/pro-aftersignup.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/pro-license-key2.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/pro-new-dashboard.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/profile-form-after-signup---sso.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/review-tenant-details-form.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/tenant-name-form.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added pro/images/tenants-list-page.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions pro/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Netmaker Professional

pro-setup
pro-users
../oauth
pro-relay-server
pro-metrics
pro-branding
Expand All @@ -31,6 +32,8 @@ Netmaker Professional is our advanced Netmaker offering for business use cases.

- **Users:** On community you can only create admin users, where as on PRO it gives ability to create non-admin users which you can pair with remote-access gateway to segment users on different networks.

- **OAuth:** By integrating with an OAuth provider, Netmaker users can log in via the provider, rather than the default simple auth.

- **Remote Access Client:** Netmaker Professional comes with a remote access client that allows you to connect to your network from anywhere. This is a great way to connect to your network from a laptop or mobile device (soon).

- **FailOvers:** FailOvers are made to help two peers communicate where they cannot talk directly due to their firewall restrictions, in which case their connection falls back through a failover node set by the user in the network.
Expand Down
Loading

0 comments on commit 3cc1c35

Please sign in to comment.