docs: Add agent-ctl examples section

Add a new `Examples` section to the `agent-ctl` docs giving some
examples of how to use the tool with QEMU and stand-alone.

Fixes: #4414.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>

src/tools/agent-ctl/README.md

@@ -97,10 +97,11 @@ An example showing how to specify the messages fields for an API call
 $ cargo run -- -l debug connect --server-address "unix://@/tmp/foo.socket" --bundle-dir "$bundle_dir" -c Check -c 'GetGuestDetails json://{"mem_block_size": true, "mem_hotplug_probe": true}'
 ```
 
-> **Note:**
+> **Notes:**
 >
-> For details of the names of the APIs to call and the available fields
-> in each API, see the [Code Summary](#code-summary) section.
+> - For details of the names of the APIs to call and the available fields
+>   in each API, see the [Code Summary](#code-summary) section.
+> - For further examples, see the [Examples](#examples) section.
 
 ### Connect to a real Kata Container
 
@@ -262,3 +263,121 @@ running.
 
    $ cargo run -- -l debug connect --server-address "vsock://${vsock_loopback_cid}:${agent_vsock_port}" --bundle-dir "$bundle_dir" -c Check -c GetGuestDetails
    ```
+
+## Examples
+
+### QEMU examples
+
+The following examples assume you have:
+
+- Configure Kata Containers to use QEMU.
+- Created a container using a command such as this:
+  ```bash
+  $ container_id="foo"
+  $ sudo ctr --debug run --runtime "io.containerd.kata.v2" --rm -t "quay.io/prometheus/busybox:latest" "$container_id" sh
+  ```
+
+#### Check the agent is running with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c Check
+```
+
+#### Show guest environment details with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c GetGuestDetails
+```
+
+#### Show sandbox metrics with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c GetMetrics
+```
+
+#### Show container statistics with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "StatsContainer json://{\"container_id\": \"${container_id}\"}"
+```
+
+#### Pause a running container with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "PauseContainer json://{\"container_id\": \"$container_id\"}"
+```
+
+#### Resume a paused container with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "ResumeContainer json://{\"container_id\": \"$container_id\"}"
+```
+
+#### Destroy a running container with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c "RemoveContainer json://{\"container_id\": \"$container_id\"}"
+```
+
+> **Note:**
+>
+> Only run this on a test or development system!
+
+#### Destroy a running sandbox with QEMU
+
+```bash
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:${agent_vsock_port}" -c 'DestroySandbox'
+```
+
+> **Notes:**
+>
+> - Only run this on a test or development system!
+> - This will destroy the sandbox and all resources associated with it
+>   (including all containers and the VM that hosts the agent).
+> - You cannot create a sandbox this way since the Kata Containers
+>   runtime and agent will already have created one inside the QEMU
+>   VM.
+>
+>   See [Create a sandbox manually](#create-a-sandbox-manually).
+
+### Local examples
+
+> **Note:**
+>
+> These examples assume you have
+> [already started the agent manually](#use-a-unix-abstract-domain-socket).
+
+#### Create a sandbox manually
+
+```bash
+$ sandbox_id="foo"
+
+# Critical to clear up from any previous run
+$ sudo umount /run/sandbox-ns/*
+
+$ server_addr='unix://@/tmp/foo.socket'
+
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "${server_addr}" -c "CreateSandbox json://{\"sandbox_id\": \"$sandbox_id\"}"
+```
+
+> **Note:**
+>
+> Although it should be possible to create a container inside the
+> sandbox, this is difficult since the JSON `CreateContainer` request
+> must include an OCI configuration file specification in (quoted)
+> JSON format.
+
+#### Delete a sandbox manually
+
+```bash
+$ sandbox_id="foo"
+
+$ server_addr='unix://@/tmp/foo.socket'
+
+$ cargo run -- -l trace connect --no-auto-values --bundle-dir "${bundle_dir}" --server-address "${server_addr}" -c DestroySandbox
+```
+
+> **Note:**
+>
+> No parameters are required for the `DestroySandbox` API call
+> (since only a single sandbox can be created).