diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 135a6cd20..b3d549e63 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -27,6 +27,18 @@ Manage service dependencies ``` +## Manage a remote system + +Pebble provides exec and file management functions to coordinate with remote systems. + +```{toctree} +:titlesonly: +:maxdepth: 1 + +Manage a remote system +``` + + ## Logging To better understand the operation of the services, you may need to work with logs. diff --git a/docs/how-to/manage-a-remote-system.md b/docs/how-to/manage-a-remote-system.md new file mode 100644 index 000000000..3f32649a9 --- /dev/null +++ b/docs/how-to/manage-a-remote-system.md @@ -0,0 +1,129 @@ +# How to use Pebble to manage a remote system + +Managing server clusters remotely takes time and effort. Servers need regular updates and configuration changes, which typically involves transferring files and running commands. Directly managing remote servers or using tools that require SSH access (such as Ansible) increases overhead and security risks. The [XZ Utils backdoor incident](https://en.wikipedia.org/wiki/XZ_Utils_backdoor) in 2024 highlighted vulnerabilities associated with SSH access. + +Pebble offers commands and an HTTP API over Unix socket for remote system management, avoiding the need for extra open ports. + +> Note: By "remote system", we mean that the Pebble daemon is running in a separate system and there's a Unix socket for clients to interact with the daemon. + +## Run commands in a remote system + +One common task in system administration is updating and installing packages. With Pebble, we can use the `pebble exec` command to achieve this. + +> Note: Set the environment variable `PEBBLE_SOCKET` to override the Unix socket used for the API (defaults to `$PEBBLE/.pebble.socket`, or to `/var/lib/pebble/default/.pebble.socket` if `PEBBLE` is not set). + +For example, if Pebble is running as a user with root privileges, we can use this command to update and install packages in a remote system: + +```{terminal} +:input: pebble exec apt update +Hit:1 http://ports.ubuntu.com/ubuntu-ports noble InRelease +Get:2 http://ports.ubuntu.com/ubuntu-ports noble-updates InRelease [126 kB] +Get:3 http://ports.ubuntu.com/ubuntu-ports noble-backports InRelease [126 kB] +... +Fetched 3121 kB in 38s (81.5 kB/s) +Reading package lists... Done +Building dependency tree... Done +Reading state information... Done +41 packages can be upgraded. Run 'apt list --upgradable' to see them. +``` + +To install a package, run: + +```bash +pebble exec apt install cowsay +``` + +To confirm the package is successfully installed in the remote system, run: + +```{terminal} +:input: pebble exec cowsay moo + _____ +< moo > + ----- + \ ^__^ + \ (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` + +For more information, see {ref}`reference_pebble_exec_command`. + +## Manage files in a remote system + +Another common task in a remote system is configuration management. For example, updating configuration files, pushing files to servers, pulling files generated by running services, and so on. + +With Pebble, this can be done using its file commands. For example, if we want to install Nginx, create our own website, and serve it on a newly created virtual host, we can first install Nginx: + +```bash +pebble exec apt install nginx +``` + +Then create our website _locally_: + +```bash +echo "Hello, Pebble!" > /tmp/index.html +``` + +Create a directory in the remote system: + +```bash +pebble mkdir -p /var/www/demo +``` + +Push our local website file to the remote system: + +```bash +pebble push /tmp/index.html /var/www/demo/index.html +``` + +Create a virtual host configuration _locally_: + +``` +cat < /tmp/demo +server { + listen 81; + listen [::]:81; + + server_name example.ubuntu.com; + + root /var/www/demo; + index index.html; + + location / { + try_files \$uri \$uri/ =404; + } +} +EOF +``` + +Push the file to the remote system: + +```bash +pebble push /tmp/demo /etc/nginx/sites-enabled/demo +``` + +Activate the newly added virtual host in the remote system by restarting Nginx: + +```bash +pebble exec service nginx restart +``` + +Finally, we can test the result: + +```{terminal} +:input: curl localhost:81 +Hello, Pebble! +``` + +For more information about related Pebble commands, see: + +- {ref}`reference_pebble_ls_command` +- {ref}`reference_pebble_mkdir_command` +- {ref}`reference_pebble_pull_command` +- {ref}`reference_pebble_push_command` +- {ref}`reference_pebble_rm_command` + +## See more + +You can also use the Pebble API to run command and manage files. This is normally done using the Go or Python client libraries. For more information, see [How to use the Pebble API](/how-to/use-the-pebble-api). diff --git a/docs/index.md b/docs/index.md index 30c734064..4a9979a9c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -29,7 +29,6 @@ Pebble is useful for developers who are building [Juju charms on Kubernetes](htt **Technical information** - [Layer specification](reference/layer-specification) - [CLI commands](reference/cli-commands) -- [Pebble in containers](reference/pebble-in-containers) ``` ```{grid-item-card} [Explanation](explanation/index) diff --git a/docs/reference/api.md b/docs/reference/api.md index acf7139d9..be91f4c25 100644 --- a/docs/reference/api.md +++ b/docs/reference/api.md @@ -51,6 +51,7 @@ We try to never change the underlying HTTP API in a backwards-incompatible way. For more information, see the [Go client documentation](https://pkg.go.dev/github.com/canonical/pebble/client). +(api_python_client)= ### Python client The Ops library for writing and testing Juju charms includes a [Python client for Pebble API](https://ops.readthedocs.io/en/latest/reference/pebble.html). You can use the Python client to access the API endpoints over the Unix socket. For example: diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md index 7a48494bb..2a5912123 100644 --- a/docs/reference/cli-commands.md +++ b/docs/reference/cli-commands.md @@ -191,7 +191,7 @@ error: cannot perform the following tasks: - exec command "sleep" (timed out after 1s: context deadline exceeded) ``` -Read more: [Use Pebble in containers](pebble-in-containers.md). +Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md). (reference_pebble_health_command)= @@ -410,7 +410,7 @@ may be specified for the last path element. ``` -Read more: [Use Pebble in containers](pebble-in-containers.md). +Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md). (reference_pebble_mkdir_command)= @@ -437,7 +437,7 @@ The mkdir command creates the specified directory. ``` -Read more: [Use Pebble in containers](pebble-in-containers.md). +Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md). (reference_pebble_notice_command)= @@ -640,7 +640,7 @@ The pull command retrieves a file from the remote system. ``` -Read more: [Use Pebble in containers](pebble-in-containers.md). +Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md). (reference_pebble_push_command)= @@ -666,7 +666,7 @@ The push command transfers a file to the remote system. ``` -Read more: [Use Pebble in containers](pebble-in-containers.md). +Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md). (reference_pebble_remove-identities_command)= @@ -810,7 +810,7 @@ The rm command removes a file or directory. ``` -Read more: [Use Pebble in containers](pebble-in-containers.md). +Read more: [How to use Pebble to manage remote systems](/how-to/manage-a-remote-system.md). (reference_pebble_run_command)= diff --git a/docs/reference/index.md b/docs/reference/index.md index 62f5e9aea..945a5ad42 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -20,7 +20,6 @@ Layers Layer specification Log forwarding Notices -Pebble in containers Service auto-restart ``` @@ -43,13 +42,6 @@ The `pebble` command has several subcommands. * [CLI commands](cli-commands) -## Pebble in containers - -When the Pebble daemon is running inside a remote system (for example, a separate container), you can manage the remote system using subcommands on the Pebble client. - -* [Pebble in containers](pebble-in-containers) - - ## Service failures Pebble provides two ways to automatically restart services when they fail. Auto-restart is based on exit codes from services. Health checks are a more sophisticated way to test and report the availability of services. diff --git a/docs/reference/pebble-in-containers.md b/docs/reference/pebble-in-containers.md deleted file mode 100644 index 7329b4b3b..000000000 --- a/docs/reference/pebble-in-containers.md +++ /dev/null @@ -1,19 +0,0 @@ -# Pebble in containers - -Pebble works well as a local service manager, but if running Pebble in a separate container, you can use the exec and file management APIs to coordinate with the remote system over the shared unix socket. - -## Run commands in a container - -To run commands in a container, see {ref}`reference_pebble_exec_command`. - -## File management - -Pebble provides various API calls and commands to manage files and directories on the server. - -The simplest way to use these is with the commands below, several of which should be familiar: - -- {ref}`reference_pebble_ls_command` -- {ref}`reference_pebble_mkdir_command` -- {ref}`reference_pebble_rm_command` -- {ref}`reference_pebble_push_command` -- {ref}`reference_pebble_pull_command`