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)