ZTNA - Setup Your First Peers

ZTNA - Setup Your First Peers

Getting Started with Your ZTNA Service

Identity Provider Usage - Creating Users

1. Login to your Identity Provider using the admin credentials that are shared via one-time use note. The URL will end in /ui/console

2. Setup MFA for you admin account. 

3. Change your admin password:

4. In the Identity Provider (Zitadel) choose Users from the top navigation

5. On the right hand side choose +New to create your first user
6. Fill in:
  1. E-mail
  2. User Name
  3. Given Name (First Name)
  4. Family Name (Last Name)
  5. Check Email Verified (You can setup your own SMTP to enable email invites, password changes, etc You can also integrate an SMS/Phone service via a service like Twillio)
  6. Check Set Initial Password (You, or in the future your users, will change their password on first login)

Netbird Configuration Role Settings for you new User

  1. Login to the HOSTS URL (provided in the single use note via email) as user admin and elevate the new user to the role of Admin
  2. Choose Teams > Users > Click on your new account > Choose Amin > Save


3. Log out and then back in as the new user. 
4. You will now see a full Netbird UI. Your clients should have the role of User. They will presented with the image below which is a  copy/paste install instructions for their operating system,

Installing Client Peers (Hosts)



From here you can follow along with the Netbird QuickStart documentation under the Install Your First Peer heading) to install clients on your hosts (computers, phones).

Navigate to Peers > Add Peer  button which will show you the instructions to install the client for your new peer.

Connecting Your First Devices

After installing the Netbird client on your device:

  1. Launch and Connect: Click the Netbird icon in your system tray (Windows/Mac) or menu bar and select "Connect"

  2. Authenticate: A browser window will open automatically. Log in using your Zitadel email and password

  3. Confirm Connection: After successful authentication, you'll see "Login successful" in the browser

  4. Verify Status: The Netbird icon in your system tray should now show "Connected"

Your device is now assigned a Netbird IP address (in the 100.x.x.x range). You can view all connected peers and their assigned IPs in the Netbird dashboard under the Peers page.

Testing Connectivity Between Peers

Once you have 2 or more peers connected:

  1. Open the Peers page in the Netbird dashboard to see the Netbird IP addresses
  2. From one device, open a terminal/command prompt
  3. Ping another peer using its Netbird IP: ping 100.x.x.x
  4. Successful ping responses confirm your secure mesh network is operational

Important: By default, the "Default Policy" in Access Control allows all peers to communicate with each other. You can customize access policies later based on your security requirements.

Installing on Headless Systems (Servers, Raspberry Pi, etc.)

For servers or systems without a desktop interface:

  1. In the Netbird dashboard, navigate to Setup Keys in the sidebar
  2. Click Create Setup Key
  3. Choose Single-use for security (one device per key) or Reusable if deploying multiple identical systems
  4. Copy the generated setup key
  5. On your headless system, run these commands:

Install Netbird: curl -fsSL https://pkgs.netbird.io/install.sh | sh

Connect using your setup key: netbird up --setup-key <YOUR_SETUP_KEY>

  1. The terminal will display "Connected" when successful
  2. The peer will appear in your Netbird dashboard's Peers page

Troubleshooting First Connection Issues

Client won't connect:

  • Verify your firewall allows outbound UDP traffic on port 3478 (STUN/TURN)
  • Some corporate networks block peer-to-peer traffic - Netbird will automatically fall back to relay servers
  • Check the Netbird logs: Click the Netbird tray icon → Advanced → View Logs

Peers show as "Disconnected" in dashboard:

  • Wait 30-60 seconds - initial connection can take a moment
  • Ensure the device has internet connectivity
  • Try disconnecting and reconnecting from the Netbird tray icon

Need detailed connection information: Run this command in your terminal to see full connection status: netbird status

This shows your Netbird IP, connection type (P2P direct or relayed), connected peers, and network routes.

Understanding Your Netbird Network

Peer-to-Peer Connectivity:

  • Netbird creates direct encrypted connections between your devices when possible
  • Traffic flows directly between peers - not through Uplevel infrastructure
  • When direct P2P isn't possible (restrictive firewalls/NAT), connections automatically relay through Netbird's relay servers

Your Management URL:

  • The "HOSTS URL" from your setup note is your Netbird management server
  • Format: https://netbird.yourcompany.uplevelsystems.com
  • This is where the --management-url flag points for CLI installations
  • Only needed if you're doing manual/advanced installations

Next Steps

Now that you have your basic Netbird network running, we recommend reading through the official Netbird Getting Started Documentation to learn about the full range of features available. This will give you a solid foundation in:

  • Creating network resources (subnets and specific hosts)
  • Setting up routing peers for remote network access
  • Configuring granular access control policies
  • Adding DNS settings for hostname resolution within your network
  • Understanding posture checks and security policies

After you've explored the documentation, we're happy to provide a more in-depth tour and help you configure advanced settings specific to your environment.

Future Improvements

We're actively working to streamline the ZTNA management experience. In the near future, both Zitadel (Identity Provider) and Netbird (ZTNA overlay) will be manageable directly from the Uplevel Portal through API integration, eliminating the need to log into multiple interfaces.

You'll always retain access to the advanced control panels with your admin credentials, allowing you to:

  • Connect your own Identity Provider for SSO (Entra ID, Google Workspace, Auth0, Active Directory, etc.)
  • Create complex ZTNA configurations and custom policies
  • Take full advantage of both platforms' enterprise features

Our goal is to make standard, straightforward deployments simple to manage from the Uplevel Portal while preserving full administrative control for advanced use cases. This product is production-ready today, and upcoming portal integration enhancements will be deployed without disrupting existing environments.

    • Related Articles

    • Site-to-Site VPN - Non-Uplevel (3rd Party VPN)

      Introduction You can quickly set up IPsec tunnels to connect to third-party firewalls and cloud services. We currently have 'pre-configured' configurations for Microsoft Azure, Amazon AWS, etc. to remove the complexity from connecting to those ...

    • Domain Controller (Active Directory) Setup

      Introduction There aren't any guidelines or instructions on the functioning of the Uplevel Domain Controller because it acts essentially identically to a conventional Microsoft Domain Controller from the standpoint of workstations. Microsoft offers a ...

    • Site to Site VPN (Uplevel to Uplevel)

      Introduction Configuring site-to-site VPNs between Uplevel Gateways is done with a single click. In addition, routing, switching, firewalling, VLANs are all configured automatically to ensure security with maximum convenience. Configuration From your ...

    • Best Practices for Managing Client Networks

      Network Security and Equipment Protection Best Practices Overview This document outlines critical best practices for securing network assets and protecting equipment when managing client networks. Following these guidelines helps ensure network ...

    • Remove an AP (Access Point) from a Customers Portal

      This article describes how to remove an AP from your Customer's site in the Portal. If you require support due to an alert that a "Wi-Fi AP unplugged or not working", please see this support article. If you disconnect or relocate an AP you will see a ...