Provided by: maas-test_0.1+bzr147-0ubuntu1_all 
NAME
maas-test - test a server for compatibility running as a MAAS node
SYNOPSIS
maas-test --interactive [options...] <network-interface>
maas-test --bmc-mac=<address> [options...] <network-interface>
DESCRIPTION
Use maas-test to test whether a server can be used as a MAAS node. It must be run as
root. The test will set up a MAAS instance and attempt to manage the node.
Do not run maas-test on the same system that you wish to test. Two systems are involved:
• The testing system. Run maas-test here. It will create a virtual MAAS server for the
duration of the test.
• The node. The MAAS server running on the testing system will control it as a node,
running it through various test steps.
MAAS controls the node remotely though IPMI. This may include powering it on or off,
booting it, and even installing an operating system.
CAUTION: Future versions of maas-test may wipe the node's disks and install a new
operating system. And in general, accidents may happen. Be prepared to lose any data
stored there, and to re-install the node after the test.
In addition to this, even in the present version, MAAS will modify the node's firmware
netboot settings.
NETWORK CONFIGURATION
Run the test in a dedicated testing network consisting of just these two systems. This
network should be as isolated as possible, and does not need a route to the internet.
For the node, that means that both the node's own network interface card (NIC) and its
baseboard management controller (BMC) should be on the testing network. The testing
system only needs one NIC on the testing network.
In addition to being on the testing network, the testing system must also have internet
access.
maas-test supports two different network architectures:
Network config #1: the IPMI NIC is connected to the interface managed by MAAS:
+----------+
+---------------+ | Internet |
| |-----+ | |
| |eth0 |+------------>| |
| |-----+ +----------+
| Host |
| (where | NIC's MAC: aa:bb:cc:dd:ee:ff
| maas-test | |
| is installed) |-----+ |
| |eth1 | +------+ |
| | |<-->|Router| V +--------+
| |-----+ | |<-->+----| |
+---------------+ +------+ |IPMI| |
^ |eth1| |
| +----| Node |
| | being |
| +----| tested |
+---->|eth0| |
| | |
+----| |
+--------+
In this case, one needs to pass the IPMI NIC's MAC address to maas-test. The invocation
of maas-test will look something like:
$ maas-test --bmc-mac aa:bb:cc:dd:ee:ff --bmc-username username --bmc-password password
eth1
Network config #2: the IPMI NIC is not connected to the interface managed by MAAS and has
a fixed IP address:
+----------+
+---------------+ | Internet |
| |-----+ | |
| |eth0 |+------------>+----------+
| |-----+
| Host | +---------+
| (where |-----+ +----| |
| maas-test |eth1 |<-------->|eth0| |
| is installed) |-----+ +----| Node |
| | | being |
| |-----+ +----| tested |
| |eth2 |<-------->|eth1| |
| |-----+ |IPMI| |
+---------------+ +----| |
^ +---------+
|
Fixed IP address
AA.BB.CC.DD
In this case, one needs to pass the IPMI NIC's IP address to maas-test. The invocation of
maas-test will look something like:
$ maas-test --bmc-ip AA.BB.CC.DD --bmc-username username --bmc-password password eth1
PREPARING TO RUN
The test will run MAAS in a virtual machine. It will not be installed on your physical
system. Nevertheless there are a few things you need to be aware of:
1. Prepare to lose any data on the node's disks.
2. Ensure that your node (both its BMC and its own NIC) is connected only to the testing
network.
3. Make sure that there is no DHCP server running on the testing network. The test
program will also check for this on startup. MAAS will act as a DHCP server on the
testing network.
4. Select a network interface on the testing system that provides access to the testing
network. You will be passing this interface to maas-test.
5. Depending on caching, the test may download and store large amounts of data on the
testing system. Make sure you have sufficient disk space and network bandwidth.
The data that needs downloading and/or caching consists mostly of system images for the
virtual machine, and for booting the node. As a rule of thumb, count on half a gigabyte
as a baseline, plus a quarter gigabyte for each combination of architecture and Ubuntu
release that will run on the node.
RUNNING
There is one required argument: the network interface which connects the testing system to
the testing network, e.g. eth1.
The test will need to power up the node. It can do that in two ways:
a. Through IPMI commands to the node's BMC. You'll need to specify its address and
authentication information using the --bmc-* options.
b. Manually when running in interactive mode. The test will stop and ask you to power up
the node.
TEST RESULTS
Once maas-test has finished testing the node it will upload the test results to Launchpad
(unless told otherwise; see the reporting options). This allows you to share the test
results with others, including the MAAS developers, by filing a Launchpad bug which
includes the test results as an attachment.
By default, the results are also written to timestamped log files under
/var/log/maas-test.
OPTIONS
-h, --help
Show help and exit.
--bmc-mac=MAC
MAC address for the node's baseboard management controller. MAAS will control the
node's power and boot sequence through this controller. It must be attached to the
testing network. This is mutually exclusive with --bmc-ip. This option is not
needed in interactive mode. In non-interactive mode, either --bmc-mac or --bmc-ip
is required.
--bmc-ip=IP
IP address of the node's baseboard management controller. Use this if the BMC is
not connected to the interface given as argument. Note that the IP address must
not change for the duration of the testing. This is mutually exclusive with
--bmc-mac. This option is not needed in interactive mode. In non-interactive
mode, either --bmc-mac or --bmc-ip is required.
--bmc-password=password
Password for IPMI authentication on the BMC. Use with --bmc-user. Not needed in
interactive mode.
--bmc-user=user
Username for IPMI authentication. Use with --bmc-password. Not needed in
interactive mode.
--ipmi-driver=driver
Specify IPMI driver version. Default is LAN_2_0 (IPMI v2.0), which is what most
modern BMCs support. Use the LAN option if your BMC only supports IPMI version
1.5.
--interactive
Interactive mode. Instead of powering up the node automatically through IPMI,
prompt the user to turn it on manually. In this mode there is no need to specify
BMC details; the MAAS enlistment process will discover them automatically.
--archive=archive
Optional package repository name. If given, the virtual machine may install
packages from this additional archive as well as from the main Ubuntu archive. The
archive is added to the virtual machine using 'add-apt-repository'; it may be
either a line in the format of apt's sources.list, or a personal package archive
identifier in the form 'ppa:<user>/<ppa-name>', or a distribution component that
should be enabled. This is typically used to test recent versions of MAAS that are
only available in a PPA such as "ppa:maas-maintainers/dailybuilds". This can be
specified multiple times.
--series=codename
Code name for the Ubuntu release series that should be run on the node during
enlistment and commissioning, e.g. "saucy" for 13.10 Saucy Salamander. Defaults to
the latest long-term support release of Ubuntu.
--architecture=architecture
CPU architecture for the node. MAAS will import boot images for this architecture
only. The architecture may include a sub-architecture name, which defaults to
generic, so e.g. i386/generic may be abbreviated to i386. The default architecture
is amd64.
--maas-series=codename
Code name for the Ubuntu release series to install on the virtual machine (where
the MAAS server will be installed). Defaults to the latest stable Ubuntu series.
--http-proxy=URL
Use the given HTTP proxy for all downloads, both on the testing system and on the
nodes: KVM images, MAAS boot images, and Ubuntu packages. Like --disable-cache,
this also disables the caching proxy that maas-test runs by default.
--disable-cache
Do not run a caching HTTP proxy on the testing system. This cache is normally used
for all downloads, both on the testing system and on the nodes: KVM images, MAAS
boot images, and Ubuntu packages. It speeds up subsequent test runs, but also
caches a large amount of data on the testing system's filesystem. The proxy
software used is polipo. The cache will be stored under /var/cache/maas-test.
--dry-run
Bring up the MAAS region controller in a virtual machine, but don't attempt to boot
any machine on its network or do any destructive testing.
--no-reporting
Turn off all reporting of test results. Results will be written to stdout but not
recorded elsewhere.
--log-results-only
Write test results to a file, but don't upload them to Launchpad. Results will be
written to a timestamped log file under /var/log/maas-test.
REPORTING BUGS
Report bugs in Launchpad: https://bugs.launchpad.net/maas-test/
SEE ALSO
The maas-test program is part of the MAAS project. Find out more about MAAS at
http://maas.ubuntu.com/
For maas-test development, see https://launchpad.net/maas-test/
Polipo caching proxy: http://www.pps.univ-paris-diderot.fr/~jch/software/polipo/
Ubuntu virtualization tools (uvtool): https://launchpad.net/uvtool
FILES
State and configuration for maas-test is stored in /var/cache/maas-test. This includes an
ssh key pair for communicating with the virtual machine. Pidfiles are stored in
/run/maas-test, and logs and test results are written to /var/log/maas-test.
If you choose to run a local proxy, downloaded data will also be cached in the
/var/cache/maas-test. It can quickly grow to gigabyte sizes.
AUTHOR
MAAS engineering team at Canonical, Ltd.
COPYRIGHT
Copyright (c) 2013, Canonical Ltd.
MAAS-TEST(8)