From e2221d34bf571a9ed7fc1c79c91dccb611fa70b0 Mon Sep 17 00:00:00 2001
From: "James O. D. Hunt" <james.o.hunt@intel.com>
Date: Thu, 15 Oct 2020 17:17:23 +0100
Subject: [PATCH] tools: Improve agent-ctl README

Add a summary to help understand how to use the `agent-ctl` tool.

Signed-off-by: James O. D. Hunt <james.o.hunt@intel.com>
---
 tools/agent-ctl/README.md | 82 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

diff --git a/tools/agent-ctl/README.md b/tools/agent-ctl/README.md
index 862a0e3351..47a1776ee2 100644
--- a/tools/agent-ctl/README.md
+++ b/tools/agent-ctl/README.md
@@ -3,6 +3,11 @@
 * [Overview](#overview)
 * [Audience and environment](#audience-and-environment)
 * [Full details](#full-details)
+* [Code summary](#code-summary)
+* [Running the tool](#running-the-tool)
+    * [Prerequisites](#prerequisites)
+    * [Connect to a real Kata Container](#connect-to-a-real-kata-container)
+    * [Run the tool and the agent in the same environment](#run-the-tool-and-the-agent-in-the-same-environment)
 
 ## Overview
 
@@ -37,3 +42,80 @@ To see some examples, run:
 ```sh
 $ cargo run -- examples
 ```
+
+## Code summary
+
+The table below summarises where to look to learn more about both this tool,
+the agent protocol and the client and server implementations.
+
+| Description | File | Example RPC or function | Example summary |
+|-|-|-|-|
+| Protocol buffers definition of the Kata Containers Agent API protocol | [`agent.proto`](../../src/agent/protocols/protos/agent.proto) | `CreateContainer` | API to create a Kata container. |
+| Agent Control (client) API calls | [`src/client.rs`](src/client.rs) | `agent_cmd_container_create()` | Agent Control tool function that calls the `CreateContainer` API. |
+| Agent (server) API implementations | [`rpc.rs`](../../src/agent/src/rpc.rs) | `create_container()` | Server function that implements the `CreateContainers` API. |
+
+## Running the tool
+
+### Prerequisites
+
+It is necessary to create an OCI bundle to use the tool. The simplest method
+is:
+
+```sh
+$ bundle_dir="bundle"
+$ rootfs_dir="$bundle_dir/rootfs"
+$ image="busybox"
+$ mkdir -p "$rootfs_dir" && (cd "$bundle_dir" && runc spec)
+$ sudo docker export $(sudo docker create "$image") | tar -C "$rootfs_dir" -xvf -
+```
+
+### Connect to a real Kata Container
+
+1. Start a Kata Container
+
+1. Establish the VSOCK guest CID number for the virtual machine:
+
+   Assuming you are running a single QEMU based Kata Container, you can look
+   at the program arguments to find the (randomly-generated) `guest-cid=` option
+   value:
+
+   ```sh
+   $ guest_cid=$(ps -ef | grep qemu-system-x86_64 | egrep -o "guest-cid=[^,][^,]*" | cut -d= -f2)
+   ```
+
+1. Run the tool to connect to the agent:
+
+   ```sh
+   $ cargo run -- -l debug connect --bundle-dir "${bundle_dir}" --server-address "vsock://${guest_cid}:1024" -c Check -c GetGuestDetails
+   ```
+
+   This examples makes two API calls:
+
+   - It runs `Check` to see if the agent's RPC server is serving.
+   - It then runs `GetGuestDetails` to establish some details of the
+     environment the agent is running in.
+
+### Run the tool and the agent in the same environment
+
+> **Warnings:**
+>
+> - This method is **only** for testing and development!
+> - Only continue if you are using a non-critical system
+>   (such as a freshly installed VM environment).
+
+1. Start the agent, specifying a local socket for it to communicate on:
+
+   ```sh
+   $ sudo KATA_AGENT_SERVER_ADDR=unix:///tmp/foo.socket target/x86_64-unknown-linux-musl/release/kata-agent
+   ```
+
+1. Run the tool in the same environment:
+
+   ```sh
+   $ cargo run -- -l debug connect --server-address "unix://@/tmp/foo.socket" --bundle-dir "$bundle_dir" -c Check -c GetGuestDetails
+   ```
+
+   > **Note:**
+   >
+   > The `@` in the server address is required - it denotes an abstract
+   > socket which the agent requires (see `unix(7)`).