Merge lp:~rvb/maas-test/power-type-support into lp:maas-test

[Raphaël Badin]

Add two parameters, --power-type and --power-parameters, to pass the power details about a node. This allows maas-test to support any power mechanism MAAS itself support instead of supporting only IPMI.

Notes:

- The legacy --bmc-* parameters (used when the node is IPMI-based) are still supported: the value of the --bmc-* parameters is converted into power-type and power-parameters.

- the trick use to power up the node to get it enlistment can appear a bit fishy but the nice thing about it is that is relies exclusively on API methods that won't change any time soon; this, I think, is much better than call MAAS' code directly.

[Jeroen T. Vermeulen (jtv)]

Thanks for working on this. The timeout is no longer needed, I suppose, now that the API client is fixed.

Is there a race condition between the node booting and maas-test deleting it? I suppose it won't matter until we get magical ultra-fast speed-booting nodes.

I have a few syntactical questions about the documentation:

  $ sudo maas-test --maas-series trusty --architecture amd64
  --power-type=amt --power-parameters=\"mac_address=aa:bb:cc:dd:ee:ff
  power_pass='my password'"

What does it mean for the opening double-quote after --power-parameters to be escaped, but not the closing quote? And, do the single quotes inside the quoted dict really work the way you'd expect? Who parses them?

I would like to recommend a few style rules for technical writing, e.g:

                    "You need to provide all the details required to power "
                    "control the node under test. "
                    "You need to provide the --bmc-* parameters if the node "
                    "supports IPMI or use --power-type and --power-parameters "
                    "if you want to use any of the other power types "
                    "supported by MAAS (see %s for a list of the supported "
                    "power types)."

Try to keep elements of a sentence in an easy-to-understand order, so readers don't have to remember or re-read text that may only make sense later. Limit the nesting of phrases. That second sentence is structured like “A if B or C if D (E)” — that's quite hard to read if you're confused, annoyed, under pressure, or not very good at English.

Only use "[statement] if [condition]" if [statement] is very brief and very simple. Even then, keep an eye out for ambiguity around ‘and’/‘or’: is it part of the condition? Or does it start a whole new statement? These are parsing ambiguities. If the reader picks the wrong interpretation at first, they will hit a “parse error” later and have to re-read, which is annoying.

So: don't try to cram all relevant information into your sentence. See how _little_ information you can put in a sentence while still making a clear chain of steps towards full understanding. Good technical writing follows Antoine de Saint Exupéry's rule: “perfection is achieved, not when there is nothing more to add, but when there is nothing more to take away.”

The same things go for these messages:

                self.error(
                    "All the BMC details (MAC address or IP address, "
                    "username and password) must be provided."
                )

...

                self.error(
                    "Value for both --power-type and --power-parameters must "
                    "be provided."

Can you find a way to make these easier to read? Changing from passive voice to active voice is usually a good step.

But back to code. In convert_bmc_details_into_parameters you use an OrderedDict to produce consistent ordering — but the ordering isn't documented. Wouldn't it be just as easy to make the tests run parameters.split() and do an assertItemsEqual on the result? Or use sorted() inside convert_bmc_details_into_parameters?

review: Approve

[lp:~rvb/maas-test/power-type-support]

165. By Raphaël Badin on 2014-04-30

Review fixes.

166. By Raphaël Badin on 2014-04-30

Fix test.

[Raphaël Badin (rvb)]

> Thanks for working on this. The timeout is no longer needed, I suppose, now
> that the API client is fixed.
>
> Is there a race condition between the node booting and maas-test deleting it?
> I suppose it won't matter until we get magical ultra-fast speed-booting nodes.
>
> I have a few syntactical questions about the documentation:
>
> $ sudo maas-test --maas-series trusty --architecture amd64
> --power-type=amt --power-parameters=\"mac_address=aa:bb:cc:dd:ee:ff
> power_pass='my password'"
>
> What does it mean for the opening double-quote after --power-parameters to be
> escaped, but not the closing quote?

An oversight that had no consequence because of the way the man page is rendered. Fixed.

> And, do the single quotes inside the
> quoted dict really work the way you'd expect? Who parses them?

Yes, there is a test for this. All the parsing is done by utils.make_json_power_parameters().

>
> I would like to recommend a few style rules for technical writing, e.g:
> [...]

Done.

>
> The same things go for these messages:
> [...]

Done.

> But back to code. In convert_bmc_details_into_parameters you use an
> OrderedDict to produce consistent ordering — but the ordering isn't
> documented. Wouldn't it be just as easy to make the tests run
> parameters.split() and do an assertItemsEqual on the result? Or use sorted()
> inside convert_bmc_details_into_parameters?

Good idea, done.

[Raphaël Badin (rvb)]

> Thanks for working on this. The timeout is no longer needed, I suppose, now
> that the API client is fixed.

Well, I still want this to work with the package published in Trusty so I'll keep the workaround for now. When the fix gets SRUed, we will think about removing it.

> Is there a race condition between the node booting and maas-test deleting it?
> I suppose it won't matter until we get magical ultra-fast speed-booting nodes.

Yeah, I think this is safe :).

