From b5ff77d0b549d785fd2dbc14987547111810957a Mon Sep 17 00:00:00 2001 From: David Wilding Date: Wed, 24 Dec 2025 14:30:16 +0800 Subject: [PATCH 1/7] capitalize Unix --- docs/explanation/api-and-clients.md | 2 +- docs/explanation/general-model.md | 2 +- docs/index.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/explanation/api-and-clients.md b/docs/explanation/api-and-clients.md index c15bdf3e3..fd206d26f 100644 --- a/docs/explanation/api-and-clients.md +++ b/docs/explanation/api-and-clients.md @@ -1,6 +1,6 @@ # API and clients -The Pebble daemon exposes an API (HTTP over a unix socket) to allow remote clients to interact with the daemon. It can start and stop services, add configuration layers to the plan, and so on. +The Pebble daemon exposes an API (HTTP over a Unix socket) to allow remote clients to interact with the daemon. It can start and stop services, add configuration layers to the plan, and so on. If `pebble run` is started with the `--http
` option, Pebble also exposes open-access HTTP endpoints using the given TCP address (see {ref}`api-access-levels` below). diff --git a/docs/explanation/general-model.md b/docs/explanation/general-model.md index 3ad51342a..fbc8217d7 100644 --- a/docs/explanation/general-model.md +++ b/docs/explanation/general-model.md @@ -1,5 +1,5 @@ # General model -Pebble is organized as a single binary that works as a daemon and also as a client to itself. When the daemon runs it loads its own configuration from the `$PEBBLE` directory, as defined in the environment, and also records in that same directory its state and unix sockets for communication. If that variable is not defined, Pebble will attempt to look for its configuration from a default system-level setup at `/var/lib/pebble/default`. Using that directory is encouraged for whole-system setup such as when using Pebble to control services in a container. +Pebble is organized as a single binary that works as a daemon and also as a client to itself. When the daemon runs it loads its own configuration from the `$PEBBLE` directory, as defined in the environment, and also records in that same directory its state and Unix sockets for communication. If that variable is not defined, Pebble will attempt to look for its configuration from a default system-level setup at `/var/lib/pebble/default`. Using that directory is encouraged for whole-system setup such as when using Pebble to control services in a container. The `$PEBBLE` directory must contain a `layers/` subdirectory that holds a stack of configuration files with names similar to `001-base-layer.yaml`, where the digits define the order of the layer and the following label uniquely identifies it. Each layer in the stack sits above the former one, and has the chance to improve or redefine the service configuration as desired. diff --git a/docs/index.md b/docs/index.md index 99c828ae2..62fc12e50 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,7 +14,7 @@ explanation/index It helps you orchestrate a set of local processes as an organized set. It resembles well-known tools such as _supervisord_, _runit_, or _s6_, in that it can easily manage non-system processes independently from the system services. However, it was designed with unique features such as layered configuration and an HTTP API that help with more specific use cases. -If you need a way to manage one or more services in a container, or as a non-root user on a machine, Pebble might be for you. It handles service logs, service dependencies, and allows you to set up ongoing health checks. Plus, it has an "HTTP over unix socket" API for all operations, with simple UID-based access control. +If you need a way to manage one or more services in a container, or as a non-root user on a machine, Pebble might be for you. It handles service logs, service dependencies, and allows you to set up ongoing health checks. Plus, it has an "HTTP over Unix socket" API for all operations, with simple UID-based access control. Pebble is useful for developers who are building {external+operator:ref}`Juju charms on Kubernetes `, creating {external+rockcraft:ref}`Rock ` or Docker images, or orchestrating services in the virtual machine. From 9cac3553addb6bc4a06f35c9c7851814d54c5b5f Mon Sep 17 00:00:00 2001 From: David Wilding Date: Wed, 24 Dec 2025 14:38:59 +0800 Subject: [PATCH 2/7] change wording in comment (and add full stops) --- docs/reference/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/index.md b/docs/reference/index.md index f4db96915..271d3a810 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -2,9 +2,9 @@ These guides provide technical information about Pebble. -% COMMENT: This toctree is for the navigation sidebar only -% Use an alphabetical listing of pages in the toctree -% For each page, make sure there's also a link in a section below +% COMMENT: This tree is for the navigation sidebar only. +% Use an alphabetical listing of pages in the tree. +% For each page, make sure there's also a link in a section below. ```{toctree} :hidden: @@ -24,7 +24,7 @@ Service auto-restart ``` -% COMMENT: The first few pages are presented in a more logical reading order +% COMMENT: The first few pages are presented in a more logical reading order. ## Layers From f44b7982ad0cb57367b57f6442f6ed29f373724d Mon Sep 17 00:00:00 2001 From: David Wilding Date: Wed, 24 Dec 2025 15:02:00 +0800 Subject: [PATCH 3/7] add code font and spelling exceptions --- docs/.custom_wordlist.txt | 14 ++++++++++++++ docs/explanation/api-and-clients.md | 4 ++-- docs/how-to/manage-identities.md | 6 +++--- docs/reference/api.md | 2 +- docs/reference/cli-commands.md | 6 +++--- docs/reference/environment-variables.md | 4 ++-- docs/reference/identities.md | 6 +++--- docs/reference/log-forwarding.md | 2 +- 8 files changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 734fdade6..4c41c430a 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -1 +1,15 @@ # Leave a blank line at the end of this file to support concatenation +backoff +boolean +Drepper +idempotently +liveness +ns +runit +replan +subcommands +supervisord +systemd +UIDs +Ulrich +Utils diff --git a/docs/explanation/api-and-clients.md b/docs/explanation/api-and-clients.md index fd206d26f..5047fe072 100644 --- a/docs/explanation/api-and-clients.md +++ b/docs/explanation/api-and-clients.md @@ -52,7 +52,7 @@ Currently the supported authentication types are: - `local`: a local user ID determined using peer credentials. - `basic`: HTTP basic authentication. -An example admin identity named "bob" with `local` type is shown below: +An example admin identity named `bob` with `local` type is shown below: ```yaml identities: @@ -62,7 +62,7 @@ identities: user-id: 42 ``` -An example identity named "alice" with `basic` type and `metrics` access level is shown below: +An example identity named `alice` with `basic` type and `metrics` access level is shown below: ```yaml identities: diff --git a/docs/how-to/manage-identities.md b/docs/how-to/manage-identities.md index ef5d0bdb0..f6ba0414b 100644 --- a/docs/how-to/manage-identities.md +++ b/docs/how-to/manage-identities.md @@ -10,7 +10,7 @@ By default any UID (user ID) connected to the API socket is a `read` user; UID 0 ## Add new identities -To extend access to Pebble's API to additional users, add named identities using the [`add-identities`](#reference_pebble_add-identities_command) command with a YAML file configuring the details. For example, to add a new admin "bob" with UID 42 and a new read user "alice" with UID 2000, prepare this file: +To extend access to Pebble's API to additional users, add named identities using the [`add-identities`](#reference_pebble_add-identities_command) command with a YAML file configuring the details. For example, to add a new admin `bob` with UID 42 and a new read user `alice` with UID 2000, prepare this file: ```yaml # idents-add.yaml @@ -37,7 +37,7 @@ Added 2 new identities. ## Remove identities -To remove existing identities, use [`remove-identities`](#reference_pebble_remove-identities_command) with a YAML file that has a `null` value for each identity you want to remove. For example, to remove "alice", prepare this file: +To remove existing identities, use [`remove-identities`](#reference_pebble_remove-identities_command) with a YAML file that has a `null` value for each identity you want to remove. For example, to remove `alice`, prepare this file: ```yaml # idents-remove.yaml @@ -75,7 +75,7 @@ pebble update-identities --from idents-update.yaml Updated 1 identity. ``` -You can use the `--replace` flag to idempotently add or update (or even remove) identities, whether or not they exist. The replace option is useful in automated scripts. For example, to update "bob", add "alice", and remove "mallory" (if it exists), prepare this file: +You can use the `--replace` flag to idempotently add or update (or even remove) identities, whether or not they exist. The replace option is useful in automated scripts. For example, to update `bob`, add `alice`, and remove `mallory` (if it exists), prepare this file: ```yaml # idents-replace.yaml diff --git a/docs/reference/api.md b/docs/reference/api.md index 51a0b61f3..162f82515 100644 --- a/docs/reference/api.md +++ b/docs/reference/api.md @@ -77,7 +77,7 @@ Some `GET` requests take optional query parameters for configuring or filterin All data sent to the API in `POST` bodies and all response data from the API is in JSON format. Requests should have a `Content-Type: application/json` header. -There are two main types of requests: synchronous ("sync"), and asynchronous ("async") for operations that can take some time to execute. Synchronous responses have the following structure: +There are two main types of requests: synchronous (`sync`), and asynchronous (`async`) for operations that can take some time to execute. Synchronous responses have the following structure: ```json { diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md index adfee1555..80cbaa07b 100644 --- a/docs/reference/cli-commands.md +++ b/docs/reference/cli-commands.md @@ -218,7 +218,7 @@ pebble exec pg_dump mydb ... ``` -The exec feature uses WebSockets under the hood, and allows you to stream stdin to the process, as well as stream stdout and stderr back. When running `pebble exec`, you can specify the working directory to run in (`-w`), environment variables to set (`--env`), and the user and group to run as (`--uid`/`--user` and `--gid`/`--group`). +The exec feature uses WebSockets under the hood, and allows you to stream `stdin` to the process, as well as stream `stdout` and `stderr` back. When running `pebble exec`, you can specify the working directory to run in (`-w`), environment variables to set (`--env`), and the user and group to run as (`--uid`/`--user` and `--gid`/`--group`). You can also apply a timeout with `--timeout`, for example: @@ -361,7 +361,7 @@ The identity command shows details for a single identity in YAML format. (reference_pebble_logs_command)= ## logs -The Pebble daemon's service manager stores the most recent stdout and stderr from each service, using a 100KB ring buffer per service. Each log line is prefixed with an RFC-3339 timestamp and the `[service-name]` in square brackets. +The Pebble daemon's service manager stores the most recent `stdout` and `stderr` from each service, using a 100KB ring buffer per service. Each log line is prefixed with an RFC-3339 timestamp and the `[service-name]` in square brackets. Logs are viewable via the logs API or using `pebble logs`: @@ -419,7 +419,7 @@ pebble logs --format=json {"time":"2022-11-14T01:39:13.889Z","service":"srv1","message":"Log 1 from srv1"} ``` -If you want to also write service logs to Pebble's own stdout, run the daemon with `--verbose`: +If you want to also write service logs to Pebble's own `stdout`, run the daemon with `--verbose`: ```{terminal} pebble run --verbose diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md index c6127a4b7..286a3eb7a 100644 --- a/docs/reference/environment-variables.md +++ b/docs/reference/environment-variables.md @@ -14,7 +14,7 @@ This will only copy the contents if the target directory, `$PEBBLE`, is empty. ## PEBBLE_DEBUG -If set to "1", debug logs will be printed to stderr. +If set to "1", debug logs will be printed to `stderr`. ## PEBBLE_PERSIST @@ -26,7 +26,7 @@ Pebble socket path. Defaults to `$PEBBLE/.pebble.socket` if not specified, or `/ ## PEBBLE_VERBOSE -If set to "1", the Pebble daemon writes service logs to stdout. +If set to "1", the Pebble daemon writes service logs to `stdout`. For `pebble run`, either `PEBBLE_VERBOSE=1` or the `--verbose` flag turns on verbose logging, with the command line flag overriding the environment variable. diff --git a/docs/reference/identities.md b/docs/reference/identities.md index 4b79bbeff..146488b08 100644 --- a/docs/reference/identities.md +++ b/docs/reference/identities.md @@ -29,7 +29,7 @@ identities: password: ``` -For example, a local identity named "bob" with UID 42 that is granted `admin` access would be defined as follows: +For example, a local identity named `bob` with UID 42 that is granted `admin` access would be defined as follows: ```yaml identities: @@ -39,7 +39,7 @@ identities: user-id: 42 ``` -For another example, a basic identity named "alice" that is granted `metrics` access would be defined as follows: +For another example, a basic identity named `alice` that is granted `metrics` access would be defined as follows: ```yaml identities: @@ -50,4 +50,4 @@ identities: password: ``` -The password is hashed using sha512-crypt, as generated by "openssl passwd -6". +The password is hashed using sha512-crypt, as generated by `openssl passwd -6`. diff --git a/docs/reference/log-forwarding.md b/docs/reference/log-forwarding.md index 8229f0404..11534cc49 100644 --- a/docs/reference/log-forwarding.md +++ b/docs/reference/log-forwarding.md @@ -22,7 +22,7 @@ Required configuration: - `override`: How this log target definition is combined with other pre-existing definitions with the same name in the plan. Supported values are `merge` and `replace`. - `type`: The type of log target. Supported types are `loki`, `opentelemetry` and `syslog`. -- `location`: The URL of the remote log target. For Loki, this needs to be the fully-qualified URL of the push API, including the API endpoint; use the format `http://:3100/loki/api/v1/push`. For OpenTelemetry, include the TCP port (normally 4318) without the API endpoint, for example: `http://:4318`. For Syslog, this needs to be either `tcp://:` or `udp://:`. +- `location`: The URL of the remote log target. For Loki, this needs to be the fully-qualified URL of the push API, including the API endpoint; use the format `http://:3100/loki/api/v1/push`. For OpenTelemetry, include the TCP port (normally 4318) without the API endpoint, for example: `http://:4318`. For `syslog`, this needs to be either `tcp://:` or `udp://:`. Optional configuration: From e8948ecbce34ccecb8f72b2878341d7969813d24 Mon Sep 17 00:00:00 2001 From: David Wilding Date: Wed, 24 Dec 2025 15:02:22 +0800 Subject: [PATCH 4/7] remove comment that's duplicated in text --- docs/reference/identities.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/reference/identities.md b/docs/reference/identities.md index 146488b08..75bd17859 100644 --- a/docs/reference/identities.md +++ b/docs/reference/identities.md @@ -46,7 +46,6 @@ identities: alice: access: metrics basic: - # The password is hashed using sha512-crypt, as generated by "openssl passwd -6". password: ``` From d0a6ddf673a469ddf8c8e38f0523fde6c3e9f717 Mon Sep 17 00:00:00 2001 From: David Wilding Date: Wed, 24 Dec 2025 15:03:09 +0800 Subject: [PATCH 5/7] fix genuine spelling mistake --- docs/explanation/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/explanation/security.md b/docs/explanation/security.md index 4a47d84d2..a0a3bcd31 100644 --- a/docs/explanation/security.md +++ b/docs/explanation/security.md @@ -49,4 +49,4 @@ Our intention is that projects that build on Pebble can [override how TLS connec ### FIPS 140 -This project also distributes [FIPS 140](https://en.wikipedia.org/wiki/FIPS_140)-compliant builds of Pebble: the source code is in the `fips` branch and there's the `fips` track for the official [`pebble` snap](https://snapcraft.io/pebble). Refer to [HACKING.md](https://github.com/canonical/pebble/blob/fips/HACKING.md#fips-140-changes) in the `fips` branch for the list of limiations in the FIPS builds. +This project also distributes [FIPS 140](https://en.wikipedia.org/wiki/FIPS_140)-compliant builds of Pebble: the source code is in the `fips` branch and there's the `fips` track for the official [`pebble` snap](https://snapcraft.io/pebble). Refer to [HACKING.md](https://github.com/canonical/pebble/blob/fips/HACKING.md#fips-140-changes) in the `fips` branch for the list of limitations in the FIPS builds. From 98caa1b48df642d3e5e46fa929fe09c680975efb Mon Sep 17 00:00:00 2001 From: David Wilding Date: Wed, 24 Dec 2025 15:05:15 +0800 Subject: [PATCH 6/7] reword to avoid "args" (and for clarity) --- docs/reference/cli-commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md index 80cbaa07b..f645eeec8 100644 --- a/docs/reference/cli-commands.md +++ b/docs/reference/cli-commands.md @@ -970,7 +970,7 @@ More ways to run the daemon: pebble run --args myservice --verbose --foo "multi str arg" ``` -* Use args terminator to pass `--hold` to Pebble at the end of the line: +* Use the argument terminator `;` to pass `--hold` to Pebble: ```bash pebble run --args myservice --verbose \; --hold From 19d27128b671dd716602ed98921f5c55709cb328 Mon Sep 17 00:00:00 2001 From: David Wilding Date: Wed, 24 Dec 2025 15:30:24 +0800 Subject: [PATCH 7/7] exclude 'mkdir' because of the CLI command links --- docs/.custom_wordlist.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index 4c41c430a..4757c08db 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -4,6 +4,7 @@ boolean Drepper idempotently liveness +mkdir ns runit replan