README.dev: Improve instructions for new machine commissioning

Discuss preliminary setup (hardware and BIOS).

Invent "mudcake0" and "mudcake1" as machines being added and use them
consistently in the example runes.

Recommend to run a host examination flight first.  (NB I am still
testing that this actually works as expected.  Host examination is a
bit new.)

Consistently suggest use of a $basis, and use of $flight variable.

Do not prepend runes with OSSTEST_CONFIG setting.  Instead, we expect
the user to have it set already (and mention this).

Use "cs-adjust-flight new:" rather than the two-step process.

Formatting improvements etc.

CC: Xudong Hao <xudong.hao@intel.com>
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>

diff --git a/README.dev b/README.dev
index 6d37ada6bb046db53fb90b792c94a0300392f59b..dc0dafdf938801a043c0d65ee06ef9a9b0df1666 100644 (file)
--- a/README.dev
+++ b/README.dev
@@ -33,45 +33,112 @@ Or you can use mg-allocate.
 Commisioning a new machine
 ==========================
 
+Firstly, arrange that it is hooked up to network, serial, and pdu.
+
+(In the Xen Project Massachusetts test lab, make sure that ansible
+playbook hosts/ has the wiring information; running `make install'
+will then arrange for /root/osstest-hosts-config to contain the Ether,
+Serial and PowerMethod configuration, and also configure the DNS and
+the DHCP server.)
+
+Go through the BIOS set up, using the serial console.  Check that:
+ - After AC power loss, machine is set to turn on
+   (NOT "last state" which is usually the default)   
+ - Serial console is enabled (usually with "redirection after boot")
+ - Boot order is 1. primary network 2. primary disk
+ - Virtualisation extensions (and VT-d if applicable) are enabled
+ - ILOM is disabled (or, us using a not-connected network port)
+
+In the Massachusetts instance you access the machines' serial consoles
+with something like
+   ssh -vt root@serial0.test-lab sympathy -r mudcake0
+
+Most BIOSes can be entered by hammering on, alternately, ESC 2
+or ESC 0 or DEL or something.
+
+The program "xduplic-copier" can be useful when used with xterm to
+type into two serial consoles at once - that lets you make sure the
+two BIOSes are set up completely identically.
+
+If the machine's ethernet address is not already in the relevant
+database, it can be collected via the BIOS and should be recorded.
+(In Massachusetts, in ansible playbook/hosts/testnet.info.)
+
+Secondly, set it up in the osstest database
+-------------------------------------------
+
+Most of these tools can operate on multiple hosts, and we like to have
+hosts in at least pairs.  Let us imagine we are adding two hosts
+mudcake0 and mudcake1.
+
 Base it on an existing machine:
 
-$ mg-hosts create-like marilith-n5 marilith-n4
+ $ ./mg-hosts create-like merlot0 mudcake0,mudcake1
+
+Allocate it for the duration of setup:
+
+ $ ./mg-allocate mudcake{0,1}          # this shell syntax provides
+                                       # two arguments, mudcake0 mudcake1
+
+Set up the host flags:
+
+ $ ./mg-hosts setflags mudcake{0,1} -- blessed-commission-mudcake equiv-mudcake arch-{amd64,i386} arch-xen-{amd64,i386} hvm hvm-intel purpose-{build,test} suite-{jessie,stretch}
+
+(Consult mg-hosts showflags to see which flags are appropriate.)
+
+Set up any necessary host properties:
+
+ $ ./mg-hosts setprops mudcake{0,1} -- ....
+
+For example, one might need something like this:
+
+ $ ./mg-hosts setprops marilith-n4 -- dhcp-watch-method 'leases dhcp3 dns-cam1.uk.xensource.com:5556'
+
+(Many of these things are not needed in Massachusetts as the ansible
+playbook will provide it via an autogenerated config file - see above.)
+
+Create the tftp directory:
 
-Allocate it for the duration of setup
-$ mg-allocate HOST
+ $ ./mg-hosts mknetbootdir mudcake{0,1}
 
-Set up the props and flags
-$ mg-hosts setprops ...
-$ mg-hosts setflags ...
+Run commissioning test flights
+------------------------------
 
-$ mg-hosts setprops marilith-n4 -- dhcp-watch-method 'leases dhcp3 dns-cam1.uk.xensource.com:5556'
-Handles multiple hosts:
-$ mg-hosts setprops HOSTA HOSTB -- "PROP" "VALUE"
+Firstly, a basic "host examination" that checks that we can install
+and boot Xen:
 
-$ mg-hosts mknetbootdir HOSTA HOSTB
+ $ basis=113124   # pick last good xen-unstable or osstest flight
+ $ flight=`./make-hosts-flight play xen-unstable blessed-commission-mudcake commission-mudcake $basis`; echo $flight
+ 113155
+ $ ./mg-execute-flight -Bcommission-mudcake -Eian.jackson@citrix.com $flight
 
-Create a flight:
-$ FLIGHT=`OSSTEST_CONFIG=production-config ./cs-flight-create commission xen-unstable`
-$ echo $FLIGHT
-20974
+This will email the specified address.  The examination should pass,
+completely.  If it does not then you may need to change the BIOS
+serial arrangements, or do other debugging.
 
-Clone an existing flight, e.g. 20855 was previous successful flight
-$ OSSTEST_CONFIG=production-config ./cs-adjust-flight $FLIGHT copy 20855 
+It is best to run mg-execute-flight in screen, so that it will survive
+ssh session disconnection.  You should be running out of an osstest
+tree (testing.git clone) with good recent code, with an appropriate
+OSSTEST_CONFIG setting (eg OSSTEST_CONFIG=production-config, in
+Massachusetts).  You can run it as yourself, though, if you have the
+right permissions set up.
 
-"commission" is a blessing, hosts should be blessed with it, e.g.
+If that works, a more thorough test:
 
-$ mg-hosts setflags HOSTA HOSTB -- blessed-commission
+ $ basis=113124   # pick last good xen-unstable or osstest flight
+ $ flight=`./cs-adjust-flight new:commission-mudcake copy $basis`; echo $flight
+ $ ./mg-execute-flight -Bcommission-mudcake -Eian.jackson@citrix.com -f$basis $flight
 
-Can use anything e.g. commission-$classofmachine if doing multiple
-commissions in parallel.
+This should show no regressions.  (Or, at least, none that are a cause
+for concern.)
 
-Run it, e.g. in a screen session:
-OSSTEST_CONFIG=production-config ./mg-execute-flight  -Bcommission -Eian.campbell@citrix.com -f20855 $FLIGHT
+Bless
+-----
 
 Once machines are ready for production use remove the commission
 blessing and add the production ones, e.g.
 
-$ mg-hosts setflags HOSTA HOSTB -- \!blessed-commission blessed-{real,play,adhoc}
+ $ ./mg-hosts setflags mudcake{0,1} -- \!blessed-commission blessed-{real,play,adhoc}
 
 
 Shutting down the whole system