=== modified file 'docs/man/maas-test.8.rst'
--- docs/man/maas-test.8.rst	2014-04-23 14:47:13 +0000
+++ docs/man/maas-test.8.rst	2014-04-30 06:58:59 +0000
@@ -185,30 +185,64 @@
   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.
+  exclusive with **--bmc-ip**.  In non-interactive mode, either **--bmc-mac**
+  or **--bmc-ip** is required. Not needed in interactive mode or when using
+  **--power-type** and **--power-parameters**.
 
 --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.
+  This is mutually exclusive with **--bmc-mac**.  In non-interactive mode,
+  either **--bmc-mac** or **--bmc-ip** is required. 
+  Not needed in interactive mode or when using --power-type and
+  --power-parameters.
 
 --bmc-password=password
   Password for IPMI authentication on the BMC.  Use with **--bmc-user**.
-  Not needed in interactive mode.
+  Not needed in interactive mode or when using **--power-type** and
+  **--power-parameters**.
 
 --bmc-user=user
   Username for IPMI authentication.  Use with **--bmc-password**.
-  Not needed in interactive mode.
+  Not needed in interactive mode or when using **--power-type** and
+  **--power-parameters**.
 
 --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.     
+  IPMI version 1.5. Not needed in interactive mode or if using **--power-type** and 
+  **--power-parameters**.
+
+--power-type=power_type
+  Power type of the node under test (e.g. 'ipmi', 'amt', etc. 
+  See http://maas.ubuntu.com/docs/api.html#power-types for a list of the supported
+  power types and their related power parameters).
+  Using **--power-type** and **--power-parameters** is an alternative to using 
+  the bmc-* arguments that allows to use any one of the power mechanisms 
+  MAAS supports.
+
+  # Example: testing a node with an Active Management Technology (AMT) interface:
+
+  $ sudo maas-test --maas-series trusty  --architecture amd64 
+  --power-type=amt --power-parameters="mac_address=aa:bb:cc:dd:ee:ff 
+  power_pass='my password'"
+
+  # Example: testing a node with an Intelligent Platform Management Interface (IPMI):
+
+  $ sudo maas-test --maas-series trusty  --architecture amd64 
+  --power-type=ipmi --power-parameters="power_address=192.168.2.3 power_user='my user'
+  power_pass='my password' power_driver=LAN_2_0"
+
+--power-parameters=power_parameters
+  Power parameters of the node under test (See
+  http://maas.ubuntu.com/docs/api.html#power-types for a list of the supported power
+  types and their related power parameters).  This is a dict-like expression of the
+  power parameters for the specified power type.  
+  Using **--power-type** and **--power-parameters** is an alternative to using 
+  the bmc-* arguments that allows to use any one of the power mechanisms 
+  MAAS supports.  
+  See the documentation for **--power-type** for examples.
 
 --interactive
   Interactive mode.  Instead of powering up the node automatically through

=== modified file 'maastest/cases.py'
--- maastest/cases.py	2014-04-28 13:44:34 +0000
+++ maastest/cases.py	2014-04-30 06:58:59 +0000
@@ -14,15 +14,19 @@
     "TestOneNode",
     ]
 
