Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,22 +57,28 @@ through the `lockssh` CLI, run confined (as lea runs agents).

## Install

lockssh runs in Docker. With Homebrew (Linux or macOS):
lockssh runs in Docker. It also takes lockhub's `lox` v0.12.0 or later
([Quick start](#quick-start)) and cosign v2.5.0 or later: `lox add` and
`lox run` verify every image with cosign. The `lockfamily` meta formula
installs the whole family, lockssh, `lox` and cosign included. With Homebrew
(Linux or macOS):

```sh
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockssh
brew install davidgodefroid/tap/lockfamily
```

The formula installs the `lockssh` launcher and pins the release images by
digest, checked with cosign when the formula was bumped. Upgrade with
`brew upgrade lockssh`, not `lockssh update`. The `lockfamily` meta formula
installs the whole family, lockssh included, with lockhub's `lox`:
Or lockssh alone, with `lox` and cosign (the `lockssh` formula does not pull
them in):

```sh
brew install davidgodefroid/tap/lockfamily
brew install davidgodefroid/tap/lockssh davidgodefroid/tap/lox cosign
```

The formula installs the `lockssh` launcher and pins the release images by
digest, checked with cosign when the formula was bumped. Upgrade with
`brew upgrade lockssh`, not `lockssh update`.

Without Homebrew, download the install script from the release you install,
read it, then run it with that release:

Expand All @@ -85,7 +91,9 @@ LOCKSSH_VERSION=$V sh install.sh

It checks the release's cosign signatures and installs the `lockssh`
launcher, which runs every command in the signed image
`ghcr.io/davidgodefroid/lockssh:X.Y.Z`, by digest.
`ghcr.io/davidgodefroid/lockssh:X.Y.Z`, by digest. Install
[lockhub's `lox`](https://github.com/DavidGodefroid/lockhub) v0.12.0 or later
beside it.

- `lockssh version` prints the launcher's and the image's versions; `lockssh update` updates both.
- The release's `-vault` image adds the pinned Vault CLI for
Expand Down
5 changes: 4 additions & 1 deletion docs/docker.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,10 @@ on first use: `install.sh` checks the image's cosign signature too (and its
`-vault` variant's) and writes the verified digests into the launcher, which
runs the image by digest, never by a tag that could be moved. Linux and
macOS (Docker Desktop); on Windows, install it in WSL 2 with Docker
Desktop's WSL integration and run it there.
Desktop's WSL integration and run it there. The console also takes
lockhub's `lox` v0.12.0 or later and cosign v2.5.0 or later: `lox add` and
`lox run` verify every image with cosign. The `lockssh` Homebrew formula
pulls in neither; the `lockfamily` meta formula installs both.

```sh
lockssh version # the launcher's version and its image's
Expand Down
4 changes: 2 additions & 2 deletions site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ <h1 id="hero-title">Your agent runs the command. <span class="key">You hold the
<pre tabindex="0" aria-label="Set-up commands"><code><span class="cmd">lox init</span>
<span class="cmd">lox add lockssh</span>
<span class="cmd">lox run</span></code></pre>
<p class="install-note">lockssh v0.3 takes lockhub’s <code>lox</code> v0.12.0 or later: an older one does not know it or its confined agents. Docker on Linux or macOS; <code>brew install davidgodefroid/tap/lockfamily</code> installs both, or the launcher of the <a href="install/">install guide</a>.</p>
<p class="install-note">lockssh v0.3 takes lockhub’s <code>lox</code> v0.12.0 or later: an older one does not know it or its confined agents. Docker on Linux or macOS; <code>brew install davidgodefroid/tap/lockfamily</code> installs both and cosign v2.5.0 or later, which <code>lox</code> verifies every image with; or the launcher of the <a href="install/">install guide</a>.</p>
</div>
<div class="actions">
<a class="button primary" href="install/">Install guide</a>
Expand Down Expand Up @@ -161,7 +161,7 @@ <h2 id="highlights">Highlights</h2>
<section aria-labelledby="quick-start">
<h2 id="quick-start">Quick start</h2>
<ol class="steps prose">
<li><p>Install the <code>lockssh</code> launcher and lockhub’s <code>lox</code> v0.12.0 or later, or both with <code>brew install davidgodefroid/tap/lockfamily</code> (<a href="install/">install guide</a>). Docker must be running.</p></li>
<li><p>Install the <code>lockssh</code> launcher and lockhub’s <code>lox</code> v0.12.0 or later and cosign v2.5.0 or later, or all three with <code>brew install davidgodefroid/tap/lockfamily</code> (<a href="install/">install guide</a>). Docker must be running.</p></li>
<li><p>In your project, write a <code>lockfamily.yaml</code> with the hub alone (once):</p>
<pre tabindex="0"><code>lox init</code></pre></li>
<li><p>Add an SSH host: host, port, login, key file in the lock’s home, allow rules. Never a secret.</p>
Expand Down
7 changes: 4 additions & 3 deletions site/install/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,12 @@ <h1>Install lockssh</h1>
<h2 id="status">Where things stand</h2>
<div class="prose">
<p>lockssh v0.3.0 is the latest release. <code>lox add lockssh</code> and <code>lox run</code> serving it ship in lockhub v0.11.0 (<a href="https://github.com/DavidGodefroid/lockhub/issues/133">lockhub#133</a>), and lockssh v0.3.0’s confined agents in v0.12.0; an older <code>lox</code> does not know lockssh and cannot start its console. <code>lox add lockssh</code> pins the latest signed lockssh release.</p>
<p>lockssh has a Homebrew formula, on Linux and macOS. The <code>lockfamily</code> meta formula installs the whole family, lockssh and lockhub’s <code>lox</code> included; or install lockssh by name.</p>
<p>lockssh has a Homebrew formula, on Linux and macOS. The <code>lockfamily</code> meta formula installs the whole family, lockssh, lockhub’s <code>lox</code> and cosign included. The <code>lockssh</code> formula alone pulls in neither <code>lox</code> nor cosign: name them with it.</p>
</div>
<div class="install">
<div class="install-head"><span>lockssh, with Homebrew</span></div>
<pre tabindex="0" aria-label="Install commands"><code><span class="cmd">brew trust davidgodefroid/tap</span>
<span class="cmd">brew install davidgodefroid/tap/lockfamily</span> <span class="cmt"># or davidgodefroid/tap/lockssh alone</span></code></pre>
<span class="cmd">brew install davidgodefroid/tap/lockfamily</span> <span class="cmt"># or lockssh alone, with lox and cosign: brew install davidgodefroid/tap/lockssh davidgodefroid/tap/lox cosign</span></code></pre>
<p class="install-note">Homebrew asks you to trust a third-party tap once. Upgrade with <code>brew upgrade lockssh</code>. Without Homebrew, install the launcher, below.</p>
</div>
</section>
Expand All @@ -78,7 +78,8 @@ <h2 id="status">Where things stand</h2>
<h2 id="requirements">Requirements</h2>
<ul class="prose">
<li><strong>Docker</strong>, on Linux or on macOS (Docker Desktop). On Windows, install in WSL 2 with Docker Desktop’s WSL integration and run it there.</li>
<li><strong><a href="https://docs.sigstore.dev/cosign/system_config/installation/">cosign</a></strong> on <code>PATH</code>, for the install script and <code>lockssh update</code>: they check the release’s and the image’s signatures.</li>
<li><strong>lockhub’s <a href="https://github.com/DavidGodefroid/lockhub"><code>lox</code></a> v0.12.0 or later</strong>: it starts the console and serves your decisions.</li>
<li><strong><a href="https://docs.sigstore.dev/cosign/system_config/installation/">cosign</a> v2.5.0 or later</strong> on <code>PATH</code>: <code>lox add</code> and <code>lox run</code> verify every image with it, and the install script and <code>lockssh update</code> check the release’s and the image’s signatures.</li>
<li><strong>An SSH account for lockssh</strong> on each server, with only the rights the allow list needs: a user of its own, no <code>sudo</code>, read access to the logs it must read. Its login shell must be a POSIX shell.</li>
</ul>
</section>
Expand Down
Loading