mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-22 10:26:36 +00:00
Getting Started Rewrite (#393)
This commit is contained in:
Brandon Hopkins
@@ -4,122 +4,188 @@ export const title = 'Getting Started'
|
||||
|
||||
## Quickstart Guide
|
||||
|
||||
Welcome to NetBird! This guide will walk you through our new onboarding process to create your account, connect your first devices,
|
||||
and build a secure peer-to-peer overlay network in less than ten minutes.
|
||||
|
||||
<div className="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/JRCZy4rLi-c" allow="fullscreen;"></iframe>
|
||||
<iframe src="https://www.youtube.com/embed/dr0u-u9uD84" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
|
||||
This guide describes how to quickly get started with NetBird and create a secure private network with two connected machines.
|
||||
For this tutorial we will use a Macbook and an EC2 node running Linux on AWS.
|
||||
## Create Your Account
|
||||
|
||||
## Install NetBird client
|
||||
First, let's create your NetBird account.
|
||||
|
||||
The NetBird client works on almost any platform, including Windows, macOS, Linux, iOS, Android, Docker, routers, and even serverless environments.
|
||||
To get started, install NetBird on your laptop by following the instructions on the [installation page](https://app.netbird.io/install):
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/add-peer.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/mac-installation.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
1. Navigate to [netbird.io](https://netbird.io/) and click Get Started in the top-right corner. Or simply click [here](https://app.netbird.io/).
|
||||
2. You’ll be redirected to the sign-in page, where NetBird uses your identity provider (IdP) for secure authentication.
|
||||
It supports any OIDC-compliant provider, including social logins like Gmail and GitHub for personal use.
|
||||
3. Follow the authentication steps for your chosen provider. If you have multi-factor authentication (MFA) enabled on your IdP account,
|
||||
it will work automatically.
|
||||
|
||||
## Connect Your Laptop
|
||||
NetBird comes with a Desktop UI application that can be found in the systray. If it hasn't automatically started, look
|
||||
for `NetBird` in the application list, run it, and click `Connect`:
|
||||
Upon your first login, you'll be greeted by a short onboarding survey. This helps us tailor your experience.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/systray.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
## Peer-to-Peer Network
|
||||
One way of using NetBird is to create a peer-to-peer network, where you run the NetBird client on your devices to connect them directly.
|
||||
|
||||
|
||||
<Note>
|
||||
Alternatively, you can run the `netbird up` command in the terminal.
|
||||
</Note>
|
||||
The onboarding process will now guide you to connect your first device, also known as a peer.
|
||||
For this guide, we'll select Peer-to-Peer Network. If you’re selecting the Remote Network Access option, you can see that process [here](http://localhost:3000/how-to/getting-started#remote-network-access).
|
||||
|
||||
At this point a browser window pops up starting an interactive SSO login session that will register your laptop.
|
||||
You will be prompt to sign up and confirm your device registration:
|
||||
### Install Your First Peer
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/device-confirmation.png" alt="login-to-netbird" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
|
||||
The NetBird systray icon will turn orange indicating that your laptop was registered in the network:
|
||||
1. On the "Let's get your first device online" screen, click the Install NetBird button.
|
||||
2. An [installation modal](https://app.netbird.io/install) will appear. Select your operating system (e.g., macOS, Windows, Linux). For this example, we're installing it on a macOS machine.
|
||||
3. Download the installer and run it. Follow the on-screen prompts to complete the installation.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/systray-connected.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
### Connect Your First Peer
|
||||
With the client installed, you now need to connect it to your network.
|
||||
|
||||
## Confirm the Laptop Registration
|
||||
|
||||
|
||||
After the registration is complete, proceed to the [NetBird dashboard](https://app.netbird.io) to confirm that your
|
||||
laptop is in the network. You will see it in the `Peers` view:
|
||||
1. After installation, find the NetBird icon in your system tray or menu bar.
|
||||
2. Click the icon and select **Connect**.
|
||||
3. This will open a new browser tab, prompting you to authorize the new device. Authenticate using the same IdP you used to sign up.
|
||||
4. Once authorized, you will see a "Login successful" message. The onboarding UI will update to show that your first peer is connected, displaying its name and assigned NetBird IP address.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/dashboard.png" alt="login-to-netbird" className="imagewrapper-big"/>
|
||||
### Add a Second Peer (Headless Linux Server)
|
||||
Next, let's add a second, headless peer, like a Linux server or a Raspberry Pi. For devices without a graphical interface, we use a [Setup Key](https://docs.netbird.io/how-to/register-machines-using-setup-keys).
|
||||
|
||||
</p>
|
||||
|
||||
|
||||
## Install NetBird on the EC2 Node
|
||||
1. In the web UI, the onboarding flow will now prompt you to "bring in your second device." Click the link that says Install with a setup key.
|
||||
2. A pop-up will explain that a one-off setup key will be created, which you can also learn more about here. Click Continue..
|
||||
3. The onboarding UI will now provide two commands to run on your Linux server:
|
||||
|
||||
Let's install NetBird on the server. In the `Peers` view, click `Add Peer` and choose Linux:
|
||||
* **Install NetBird**: A curl command to download and run the installation script.
|
||||
* **Run NetBird**: A [netbird up command](https://docs.netbird.io/how-to/cli) that includes your unique setup key.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/add-linux-peer.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
4. SSH into your Linux server and run the commands:
|
||||
|
||||
Copy the installation script and paste in the terminal of your EC2 node:
|
||||
First, copy the curl command, paste it into your server's terminal, and press **Enter**. You may be prompted for your sudo password.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://pkgs.netbird.io/install.sh | sh
|
||||
```
|
||||
|
||||
## Connect the EC2 Node
|
||||
|
||||
In the previous steps you used the interactive SSO login flow to register a user device. This flow is a convenient way to
|
||||
register devices with a user interface. However, for servers or containers that don't have a user interface,
|
||||
you can use a [setup key](/how-to/register-machines-using-setup-keys) to register them.
|
||||
|
||||
To create a setup key, go to the `Setup Keys` section, click `Create Setup Key`, name your key, and click `Create`:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/setup-key.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/setup-key-created.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Copy the newly created setup key and use it with the `netbird up --setup-key <KEY>` command to connect your EC2 node to the network.
|
||||
Run this command in the terminal of your EC2 node:
|
||||
Next, copy the netbird up --setup-key ... command and paste it into the terminal.
|
||||
|
||||
```bash
|
||||
netbird up --setup-key PASTE_YOUR_KEY_HERE
|
||||
netbird up --setup-key <YOUR_SETUP_KEY>
|
||||
```
|
||||
|
||||
## Validate the Connection
|
||||
After running the second command, the terminal will confirm Connected. Your headless device is now part of your NetBird network.
|
||||
|
||||
Return to the `Peers` view in the NetBird dashboard. You should see two machines in the list:
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/peers.png" alt="login-to-netbird" className="imagewrapper-big"/>
|
||||
</p>
|
||||
### Verify the Connection
|
||||
The onboarding UI will now display both of your connected peers. The onboarding wizard provides a simple way to test that they can communicate directly.
|
||||
|
||||
To test the connection ping the machines from each other:
|
||||
|
||||
|
||||
1. Copy the provided ping command from the onboarding UI. This command uses the NetBird IP address of your second peer (the Ubuntu server).
|
||||
2. Open a terminal on your first peer and paste the command. Replace the example below with the NetBird IP for your machine.
|
||||
|
||||
On your laptop:
|
||||
```bash
|
||||
ping ec2-demo-node.netbird.cloud
|
||||
```
|
||||
ping 100.74.76.17
|
||||
```
|
||||
|
||||
On the EC2 node:
|
||||
```bash
|
||||
ping mikhails-macbook-pro.netbird.cloud
|
||||
```
|
||||
Done! You now have a secure peer-to-peer WireGuard connection between two machines.
|
||||
3. You should see successful ping replies, confirming that the two devices are connected over the NetBird network. Click It works! - Continue in the onboarding UI.
|
||||
|
||||
## Next Steps
|
||||
### Understanding Access Control
|
||||
The final onboarding step introduces NetBird's powerful Access Control policies.
|
||||
|
||||
Try creating a [network access policy](/how-to/manage-network-access) to control the traffic between the two machines.
|
||||
|
||||
1. By default, a policy is active that allows connections between all your devices. This is why the ping command in the previous step worked.
|
||||
2. The wizard demonstrates this by allowing you to toggle the policy. If you disable the "Default Policy," the ping between your devices will immediately fail with a "Request timeout" error.
|
||||
3. Re-enabling the policy instantly restores the connection. This gives you a basic understanding of how you can control traffic within your network. You can learn much more about policies [here](/how-to/manage-network-access).
|
||||
4. Click Continue to finish.
|
||||
|
||||
|
||||
In the policy example above, we allowed _IT Admins_ port specific access to peers under the _AWS Servers_ group. Policies are a key building block to access in NetBird. You can learn more about the power of policies [here](https://docs.netbird.io/how-to/manage-network-access).
|
||||
|
||||
<Note>
|
||||
If you manage users and groups with your identity provider, you can provision and sync them with NetBird. Learn more [here](https://docs.netbird.io/how-to/idp-sync) including the supported platforms.
|
||||
</Note>
|
||||
|
||||
## Remote Network Access
|
||||
The second way to use NetBird is for remote network access by running NetBird on a single machine within your private network.
|
||||
This machine acts as a routing peer, routing traffic to internal resources that don't have the NetBird client installed.
|
||||
|
||||
The onboarding process will now guide you to build our first network resource.
|
||||
For this guide, we'll select Remote Network Access.
|
||||
|
||||
|
||||
|
||||
### Define Your Network Resource
|
||||
Next, you'll define the private network you want your users to be able to access.
|
||||
1. The onboarding UI will prompt you to "Add your first resource." There are a few options here, but the easiest way to get started is with full access to an entire Network. Select the Entire Subnet option.
|
||||
2. Enter the CIDR range of your private network. For example, `10.0.0.0/32`.
|
||||
3. Click Create Resource. A "Network" will be created in your dashboard to contain this resource and its access rules.
|
||||
|
||||
|
||||
|
||||
### Add and Configure a Routing Peer
|
||||
A [routing peer](https://docs.netbird.io/how-to/routing-traffic-to-private-networks) is a NetBird peer that lives inside your private network and acts as a gateway, forwarding traffic between your remote users and the internal resources.
|
||||
|
||||
|
||||
|
||||
1. The dashboard will now prompt you to "Add a routing peer." First, click Generate Setup Key. This creates a one-time key used to enroll the gateway machine into your NetBird account.
|
||||
2. Next, click Install Routing Peer. Select the operating system of your gateway machine (the video uses Linux).
|
||||
3. The installation modal will provide two commands: a curl script to install the NetBird agent and a netbird up command that includes your setup key.
|
||||
4. SSH into your gateway machine (which must be inside the 10.0.0.0/24 subnet) and run the commands:
|
||||
5. SSH into your Linux server and run the commands:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://pkgs.netbird.io/install.sh | sh
|
||||
```
|
||||
|
||||
Next, copy the netbird up --setup-key ... command and paste it into the terminal.
|
||||
|
||||
```bash
|
||||
netbird up --setup-key <YOUR_SETUP_KEY>
|
||||
```
|
||||
|
||||
After running the second command, the terminal will confirm Connected. Your headless device is now part of your NetBird network.
|
||||
|
||||
### Connect a Client Device
|
||||
Now, set up the device you will use to connect to your private network.
|
||||
1. Back in the web UI, the wizard will prompt you to "Time to add your client device." Click Install NetBird.
|
||||
2. Download and run the installer for your client machine's OS (e.g., macOS).
|
||||
3. Once installed, find the NetBird icon in your system tray or menu bar, click it, and select Connect.
|
||||
4. Authorize this new device in the browser tab that opens.
|
||||
|
||||
### Test the Connection
|
||||
With both the routing peer and your client device online, you can now test your connection to the private network. To properly test connectivity you should move the client device to a different network, for example, connecting the device using your phone's hotspot.
|
||||
|
||||
|
||||
|
||||
1. Open a terminal on your client device and run the test command (e.g., `ping 10.0.0.100`). Due note, the IP you ping needs to be a device on the same network that the routing peer is installed on.
|
||||
2. You should see successful replies, confirming that your client device can reach internal resources through the routing peer.
|
||||
3. Click It works! - Continue in the UI.
|
||||
|
||||
### Understanding Your Access Policy
|
||||
The final step of the onboarding wizard explains the access rule that was automatically created for you.
|
||||
|
||||
|
||||
|
||||
1. A policy, named "Users to My Subnet," is enabled by default. This policy allows all authenticated users to access the resources within the subnet you define.
|
||||
2. To demonstrate this, you can toggle this policy off. When disabled, the ping from your client device will begin to fail with a "Request timeout" error, showing that the connection is now blocked.
|
||||
3. Re-enabling the policy will immediately restore access.
|
||||
4. Click Continue to complete the setup.
|
||||
|
||||
|
||||
|
||||
Click Go to Dashboard to access the main NetBird admin panel. From here, you can:
|
||||
|
||||
* [Peers](https://docs.netbird.io/how-to/add-machines-to-your-network): View and manage all connected devices and their properties.
|
||||
* [Setup Keys](https://docs.netbird.io/how-to/register-machines-using-setup-keys): Create and manage keys for adding new headless or ephemeral devices.
|
||||
* [Access Control](https://docs.netbird.io/how-to/manage-network-access): Define granular firewall rules to control which peers can access what.
|
||||
* [Team](https://docs.netbird.io/how-to/add-users-to-your-network): Manage users and create groups for easier policy management.
|
||||
|
||||
You are now ready to explore the full capabilities of NetBird.
|
||||
|
||||
## Support Us
|
||||
|
||||
|
||||
Reference in New Issue
Block a user