+from functools import partial
 import httplib
 import json
+import socket
 import sys
 from time import sleep
+import urllib2
 
 from maastest import utils
 from maastest.maas_enums import NODE_STATUS
 import testresources
 import testtools
+from testtools.monkey import MonkeyPatcher
 from testtools.testcase import gather_details
 
 
@@ -112,42 +116,59 @@
     def power_up_node_noninteractive(self):
         """Power up the node using the provided power parameters."""
         # Power-cycle the node.
-        # TODO: Move these into MAASFixture?
-        power_address = self.find_bmc_ip_address()
-        self.maas.kvm_fixture.run_command([
-            'ipmipower', '-h', power_address,
-            '-W', 'opensesspriv',
-            '-D', self.args.ipmi_driver,
-            '-u', self.args.bmc_username,
-            '-p', self.args.bmc_password, '--off'],
-            check_call=True)
-        self.maas.kvm_fixture.run_command([
-            'ipmipower', '-h', power_address,
-            '-W', 'opensesspriv',
-            '-D', self.args.ipmi_driver,
-            '-u', self.args.bmc_username,
-            '-p', self.args.bmc_password, '--on'],
-            check_call=True)
-
-    def find_bmc_ip_address(self):
-        """Returns the BMC IP address.
-
-        This is done by scanning the network it the BMC MAC address was given
-        or by simply returning the IP address of the BMC is it was passed.
-        """
-        if self.args.bmc_mac is not None:
-            # The BMC's MAC address was passed: scan the network to find the
-            # IP address of the node's BMC.
-            for retry in utils.retries(delay=20, timeout=5 * 60):
-                ip_scan = self.maas.kvm_fixture.get_ip_from_network_scan
-                power_address = ip_scan(self.args.bmc_mac)
-                if power_address is not None:
-                    return power_address
-        else:
-            # The BMC IP address was passed: just return that.
-            return self.args.bmc_ip
-        if power_address is None:
-            self.fail("Failed to get the IP address of the BMC.")
+        # We use a little trick here to be able to test enlistment while
+        # leveraging MAAS' capabilities to boot a node for all the
+        # supported power types.  In order to get a node enlisted, this code:
+        # - adds a node using the client library (passing the power type
+        #   and all the power parameters given on the command line).  Since
+        #   the node is getting enlisted by an admin user, the node will be
+        #   started.
+        # - deletes the node.
+        # The node will now be unknown to MAAS and will thus be enlisted
+        # as a new node.
+        #
+        # 0. Force a network scan: this populates the ARP cache used to lookup
+        # IP addresses using MAC addresses.
+        self.maas.kvm_fixture.get_network_scan()
+
+        # 1. Register the node.
+        nodes_uri = utils.get_uri('nodes/')
+        cluster_uuid = self.maas.get_master_ng_uuid()
+        json_power_parameters = utils.make_json_power_parameters(
+            self.args.power_parameters)
+        response = self.maas.admin_maas_client.post(
+            nodes_uri, op='new',
+            architecture=self.args.architecture,
+            nodegroup=cluster_uuid,
+            power_type=self.args.power_type,
+            power_parameters=json_power_parameters,
+            # Use a bogus MAC address as one MAC address is required.
+            # Its value will be overridden by the value passed in
+            # the power parameters.
+            mac_addresses=['aa:bb:cc:dd:ee:ff'],
+        )
+        if response.code != httplib.OK:
+            raise self.fail(
+                "Failed to power up node (registration): %s" % (
+                    response.content))
+        node_dict = json.loads(response.read())
+        node_uri = utils.get_uri('nodes/%s/' % node_dict['system_id'])
+
+        # 2. Delete the node.
+        # XXX: rvb 2014-03-28 bug=https://bugs.launchpad.net/maas/+bug/1313556
+        # Workaround a bug affecting the API client (deleting a resource
+        # blocks) by forcing a timeout for the request.
+        urlopen_with_timeout = partial(urllib2.urlopen, timeout=10)
+        patcher = MonkeyPatcher()
+        from apiclient import maas_client
+        patcher.add_patch(maas_client.urllib2, "urlopen", urlopen_with_timeout)
+
+        def delete_and_survive_timeout():
+            try:
+                self.maas.admin_maas_client.delete(node_uri)
+            except socket.timeout:
+                pass
+        response = patcher.run_with_patches(delete_and_survive_timeout)
 
     def test_enlist_node(self):
         """Enlist node."""

