Create host

POST /v1/hosts

Create a new host, lighthouse, or relay.

Token scope required: hosts:create

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[]

  Default value: ``

  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.

Responses

• 200
• 400

---

Successful operation

application/json

Schema

Schema

• data object

  id string

  organizationID string

  networkID string

  roleID string nullable

  name string

  ipAddress ipv4

  staticAddresses ipv4: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
• metadata object

Example (from schema)

{
  "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

Schema

• errors object[]

  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

  ]

Example (from schema)

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

existingHostName

A host already exists with the name.

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

cannotFindNetwork

Cannot find the supplied networkID.

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

duplicateIpAddress

A host with the ipAddress supplied already exists.

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

cannotFindRole

Cannot find the supplied roleID.

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

lighthouseXorRelay

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"
    }
  ]
}

lighthouseNeedsStaticIP

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"
    }
  ]
}

lighthouseNeedsStaticPort

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"
    }
  ]
}

relayNeedsStaticPort

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"
    }
  ]
}

Loading...