Skip to Content

Start, stop, copy and remove

Starting and stopping a host, copying it under another name, and what removing it keeps or destroys.

A host has four actions for its life as a machine, which are Start, Stop, Duplicate and Remove. They are listed on its overview with the other actions, and rookery action list HOST lists them too. Each says whether it can run now, and why not when it can't. Each that changes something runs as a job of the server.

ActionCommandRole
startrookery host start studiooperate
stoprookery host stop studiooperate
duplicaterookery host duplicate studio attic [--create]admin
removerookery host remove studio [--destroy]admin

rookery run studio ACTION NAME=VALUE runs them as well, such as rookery run studio remove destroy=yes --yes.

Starting and stopping

A host declares whether it can be started and stopped. Rookery says so in power of the host in hosts.list and hosts.show:

"power": { "start": true, "stop": true, "state": "stopped", "start_by": "provisioner", "stop_by": "provisioner" }

start and stop say whether Rookery can do either. state is running, stopped or unknown: running when the host's controller answers, and otherwise what its provisioner said last. start_by and stop_by name the way.

The hostStarted byStopped by
Made by a provisioner whose machines have the verbs start and stopThe provisionerThe provisioner, which keeps the disk
Made by a provisioner without themNothingWhat the profile's power.stop says, or nothing
Any other hostNothingWhat the profile's power.stop says, or nothing

A host that declares nothing can be neither started nor stopped, and the action's reason says so. To let a host's controller shut it down, set the way in its profile:

rookery host set forge power_stop=controller

For a host installed over SSH, the Stopped by row on the Install tab of its set-up sets the same field. Stopping by the controller ends the sessions on the host. The controller refuses while sessions run, unless you stop it with rookery run forge stop force=yes. Rookery can't start such a host again, as nothing of Rookery runs on it while it's off: it's started by hand, or by whatever powers it. The profile reference lists the field.

The home screen shows a host that is off as ◌ stopped rather than as a host that doesn't answer. s starts the selected host when Rookery can start it.

Duplicating a host

rookery host duplicate studio attic

This saves a copy of studio's profile as the host attic. The copy leaves out what belongs to the one machine:

WhatIn the copy
What is installed, the accounts, features, secrets and registries by nameYes
The SSH user, port and auth that Rookery logs in withYes
The hostnameNo. The copy takes its own name
The address, and the command Rookery connects to it with. The address is also its name on a tailnetNo
The hashes of the passwords Rookery generated, and those passwordsNo. A hash you typed stays
The host keys Rookery recorded, the passwords it logs in with, its jobs and messagesNo
The record of what was applied to itNo. That stays on the machine
Its device on the tailnetNo. The copy joins as a device of its own

The disk isn't cloned. The new host is installed from its profile, as any other.

When a provisioner made studio's machine, the copy's machine is planned with the same provisioner and the same settings. It's shown as planned and is not made yet. The copy's Run tab offers Create with those settings, and rookery host create attic makes it. With --create, or create=yes, the same job makes it at once.

Rookery refuses the copy when a host has the new name already.

Removing a host

rookery host remove studio

This forgets the host with its profile. The passwords Rookery generated and its host keys go with it. The machine is left as it is. Rookery asks first, and --yes answers.

When a provisioner made the host's machine, removing it without --destroy keeps the machine's record as a resource of that provisioner with no host. rookery resource list shows it, and rookery resource remove ID deletes it later.

rookery host remove studio --destroy

With --destroy, or destroy=yes, the provisioner destroys the machine with its disk first, and then Rookery forgets the host. The question before it says which provisioner and which machine. For a host no provisioner made, --destroy is refused, as there is nothing for Rookery to destroy. If destroying fails, the host and its machine's record stay, so you can try again.

Once the machine is destroyed, Rookery also removes its device on the tailnet. When it can't, such as without the API key or with a key that may not remove devices, the job says why and Rookery forgets the host all the same. Remove the device in the tailnet's admin console then. Without --destroy, the device stays.

On the home screen, x asks the same. For a host a provisioner made, f forgets it and leaves the machine, and d destroys the machine too, after asking once more.

Edit on GitHub

Last updated on

On this page