=== modified file 'maastest/kvmfixture.py'
--- maastest/kvmfixture.py	2014-04-26 08:38:08 +0000
+++ maastest/kvmfixture.py	2014-04-30 06:58:59 +0000
@@ -435,15 +435,20 @@
             ['scp'] + self._get_base_ssh_options() + [source, remote_dest],
             check_call=True)
 
-    def get_ip_from_network_scan(self, mac_address):
-        """Return the IP address associated with a MAC address.
-
-        The IP address is found by scanning the direct network using nmap.
-        """
+    def get_network_scan(self):
+        """Return the result of scanning the 'direct' network using `nmap`."""
         network_repr = "%s" % self.direct_network
         nmap_scan_cmd = ['sudo', 'nmap', '-sP', network_repr, '-oX', '-']
         _, output, _ = self.run_command(
             nmap_scan_cmd, check_call=True)
+        return output
+
+    def get_ip_from_network_scan(self, mac_address):
+        """Return the IP address associated with a MAC address.
+
+        The IP address is found by scanning the 'direct' network using nmap.
+        """
+        output = self.get_network_scan()
         mapping = extract_mac_ip_mapping(output)
         ip = mapping.get(mac_address.upper())
         if ip is not None:

=== modified file 'maastest/main.py'
--- maastest/main.py	2014-04-10 10:08:14 +0000
+++ maastest/main.py	2014-04-30 06:58:59 +0000
@@ -284,6 +284,16 @@
         check_against_virtual_host()
         check_against_dhcp_servers(args.interface)
 
+        # Support legacy BMC details-passing:
+        if args.bmc_username is not None:
+            # Generate args.power_type and args.power_parameters from the
+            # bmc_* arguments.
+            args.power_type = 'ipmi'
+            args.power_parameters = (
+                utils.convert_bmc_details_into_parameters(
+                    args.bmc_mac, args.bmc_ip, args.bmc_username,
+                    args.bmc_password, args.ipmi_driver))
+
         proxy_url, proxy_fixture = set_up_proxy(args)
         machine_fixture = create_vm(args, proxy_url)
         machine_fixture.setUp()

=== modified file 'maastest/parser.py'
--- maastest/parser.py	2014-04-10 08:16:16 +0000
+++ maastest/parser.py	2014-04-30 06:58:59 +0000
@@ -21,6 +21,10 @@
 from six import text_type
 
 
+# Link to the documentation about power types and power parameters.
+POWER_TYPES_DOC_URL = 'http://maas.ubuntu.com/docs/api.html#power-types'
+
+
 class MAASTestArgumentParser(argparse.ArgumentParser):
 
     def parse_args(self, *args, **kwargs):
@@ -40,10 +44,41 @@
                 (args.bmc_mac is not None or args.bmc_ip is not None) and
                 args.bmc_username is not None and
                 args.bmc_password is not None)
-            if not bmc_details_all_set:
-                self.error(
-                    "All the BMC details (MAC address or IP address, username "
-                    "and password) must be provided.")
+            one_bmc_param_set = (
+                args.bmc_mac is not None or args.bmc_ip is not None or
+                args.bmc_username is not None or
+                args.bmc_password is not None)
+
+            power_details_all_set = (
+                args.power_type is not None and
+                args.power_parameters is not None)
+            one_power_details_all_set = (
+                args.power_type is not None or
+                args.power_parameters is not None)
+
+            if not one_bmc_param_set and not one_power_details_all_set:
+                self.error(
+                    "You need to provide all the details required to power "
+                    "control the node under test. "
+                    "If the node supports IPMI, you can use the legacy "
+                    "--bmc-* parameters.  For any other power type supported "
+                    "by MAAS (see %s for a list of the supported "
+                    "power types), including IPMI, you can use --power-type "
+                    "and --power-parameters." % POWER_TYPES_DOC_URL
+                )
+
+            if one_bmc_param_set and not bmc_details_all_set:
+                self.error(
+                    "You must provide all the BMC details (MAC address "
+                    "or IP address, username and password)."
+                )
+
+            if one_power_details_all_set and not power_details_all_set:
+                self.error(
+                    "You must provide values for both --power-type and "
+                    "--power-parameters."
+                )
+
         return args
 
 
