DOCSEARCHbyAlgolia
Submit Docs

Defined Networking Documentation

website·Indexed 34 days ago

https://docs.defined.net/

Documentation for Managed Nebula, a management plane for overlay networks. Includes guides for installing DNClient on Linux, macOS, and Windows, configuring lighthouses and dedicated relays, managing firewall rules via roles and tags, and using the Defined Networking API v1.0.0.

Tokens
18.8K
Snippets
80
Records
167
Agent score
62%

What's inside Defined Networking

  1. Overview of Managed Nebula components

    Managed Nebula is a secure overlay networking solution by Defined Networking that provides centralized control over hosts, security policies, and network configuration. It removes the operational burden of manual certificate and key management through the following core components:

    • Admin Web App: A single dashboard for managing hosts, groups, firewall rules, and overlay IPs.
    • Automation Web Service: Handles automated enrollment and updates across the host fleet.
    • Host Client Software: Powered by Nebula, this client automatically updates certificates, keys, and configuration, including groups-based firewall settings.
    • Managed Lighthouse: A built-in discovery service included with every network, allowing hosts to find each other without requiring the user to manage discovery infrastructure.

  2. Overview of DNClient Desktop

    DNClient Desktop is a desktop application for Mac and Windows designed to manage connections to Managed Nebula networks. Key features include:

    • Support for multiple simultaneous network connections.
    • Automatic startup and connection upon user login (default behavior).
    • Connection status visibility via a taskbar or menubar icon.
    • Enrollment support via enroll codes or endpoint SSO authentication.

    For management of the desktop application, use dnclientd.

  3. Overview of Managed Nebula Lighthouses

    A managed lighthouse is a component provided by Defined Networking that allows hosts in a Nebula network to discover each other and establish connections. It removes the need for users to install, configure, or maintain their own discovery infrastructure. Every new Managed Nebula network includes a managed lighthouse by default.

  4. Overview of DNClient Server

    DNClient Server is a CLI-based application used to manage connections to Managed Nebula networks. Unlike DNClient Desktop, it lacks a graphical user interface and does not support endpoint SSO authentication. It supports enrollment via enroll codes and can be installed as a service to automatically connect to networks upon user login.

  5. Use Relays to ensure 100% connectivity in Managed Nebula

    A relay is a specialized host in the Managed Nebula network that forwards traffic between two other hosts that cannot communicate directly. Because traffic is end-to-end encrypted and authenticated, the relay cannot inspect or modify the data; it only handles the routing. To ensure maximum connectivity, relays should be deployed with a public internet IP and appropriate firewall rules, similar to a lighthouse deployment.

  6. Fetch network information using the GET /v2/networks/:networkID endpoint

    Retrieve detailed information about a specific network by providing its networkID in the URL path. To successfully call this endpoint, the authentication token must have the networks:read scope.

    Possible responses include:

    • 200: Successful operation
    • 404: Network not found
    curl -X GET "https://api.defined.net/v2/networks/{networkID}"
     -H "Authorization: Bearer YOUR_TOKEN"

  7. Retrieve information about a specific role

    Use the GET /v1/roles/:roleID endpoint to fetch detailed information about a particular role. To call this API, the authentication token must have the roles:read scope.
    curl -X GET "https://<api-domain>/v1/roles/:roleID" \
     -H "Authorization: Bearer <token>"

  8. Understand and use Tags for host identification and configuration

    A tag is a key:value label assigned to a host to describe a facet of its identity (e.g., region:us-west-1, os:windows). Hosts can have multiple tags. Tags can be pre-defined in the Defined Networking admin panel or created on-the-fly during host creation/editing.

    Constraints:

    • Tag keys: Maximum 20 characters.
    • Tag values: Maximum 50 characters.
    • No surrounding whitespace allowed.

    Primary Use Cases:

    1. Firewall Rules: Tags can be referenced in firewall rules to grant access based on host attributes (e.g., allowing SSH only to hosts with user-type:admin).
    2. Inbound Rules: Tags can carry their own inbound firewall rules that apply to every host assigned that tag.
    3. Configuration Management: Tags can carry configuration settings (such as Nebula lighthouse.local_allow_list rules) that are automatically pushed to all assigned hosts.

  9. Fetch information about a specific tag

    Retrieve details for a particular tag using the GET /v1/tags/:tag endpoint. This operation requires an authentication token with the tags:read scope.
    curl -X GET "https://<api-url>/v1/tags/{tag}"

  10. Fetch host information using the Get host API

    Retrieve detailed information about a specific host by making a GET request to the /v2/hosts/:hostID endpoint. To access this endpoint, your authentication token must have the hosts:read scope. The API returns a 200 status code upon a successful operation or a 404 status code if the host is not found.
    curl -X GET "https://<api-domain>/v2/hosts/{hostID}"

  11. Fetch host information using the deprecated v1 API

    The GET /v1/hosts/:hostID endpoint allows you to fetch information about a specific host, lighthouse, or relay on an IPv4-only network. This endpoint requires the hosts:read token scope.

    Warning: This endpoint is deprecated and may be removed in future versions. It is recommended to migrate to the v2 equivalent: GET /v2/hosts/{hostID}.

    curl -X GET "https://api.defined.net/v1/hosts/:hostID" \
     -H "Authorization: Bearer <TOKEN>"

  12. Understand Defined Networking API key scopes

    Every Defined Networking API key is granted a set of permission scopes written in the format resource:action (e.g., hosts:read). An API key can only call an endpoint if it has been granted the specific scope required by that endpoint. It is recommended to follow the principle of least privilege by granting only the minimum scopes necessary for a key's intended function.