package management

Get desktop application:
View/edit binary Protocol Buffers messages

• rpc GetDeviceAuthorizationFlow (EncryptedMessage, EncryptedMessage)

  management.proto:34

  Exposes a device authorization flow information This is used for initiating a Oauth 2 device authorization grant flow which will be used by our clients to Login. EncryptedMessage of the request has a body of DeviceAuthorizationFlowRequest. EncryptedMessage of the response has a body of DeviceAuthorizationFlow.

• rpc GetPKCEAuthorizationFlow (EncryptedMessage, EncryptedMessage)

  management.proto:41

  Exposes a PKCE authorization code flow information This is used for initiating a Oauth 2 authorization grant flow with Proof Key for Code Exchange (PKCE) which will be used by our clients to Login. EncryptedMessage of the request has a body of PKCEAuthorizationFlowRequest. EncryptedMessage of the response has a body of PKCEAuthorizationFlow.

• rpc GetServerKey (Empty, ServerKeyResponse)

  management.proto:24

  Exposes a Wireguard public key of the Management service. This key is used to support message encryption between client and server

  message ServerKeyResponse

  management.proto:181

  • string key = 1

    Server's Wireguard public key

  • optional google.protobuf.Timestamp expiresAt = 2

    Key expiration timestamp after which the key should be fetched again by the client

  • int32 version = 3

    Version of the Netbird Management Service protocol

• rpc Login (EncryptedMessage, EncryptedMessage)

  management.proto:14

  Login logs in peer. In case server returns codes.PermissionDenied this endpoint can be used to register Peer providing LoginRequest.setupKey Returns encrypted LoginResponse in EncryptedMessage.Body

• rpc Logout (EncryptedMessage, Empty)

  management.proto:50

  Logout logs out the peer and removes it from the management server

• rpc Sync (EncryptedMessage, stream EncryptedMessage)

  management.proto:20

  Sync enables peer synchronization. Each peer that is connected to this stream will receive updates from the server. For example, if a new peer has been added to an account all other connected peers will receive this peer's Wireguard public key as an update The initial SyncResponse contains all of the available peers so the local state can be refreshed Returns encrypted SyncResponse in EncryptedMessage.Body

• rpc SyncMeta (EncryptedMessage, Empty)

  management.proto:47

  SyncMeta is used to sync metadata of the peer. After sync the peer if there is a change in peer posture check which needs to be evaluated by the client, sync meta will evaluate the checks and update the peer meta with the result. EncryptedMessage of the request has a body of Empty.

• rpc isHealthy (Empty, Empty)

  management.proto:27

  health check endpoint

Used in: LoginResponse, SyncResponse

• repeated string Files = 1

CustomZone represents a dns.CustomZone

Used in: DNSConfig

• string Domain = 1

• repeated SimpleRecord Records = 2

DNSConfig represents a dns.Update

Used in: NetworkMap

• bool ServiceEnable = 1

• repeated NameServerGroup NameServerGroups = 2

• repeated CustomZone CustomZones = 3

• int64 ForwarderPort = 4

DeviceAuthorizationFlow represents Device Authorization Flow information that can be used by the client to login initiate a Oauth 2.0 device authorization grant flow see https://datatracker.ietf.org/doc/html/rfc8628

• DeviceAuthorizationFlow.provider Provider = 1

  An IDP provider , (eg. Auth0)

• optional ProviderConfig ProviderConfig = 2

Used in: DeviceAuthorizationFlow

• HOSTED = 0

DeviceAuthorizationFlowRequest empty struct for future expansion

(message has no fields)

Used as request type in: ManagementService.GetServerKey, ManagementService.isHealthy

Used as response type in: ManagementService.Logout, ManagementService.SyncMeta, ManagementService.isHealthy

(message has no fields)

Used as request type in: ManagementService.GetDeviceAuthorizationFlow, ManagementService.GetPKCEAuthorizationFlow, ManagementService.Login, ManagementService.Logout, ManagementService.Sync, ManagementService.SyncMeta

Used as response type in: ManagementService.GetDeviceAuthorizationFlow, ManagementService.GetPKCEAuthorizationFlow, ManagementService.Login, ManagementService.Sync

• string wgPubKey = 1

  Wireguard public key

• bytes body = 2

  encrypted message Body

• int32 version = 3

  Version of the Netbird Management Service protocol

