Skip to Content

General

The version, and reading the configuration again.

OperationKindHTTP
versioncallGET /v1/version
accesscallGET /v1/access

version

The version of rookery serve and of its API.

Needs the role view.

Result

FieldTypeDescription
apiinteger
applied (optional)Applied | null
mode (optional)stringsystem or single.
simulated (optional)booleanWhether it is simulated, as rookery serve --simulate and its hosts are: nothing it does reaches a real machine.
type (optional)HostType | null
versionstring
Request
{
  "id": 1,
  "op": "version"
}
Reply
{
  "id": 1,
  "result": {
    "api": 1,
    "applied": {
      "offers": [
        {
          "aliases": {},
          "feature": "text",
          "fingerprint": "text",
          "provisioners": [],
          "secrets": {},
          "settings": {}
        }
      ],
      "plugins": [
        {
          "digest": "text",
          "id": "k3v9qz2m8w1x",
          "package": "text",
          "version": "0.6.0"
        }
      ],
      "rookery": "text",
      "tailnet": {
        "addresses": [
          "text"
        ],
        "dns_name": "text",
        "host_name": "text",
        "id": "k3v9qz2m8w1x",
        "tailnet": "text"
      }
    },
    "mode": "text",
    "simulated": true,
    "type": "ssh",
    "version": "0.6.0"
  }
}

access

What the caller may do here.

Needs the role view.

Result

FieldTypeDescription
rolestringview, operate or admin: each includes the ones before.
setupbooleanWhether an admin may set the server up over the network.
subject (optional)string | nullWhose access token it is, when it is one.
Request
{
  "id": 1,
  "op": "access"
}
Reply
{
  "id": 1,
  "result": {
    "role": "text",
    "setup": true,
    "subject": "text"
  }
}

Types

The named types used on this page.

Applied

What rookery recorded on a host when it applied the configuration: its own version, the plugins whose features the host has, and the provisioners those features offer.

FieldTypeDescription
offers (optional)Offer[]
plugins (optional)AppliedPlugin[]
rookerystring
tailnet (optional)TailnetDevice | null

HostType

What rookery does with a host: what its profile means it to be, or what it was seen to be. They are in the order of how much of rookery each has.

HostType

What rookery does with a host: what its profile means it to be, or what it was seen to be. They are in the order of how much of rookery each has.

Offer

Provisioners a feature of a host offers, as its tasks found them: rookery registers each under a name of its own that names the host. The host serves this to anyone who may read it, so it holds public values only, such as a server's certificate, never a key.

FieldTypeDescription
aliases (optional)map of string[]Other values of a setting that reach the same server, such as the name a rookery server on the host gives it: a provisioner registered by hand with one of them is named to its owner, who can make it the host's.
featurestringThe feature, as PLUGIN/FEATURE.
fingerprint (optional)stringWhat the host says identifies the server, such as the fingerprint of its certificate, for the person who reads the report.
provisionersstring[]The plugin's provisioners it offers, by their ids in the plugin.
secrets (optional)map of stringValues of the provisioners' secrets, such as the certificate of the server to pin, kept as the provisioners' own.
settings (optional)map of stringValues of the provisioners' own arguments. {address}, {user} and {port} stand for where rookery reaches the host and as whom.

AppliedPlugin

A plugin as it was when a host's configuration was applied.

FieldTypeDescription
digeststringSHA-256 of its files, so a change without a new version shows too.
idstring
packagestring
versionstring

TailnetDevice

A host's device on the tailnet, from tailscale status --json. It holds public values only, which the control server's API finds it by.

FieldTypeDescription
addresses (optional)string[]Its addresses on the tailnet.
dns_name (optional)stringIts MagicDNS name, such as studio.example.ts.net, without the final dot.
host_name (optional)stringThe machine's own hostname, as the client reports it.
idstringThe device's stable id: Tailscale's nodeId, or the number of Headscale's node.
tailnet (optional)stringThe tailnet's name, when the client knows it.

On this page