From 90799c1adf0e50d3f88f6d91a6e5638dfa5798fb Mon Sep 17 00:00:00 2001
From: Alan Hanson <alan@oxidecomputer.com>
Date: Thu, 23 Jun 2022 12:30:46 -0700
Subject: [PATCH 1/2] Updated how-to-run instructions for image size

---
 docs/how-to-run.adoc | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/how-to-run.adoc b/docs/how-to-run.adoc
index 61d70d17b1a..f5fc053e43b 100644
--- a/docs/how-to-run.adoc
+++ b/docs/how-to-run.adoc
@@ -137,14 +137,16 @@ other services and allocating them with vNICs and IPv6 addresses.
 === How to provision an instance using the CLI
 
 Here are the current steps to provision an instance using the https://github.com/oxidecomputer/cli[oxide]
-command line interface.
+command line interface.  Note that the `jq` command is required. In addition, the examples build on each other, so a previous name (or org, or project) are used in later steps.
 
 1. Create an organization and project that the resources will live under:
 
     oxide org create myorg
     oxide project create -o myorg myproj
 
-2. Define a global image that will be used as initial disk contents. This can be the alpine.iso image that ships with propolis, or an ISO / raw disk image / etc hosted at a URL:
+2. Define a global image that will be used as initial disk contents.
+
+This can be the alpine.iso image that ships with propolis:
 
     oxide api /images --method POST --input - <<EOF
     {
@@ -161,6 +163,8 @@ command line interface.
     }
     EOF
 
+Or an ISO / raw disk image / etc hosted at a URL:
+
     oxide api /images --method POST --input - <<EOF
     {
       "name": "crucible-tester-sparse",
@@ -177,14 +181,14 @@ command line interface.
     }
     EOF
 
-3. Create a disk from that global image (note that disk size must be greater than or equal to image size!). The example below creates a disk using the image made from the alpine ISO that ships with propolis, and sets the size to be the exact same as the image size:
+3. Create a disk from that global image (note that disk size must be greater than or equal to image size and a 1GiB multiple!). The example below creates a disk using the image made from the alpine ISO that ships with propolis, and sets the size to the next 1GiB multiple of the original alpine source:
 
     oxide api /organizations/myorg/projects/myproj/disks/ --method POST --input - <<EOF
     {
       "name": "alpine",
       "description": "alpine.iso blob",
       "block_size": 512,
-      "size": $(oxide api /images/alpine | jq -r .size),
+      "size": 1073741824,
       "disk_source": {
           "type": "global_image",
           "image_id": "$(oxide api /images/alpine | jq -r .id)"
@@ -192,7 +196,7 @@ command line interface.
     }
     EOF
 
-4. Create an instance, attaching the disk created above:
+4. Create an instance, attaching the alpine disk created above:
 
     oxide api /organizations/myorg/projects/myproj/instances --method POST --input - <<EOF
     {
@@ -210,7 +214,7 @@ command line interface.
     }
     EOF
 
-5. Optionally, attach to the propolis server serial console:
+5. Optionally, attach to the propolis server serial console, though the serial console is under active development and these commands are subject to change:
 
   a. find the zone launched for the instance: `zoneadm list -c | grep oxz_propolis-server`
   b. get the instance uuid from the zone name. if the zone's name is `oxz_propolis-server_3b03ad43-4e9b-4f3a-866c-238d9ec4ac45`, then the uuid is `3b03ad43-4e9b-4f3a-866c-238d9ec4ac45`

From 891f90f15510f8dce6da9d256000399ae778e5b4 Mon Sep 17 00:00:00 2001
From: Alan Hanson <alan@oxidecomputer.com>
Date: Thu, 23 Jun 2022 12:34:26 -0700
Subject: [PATCH 2/2] Add sub section to section 2, fix formatting

---
 docs/how-to-run.adoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/how-to-run.adoc b/docs/how-to-run.adoc
index f5fc053e43b..0805eef3624 100644
--- a/docs/how-to-run.adoc
+++ b/docs/how-to-run.adoc
@@ -146,7 +146,7 @@ command line interface.  Note that the `jq` command is required. In addition, th
 
 2. Define a global image that will be used as initial disk contents.
 
-This can be the alpine.iso image that ships with propolis:
+ a. This can be the alpine.iso image that ships with propolis:
 
     oxide api /images --method POST --input - <<EOF
     {
@@ -163,7 +163,7 @@ This can be the alpine.iso image that ships with propolis:
     }
     EOF
 
-Or an ISO / raw disk image / etc hosted at a URL:
+ b. Or an ISO / raw disk image / etc hosted at a URL:
 
     oxide api /images --method POST --input - <<EOF
     {