Environment is part of the PeerSystemMeta and describes the environment the agent is running in.

Used in: PeerSystemMeta

• string cloud = 1

  cloud is the cloud provider the agent is running in if applicable.

• string platform = 2

  platform is the platform the agent is running on if applicable.

File represents a file on the system.

Used in: PeerSystemMeta

• string path = 1

  path is the path to the file.

• bool exist = 2

  exist indicate whether the file exists.

• bool processIsRunning = 3

  processIsRunning indicates whether the file is a running process or not.

FirewallRule represents a firewall rule

Used in: NetworkMap

• string PeerIP = 1

• RuleDirection Direction = 2

• RuleAction Action = 3

• RuleProtocol Protocol = 4

• string Port = 5

• optional PortInfo PortInfo = 6

• bytes PolicyID = 7

  PolicyID is the ID of the policy that this rule belongs to

Used in: PeerSystemMeta

• bool rosenpassEnabled = 1

• bool rosenpassPermissive = 2

• bool serverSSHAllowed = 3

• bool disableClientRoutes = 4

• bool disableServerRoutes = 5

• bool disableDNS = 6

• bool disableFirewall = 7

• bool blockLANAccess = 8

• bool blockInbound = 9

• bool lazyConnectionEnabled = 10

Used in: NetbirdConfig

• string url = 1

• string tokenPayload = 2

• string tokenSignature = 3

• optional google.protobuf.Duration interval = 4

• bool enabled = 5

• bool counters = 6

  counters determines if flow packets and bytes counters should be sent

• bool exitNodeCollection = 7

  exitNodeCollection determines if event collection on exit nodes should be enabled

• bool dnsCollection = 8

  dnsCollection determines if DNS event collection should be enabled

Used in: NetworkMap

• RuleProtocol protocol = 1

  Protocol of the forwarding rule

• optional PortInfo destinationPort = 2

  portInfo is the ingress destination port information, where the traffic arrives in the gateway node

• bytes translatedAddress = 3

  IP address of the translated address (remote peer) to send traffic to

• optional PortInfo translatedPort = 4

  Translated port information, where the traffic should be forwarded to

HostConfig describes connection properties of some server (e.g. STUN, Signal, Management)

Used in: NetbirdConfig, ProtectedHostConfig

• string uri = 1

  URI of the resource e.g. turns://stun.netbird.io:4430 or signal.netbird.io:10000

• HostConfig.Protocol protocol = 2

Used in: HostConfig

• UDP = 0

• TCP = 1

• HTTP = 2

• HTTPS = 3

• DTLS = 4

• string setupKey = 1

  Pre-authorized setup key (can be empty)