@@ -80,22 +115,26 @@
         help="MAC address of the node's baseboard management controller.  "
              "Use this if the BMC is connected to the interface given as "
              "argument. In non-interactive mode, either --bmc-mac or "
-             "--bmc-ip.  Not needed in interactive mode.")
+             "--bmc-ip.  Not needed in interactive mode or if using "
+             "--power-type and --power-parameters.")
     parser.add_argument(
         '--bmc-ip', type=text_type,
         help="IP address of the node's baseboard management controller.  "
              "Use this if the BMC is not connected to the inteface given as "
              "argument.  Note that the IP address must not change for the "
              "duration of the testing.  In non-interactive mode, either "
-             "--bmc-mac or --bmc-ip.  Not needed in interactive mode.")
+             "--bmc-mac or --bmc-ip.  Not needed in interactive mode or if "
+             "using --power-type and --power-parameters.")
     parser.add_argument(
         '--bmc-username', type=text_type,
         help="Username for authenticating to the node's BMC.  "
-             "Not needed in interactive mode.")
+             "Not needed in interactive mode or if "
+             "using --power-type and --power-parameters.")
     parser.add_argument(
         '--bmc-password', type=text_type,
         help="Password for authenticating to the node's BMC.  "
-             "Not needed in interactive mode.")
+             "Not needed in interactive mode or if "
+             "using --power-type and --power-parameters.")
     parser.add_argument(
         '--ipmi-driver', type=text_type, default='LAN_2_0',
         help="IPMI driver type for the node's BMC. Defaults to LAN_2_0 "
@@ -103,7 +142,38 @@
              "Other option is LAN (IPMI version 1.5).  Many BMCs can work "
              "with either IPMI 1.5 or 2.0, but, some BMCs such as HP's iLO "
              "only use IPMI 2.0. "
-             "You may need to pass LAN if your BMC only supports IPMI 1.5.")
+             "You may need to pass LAN if your BMC only supports IPMI 1.5. "
+             "Not needed in interactive mode or if "
+             "using --power-type and --power-parameters.")
+
+    # Power type and power parameters.
+    parser.add_argument(
+        '--power-type', type=text_type,
+        help=(
+            "Power type of the node under test (e.g. 'ipmi', 'amt', etc. "
+            "See %s for a list of the supported "
+            "power types and their related power parameters).  "
+            "Using --power-type and --power-parameters is an alternative to "
+            "using the bmc-* arguments that allows to use any one of the "
+            "power mechanisms MAAS supports.  See the manpage for examples "
+            "on how to use --power-type and --power-parameters."
+            % POWER_TYPES_DOC_URL
+        )
+    )
+    parser.add_argument(
+        '--power-parameters', type=text_type,
+        help=(
+            "Power parameters of the node under test (See %s "
+            "for a list of the supported power types and their related power "
+            "parameters).  This is a dict-like expression of the "
+            "power parameters for the specified power type.  "
+            "Using --power-type and --power-parameters is an alternative to "
+            "using the bmc-* arguments that allows to use any one of the "
+            "power mechanisms MAAS supports. "
+            "See the documentation for --power-type for examples."
+            % POWER_TYPES_DOC_URL
+        )
+    )
 
     # VM details.
     parser.add_argument(

=== modified file 'maastest/tests/test_utils.py'
--- maastest/tests/test_utils.py	2014-04-25 15:46:59 +0000
+++ maastest/tests/test_utils.py	2014-04-30 06:58:59 +0000
@@ -16,10 +16,11 @@
 import os.path
 from pipes import quote
 import platform
+import re
+import shlex
 from subprocess import PIPE
 from textwrap import dedent
 import time
-import re
 
 import distro_info
 from fixtures import TempDir
@@ -470,3 +471,55 @@
         self.assertEqual(
             '%s~(x\\.y\\*)' % key,
             utils.compose_filter(key, ['x.y*']))
+
+
+class TestBMCDetailsConversion(testtools.TestCase):
+
+    def test_convert_parameters_with_power_address(self):
+        ip = self.getUniqueString()
+        username = self.getUniqueString()
+        password = self.getUniqueString()
+        driver = self.getUniqueString()
+        parameters = utils.convert_bmc_details_into_parameters(
+            None, ip, username, password, driver)
+        self.assertItemsEqual(
+            [
+                "power_user=%s" % username,
+                "power_pass=%s" % password,
+                "power_driver=%s" % driver,
+                "power_address=%s" % ip,
+            ],
+            shlex.split(parameters))
+
+    def test_convert_parameters_with_mac_address(self):
+        mac = self.getUniqueString()
+        username = self.getUniqueString()
+        password = self.getUniqueString()
+        driver = self.getUniqueString()
+        parameters = utils.convert_bmc_details_into_parameters(
+            mac, None, username, password, driver)
+        self.assertItemsEqual(
+            [
+                "power_user=%s" % username,
+                "power_pass=%s" % password,
+                "power_driver=%s" % driver,
+                "power_address=",
+                "mac_address=%s" % mac,
+            ],
+            shlex.split(parameters))
+
+    def test_convert_parameters_that_need_quoting(self):
+        ip = self.getUniqueString()
+        username = self.getUniqueString() + "'+" + self.getUniqueString()
+        password = "'" + self.getUniqueString() + "'"
+        driver = self.getUniqueString()
+        parameters = utils.convert_bmc_details_into_parameters(
+            None, ip, username, password, driver)
+        self.assertItemsEqual(
+            [
+                "power_user=%s" % username,
+                "power_pass=%s" % password,
+                "power_driver=%s" % driver,
+                "power_address=%s" % ip,
+            ],
+            shlex.split(parameters))

=== modified file 'maastest/utils.py'
--- maastest/utils.py	2014-04-25 15:46:59 +0000
+++ maastest/utils.py	2014-04-30 06:58:59 +0000
@@ -26,12 +26,15 @@
     ]
 
 
