Ysra Docs
Open Ysra

Machine list reference

Look up every field in a gateway's machine list, ~/.ysra/targets.json, and which edits are safe to make by hand.

On this page

The machine list is the file ~/.ysra/targets.json on a gateway, with one entry per machine it reaches. Read it when you need to know what a field means or whether a hand edit is safe; for adding machines, use ysra machines add, ysra machines import or Settings → Machines, which check what you enter and pin the host key. The file kept its older name: machines used to be called “targets”.

Where it lives#

Property Value
Path ~/.ysra/targets.json, on the gateway only
Permissions 0600, inside ~/.ysra (0700)
Uploaded Never
Ysra’s servers see name, kind, via, cli, mode, production, groups, tags, environment
Never sent ssh_alias, host name, address, user, port, keys
Synced to another computer No, by design: add each machine again there and confirm its host key

Example#

[
  {
    "name": "edge-01",
    "kind": "linux",
    "via": "ssh",
    "ssh_alias": "edge-01",
    "mode": "observe",
    "production": false,
    "host_key_fingerprint": "SHA256:pV3n0cT7q…k9Q"
  },
  {
    "name": "lab-vcenter",
    "kind": "esxi",
    "via": "cli",
    "cli": "govc",
    "mode": "change",
    "production": true
  }
]

Fields#

Field Required Values What it does
name Yes Lowercase letters, digits, ., _, -; starts with a letter or digit; up to 63 characters What you and Ysra call the machine; also the name typed to confirm a destructive step on production
kind Yes linux, jetson, esxi, network, oss, other What sort of machine it is (jetson is set by ysra machines import)
via Yes ssh or cli How Ysra reaches it
ssh_alias When via is ssh A Host from your ~/.ssh/config Host, user, port and key come from your SSH config; none is copied here
managed_ssh No true Set by ysra machines import: the host lives in Ysra’s own ~/.ysra/targets/ssh_config, not yours
cli When via is cli One tool name, such as govc or kubectl The tool Ysra runs on the gateway with your sign-in. Not a shell, sudo, ssh or a scripting language
mode Yes observe or change observe: Ysra only reads. change: changes, each after your OK
production Yes true or false true: destructive commands need the machine’s name typed
reads No ask (default) or allowed allowed: Ysra may look without asking; see Let an unattended gateway look
groups, tags No Lowercase words such as site-a, up to 20 each Organise the inventory
environment No prod, staging, lab, dev Shown in the inventory
host_key_fingerprint SSH machines SHA256:… The fingerprint you confirmed, shown in lists; for display only

Editing it safely#

Change By hand? Better
mode Fine ysra machines mode <name> observe|change
production Fine ysra machines production <name> on|off
reads Fine ysra machines reads <name> allowed|ask
kind, groups, tags, environment Fine Import the CSV again
Add an SSH machine No ysra machines add: only that fetches, shows and pins the host key. An SSH machine without a pinned key is refused
Change ssh_alias No Remove the machine and add it again, so the new host’s key is checked
Rename a machine No Remove and add again; the pinned key and the log are kept under the name
host_key_fingerprint No Changing the text doesn’t change which key is pinned

Before a hand edit:

  1. Close Ysra, so it doesn’t write over your edit.
  2. Keep it valid JSON. If the file can’t be read, Ysra treats it as having no machines and says so; nothing is deleted.
  3. Keep it private: chmod 600 ~/.ysra/targets.json.
  4. Run ysra machines list to confirm it reads the way you meant.

There is no field for passwords, keys or tokens, and Ysra never uses one.

Path What
~/.ysra/targets/known_hosts The pinned host keys. Managed for you; don’t edit
~/.ysra/targets/ssh_config Addresses from ysra machines import. Your own ~/.ssh/config is never touched
~/.ysra/targets/<name>/log.jsonl What ran on that machine and who approved it. Kept when the machine is removed
YsraDocs