Say which machine each setting is about, and stop defaulting to root #3

2026-08-28T16:44:22-07:00

dejima-agent commented

2026-08-28 16:44:22 -07:00

Summary generated by LLM agent

Both reported while setting this up. The second is a defect rather than a documentation gap.

`DEJIMA_GUARD_HOST` named the wrong end of the connection

It read as the host the guard runs on. It meant the one it watches — the wrong end of the only connection this program makes, and the kind of mistake that produces a guard pointed at itself.

A name that needs a comment to be read correctly is the wrong name. So: devbox_host and devbox_user, grouped under a heading that says everything in it describes the machine at the other end.

`devbox_user` defaulted to root

On a machine whose own runbook builds it with no root password, expecting sudo from an ordinary account. The default was wrong for every devbox built the documented way.

There is no default now. Falling back to nothing would be no better — ssh would use the local username, which in a container is an account that does not exist on the devbox — so it names the missing setting instead.

This pairs with dejima-devbox-hardener#22, which adds the authorized_keys forced command and the sudoers rule the guard now needs on the other side.

Documentation for every setting

Three places, because they are read at different moments:

A table in the README, saying what goes in each one.
etc/config.example, the same list with the reasoning attached — why the ntfy topic must not be dejima's, why ssh_known_hosts has to persist, why there is no default account.
docker-compose.example.yml, a comment per variable rather than a bare list, since that is the file somebody actually edits.

Tested

bats test/ — 26 passing, 3 new beyond the rename:

no setting is named so that it could mean this machine — a grep guard, so the ambiguity cannot come back by someone adding host for brevity;
a missing devbox_user is refused rather than guessed;
the two SSH commands still match what the devbox permits. dejima-guard-shell over in the hardener whitelists those two strings exactly. One contract across two repositories, and if it drifts the symptom is a failed collection reported as the devbox being unreachable — true, and misleading.

Still not run

No docker here, and ssh/curl are stubbed. The compose file and Dockerfile remain reviewed rather than tested.

**Summary generated by LLM agent** Both reported while setting this up. The second is a defect rather than a documentation gap. ## `DEJIMA_GUARD_HOST` named the wrong end of the connection It read as *the host the guard runs on*. It meant *the one it watches* — the wrong end of the only connection this program makes, and the kind of mistake that produces a guard pointed at itself. A name that needs a comment to be read correctly is the wrong name. So: `devbox_host` and `devbox_user`, grouped under a heading that says everything in it describes the machine at the other end. ## `devbox_user` defaulted to root On a machine whose own runbook builds it **with no root password**, expecting sudo from an ordinary account. The default was wrong for every devbox built the documented way. There is no default now. Falling back to nothing would be no better — ssh would use the local username, which in a container is an account that does not exist on the devbox — so it names the missing setting instead. This pairs with [dejima-devbox-hardener#22](https://gitbox.branderson.io/dejima/dejima-devbox-hardener/pulls/22), which adds the `authorized_keys` forced command and the sudoers rule the guard now needs on the other side. ## Documentation for every setting Three places, because they are read at different moments: - **A table in the README**, saying what goes in each one. - **`etc/config.example`**, the same list with the reasoning attached — why the ntfy topic must not be dejima's, why `ssh_known_hosts` has to persist, why there is no default account. - **`docker-compose.example.yml`**, a comment per variable rather than a bare list, since that is the file somebody actually edits. ## Tested `bats test/` — 26 passing, 3 new beyond the rename: - **no setting is named so that it could mean this machine** — a grep guard, so the ambiguity cannot come back by someone adding `host` for brevity; - **a missing `devbox_user` is refused rather than guessed**; - **the two SSH commands still match what the devbox permits.** `dejima-guard-shell` over in the hardener whitelists those two strings exactly. One contract across two repositories, and if it drifts the symptom is a failed collection reported as the devbox being unreachable — true, and misleading. ## Still not run No docker here, and `ssh`/`curl` are stubbed. The compose file and Dockerfile remain reviewed rather than tested.

dejima-agent added 1 commit 2026-08-28 16:44:23 -07:00

Say which machine each setting is about, and stop defaulting to root 9c71beeea2

Two reports from setting this up, and the second is a real defect rather
than a documentation one.

DEJIMA_GUARD_HOST READ AS THE HOST THE GUARD RUNS ON. It meant the one it
watches - the wrong end of the only connection this program makes. A name
that needs a comment to be read correctly is the wrong name, so it is
devbox_host and devbox_user now, under a heading that says everything in that
group describes the machine at the other end.

AND devbox_user DEFAULTED TO ROOT, on a machine whose own runbook builds it
with no root password and expects sudo from an ordinary account. The default
was wrong for every devbox built the documented way. There is no default now:
falling back to nothing would have ssh use the local username, which in a
container is an account that does not exist over there, so it says which is
missing instead.

Every setting is documented twice over: a table in the README saying what
goes in it, and etc/config.example with the reasoning attached. The compose
example carries a comment per variable rather than a bare list, since that is
the file somebody actually edits.

Three tests worth having beyond the rename: that no setting is named so it
could mean this machine, that a missing devbox_user is refused rather than
guessed, and that the two SSH commands still match the strings
dejima-devbox-hardener's dejima-guard-shell whitelists - one contract across
two repositories, and the failure if it drifts is a collection that fails and
gets reported as the devbox being unreachable.

`bats test/` 26 passing, 3 new.

branderson approved these changes 2026-08-28 16:48:15 -07:00

branderson merged commit a40e3da41a into main

2026-08-28 16:48:23 -07:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dejima/dejima-guard#3