Ysra Docs
Open Ysra

targets.json

The file your targets are kept in: where it lives, what each field means, and how to edit it safely.

On this page

Your targets are kept in one file:

~/.ysra/targets.json

It lives only on your computer. It's readable and writable by you alone (mode 0600, inside ~/.ysra, which is 0700). It's never uploaded. Ysra's servers learn each target's name, kind, via, cli, mode and production, so I know what I can ask for. They never learn ssh_alias, a host name, an address, a user or a port.

Tip

Prefer the commands (ysra target …) or Settings → Targets. They check what you enter and pin the host key. Edit the file by hand only for the cases listed under Editing it safely.

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

The file is a list. Each entry is one target.

Fields#

Field Required Values Meaning
name Yes Lowercase letters, digits, ., _, -. Starts with a letter or digit. Up to 63 characters What you and I call the target. Also the name you type to confirm a destructive step on production
kind Yes linux, esxi, network, oss, other What sort of machine it is
via Yes ssh or cli How I reach it
ssh_alias When via is ssh A Host from your ~/.ssh/config The host, user, port and key all come from your SSH config. None of that is copied here
cli When via is cli One tool name, for example govc, kubectl The command-line tool I run on your computer with your sign-in. Not a shell, sudo, ssh or a scripting language
mode Yes observe or change observe: I only read. change: I may run changes, each after your OK
production Yes true or false true: destructive commands need the target's name typed
host_key_fingerprint SSH targets SHA256:… The fingerprint you confirmed when adding the target. Shown in lists so you can recognise it. For display

Editing it safely#

Change By hand? Better
mode Fine ysra target mode <name> observe\|change
production Fine ysra target production <name> on\|off
kind Fine —
Add an SSH target No ysra target add. Only adding it properly fetches the host key, shows you the fingerprint and pins it. An SSH target without a pinned key is refused
Change ssh_alias No Remove the target and add it again, so the new host's key is checked
Rename a target 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

If you do edit by hand:

  1. Close Ysra first, so it doesn't write over your edit.
  2. Keep it valid JSON. If the file can't be read, I treat it as having no targets and say so. Nothing is deleted.
  3. Keep it private: chmod 600 ~/.ysra/targets.json.
  4. Run ysra target list to confirm it reads the way you meant.

Don't put passwords, keys or tokens in this file. There's no field for them, and I never use one.

Path What
~/.ysra/targets/known_hosts The pinned host keys. Managed for you; don't edit
~/.ysra/targets/<name>/log.jsonl What ran on that target and who approved it. Kept when the target is removed

Moving to another computer#

Targets don't sync, by design. On the new computer, add each one again with ysra target add and confirm its host key there.

YsraDocs