+from collections import OrderedDict
 import inspect
 from io import BytesIO
+import json
 import logging
 from pipes import quote
 import platform
 import re
+import shlex
 from subprocess import (
     PIPE,
     Popen,
@@ -48,7 +51,6 @@
 from testtools.content import Content
 from testtools.content_type import ContentType
 
-
 # Default location for maas-test state, such as SSH keys for the virtual
 # machine, and the http proxy cache.
 DEFAULT_STATE_DIR = '/var/cache/maas-test'
@@ -352,3 +354,36 @@
         key,
         '|'.join(re.escape(literal) for literal in values),
         )
+
+
+def make_json_power_parameters(raw_power_parameters):
+    """Convert a command-line string with power parameters into json."""
+    return json.dumps(
+        dict(
+            token.split('=')
+            for token in shlex.split(raw_power_parameters)
+        )
+    )
+
+
+def convert_bmc_details_into_parameters(mac, ip, username, password,
+                                        driver):
+    """Convert BMC details into MAAS-style power parameters."""
+    # Use an OrderedDict to ease testing.
+    power_parameters = OrderedDict([
+        ('power_user', username),
+        ('power_pass', password),
+        ('power_driver', driver),
+    ])
+    if mac is not None:
+        # XXX: rvb 2014-03-29 bug=https://bugs.launchpad.net/maas/+bug/1314174
+        # Set power_address to the empty string to avoid the power_address to
+        # be set to a wrong default.
+        power_parameters['power_address'] = ''
+        power_parameters['mac_address'] = mac
+    else:
+        power_parameters['power_address'] = ip
+    return ' '.join(
+        '%s=%s' % (key, quote(value))
+        for key, value in power_parameters.items()
+    )