• optional PeerSystemMeta meta = 2

  Meta data of the peer (e.g. name, os_name, os_version,

• string jwtToken = 3

  SSO token (can be empty)

• optional PeerKeys peerKeys = 4

  Can be absent for now.

• repeated string dnsLabels = 5

• optional NetbirdConfig netbirdConfig = 1

  Global config

• optional PeerConfig peerConfig = 2

  Peer local config

• repeated Checks Checks = 3

  Posture checks to be evaluated by client

NameServer represents a dns.NameServer

Used in: NameServerGroup

• string IP = 1

• int64 NSType = 2

• int64 Port = 3

NameServerGroup represents a dns.NameServerGroup

Used in: DNSConfig

• repeated NameServer NameServers = 1

• bool Primary = 2

• repeated string Domains = 3

• bool SearchDomainsEnabled = 4

NetbirdConfig is a common configuration of any Netbird peer. It contains STUN, TURN, Signal and Management servers configurations

Used in: LoginResponse, SyncResponse

• repeated HostConfig stuns = 1

  a list of STUN servers

• repeated ProtectedHostConfig turns = 2

  a list of TURN servers

• optional HostConfig signal = 3

  a Signal server config

• optional RelayConfig relay = 4

• optional FlowConfig flow = 5

Used in: PeerSystemMeta

• string netIP = 1

• string mac = 2

NetworkMap represents a network state of the peer with the corresponding configuration parameters to establish peer-to-peer connections

Used in: SyncResponse

• uint64 Serial = 1

  Serial is an ID of the network state to be used by clients to order updates. The larger the Serial the newer the configuration. E.g. the client app should keep track of this id locally and discard all the configurations with a lower value

• optional PeerConfig peerConfig = 2

  PeerConfig represents configuration of a peer

• repeated RemotePeerConfig remotePeers = 3

  RemotePeerConfig represents a list of remote peers that the receiver can connect to

• bool remotePeersIsEmpty = 4

  Indicates whether remotePeers array is empty or not to bypass protobuf null and empty array equality.

• repeated Route Routes = 5

  List of routes to be applied

• optional DNSConfig DNSConfig = 6

  DNS config to be applied

• repeated RemotePeerConfig offlinePeers = 7

  RemotePeerConfig represents a list of remote peers that the receiver can connect to

• repeated FirewallRule FirewallRules = 8

  FirewallRule represents a list of firewall rules to be applied to peer

• bool firewallRulesIsEmpty = 9

  firewallRulesIsEmpty indicates whether FirewallRule array is empty or not to bypass protobuf null and empty array equality.

• repeated RouteFirewallRule routesFirewallRules = 10

  RoutesFirewallRules represents a list of routes firewall rules to be applied to peer

• bool routesFirewallRulesIsEmpty = 11

  RoutesFirewallRulesIsEmpty indicates whether RouteFirewallRule array is empty or not to bypass protobuf null and empty array equality.

• repeated ForwardingRule forwardingRules = 12

PKCEAuthorizationFlow represents Authorization Code Flow information that can be used by the client to login initiate a Oauth 2.0 authorization code grant flow with Proof Key for Code Exchange (PKCE). See https://datatracker.ietf.org/doc/html/rfc7636

• optional ProviderConfig ProviderConfig = 1

PKCEAuthorizationFlowRequest empty struct for future expansion

(message has no fields)

PeerConfig represents a configuration of a "our" peer. The properties are used to configure local Wireguard

Used in: LoginResponse, NetworkMap, SyncResponse

• string address = 1

  Peer's virtual IP address within the Netbird VPN (a Wireguard address config)

• string dns = 2

  Netbird DNS server (a Wireguard DNS config)

• optional SSHConfig sshConfig = 3

  SSHConfig of the peer.

• string fqdn = 4

  Peer fully qualified domain name

• bool RoutingPeerDnsResolutionEnabled = 5

• bool LazyConnectionEnabled = 6

• int32 mtu = 7

PeerKeys is additional peer info like SSH pub key and WireGuard public key. This message is sent on Login or register requests, or when a key rotation has to happen.

Used in: LoginRequest

• bytes sshPubKey = 1

  sshPubKey represents a public SSH key of the peer. Can be absent.

• bytes wgPubKey = 2

  wgPubKey represents a public WireGuard key of the peer. Can be absent.

PeerSystemMeta is machine meta data like OS and version.

Used in: LoginRequest, SyncMetaRequest, SyncRequest

• string hostname = 1

• string goOS = 2

• string kernel = 3

• string core = 4

• string platform = 5

• string OS = 6

• string netbirdVersion = 7

• string uiVersion = 8

• string kernelVersion = 9

• string OSVersion = 10

• repeated NetworkAddress networkAddresses = 11

• string sysSerialNumber = 12

• string sysProductName = 13

• string sysManufacturer = 14

• optional Environment environment = 15

• repeated File files = 16

• optional Flags flags = 17

Used in: FirewallRule, ForwardingRule, RouteFirewallRule

• oneof portSelection

  • uint32 port = 1

  • PortInfo.Range range = 2

Used in: PortInfo

• uint32 start = 1

• uint32 end = 2

ProtectedHostConfig is similar to HostConfig but has additional user and password Mostly used for TURN servers

Used in: NetbirdConfig

• optional HostConfig hostConfig = 1

• string user = 2

• string password = 3

ProviderConfig has all attributes needed to initiate a device/pkce authorization flow

Used in: DeviceAuthorizationFlow, PKCEAuthorizationFlow

• string ClientID = 1

  An IDP application client id

• string ClientSecret = 2

  An IDP application client secret

• string Domain = 3

  An IDP API domain Deprecated. Use a DeviceAuthEndpoint and TokenEndpoint

• string Audience = 4

  An Audience for validation

• string DeviceAuthEndpoint = 5

  DeviceAuthEndpoint is an endpoint to request device authentication code.

• string TokenEndpoint = 6

  TokenEndpoint is an endpoint to request auth token.

• string Scope = 7

  Scopes provides the scopes to be included in the token request

• bool UseIDToken = 8

  UseIDToken indicates if the id token should be used for authentication

• string AuthorizationEndpoint = 9

  AuthorizationEndpoint is the endpoint of an IDP manager where clients can obtain authorization code.

• repeated string RedirectURLs = 10

  RedirectURLs handles authorization code from IDP manager

• bool DisablePromptLogin = 11

  DisablePromptLogin makes the PKCE flow to not prompt the user for login

• uint32 LoginFlag = 12

  LoginFlags sets the PKCE flow login details

Used in: NetbirdConfig

• repeated string urls = 1

• string tokenPayload = 2

• string tokenSignature = 3

RemotePeerConfig represents a configuration of a remote peer. The properties are used to configure WireGuard Peers sections

Used in: NetworkMap, SyncResponse

• string wgPubKey = 1

  A WireGuard public key of a remote peer

• repeated string allowedIps = 2

  WireGuard allowed IPs of a remote peer e.g. [10.30.30.1/32]

• optional SSHConfig sshConfig = 3

  SSHConfig is a SSH config of the remote peer. SSHConfig.sshPubKey should be ignored because peer knows it's SSH key.

• string fqdn = 4

  Peer fully qualified domain name

• string agentVersion = 5

Route represents a route.Route object

Used in: NetworkMap

• string ID = 1

• string Network = 2

• int64 NetworkType = 3

• string Peer = 4

• int64 Metric = 5

• bool Masquerade = 6

• string NetID = 7

• repeated string Domains = 8

• bool keepRoute = 9

• bool skipAutoApply = 10

RouteFirewallRule signifies a firewall rule applicable for a routed network.

Used in: NetworkMap

• repeated string sourceRanges = 1

  sourceRanges IP ranges of the routing peers.

• RuleAction action = 2

  Action to be taken by the firewall when the rule is applicable.

• string destination = 3

  Network prefix for the routed network.

• RuleProtocol protocol = 4

  Protocol of the routed network.

• optional PortInfo portInfo = 5

  Details about the port.

• bool isDynamic = 6

  IsDynamic indicates if the route is a DNS route.

• repeated string domains = 7

  Domains is a list of domains for which the rule is applicable.

• uint32 customProtocol = 8

  CustomProtocol is a custom protocol ID.

• bytes PolicyID = 9

  PolicyID is the ID of the policy that this rule belongs to

• string RouteID = 10

  RouteID is the ID of the route that this rule belongs to

Used in: FirewallRule, RouteFirewallRule

• ACCEPT = 0

• DROP = 1

Used in: FirewallRule

• IN = 0

• OUT = 1

Used in: FirewallRule, ForwardingRule, RouteFirewallRule

• UNKNOWN = 0

• ALL = 1

• TCP = 2

• UDP = 3

• ICMP = 4

• CUSTOM = 5

SSHConfig represents SSH configurations of a peer.

Used in: PeerConfig, RemotePeerConfig

• bool sshEnabled = 1

  sshEnabled indicates whether a SSH server is enabled on this peer

• bytes sshPubKey = 2

  sshPubKey is a SSH public key of a peer to be added to authorized_hosts. This property should be ignore if SSHConfig comes from PeerConfig.

SimpleRecord represents a dns.SimpleRecord

Used in: CustomZone

• string Name = 1

• int64 Type = 2

• string Class = 3

• int64 TTL = 4

• string RData = 5

• optional PeerSystemMeta meta = 1

  Meta data of the peer

• optional PeerSystemMeta meta = 1

  Meta data of the peer

SyncResponse represents a state that should be applied to the local peer (e.g. Netbird servers config as well as local peer and remote peers configs)

• optional NetbirdConfig netbirdConfig = 1

  Global config

• optional PeerConfig peerConfig = 2

  Deprecated. Use NetworkMap.PeerConfig

• repeated RemotePeerConfig remotePeers = 3

  Deprecated. Use NetworkMap.RemotePeerConfig

• bool remotePeersIsEmpty = 4

  Indicates whether remotePeers array is empty or not to bypass protobuf null and empty array equality. Deprecated. Use NetworkMap.remotePeersIsEmpty

• optional NetworkMap NetworkMap = 5

• repeated Checks Checks = 6

  Posture checks to be evaluated by client