Create host & enrollment code

POST /v1/host-and-enrollment-code

Token scopes required: hosts:create, hosts:enroll

Request

application/json

Request Body required

name string required
Possible values: non-empty and <= 255 characters
Name of the new host
networkID string required
ID of your network
roleID string nullable
ID of the role you want to assign
ipAddress ipv4
Assign an IP address to be used within the Managed Nebula network. Must be within the network's CIDR range. Will be chosen automatically if not provided.
staticAddresses ipv4:port[]
List of static IPv4:port addresses. At least one is required if isLighthouse is true.
listenPort integer
Possible values: <= 65535
The UDP port nebula should use on the host. An available port will be automatically selected if 0 is specified. Required for lighthouses and relays.
isLighthouse boolean
Set to true to create a new lighthouse. A Lighthouse cannot also be relay.
isRelay boolean
Set to true to create a new relay. A relay cannot also be a lighthouse.
tags key:value[]
configOverrides object[]
List of config overrides for the nebula config
Array [
anyOf
lighthouse.dns.host
lighthouse.dns.port
lighthouse.local_allow_list
lighthouse.remote_allow_list
lighthouse.serve_dns
listen.batch
listen.read_buffer
listen.write_buffer
logging.format
logging.level
logging.timestamp_format
preferred_ranges
routines
stats.host
stats.interval
stats.lighthouse_metrics
stats.listen
stats.message_metrics
stats.namespace
stats.path
stats.prefix
stats.subsystem
stats.type
tun.dev
tun.mtu
tun.tx_queue
key string required
Possible values: [lighthouse.dns.host]
value string required
key string required
Possible values: [lighthouse.dns.port]
value number required
key string required
Possible values: [lighthouse.local_allow_list]
value object required
interfaces object required
property name* boolean
anyOf
key string required
Possible values: [lighthouse.remote_allow_list]
value object required
property name* boolean
key string required
Possible values: [lighthouse.serve_dns]
value boolean required
key string required
Possible values: [listen.batch]
value number required
key string required
Possible values: [listen.read_buffer]
value number required
key string required
Possible values: [listen.write_buffer]
value number required
key string required
Possible values: [logging.format]
value string required
Possible values: [text, json]
key string required
Possible values: [logging.level]
value string required
Possible values: [panic, fatal, error, warning, info, debug]
key string required
Possible values: [logging.timestamp_format]
value string required
key string required
Possible values: [preferred_ranges]
value string[] required
key string required
Possible values: [routines]
value number required
key string required
Possible values: [stats.host]
value string required
key string required
Possible values: [stats.interval]
value string required
key string required
Possible values: [stats.lighthouse_metrics]
value boolean required
key string required
Possible values: [stats.listen]
value string required
key string required
Possible values: [stats.message_metrics]
value boolean required
key string required
Possible values: [stats.namespace]
value string required
key string required
Possible values: [stats.path]
value string required
key string required
Possible values: [stats.prefix]
value string required
key string required
Possible values: [stats.subsystem]
value string required
key string required
Possible values: [stats.type]
value string required
Possible values: [graphite, prometheus]
key string required
Possible values: [tun.dev]
value string required
key string required
Possible values: [tun.mtu]
value number required
key string required
Possible values: [tun.tx_queue]
value number required
]

Responses

Successful operation

application/json

Schema
Example (from schema)

Schema

data object
host object required
id string
organizationID string
networkID string
roleID string nullable
name string
ipAddress ipv4
staticAddresses address:port[]
listenPort int64
Will be zero if a regular host
isLighthouse boolean
Default value: false
isRelay boolean
Default value: false
createdAt date-time
isBlocked boolean
Default value: false
metadata object
lastSeenAt string nullable
version string nullable
platform string nullable
Possible values: [dnclient, mobile, null]
updateAvailable boolean nullable
tags key:value[]
configOverrides object[]
List of config overrides for the nebula config
Array [
anyOf
lighthouse.dns.host
lighthouse.dns.port
lighthouse.local_allow_list
lighthouse.remote_allow_list
lighthouse.serve_dns
listen.batch
listen.read_buffer
listen.write_buffer
logging.format
logging.level
logging.timestamp_format
preferred_ranges
routines
stats.host
stats.interval
stats.lighthouse_metrics
stats.listen
stats.message_metrics
stats.namespace
stats.path
stats.prefix
stats.subsystem
stats.type
tun.dev
tun.mtu
tun.tx_queue
key string required
Possible values: [lighthouse.dns.host]
value string required
]
enrollmentCode object
code string
lifetimeSeconds int64

metadata object

{
  "data": {
    "host": {
      "createdAt": "2023-01-25T18:15:27Z",
      "id": "host-24NVITKMNU3CYCEDNFWKAOBX7I",
      "ipAddress": "100.100.0.29",
      "isBlocked": false,
      "isLighthouse": false,
      "isRelay": false,
      "listenPort": 0,
      "name": "Host 1",
      "networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
      "organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
      "roleID": "role-PZEDBXHCEXKAKJPZ6XOQTIAJA4",
      "staticAddresses": [],
      "metadata": {
        "lastSeenAt": "2023-04-05T17:19:42Z",
        "platform": "dnclient",
        "updateAvailable": false,
        "version": "0.1.9"
      }
    },
    "enrollmentCode": {
      "code": "H8NEbm99QvupjqW1PsdVR9DNSiFmoQtJXyGTQxerlSU",
      "lifetimeSeconds": 86400
    }
  },
  "metadata": {}
}

Validation error

application/json

Schema

errors object[] required
Array [
code string required
A static name for the error type
message string required
A short human readable description of the error
path string nullable
Describes the variable missing or malformed
]

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "path": "string"
    }
  ]
}

A host already exists with the name.

{
  "errors": [
    {
      "code": "ERR_DUPLICATE_VALUE",
      "message": "value already exists",
      "path": "name"
    }
  ]
}

Cannot find the supplied networkID.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "referenced value is invalid (perhaps it does not exist?)",
      "path": "networkID"
    }
  ]
}

A host with the ipAddress supplied already exists.

{
  "errors": [
    {
      "code": "ERR_DUPLICATE_VALUE",
      "message": "value already exists",
      "path": "ipAddress"
    }
  ]
}

Cannot find the supplied roleID.

{
  "errors": [
    {
      "code": "ERR_INVALID_REFERENCE",
      "message": "referenced value is invalid (perhaps it does not exist?)",
      "path": "roleID"
    }
  ]
}

A host may be a lighthouse OR a relay, but not both.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must not also be relay hosts"
    }
  ]
}

A lighthouse requires at least one static IP address.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must have at least one static ip address",
      "path": "staticAddresses"
    }
  ]
}

A lighthouse requires a static listen port, like `4242`.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "lighthouse hosts must specify a static listen port",
      "path": "listenPort"
    }
  ]
}

A relay requires a static listen port, like `4242`.

{
  "errors": [
    {
      "code": "ERR_INVALID_VALUE",
      "message": "relay hosts must specify a static listen port",
      "path": "listenPort"
    }
  ]
}

Create host & enrollment code

Request​

Request