[OSSTEST PATCH 4/4] README.dev: Improve instructions for new machine commissioning

[Ian Jackson <ian.jackson@eu.citrix.com>]

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>
---
 README.dev | 113 ++++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 90 insertions(+), 23 deletions(-)

diff --git a/README.dev b/README.dev
index 6d37ada..dc0dafd 100644
--- 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
-- 
2.1.4


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel