Skip to Content

rookery serve

The operations of rookery serve, on your machine.

The operations of rookery serve. Every operation of a host is one here too: on the portal with "host": "NAME" in the frame, over HTTP under /v1/hosts/NAME/controller. Only the controller's own secrets action is refused, for which the server's secrets action of the host sends the server's secrets, and endpoints.connect, which the server opens itself for resources.connect. An action's own role is asked when it runs. Each operation names the least role a caller over TCP needs: view, operate or admin.

Every operation of rookeryd is also an operation here: on the portal with "host": "NAME" in the frame, over HTTP under /v1/hosts/NAME.

OperationKindSummary
versioncallThe version of rookery serve and of its API.
accesscallWhat the caller may do here.
setup_key.checkcallWhether a setup key works, and the rookery serve it is for.
setup_key.claimcallCollect the server's token with a setup key. It can be asked again until the key is done.
setup_key.donecallEnd the setup key, once its user has the token.
hosts.listcallThe saved hosts and whether each answers.
hosts.getcallOne host: its address, and whether it answers.
hosts.removecallRemove a host's profile. The host itself is left as it is.
hosts.profilecallA host's profile, as it is saved.
hosts.savecallSave a host's profile: a new host, or a changed one. A host that is not a workstation needs only its type and access.
hosts.credentialscallThe passwords the server generated for a host's accounts.
hosts.actionscallWhat can be done to a host: the actions its controller lists, and rookery's own.
hosts.actcallRun one of a host's actions. One of rookery's that changes something is a job; an action of the host's controller is a session there, which a job follows unless it needs a terminal.
installation.actionscallWhat can be done to the installation as a whole, such as a roll-out over its hosts.
installation.actcallRun one of the installation's actions, as a job.
keys.listcallThe SSH keys of the server's key ring, by their public halves, with the hosts that log in with each and the key that replaces it while it rotates.
keys.addcallAdd a key to the ring: a new ed25519 key without a body, or the OpenSSH private key in the body, which may have no passphrase. The answer has its public half only.
keys.removecallRemove a key from the ring. Refused for the key rookery, while a host logs in with the key, and while it rotates.
keys.rotatecallReplace a key on every host that takes it, as a job: a new key beside it, and on each host the new one added, a login with it checked, and the old one removed. A host that does not answer stays pending; running it again goes on from there. When none is pending the old key is deleted.
secrets.listcallThe names of the secrets.
secrets.setcallSet a secret's value.
secrets.removecallRemove a secret.
secrets.renamecallGive a global secret another name.
registries.listcallThe registries.
registries.savecallAdd a registry, or change one.
registries.removecallRemove a registry with its stored login.
registries.renamecallGive a registry another name.
registries.checkcallWhether a registry answers and takes its login.
plugins.listcallThe plugins: those that come with rookery and the server's own.
plugins.addcallInstall a plugin with npm from a registry or an address.
plugins.uploadcallInstall a plugin from a .tgz, as npm pack makes one, which the server keeps.
plugins.removecallRemove one of the server's own plugins.
plugins.checkcallAsk the registries the server's own plugins came from whether they have newer versions.
plugins.updatecallUpdate one of the server's own plugins, or all, to the latest version of their registry, and say which hosts are behind then.
settings.listcallThe server's settings.
settings.setcallChange one of the settings that are open to callers, or any for the user the server runs as.
setup.cataloguecallWhat a new host starts from, and what plugins can install on one.
setup.generatecallMake up a host name, or hash or make up a password.
provisioners.listcallWhat the plugins can create machines and other resources with, what each asks for and can do, and whether it can be used here.
provisioners.typescallThe types of provisioner the plugins bring, which a provisioner is registered as.
provisioners.getcallA provisioner's page: what it says of itself now, such as whether its engine answers, and what it holds: rookery's resources, with what its own list says.
provisioners.savecallRegister a provisioner under a name of its own, of a type a plugin brings, or change the settings of one that is registered. A registered one keeps its type.
provisioners.removecallForget a registered provisioner, with its settings and the secrets it keeps of its own. It is kept while it holds resources.
provisioners.actionscallWhat can be done to a provisioner: its plugin's actions, and rookery's own settings of it.
provisioners.actcallRun one of a provisioner's actions. One that changes something is a job, which holds the provisioner's lock; one that only reads answers at once.
resources.listcallWhat provisioners made for rookery, as rookery's records have it. Nothing is asked of the provisioners.
resources.createcallCreate a resource with a provisioner, as a job: a host's machine, which is then set up as the host, or a kind its plugin declares, such as a deployment from a specification.
resources.getcallOne resource, as its provisioner says it is now. One it no longer finds is missing, and its record stays.
resources.changecallChange a resource, as a job: other values of its kind's arguments, a new specification, other secrets. What is not given stays.
resources.removecallRemove a resource with its provisioner, as a job, and forget it. A host's profile stays.
resources.actionscallWhat can be done to a resource: start, stop and change as its kind can, its plugin's actions of the kind, and removing it.
resources.actcallRun one of a resource's actions. One that changes something is a job of the resource, which holds its lock; one that only reads answers at once.
resources.logscallWhat a resource wrote, as its provisioner gives it, with secrets masked: the last lines as text, or as a WebSocket those and what follows.
resources.followstreamWhat a resource writes, as its provisioner gives it, with secrets masked: the last lines, then what follows.
resources.connectstreamA TCP connection to an endpoint its provisioner reported for a resource, named by the endpoint's name or its port. The server dials it first, so one that nothing answers on, or an address rookery refuses, is an error and not a stream.
jobs.listcallThe jobs, newest first.
jobs.getcallOne job's state.
jobs.followstreamA job's output as it is produced.
jobs.outputcallWhat a job wrote, by bytes or by lines.
jobs.stopcallStop a running job: its programs end, a session it follows ends on its host, and its record says who stopped it.
inbox.listcallMessages taken in from the hosts' channels.
inbox.followstreamMessages as they are taken in from the hosts.
inbox.donecallMark a message as done.
inbox.reopencallMark a message as open again.
kv.listcallThe keys of a namespace with their values.
kv.followstreamChanges to a namespace of the key-value store.
kv.getcallOne key's value and revision.
kv.setcallWrite a key, optionally only if nobody wrote in between.
kv.deletecallRemove a key.
events.followstreamChannel messages of chosen hosts, jobs, key-value changes and changes to hosts and resources together. The first frame sent names what to follow; each frame received says where it came from.