=== modified file 'man/maas-test.8'
--- man/maas-test.8	2014-04-23 14:47:13 +0000
+++ man/maas-test.8	2014-04-30 06:58:59 +0000
@@ -210,30 +210,64 @@
 MAC address for the node\(aqs baseboard management controller.  MAAS will
 control the node\(aqs power and boot sequence through this controller.
 It must be attached to the testing network.  This is mutually
-exclusive with \fB\-\-bmc\-ip\fP\&.  This option is not needed in
-interactive mode.  In non\-interactive mode, either \fB\-\-bmc\-mac\fP or
-\fB\-\-bmc\-ip\fP is required.
+exclusive with \fB\-\-bmc\-ip\fP\&.  In non\-interactive mode, either \fB\-\-bmc\-mac\fP
+or \fB\-\-bmc\-ip\fP is required. Not needed in interactive mode or when using
+\fB\-\-power\-type\fP and \fB\-\-power\-parameters\fP\&.
 .TP
 .BI \-\-bmc\-ip\fB= IP
 IP address of the node\(aqs 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 \fB\-\-bmc\-mac\fP\&.  This option is not
-needed in interactive mode.  In non\-interactive mode, either
-\fB\-\-bmc\-mac\fP or \fB\-\-bmc\-ip\fP is required.
+This is mutually exclusive with \fB\-\-bmc\-mac\fP\&.  In non\-interactive mode,
+either \fB\-\-bmc\-mac\fP or \fB\-\-bmc\-ip\fP is required.
+Not needed in interactive mode or when using \-\-power\-type and
+\-\-power\-parameters.
 .TP
 .BI \-\-bmc\-password\fB= password
 Password for IPMI authentication on the BMC.  Use with \fB\-\-bmc\-user\fP\&.
-Not needed in interactive mode.
+Not needed in interactive mode or when using \fB\-\-power\-type\fP and
+\fB\-\-power\-parameters\fP\&.
 .TP
 .BI \-\-bmc\-user\fB= user
 Username for IPMI authentication.  Use with \fB\-\-bmc\-password\fP\&.
-Not needed in interactive mode.
+Not needed in interactive mode or when using \fB\-\-power\-type\fP and
+\fB\-\-power\-parameters\fP\&.
 .TP
 .BI \-\-ipmi\-driver\fB= 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.
+IPMI version 1.5. Not needed in interactive mode or if using \fB\-\-power\-type\fP and
+\fB\-\-power\-parameters\fP\&.
+.TP
+.BI \-\-power\-type\fB= power_type
+Power type of the node under test (e.g. \(aqipmi\(aq, \(aqamt\(aq, etc.
+See \fI\%http://maas.ubuntu.com/docs/api.html#power\-types\fP for a list of the supported
+power types and their related power parameters).
+Using \fB\-\-power\-type\fP and \fB\-\-power\-parameters\fP is an alternative to using
+the bmc\-* arguments that allows to use any one of the power mechanisms
+MAAS supports.
+.sp
+# Example: testing a node with an Active Management Technology (AMT) interface:
+.sp
+$ sudo maas\-test \-\-maas\-series trusty  \-\-architecture amd64
+\-\-power\-type=amt \-\-power\-parameters="mac_address=aa:bb:cc:dd:ee:ff
+power_pass=\(aqmy password\(aq"
+.sp
+# Example: testing a node with an Intelligent Platform Management Interface (IPMI):
+.sp
+$ sudo maas\-test \-\-maas\-series trusty  \-\-architecture amd64
+\-\-power\-type=ipmi \-\-power\-parameters="power_address=192.168.2.3 power_user=\(aqmy user\(aq
+power_pass=\(aqmy password\(aq power_driver=LAN_2_0"
+.TP
+.BI \-\-power\-parameters\fB= power_parameters
+Power parameters of the node under test (See
+\fI\%http://maas.ubuntu.com/docs/api.html#power\-types\fP for a list of the supported power
+types and their related power parameters).  This is a dict\-like expression of the
+power parameters for the specified power type.
+Using \fB\-\-power\-type\fP and \fB\-\-power\-parameters\fP is an alternative to using
+the bmc\-* arguments that allows to use any one of the power mechanisms
+MAAS supports.
+See the documentation for \fB\-\-power\-type\fP for examples.
 .TP
 .B \-\-interactive
 Interactive mode.  Instead of powering up the node automatically through