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
istrue
. - 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 requiredPossible values: [
lighthouse.dns.host
]value string requiredkey string requiredPossible values: [
lighthouse.dns.port
]value number requiredkey string requiredPossible values: [
lighthouse.local_allow_list
]value object required
interfaces object required
property name*
booleananyOfkey string requiredPossible values: [
lighthouse.remote_allow_list
]value object required
property name*
booleankey string requiredPossible values: [
lighthouse.serve_dns
]value boolean requiredkey string requiredPossible values: [
listen.batch
]value number requiredkey string requiredPossible values: [
listen.read_buffer
]value number requiredkey string requiredPossible values: [
listen.write_buffer
]value number requiredkey string requiredPossible values: [
logging.format
]value string requiredPossible values: [
text
,json
]key string requiredPossible values: [
logging.level
]value string requiredPossible values: [
panic
,fatal
,error
,warning
,info
,debug
]key string requiredPossible values: [
logging.timestamp_format
]value string requiredkey string requiredPossible values: [
preferred_ranges
]value string[] requiredkey string requiredPossible values: [
routines
]value number requiredkey string requiredPossible values: [
stats.host
]value string requiredkey string requiredPossible values: [
stats.interval
]value string requiredkey string requiredPossible values: [
stats.lighthouse_metrics
]value boolean requiredkey string requiredPossible values: [
stats.listen
]value string requiredkey string requiredPossible values: [
stats.message_metrics
]value boolean requiredkey string requiredPossible values: [
stats.namespace
]value string requiredkey string requiredPossible values: [
stats.path
]value string requiredkey string requiredPossible values: [
stats.prefix
]value string requiredkey string requiredPossible values: [
stats.subsystem
]value string requiredkey string requiredPossible values: [
stats.type
]value string requiredPossible values: [
graphite
,prometheus
]key string requiredPossible values: [
tun.dev
]value string requiredkey string requiredPossible values: [
tun.mtu
]value number requiredkey string requiredPossible values: [
tun.tx_queue
]value number required]
- 200
- 400
Successful operation
- application/json
- Schema
- Example (from schema)
Schema
data object
host object required
id stringorganizationID stringnetworkID stringroleID string nullablename stringipAddress ipv4staticAddresses address:port[]listenPort int64Will be zero if a regular host
isLighthouse booleanDefault value:
false
isRelay booleanDefault value:
false
createdAt date-timeisBlocked booleanDefault value:
false
metadata object
lastSeenAt string nullableversion string nullableplatform string nullablePossible values: [
dnclient
,mobile
,null
]updateAvailable boolean nullabletags 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 requiredPossible values: [
lighthouse.dns.host
]value string requiredkey string requiredPossible values: [
lighthouse.dns.port
]value number requiredkey string requiredPossible values: [
lighthouse.local_allow_list
]value object required
interfaces object required
property name*
booleananyOfkey string requiredPossible values: [
lighthouse.remote_allow_list
]value object required
property name*
booleankey string requiredPossible values: [
lighthouse.serve_dns
]value boolean requiredkey string requiredPossible values: [
listen.batch
]value number requiredkey string requiredPossible values: [
listen.read_buffer
]value number requiredkey string requiredPossible values: [
listen.write_buffer
]value number requiredkey string requiredPossible values: [
logging.format
]value string requiredPossible values: [
text
,json
]key string requiredPossible values: [
logging.level
]value string requiredPossible values: [
panic
,fatal
,error
,warning
,info
,debug
]key string requiredPossible values: [
logging.timestamp_format
]value string requiredkey string requiredPossible values: [
preferred_ranges
]value string[] requiredkey string requiredPossible values: [
routines
]value number requiredkey string requiredPossible values: [
stats.host
]value string requiredkey string requiredPossible values: [
stats.interval
]value string requiredkey string requiredPossible values: [
stats.lighthouse_metrics
]value boolean requiredkey string requiredPossible values: [
stats.listen
]value string requiredkey string requiredPossible values: [
stats.message_metrics
]value boolean requiredkey string requiredPossible values: [
stats.namespace
]value string requiredkey string requiredPossible values: [
stats.path
]value string requiredkey string requiredPossible values: [
stats.prefix
]value string requiredkey string requiredPossible values: [
stats.subsystem
]value string requiredkey string requiredPossible values: [
stats.type
]value string requiredPossible values: [
graphite
,prometheus
]key string requiredPossible values: [
tun.dev
]value string requiredkey string requiredPossible values: [
tun.mtu
]value number requiredkey string requiredPossible values: [
tun.tx_queue
]value number required]enrollmentCode object
code stringlifetimeSeconds 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
- Example (from schema)
- existingHostName
- cannotFindNetwork
- duplicateIpAddress
- cannotFindRole
- lighthouseXorRelay
- lighthouseNeedsStaticIP
- lighthouseNeedsStaticPort
- relayNeedsStaticPort
Schema
errors object[] required
Array [code string requiredA static name for the error type
message string requiredA short human readable description of the error
path string nullableDescribes 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"
}
]
}