Create host
POST/v1/hosts
Create a new host, lighthouse, or relay.
Token scope required: hosts:create
Request
- application/json
Body
required
Array [
- 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
- MOD1
- MOD2
]
Name of the new host
Possible values: non-empty
and <= 255 characters
My new host
ID of your network
network-KAOWMXZHZWCVMGGFKM22XEGYLE
ID of the role you want to assign
role-PZEDBXHQEXKACJPZ6XOQTIAJA4
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.
100.100.0.29
List of static IPv4:port/hostname:port addresses. At least one is required if isLighthouse
is true
.
["84.123.10.1:4242"]
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.
Possible values: <= 65535
0
Set to true to create a new lighthouse. A Lighthouse cannot also be relay.
Set to true to create a new relay. A relay cannot also be a lighthouse.
configOverrides
object[]
List of config overrides for the nebula config
anyOf
Possible values: [lighthouse.dns.host
]
Possible values: [lighthouse.dns.port
]
Possible values: [lighthouse.local_allow_list
]
value
object
required
interfaces
object
required
property name*
object
anyOf
boolean
Possible values: [lighthouse.remote_allow_list
]
value
object
required
Possible values: [lighthouse.serve_dns
]
Possible values: [listen.batch
]
Possible values: [listen.read_buffer
]
Possible values: [listen.write_buffer
]
Possible values: [logging.format
]
Possible values: [text
, json
]
Possible values: [logging.level
]
Possible values: [panic
, fatal
, error
, warning
, info
, debug
]
Possible values: [logging.timestamp_format
]
Possible values: [preferred_ranges
]
Possible values: [routines
]
Possible values: [stats.host
]
Possible values: [stats.interval
]
Possible values: [stats.lighthouse_metrics
]
Possible values: [stats.listen
]
Possible values: [stats.message_metrics
]
Possible values: [stats.namespace
]
Possible values: [stats.path
]
Possible values: [stats.prefix
]
Possible values: [stats.subsystem
]
Possible values: [stats.type
]
Possible values: [graphite
, prometheus
]
Possible values: [tun.dev
]
Possible values: [tun.mtu
]
Possible values: [tun.tx_queue
]
Responses
- 200
- 400
Successful operation
- application/json
- Schema
- Example (from schema)
Schema
Array [
- 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
- MOD1
- MOD2
]
data
object
Will be zero if a regular host
false
false
false
metadata
object
Possible values: [dnclient
, mobile
, null
]
configOverrides
object[]
List of config overrides for the nebula config
anyOf
Possible values: [lighthouse.dns.host
]
Possible values: [lighthouse.dns.port
]
Possible values: [lighthouse.local_allow_list
]
value
object
required
interfaces
object
required
property name*
object
anyOf
boolean
Possible values: [lighthouse.remote_allow_list
]
value
object
required
Possible values: [lighthouse.serve_dns
]
Possible values: [listen.batch
]
Possible values: [listen.read_buffer
]
Possible values: [listen.write_buffer
]
Possible values: [logging.format
]
Possible values: [text
, json
]
Possible values: [logging.level
]
Possible values: [panic
, fatal
, error
, warning
, info
, debug
]
Possible values: [logging.timestamp_format
]
Possible values: [preferred_ranges
]
Possible values: [routines
]
Possible values: [stats.host
]
Possible values: [stats.interval
]
Possible values: [stats.lighthouse_metrics
]
Possible values: [stats.listen
]
Possible values: [stats.message_metrics
]
Possible values: [stats.namespace
]
Possible values: [stats.path
]
Possible values: [stats.prefix
]
Possible values: [stats.subsystem
]
Possible values: [stats.type
]
Possible values: [graphite
, prometheus
]
Possible values: [tun.dev
]
Possible values: [tun.mtu
]
Possible values: [tun.tx_queue
]
{
"data": {
"createdAt": "2023-01-25T18:15:27Z",
"id": "host-24NVITKMNU3CYCEDNFWKAOBX7I",
"ipAddress": "100.100.0.29",
"isBlocked": false,
"isLighthouse": false,
"isRelay": false,
"listenPort": 0,
"name": "My new host",
"networkID": "network-KAOWMXZHZWCVMGGFKM22XEGYLE",
"organizationID": "org-F63A24JGCLJV3ZEUTLCBISGETA",
"roleID": "role-PZEDBXHQEXKACJPZ6XOQTIAJA4",
"staticAddresses": [
"84.123.10.1:4242"
],
"metadata": {
"lastSeenAt": "2023-01-25T18:15:27Z",
"platform": "dnclient",
"updateAvailable": false,
"version": "0.1.9"
}
},
"metadata": {}
}
Validation error
- application/json
- Schema
- Example (from schema)
- existingHostName
- cannotFindNetwork
- duplicateIpAddress
- cannotFindRole
- lighthouseXorRelay
- lighthouseNeedsStaticIP
- lighthouseNeedsStaticPort
- relayNeedsStaticPort
Schema
Array [
]
errors
object[]
A static name for the error type
A short human readable description of the error
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"
}
]
}