[sdk][docs] Document the role of SSH when working with a target device.
This documentation is intentionally minimal for now, as more related documentation will soon be added, which will likely require moving some information around.
Test: verified that docs appeared in SDK archives.
Bug: DX-546
Bug: DX-732
Change-Id: I6c72f31b2b6cc32cb716eff3e3b8906181f0d90c
diff --git a/public/sdk/docs/BUILD.gn b/public/sdk/docs/BUILD.gn
index 0da0680..8fcc904 100644
--- a/public/sdk/docs/BUILD.gn
+++ b/public/sdk/docs/BUILD.gn
@@ -4,23 +4,24 @@
import("//build/sdk/sdk_documentation.gni")
+docs = [
+ "bootserver",
+ "packages",
+ "ssh",
+]
+
sdk_documentation("docs") {
name = "low_level"
category = "partner"
- files = [
- {
- source = "ssh.md"
- dest = "docs/ssh.md"
- },
- {
- source = "bootserver.md"
- dest = "docs/bootserver.md"
- },
- {
- source = "packages.md"
- dest = "docs/packages.md"
- },
- ]
+ files = []
+ foreach(doc, docs) {
+ files += [
+ {
+ source = "$doc.md"
+ dest = "docs/$doc.md"
+ },
+ ]
+ }
}
diff --git a/public/sdk/docs/ssh.md b/public/sdk/docs/ssh.md
index b884d2a..f3be058 100644
--- a/public/sdk/docs/ssh.md
+++ b/public/sdk/docs/ssh.md
@@ -1,3 +1,50 @@
# SSH
-_Content to be added soon!_
+SSH is the supported protocol for communication between a Fuchsia target device
+and a host device.
+This document describes how to properly set up an SSH connection between these
+devices.
+
+## Prerequisites
+
+On the host side, a proper SSH distribution is required.
+
+A public/private keypair is also needed.
+It may be generated via the `ssh-keygen` command, or extracted from the running
+SSH agent via `ssh-add -L`.
+
+## Provisioning a device
+
+There are two options for installing the public key onto the target.
+
+### By installing it during paving (preferred)
+
+Follow the instruction for [paving](bootserver.md) the target device, and add an
+extra argument to the `bootserver` call pointing to the public key:
+```
+$ bootserver --authorized-keys $PUBLIC_KEY <other args>
+```
+
+### By modifying the Fuchsia image directly
+
+The `fuchsia.zbi` image may be modified to include the public key using the
+`zbi` tool:
+```
+$ zbi -o $FUCHSIA_DOT_ZBI -e data/ssh/authorized_keys=$PUBLIC_KEY
+```
+
+Note that this method is mainly designed for situations where paving is not
+necessarily an efficient option (e.g. testing on an emulator).
+Use with care.
+
+## Connecting to a device
+
+Provided that the address of the target device is known as `$TARGET_ADDRESS`,
+open a shell on that device with:
+```
+$ ssh -i $PRIVATE_KEY fuchsia@$TARGET_ADDRESS
+```
+
+Note that if you got the key from your SSH agent, or if the key is in a well
+known location (`$SSH_HOME`) under a well known name (`id_*`), you may omit the
+`-i` argument.
