diff --git a/README-install.md b/README-install.md index a66aec1a..88943b91 100644 --- a/README-install.md +++ b/README-install.md @@ -8,24 +8,26 @@ operator-supplied candidate until a compatible signed release is published. ## Install with apt on Ubuntu 24.04 amd64 -Use this route when your operator supplies a published apt repository, its -OpenPGP key fingerprint and an exact Debian package version. Verify the key +The official public apt channel is not yet published. Use this route only when +your operator supplies a published apt repository, its OpenPGP key fingerprint +and an exact Debian package version. Verify the key through an independent trusted channel, then install the operator's keyring and repository configuration with `Signed-By` scoped to that keyring. Follow the -complete [apt setup procedure](docs/operations/apt-repository.md); no official -live repository URL or production signing key is implied by this guide. +complete [apt setup procedure](docs/operations/apt-repository.md). ```sh sudo apt-get update sudo apt-get install debuglet=DEBIAN_VERSION_PROVIDED_BY_OPERATOR -dbl --output json version -dbl demo +/usr/bin/dbl --output json version +/usr/bin/dbl demo ``` The `debuglet` package selects the matching full payload, including the CLI, -executor, dispatcher and bundled samples. Installation stages software; choose -account setup, executor enrollment and service activation explicitly. Upgrades -retain payloads referenced by managed services. Follow the [Debian lifecycle +executor, dispatcher and bundled samples. Installation creates a missing +`debuglet` system account and the parent state directories. Account registration, +executor enrollment and service activation remain explicit. Use `/usr/bin/dbl` +to avoid selecting an older tar installation on `PATH`. Upgrades retain payloads +referenced by managed services. Follow the [Debian lifecycle procedure](docs/operations/debian.md) to drain, back up, replace and resume an existing service. Tar installation remains available below. @@ -59,6 +61,20 @@ service account, or restart an existing service; follow [executor setup](docs/operations/executor-onboarding.md) or [managed services](docs/operations/services.md) next. +For a system-wide candidate used by a managed service, run this command instead +of the user-local installation above, with the same trusted inputs: + +```sh +sudo env DEBUGLET_VERSION=VERSION_PROVIDED_BY_OPERATOR \ + DEBUGLET_RELEASE_DIR="$HOME/Downloads/debuglet-candidate" \ + DEBUGLET_ALLOW_UNSIGNED=1 DEBUGLET_PREFIX=/usr/local \ + sh "$HOME/Downloads/bootstrap.sh" +/usr/local/bin/dbl --output json version +``` + +Tar installation leaves service-account creation to the +[persistent executor setup](docs/operations/executor-onboarding.md#run-persistently-on-linux). + ## Install a signed release Once your operator identifies an exact published version with signed assets, diff --git a/README.md b/README.md index fefed4e7..e2d41754 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ The versioned guides in [`docs/`](docs/README.md) are published at the [document | Need | Start here | | --- | --- | | Install and run a local demo | [Install Debuglet](README-install.md) | +| Run a first console measurement | [HTTP check and two-executor comparison](docs/measurements.md#run-your-first-measurement) | | Use the CLI | [CLI reference](docs/cli.md) | | Write a Go application client | [Go client library](docs/client.md) | | Write a debuglet | [Write a debuglet](docs/debuglets.md) | diff --git a/docs/README.md b/docs/README.md index e612346c..1b870578 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,6 +4,7 @@ This directory is the versioned source for the [Debuglet documentation site](htt ## Use Debuglet +- [Run your first measurement](measurements.md#run-your-first-measurement) — use the console to check an HTTP endpoint, read its result and compare two executors. - [CLI reference](cli.md) — commands, local demo, and scriptable workflows. - [Go client library](client.md) — submit debuglets and read results from an application. - [Reusable and coordinated measurements](measurements.md) — saved profiles, retries and experiments across executors. @@ -28,6 +29,7 @@ This directory is the versioned source for the [Debuglet documentation site](htt - [Configuration reference](operations/configuration.md) - [Run Debuglet across hosts](operations/remote-deployment.md) - [Add your executor](operations/executor-onboarding.md) — console enrollment, shell-only setup and persistent installation. +- [Debian installation and updates](operations/debian.md) — apt packages, explicit service activation and retained rollback payloads. - [Managed services](operations/services.md) - [Data retention, export and deletion](operations/data-retention.md) - [Chain payments](operations/payments.md) — modes, the supported Sui Testnet profile, startup validation, transfers and enablement. diff --git a/docs/measurements.md b/docs/measurements.md index 92d40b70..54c60313 100644 --- a/docs/measurements.md +++ b/docs/measurements.md @@ -1,9 +1,74 @@ -# Reusable measurements and deliberate retries - -HTTP API 1.12 adds saved profiles, durable batch details, linked retries and TCP -listener readiness. These operations use the same account ownership checks as -run output. The companion console exposes the catalogue, profiles, measurement -history and editable new requests. +# Run and reuse measurements + +## Run your first measurement + +Use this walkthrough on a deployment whose operator confirms compatible console, +dispatcher and executor versions and provides the console URL. + +Ask the operator for a health endpoint they own that returns a small **HTTP 200** +response and is permitted from the chosen executor. For example, +`https://service.example/health` is a placeholder: replace it with that endpoint's +complete URL, including the correct scheme, port and path. A public website is +not a guaranteed test target. The console cannot inspect the operator's private +destination and port restrictions in advance. + +1. Sign in and open **New measurement**. Choose **HTTP timing & status** and + enter the approved URL in **HTTP target**. Leave **Response time threshold** + empty for this first check. +2. Under **Vantage point**, select an executor marked **Available** and + **TEST · no wallet**. Open **Node details** to check its identity and reported + capabilities. Availability does not prove that your target is permitted or + reachable. +3. Choose **Review measurement**. Check the executor, endpoint, **Permitted + destinations**, timeout and bandwidth. Keep the immediate start and default + limits if the deployment accepts them, then choose **Run with TEST**. +4. On the run page, wait for **All program output received.** Inspect + **Measurement results** for **Checks passed**, **HTTP status** `200`, + **Time** and **Response body**. Check the **Raw program output** JSON too: + its `schema` is `debuglet.measurement.v1`, `template` is `http`, and `ok` and + the check's `ok` should be `true`. Keep the run ID from **Run details**; + **Download output** saves the received program output. + +TEST needs no wallet. If the dispatcher enforces TEST allowances, your account +also needs enough operator-granted units; signing up does not grant them +automatically. See [TEST allowances](operations/configuration.md#dispatcher-usage-allowances). + +The template preserves `http://` or `https://` as entered; HTTPS uses TLS. It +makes one GET request and requires a 2xx response. It does not follow redirects. +**Time** measures the whole HTTP check, including connection setup, TLS when +used, request transmission and reading the response body. Service processing +contributes to it; this is not a pure network round-trip time (RTT). + +An **exited** state means execution ended, not that the check passed. A parsed +result can appear before all output arrives. Confirm the result, execution state +and output completeness separately; **All program output received.** alone +does not mean success. + +| What you see | Next step | +| --- | --- | +| No available executor, **Offline** or **Maintenance** | Wait for readiness or ask the operator; the list refreshes automatically. | +| Target denied by the operator network policy | Ask for a permitted endpoint or an executor whose policy permits it. Changing HTTP to HTTPS does not grant permission; do not bypass the policy. | +| **Checks failed** with HTTP 3xx | Use the final URL only if the operator approves it. A redirect fails the template's 2xx expectation. | +| Output still arriving, incomplete or completeness unconfirmed | Wait while output arrives; reload if completeness is unconfirmed. Keep incomplete output marked as incomplete rather than inferring success. | + +## Compare two executors + +1. Open **Grouped measurement**, choose **Compare HTTP responses**, and enter + the same approved **HTTP target**. Confirm that both operators permit it. +2. Under **Choose your nodes**, select two available TEST executors. Keep the + same timeout, bandwidth and response threshold for both. Choose **Review + group**, check both participants and their permitted destinations, then + **Submit group with TEST**. +3. On **Grouped measurement**, open **Details and output** for each participant. + Check its complete output and result as above, then compare HTTP status, + response size and time alongside the executor and run IDs. **Export group + results** saves a snapshot; it can still contain running participants or + incomplete output. + +These are two independent HTTP probes in one submission. They do not wait for a +synchronized start, and one sample per executor does not establish a stable +latency difference. For coordinated programs, see +[Coordinate a batch of debuglets](#coordinate-a-batch-of-debuglets). ## Save and apply a profile diff --git a/docs/operations/debian.md b/docs/operations/debian.md index ae439285..25b43a83 100644 --- a/docs/operations/debian.md +++ b/docs/operations/debian.md @@ -1,10 +1,10 @@ # Debian packages -The initial apt target is **Ubuntu 24.04 amd64**. Install the `debuglet` package -from a reviewed signed repository following [repository setup](apt-repository.md). +The initial apt target is **Ubuntu 24.04 amd64**. The official public apt channel +is not yet published. When your operator supplies a reviewed signed repository, +install the `debuglet` package following [repository setup](apt-repository.md). Use the independently supplied OpenPGP fingerprint and a dedicated `Signed-By` -keyring; an archive checksum alone does not establish trust. No official live -repository URL is assumed by these instructions. +keyring; an archive checksum alone does not establish trust. `debuglet` selects the commands `/usr/bin/dbl`, `/usr/bin/debuglet-executor` and `/usr/bin/debuglet-dispatcher`. Its exact dependency is a separately named @@ -26,43 +26,46 @@ read-only removal guard; it adds no background process. ## Enrollment and activation Use `/usr/bin/dbl` explicitly if an older tar-installed command appears earlier -on `PATH`. Follow [executor onboarding](executor-onboarding.md) to register, -establish trust and join using the service account. Joining creates the named -executor's state directory under `/var/lib/debuglet/executors`. Install and -activate that enrolled executor explicitly with the documented service command. +on `PATH`. Follow [persistent executor onboarding](executor-onboarding.md#run-persistently-on-linux) +with `dbl_cli=/usr/bin/dbl`; skip its tar-only account setup. Join with `sudo` +to create the named executor's private state under `/var/lib/debuglet/executors`. +The service installer assigns that state to the `debuglet` account. Install, +start and check the enrolled service explicitly with the documented commands. Dispatcher and local demo setup remain explicit as described in [services](services.md). ## Updates and rollback -An apt update stages a new full payload and switches the three command links. +Installing a newer `debuglet` version stages a full payload and switches the +three command links. `apt-get update` alone only refreshes repository metadata. It leaves running and stopped managed services on their previously recorded absolute payload paths. Even `apt upgrade` does not restart, enroll, migrate or -replace a managed service. Inspect the selected payload with: +replace a managed service. Select the exact operator-approved version and inspect +its payload before maintenance: ```sh +sudo apt-get update +sudo apt-get install debuglet=DEBIAN_VERSION_PROVIDED_BY_OPERATOR dpkg-query -W -f='${Version}\n' debuglet candidate=$(dirname "$(dirname "$(readlink -f /usr/bin/dbl)")") -printf '%s\n' "$candidate" +replacement_cli="$candidate/bin/dbl" +"$replacement_cli" --output json version ``` -For an enrolled executor, follow the [release rollout](release-rollout.md): -drain it, create and verify an offline backup of its complete identity, keys, -trust, configuration, database, outputs and service records, then use the -verified replacement command while the unit is stopped and disabled: - -```sh -sudo /usr/bin/dbl service install --role executor --name worker \ - --enrolled-state /var/lib/debuglet/executors/worker \ - --replace-package "$candidate" --start=false --enable=false -``` - -Use the recorded instance name instead of `worker`. Replacement preserves its -service account, state paths and identity. Check compatibility and explicitly -resume using the rollout procedure. Rollback selects a retained older payload -with the same replacement command and is subject to database compatibility; -an apt downgrade alone does not roll back a service or a database. Existing -dispatcher replacement limits are unchanged; see the rollout documentation. +For an enrolled executor, use the +[controlled replacement procedure](services.md#replace-an-enrolled-executors-package) +with this candidate; its tar staging command is unnecessary. Use the recorded +instance name throughout. The procedure requires a drain with `joined: true` +and `enabled: false`, a verified private offline backup of the complete state, +identity and service records, and retention of the previous payload. Replacement +preserves the account, state paths and identity; it does not migrate or enroll +again. Explicitly resume after success, check readiness and the connected version, +then complete a permitted TEST measurement. + +Rollback uses the replacement-capable CLI to select a retained older payload and +requires compatible state; an apt downgrade alone does not roll back a service +or database. The linked procedure covers interrupted replacement, rollback and +unsupported dispatcher replacement. Release `v1.2.3` has Debian version `1.2.3-1`; prerelease `v1.2.3-rc.1` becomes `1.2.3~rc.1-1`, which sorts before the final release. Development versions such diff --git a/docs/operations/executor-onboarding.md b/docs/operations/executor-onboarding.md index 9de81be3..5ac4ce0c 100644 --- a/docs/operations/executor-onboarding.md +++ b/docs/operations/executor-onboarding.md @@ -5,13 +5,18 @@ machine to a dispatcher that supports account-owned enrollment. Your existing account owns the machine; it does not need dispatcher administrator privileges. 1. Give the machine a name. It appears as **Awaiting setup** until enrollment. -2. Install a Debuglet package that provides `dbl executor join`. Use the package - recommended by the service operator. The published v0.2.0 package predates - this command. -3. Copy the setup command from the console and run it on the executor machine: +2. Install the operator's compatible **full** package using the + [installation guide](../../README-install.md). Set `dbl_cli=/usr/bin/dbl` for + apt, `dbl_cli=/usr/local/bin/dbl` for system-wide tar, or + `dbl_cli="$HOME/.local/bin/dbl"` for user-local tar. Confirm + `"$dbl_cli" --output json version` matches the supplied version and source + revision. The published v0.2.0 package predates `executor join`. +3. Use the setup values from the console with that selected CLI on the executor + machine. For a system service, follow [persistent setup](#run-persistently-on-linux) + instead of this terminal trial: ```sh - dbl executor join --dispatcher https://debuglet.example/api \ + "$dbl_cli" executor join --dispatcher https://debuglet.example/api \ --executor YOUR-EXECUTOR-ID --state-dir ./debuglet-node ``` @@ -45,8 +50,9 @@ states do not certify its geographic location, measurement results or uptime. The executor needs no browser or graphical desktop. Open the console on your laptop, create the executor, then SSH into the Linux machine and install the -compatible full bundle. Run its displayed `dbl executor join` command there and -paste the token at the hidden prompt. For a system service, use the canonical +compatible full bundle. Select `dbl_cli` in that SSH shell as above, then run +`"$dbl_cli" executor join` with the displayed values and paste the token at the +hidden prompt. For a system service, use the canonical state directory in [persistent setup](#run-persistently-on-linux) from the start. For a terminal trial or container, run the printed start command and keep its process and state directory. A container's supervisor is managed separately. @@ -54,8 +60,9 @@ process and state directory. A container's supervisor is managed separately. ### Without a browser anywhere For a dispatcher that allows account-key registration, the existing CLI and -HTTP API support the whole setup. This example needs `dbl`, `curl` and `jq` and -uses a **publicly trusted HTTPS API**, including its `/api` prefix if present. +HTTP API support the whole setup. Select `dbl_cli` as above; this example also +needs `curl` and `jq` and uses a **publicly trusted HTTPS API**, including its +`/api` prefix if present. It creates a new ordinary account and one executor; run it once. The private setup directory keeps keys, recovery data and API responses out of command arguments. Do not print these files or include them in shared logs. @@ -68,8 +75,8 @@ umask 077 api=https://debuglet.example/api setup_dir="$HOME/debuglet-operator" mkdir -m 700 "$setup_dir" # Fails if it exists; do not overwrite saved credentials. -dbl --config "$setup_dir/connections.toml" connect "$api" --name operator -dbl --config "$setup_dir/connections.toml" --dispatcher operator login \ +"$dbl_cli" --config "$setup_dir/connections.toml" connect "$api" --name operator +"$dbl_cli" --config "$setup_dir/connections.toml" --dispatcher operator login \ --register 'Shell operator' --account-key-file "$setup_dir/account-key.txt" \ --recovery-file "$setup_dir/recovery.txt" @@ -86,7 +93,7 @@ curl --proto '=https' --fail --silent --show-error \ --output "$setup_dir/executor.json" executor_id=$(jq -er '.executor.id' "$setup_dir/executor.json") jq -er '.token' "$setup_dir/executor.json" > "$setup_dir/setup-token.txt" -dbl executor join --dispatcher "$api" --executor "$executor_id" \ +"$dbl_cli" executor join --dispatcher "$api" --executor "$executor_id" \ --state-dir "$HOME/debuglet-node" --token-file "$setup_dir/setup-token.txt" rm "$setup_dir/setup-token.txt" "$setup_dir/executor.json" "$setup_dir/login.json" ``` @@ -107,7 +114,7 @@ Do not enroll into the trial directory first; the service installer does not move identities. Remove the setup token and response after enrollment succeeds. For an existing account, reuse its private directory and replace registration -with `dbl --config "$setup_dir/connections.toml" --dispatcher operator login +with `"$dbl_cli" --config "$setup_dir/connections.toml" --dispatcher operator login --account-key-file "$setup_dir/account-key.txt"`; skip `mkdir` and `--register`. Do not create another account to restart an executor. An uncertain executor-create response should be checked with `GET /operator/executors` before repeating it. @@ -125,7 +132,7 @@ rm "$setup_dir/session.json" "$setup_dir/auth.header" The CLI's separately saved session remains available. If the service requires browser OAuth, use its console on another computer and the SSH flow above; these commands do not implement headless OAuth. For a privately certified API, -pass its public CA file to `dbl connect --ca-file /path/to/api-ca.crt`; this +pass its public CA file to `"$dbl_cli" connect --ca-file /path/to/api-ca.crt`; this trust is saved for subsequent CLI commands. The `curl --cacert` and `join --ca-file` options must trust that API certificate. No account session or recovery file is needed by @@ -133,33 +140,41 @@ the running executor; retain its generated identity and database for later start ## Run persistently on Linux -For a Linux amd64 machine with systemd, first install the operator-recommended -**full** bundle under `/usr/local` using the [installation guide](../../README-install.md). -The CLI-only bundle cannot run an executor. Verify the exact version with -`/usr/local/bin/dbl --output json version` before enrollment. For an unpublished -candidate, use the guide's trusted local package directory and explicit unsigned -candidate option; do not use an invented release URL. Package installation does -not create a service account or enroll a node. +For a Linux amd64 machine with systemd, install the operator's compatible full +package through apt or system-wide tar using the [installation guide](../../README-install.md). +Set `dbl_cli=/usr/bin/dbl` for apt or `dbl_cli=/usr/local/bin/dbl` for tar in this +shell, and check `"$dbl_cli" --output json version`. Use the same selection for +the maintenance commands below; an unqualified `dbl` may select another package. -Use this sequence for a **new enrollment**, replacing the dispatcher URL and -executor ID with the supplied values: +Apt creates the missing service account and parent directories. **For tar only**, +prepare them before enrollment: ```sh # Create this account once; omit useradd if debuglet already exists. sudo useradd --system --user-group --home-dir /var/lib/debuglet --shell /usr/sbin/nologin debuglet sudo install -d -m 0755 /var/lib/debuglet /var/lib/debuglet/executors -sudo /usr/local/bin/dbl executor join --dispatcher https://debuglet.example/api \ +``` + +For either installation, use this sequence for a **new enrollment**, replacing +the dispatcher URL and executor ID with the supplied values. `worker` is the +local service name; keep it consistent in the state path and service commands. +The new state directory must not already exist: + +```sh +sudo "$dbl_cli" executor join --dispatcher https://debuglet.example/api \ --executor YOUR-EXECUTOR-ID --state-dir /var/lib/debuglet/executors/worker # Paste the setup token at the hidden prompt. Do not start a foreground daemon. -sudo /usr/local/bin/dbl service install --role executor --name worker \ - --enrolled-state /var/lib/debuglet/executors/worker -sudo /usr/local/bin/dbl service status --role executor --name worker +sudo "$dbl_cli" service install --role executor --name worker \ + --enrolled-state /var/lib/debuglet/executors/worker --start=true --enable=true +sudo "$dbl_cli" service status --role executor --name worker sudo journalctl -u debuglet-executor-worker.service -n 50 --no-pager ``` -Administrator privileges are needed for these setup commands. The executor -itself runs as `debuglet` with `NoNewPrivileges=yes`. New Linux enrollments at -this managed path select `packet_counter = "auto"`. For an enrolled configuration +Administrator privileges are needed for these setup commands. Service installation +assigns the enrolled files to `debuglet`; the executor itself runs as that account +with `NoNewPrivileges=yes`. Confirm service readiness and **Ready** in My nodes. +New Linux enrollments at this managed path select `packet_counter = "auto"`. +For an enrolled configuration that explicitly selects `auto`, the unit grants only `CAP_BPF`, `CAP_PERFMON`, `CAP_NET_ADMIN` and `CAP_NET_RAW`. Separate isolated worker processes drop those capabilities before executing code; the default trusted @@ -200,15 +215,15 @@ administrator launches. After adoption, use service commands to run this state. Existing enrollments in another directory remain usable with their printed foreground command; this installer does not move them or rewrite their paths. -For maintenance, use `sudo dbl drain --role executor --name worker` and -`sudo dbl drain --role executor --name worker --resume`. Normal service uninstall -keeps the identity and database for recovery. See [managed services](services.md) +Normal service uninstall keeps the identity and database for recovery. +See [managed services](services.md) for stopping, removal and package handling. Back up an enrolled executor by stopping it cleanly and preserving its entire private state directory; the foreground TEST backup command does not include enrolled credentials. To change the package of this enrolled managed executor, follow [controlled package replacement](services.md#replace-an-enrolled-executors-package). +For apt, start with the [Debian update procedure](debian.md#updates-and-rollback). It requires a clean joined shutdown, a disabled unit, an offline private backup and explicit `--replace-package PATH --start=false --enable=false` using a CLI that supports replacement. It preserves the existing enrollment and service @@ -219,13 +234,14 @@ account; do not obtain another setup token or purge the state to upgrade. Keep the generated state directory. Restarting with the same configuration, private key, certificate and database preserves the machine identity and does not need another setup token. A stopped machine remains in My nodes. For a -managed service, perform a planned restart with: +managed service, select `dbl_cli` as in [persistent setup](#run-persistently-on-linux) +in this shell, then perform a planned restart with: ```sh -sudo dbl --output json drain --role executor --name worker +sudo "$dbl_cli" --output json drain --role executor --name worker # Continue after joined: true and enabled: false. -sudo dbl drain --role executor --name worker --resume -sudo dbl service status --role executor --name worker +sudo "$dbl_cli" drain --role executor --name worker --resume +sudo "$dbl_cli" service status --role executor --name worker ``` Check **Ready** in My nodes afterward. Do not use Set up again for an ordinary @@ -246,7 +262,8 @@ identity. Never put a setup token in a command argument, URL or shared log. Enrollment certificates last at most 90 days, bounded by the issuer's expiry. Renewal is manual. Before expiry, use a full package with `executor join --renew` -and keep the same managed executor ID and state directory. This operation uses +and select `dbl_cli` as in [persistent setup](#run-persistently-on-linux). Keep +the same managed executor ID and state directory. This operation uses a fresh **Set up again** token from the existing node; it retains the private key, configuration, database, native trust, service account and installed package. It replaces only `executor.crt`. Do not create another node or move its state. @@ -254,7 +271,7 @@ It replaces only `executor.crt`. Do not create another node or move its state. 1. Drain the service and require `joined: true` and `enabled: false`: ```sh - sudo dbl --output json drain --role executor --name worker + sudo "$dbl_cli" --output json drain --role executor --name worker ``` 2. Keep other administrators, automation and foreground executors from starting @@ -263,7 +280,7 @@ It replaces only `executor.crt`. Do not create another node or move its state. run the renewal command and paste the fresh token at the hidden prompt: ```sh - sudo /usr/local/bin/dbl executor join --renew \ + sudo "$dbl_cli" executor join --renew \ --dispatcher https://debuglet.example/api --executor YOUR-EXECUTOR-ID \ --state-dir /var/lib/debuglet/executors/worker ``` @@ -275,8 +292,8 @@ It replaces only `executor.crt`. Do not create another node or move its state. 3. After the CLI reports successful certificate renewal, resume and inspect it: ```sh - sudo dbl drain --role executor --name worker --resume - sudo dbl service status --role executor --name worker + sudo "$dbl_cli" drain --role executor --name worker --resume + sudo "$dbl_cli" service status --role executor --name worker ``` The service stays stopped and disabled until you resume it. An expired old diff --git a/docs/operations/services.md b/docs/operations/services.md index 125a990e..8cb7ec35 100644 --- a/docs/operations/services.md +++ b/docs/operations/services.md @@ -88,16 +88,44 @@ start the service or enable it at boot. Keep other administrators, automation and foreground executors from starting or changing this instance throughout maintenance; the command does not serialize concurrent administrator actions. -Obtain the operator-approved full package and verify its release trust as -described in [signed releases](releases.md). Retain the previous full package. -Stage the candidate without changing command links, then use its CLI explicitly: +Retain the previous full package and choose the staging method matching your +installation. Run the remaining steps in the same shell, using the selected +`replacement_cli` and `candidate` rather than whichever `dbl` appears on `PATH`. + +For **apt**, configure the [signed repository](apt-repository.md) first, then +install the operator-approved exact Debian version. This changes the command +links but leaves the service on its recorded package: ```sh +set -eu +DEBUGLET_DEBIAN_VERSION=VERSION_PROVIDED_BY_OPERATOR +sudo apt-get update +sudo apt-get install "debuglet=$DEBUGLET_DEBIAN_VERSION" +test "$(dpkg-query -W -f='${Version}' debuglet)" = "$DEBUGLET_DEBIAN_VERSION" +candidate=$(dirname "$(dirname "$(readlink -f /usr/bin/dbl)")") +replacement_cli="$candidate/bin/dbl" +``` + +Before replacing the service, mark its previous `debuglet-payload-*` package +manual with `sudo apt-mark manual PAYLOAD_PACKAGE_NAME` so it remains available +for rollback after the service record changes. See [payload retention](debian.md#removal-and-repair). + +For a **tar installation**, obtain and verify the operator-approved full bundle +as described in [signed releases](releases.md). Stage it without changing command +links: + +```sh +set -eu DEBUGLET_VERSION=VERSION_PROVIDED_BY_OPERATOR sudo sh ./install.sh --archive "./debuglet-${DEBUGLET_VERSION}-linux-amd64.tar.gz" \ --checksums ./SHA256SUMS --version "$DEBUGLET_VERSION" --prefix /usr/local --stage-only candidate="/usr/local/lib/debuglet/$DEBUGLET_VERSION" replacement_cli="$candidate/bin/dbl" +``` + +For either installation method, drain the existing service: + +```sh sudo "$replacement_cli" --output json drain --role executor --name worker ```