zhmccli - A CLI for the IBM Z HMC, written in pure Python

Introduction

What this package provides

The zhmccli package provides a CLI written in pure Python that interacts with the Hardware Management Console (HMC) of IBM Z or LinuxONE machines. The goal of this package is to provide an easy-to-use command line interface for operators.

The zhmccli package uses the API provided by the zhmcclient package, which interacts with the Web Services API of the HMC. It supports management of the lifecycle and configuration of various platform resources, such as partitions, CPU, memory, virtual switches, I/O adapters, and more.

Supported environments

The zhmccli package is supported in these environments:

  • Operating systems: Linux, Windows, OS-X
  • Python versions: 2.7, 3.4, and higher 3.x
  • HMC versions: 2.11.1 and higher

Installation

The easiest way to install the zhmccli package is by using Pip. Pip ensures that any dependent Python packages also get installed.

Pip will install the packages into your currently active Python environment (that is, your system Python or a virtual Python environment you have set up).

It is beneficial to set up a virtual Python environment for your project, because that leaves your system Python installation unchanged, it does not require sudo rights, and last but not least it gives you better control about the installed packages and their versions.

Installation of latest released version

The following command installs the latest released version of the zhmccli package from Pypi into the currently active Python environment:

$ pip install zhmccli

Installation of latest development version

If you want to install the latest development level of the zhmccli package instead for some reason, you can install directly from the master branch of its Git repository.

The following command installs the latest development level of the zhmccli package into the currently active Python environment:

$ pip install git+https://github.com/zhmcclient/zhmccli.git@master

Installation on a system without Internet access

In both cases described above, Internet access is needed to access these repositories.

If you want to install the zhmccli package on a system that does not have Internet access, you can do this by first downloading the zhmccli package and its dependent packages on a download system that does have Internet access, making these packages available to the target system, and installing on the target system from the downloaded packages.

For simplicity, the following example uses a shared file system between the download and target systems (but that is not a requirement; you can also copy the downloaded files to the target system):

[download]$ pip download zhmccli

[download]$ ls zhmccli*
zhmccli-0.18.0-py2.py3-none-any.whl

[target]$ ls zhmccli*
zhmccli-0.18.0-py2.py3-none-any.whl

[target]$ pip install -f . --no-index zhmccli-0.18.0-py2.py3-none-any.whl

Verification of the installation

You can verify that the zhmccli package and its dependent packages are installed correctly by invoking:

$ zhmc --version
0.18.0

Setting up the HMC

Usage of the zhmccli package requires that the HMC in question is prepared accordingly:

  1. The Web Services API must be enabled on the HMC.

  2. The HMC user ID that will be used by the zhmccli package must be authorized for the following tasks:

    • Use of the Web Services API.

    When using CPCs in DPM mode:

    • Start (a CPC in DPM mode)
    • Stop (a CPC in DPM mode)
    • New Partition
    • Delete Partition
    • Partition Details
    • Start Partition
    • Stop Partition
    • Dump Partition
    • PSW Restart (a Partition)
    • Create HiperSockets Adapter
    • Delete HiperSockets Adapter
    • Adapter Details
    • Manage Adapters
    • Export WWPNs

    When using CPCs in classic mode (or ensemble mode):

    • Activate (an LPAR)
    • Deactivate (an LPAR)
    • Load (an LPAR)
    • Customize/Delete Activation Profiles
    • CIM Actions ExportSettingsData

  3. (Optional) If desired, the HMC user ID that will be used by the zhmccli can be restricted to accessing only certain resources managed by the HMC. To establish such a restriction, create a custom HMC user role, limit resource access for that role accordingly, and associate the HMC user ID with that role.

    The zhmccli package needs object-access permission for the following resources:

    • CPCs to be accessed

    For CPCs in DPM mode:

    • Partitions to be accessed
    • Adapters to be accessed

    For CPCs in classic mode (or ensemble mode):

    • LPARs to be accessed

For details, see the HMC Operations Guide.

A step-by-step description for a similar use case can be found in chapter 11, section “Enabling the System z HMC to work the Pacemaker STONITH Agent”, in the KVM for IBM z Systems V1.1.2 System Administration book.

Examples

The following example lists the machines (CPCs) managed by an HMC:

$ hmc_host="<IP address or hostname of the HMC>"
$ hmc_userid="<userid on that HMC>"
$ zhmc -h $hmc_host -u $hmc_userid cpc list
Enter password (for user <hmc_user> at HMC <hmc_host>): .......
+----------+------------------+
| name     | status           |
|----------+------------------|
| P000S67B | service-required |
+----------+------------------+

Versioning

This documentation applies to version 0.21.0 of the zhmccli package. You can also see that version in the top left corner of this page.

The zhmccli package uses the rules of Semantic Versioning 2.0.0 for its version.

The package version can be shown using:

$ zhmc --version
0.18.0

This documentation may have been built from a development level of the package. You can recognize a development version of this package by the presence of a “.devD” suffix in the version string. Development versions are pre-versions of the next assumed version that is not yet released. For example, version 0.18.1.dev25 is development pre-version #25 of the next version to be released after 0.18.0. Version 0.18.1 is an assumed next version, because the actually released next version might as well be 0.19.0 or even 1.0.0.

Compatibility

In this package, compatibility is always seen from the perspective of the user of the CLI. Thus, a backwards compatible new version of this package means that the user can safely upgrade to that new version without encountering compatibility issues in the CLI that is invoked.

This package uses the rules of Semantic Versioning 2.0.0 for compatibility between package versions, and for deprecations.

The public API of this package that is subject to the semantic versioning rules (and specificically to its compatibility rules) is the API described in this documentation.

Violations of these compatibility rules are described in section Change log.

Deprecations

TODO: Verify how deprecation warnings are shown in the CLI.

Deprecated functionality is marked accordingly in this documentation and in the Change log, and is made visible at runtime by issuing Python warnings of type DeprecationWarning (see warnings for details).

Since Python 2.7, DeprecationWarning warnings are suppressed by default. They can be shown for example in any of these ways:

  • by specifying the Python command line option:

    -W default

  • by invoking Python with the environment variable:

    PYTHONWARNINGS=default

  • by issuing in your Python program:

    warnings.filterwarnings(action='default', category=DeprecationWarning)

It is recommended that users of this package run their test code with DeprecationWarning warnings being shown, so they become aware of any use of deprecated functionality.

It is even possible to raise an exception instead of issuing a warning message upon the use of deprecated functionality, by setting the action to 'error' instead of 'default'.

Reporting issues

If you encounter any problem with this package, or if you have questions of any kind related to this package (even when they are not about a problem), please open an issue in the zhmccli issue tracker.

License

This package is licensed under the Apache 2.0 License.

Command line interface

This package provides a command line interface (CLI) that utilizes the API of the zhmcclient package in order to support shell scripting or simply manual command use in a terminal session.

Modes of operation

The zhmc CLI supports two modes of operation:

  • Interactive mode: Invoking an interactive zhmc shell for typing zhmc sub-commands.
  • Command mode: Using it as a standalone non-interactive command.

Interactive mode

In interactive mode, an interactive shell environment is brought up that allows typing zhmc commands, internal commands (for operating the zhmc shell), and external commands (that are executed in the standard shell for the user).

This zhmc shell is started when the zhmc command is invoked without specifying any (sub-)commands:

$ zhmc [GENERAL-OPTIONS]
> _

Alternatively, the zhmc shell can also be started by specifying the repl (sub-)command:

$ zhmc [GENERAL-OPTIONS] repl
> _

The zhmc shell uses the > prompt, and the cursor is shown in the examples above as an underscore _.

General options may be specified on the zhmc command, and they serve as defaults for the zhmc commands that can be typed in the zhmc shell.

The zhmc commands that can be typed in the zhmc shell are simply the command line arguments that would follow the zhmc command when used in command mode:

$ zhmc -h zhmc.example.com -u hmcuser
Enter password: <password>
> cpc list
. . . <list of CPCs managed by this HMC>
> partition list JLSE1
. . . <list of partitions in CPC JLSE1>
> :q

For example, the zhmc shell command cpc list in the example above has the same effect as the standalone command:

$ zhmc -h zhmc.example.com -u hmcuser cpc list
Enter password: <password>
. . . <list of CPCs managed by this HMC>

However, the zhmc shell will prompt for a password only once during its invocation, while the standalone command will prompt for a password every time. See also Environment variables and avoiding password prompts.

The internal commands :?, :h, or :help display general help information for external and internal commands:

> :help
REPL help:

  External Commands:
    prefix external commands with "!"

  Internal Commands:
    prefix internal commands with ":"
    :?, :h, :help     displays general help information
    :exit, :q, :quit  exits the repl

In this help text, “REPL” stands for “Read-Execute-Print-Loop” which is a term that denotes the approach used in the zhmc shell (or in any shell, for that matter).

In addition to using one of the internal shell commands shown in the help text above, you can also exit the zhmc shell by typing Ctrl-D.

Typing --help in the zhmc shell displays general help information for the zhmc commands, which includes global options and a list of the supported commands:

> --help
Usage: zhmc  [OPTIONS] COMMAND [ARGS]...

  Command line interface for the IBM Z HMC.
  . . .

Options:
  -h, --host TEXT                 Hostname or IP address of the HMC (Default:
                                  ZHMC_HOST environment variable).
  -u, --userid TEXT               Username for the HMC (Default: ZHMC_USERID
                                  environment variable).
  -p, --password TEXT             Password for the HMC (Default: ZHMC_PASSWORD
                                  environment variable).
  -o, --output-format [[table|plain|simple|psql|rst|mediawiki|html|latex|
                      json]]
                                  Output format (Default: table).
  -x, --transpose                 Transpose the output table for metrics.
  -e, --error-format [msg|def]    Error message format (Default: msg).
  -t, --timestats                 Show time statistics of HMC operations.
  --log COMP=LEVEL,...            Set a component to a log level
                                  (COMP: [api|hmc|console|all],
                                   LEVEL: [error|warning|info|debug],
                                   Default: all=warning).
  --log-dest [stderr|syslog|none]
                                  Log destination for this command (Default:
                                  stderr).
  --syslog-facility [user|local0|local1|local2|local3|local4|local5|local6|local7]
                                  Syslog facility when logging to the syslog
                                  (Default: user).
  --version                       Show the version of this command and exit.
  --help                          Show this message and exit.

Commands:
  adapter           Command group for managing adapters.
  capacitygroup     Command group for managing capacity groups.
  cpc               Command group for managing CPCs.
  hba               Command group for managing HBAs.
  help              Show help message for interactive mode.
  info              Show information about the HMC.
  lpar              Command group for managing LPARs.
  metrics           Command group for reporting metrics.
  nic               Command group for managing NICs.
  partition         Command group for managing partitions.
  port              Command group for managing adapter ports.
  repl              Enter interactive (REPL) mode (default).
  session           Command group for managing sessions.
  storagegroup      Command group for managing storage groups.
  storagevolume     Command group for managing storage volumes.
  vfunction         Command group for managing virtual functions.
  vstorageresource  Command group for managing virtual storage resources.
  vswitch           Command group for managing virtual switches.

The usage line in this help text show the standalone command use. Within the zhmc shell, the zhmc word is ommitted and the remainder is typed in.

Typing COMMAND --help in the zhmc shell displays help information for the specified zhmc command, for example:

> cpc --help
Usage: zhmc  cpc [OPTIONS] COMMAND [ARGS]...

  Command group for managing CPCs.

Options:
  --help  Show this message and exit.

Commands:
  list  List the CPCs.
  show  Show details of a CPC.

The zhmc shell supports popup help text while typing, where the valid choices are shown based upon what was typed so far, and where an item from the popup list can be picked with <TAB> or with the cursor keys. In the following examples, an underscore _ is shown as the cursor:

> --_
    --host            Hostname or IP address of the HMC (Default: ZHMC_HOST environment variable).
    --userid          Username for the HMC (Default: ZHMC_USERID environment variable).
    --password        Password for the HMC (Default: ZHMC_PASSWORD environment variable).
    --output-format   Output format (Default: table).
    --transpose       Transpose the output table for metrics.
    --error-format    Error message format (Default: msg).
    --timestats       Show time statistics of HMC operations.
    --log             Set a component to a log level (COMP: [api|hmc|console|all], LEVEL: [error|warning|info|debug], Default: all=warning).
    --log-dest        Log destination for this command (Default: stderr).
    --syslog-facility Syslog facility when logging to the syslog (Default: user).
    --version         Show the version of this command and exit.

> c_
   cpc    Command group for managing CPCs.

The zhmc shell supports history (within one invocation of the shell, not persisted across zhmc shell invocations).

Command mode

In command mode, the zhmc command performs its task and terminates, like any other standalone non-interactive command.

This mode is used when the zhmc command is invoked with a (sub-)command:

$ zhmc [GENERAL-OPTIONS] COMMAND [ARGS...] [COMMAND-OPTIONS]

Examples:

$ zhmc -h zhmc.example.com -u hmcuser cpc list
Enter password: <password>
. . . <list of CPCs managed by this HMC>

$ zhmc -h zhmc.example.com info
Enter password: <password>
. . . <information about this HMC>

In command mode, bash tab completion is also supported, but must be enabled first as follows (in a bash shell):

$ eval "$(_ZHMC_COMPLETE=source zhmc)"

Bash tab completion for zhmc is used like any other bash tab completion:

$ zhmc --<TAB><TAB>
... <shows the global options to select from>

$ zhmc <TAB><TAB>
... <shows the commands to select from>

$ zhmc cpc <TAB><TAB>
... <shows the cpc sub-commands to select from>

Environment variables and avoiding password prompts

The zhmc CLI has command line options for specifying the HMC host, userid and password to be used.

If the HMC operations performed by a particular zhmc command require a password, and the password is not specified otherwise, the password is prompted for (in both modes of operation):

$ zhmc -h zhmc.example.com -u hmcuser cpc list
Enter password: <password>
. . . <list of CPCs managed by this HMC>

If the HMC operations performed by a particular zhmc command do not require a password, no password is prompted for:

$ zhmc -h zhmc.example.com info
. . . <information about this HMC>

For script integration, it is important to have a way to avoid the interactive password prompt, and still not being forced to specify the password on the command line. This can be done in either of two ways:

  • by storing the session-id string returned by the HMC when logging on, in an environment variable.

    The zhmc command supports a session create (sub-)command that outputs the (bash) shell commands to set all needed environment variables:

    $ zhmc -h zhmc.example.com -u hmcuser session create
Enter password: <password>
export ZHMC_HOST=zhmc.example.com
export ZHMC_USERID=hmcuser
export ZHMC_SESSION_ID=<session-id>

    This ability can be used to set those environment variables and thus to persist the session-id in the shell environment, from where it will be used in any subsequent zhmc commands:

    $ eval $(zhmc -h zhmc.example.com -u hmcuser session create)
Enter password: <password>

$ env |grep ZHMC
ZHMC_HOST=zhmc.example.com
ZHMC_USERID=hmcuser
ZHMC_SESSION_ID=<session-id>

$ zhmc cpc list
. . . <list of CPCs managed by this HMC>

    As you can see from this example, the password is only prompted for when creating the session, and the session-id stored in the shell environment is utilized in the zhmc cpc list command, avoiding another password prompt.

    Using the session-id from the environment is also a performance improvement, because it avoids the HMC Logon operation that otherwise would take place.

  • by storing the HMC password in the ZHMC_PASSWORD environment variable.

The ZHMC_HOST, ZHMC_USERID, and ZHMC_PASSWORD environment variables act as defaults for the corresponding command line options.

CLI commands

For a description of the commands supported by the zhmc CLI, consult its help system. For example:

$ zhmc --help
. . . <general help, listing the general options and possible commands>

$ zhmc cpc --help
. . . <help for cpc command, listing its arguments and command-specific options>

Note that the help text for any zhmc (sub-)commands (such as cpc) will not show the general options again. This is caused by flaws in the tooling environment used for the zhmc CLI. The general options (listed by zhmc --help) can still be specified together with (sub-)commands even though they are not listed in their help text, but they must be specified before the (sub-)command, and any command-specific options (listed by zhmc COMMAND --help) must be specified after the (sub-)command, like shown here:

$ zhmc [GENERAL-OPTIONS] COMMAND [ARGS...] [COMMAND-OPTIONS]

Resource properties

The properties of any resources (e.g. CPC or partition) are shown in any output using the names and units documented in the HMC WS API book.

Some of the commands have additional help options to explain output that is not documented in the HMC WS API book. For example, partition list command has a --help-usage option that explains the output of the usage-related options --memory-usage, --ifl-usage and --cp-usage.

Output formats

The zhmc CLI supports various output formats for the results. The output format can be selected with the -o or --output-format option. The following output formats are supported:

  • -o table: Tables with a single-line border. This is the default:

    +----------+------------------+
| name     | status           |
|----------+------------------|
| P0000P27 | operating        |
| P0000P28 | service-required |
| P0ZGMR12 | no-power         |
+----------+------------------+

  • -o psql: Same as ‘table’.

  • -o simple: Tables with a line between header row and data rows, but otherwise without borders:

    name      status
--------  ----------------
P0000P27  operating
P0000P28  service-required
P0ZGMR12  no-power

  • -o plain: Tables without borders:

    name      status
P0000P27  operating
P0000P28  service-required
P0ZGMR12  no-power

  • -o rst: Simple tables in reStructuredText markup:

    ========  ================
name      status
========  ================
P0000P27  operating
P0000P28  service-required
P0ZGMR12  no-power
========  ================

  • -o mediawiki: Tables in Mediawiki markup:

    {| class="wikitable" style="text-align: left;"
|+ <!-- caption -->
|-
! name     !! status
|-
| P0000P27 || operating
|-
| P0000P28 || service-required
|-
| P0ZGMR12 || no-power
|}

  • -o html: Tables in HTML markup:

    <table>
<thead>
<tr><th>name    </th><th>status          </th></tr>
</thead>
<tbody>
<tr><td>P0000P27</td><td>operating       </td></tr>
<tr><td>P0000P28</td><td>service-required</td></tr>
<tr><td>P0ZGMR12</td><td>no-power        </td></tr>
</tbody>
</table>

  • -o latex: Tables in LaTeX markup:

    \begin{tabular}{ll}
\hline
 name     & status           \\
\hline
 P0000P27 & operating        \\
 P0000P28 & service-required \\
 P0ZGMR12 & no-power         \\
\hline
\end{tabular}

  • -o json: JSON objects:

    [{"name": "P0000P28", "status": "service-required"},
 {"name": "P0ZGMR12", "status": "no-power"},
 {"name": "P0000P27", "status": "operating"}]

Error message formats

In order to be able to programmatically process errors, the zhmc CLI supports multiple formats for its error messages.

Error messages are always printed to stderr, and the zhmc command always ends with a non-zero return code in case of errors.

The format of error messages can be selected with the -e or --error-format option. The following error message formats are supported:

  • -e msg: Human-readable message. This is the default. This format should not be parsed by scripts, because it may change. Example:

    Error: ConnectTimeout: Connection to 9.152.150.86 timed out. (connect timeout=30)

  • -e def: Definition-style (e.g. “name: value”). In this format, the instance variables of the exception object causing the error are shown as variables. This format is meant for parsing by scripts that invoke the zhmc CLI and that need to handle specific error situations.

    The format of each error message is:

    Error: {str-def-result}

    where {str-def-result} is the return value of the str_def() method of the exception causing the error message (or rather its implementations in derived exception classes). Example:

    Error: classname='ConnectTimeout'; connect_timeout=30; connect_retries=3; message=u'Connection to 9.152.150.86 timed out. (connect timeout=30)';

    The variables for any particular exception is documented in the str_def() method of the exception class, in this case zhmcclient.ConnectTimeout.str_def():

    classname={}; connect_timeout={}; connect_retries={}; message={};

    The {} sequences contain the Python representations for the values (using repr()).

    With the exception of the initial “Error:”, this is in fact Python syntax for setting variables. Therefore, it is best to use Python for parsing it from within a shell script that invokes the zhmc CLI, for example as follows:

    err_file=$(mktemp)
cpc_list=$(zhmc -o json -e def cpc list 2>$err_file)
rc=$?
err=$(tail -n 1 <$err_file | sed -e 's/^Error: //')
rm $err_file
if [[ $rc != 0 ]]; then
    if [[ "$err" =~ "classname='ConnectTimeout';" ]]; then
        ct=$(python -c "$err print(connect_timeout)")
        echo "connect-timeout: $ct"
    fi
    msg=$(python -c "$err print(message)")
    echo "message: $msg"
    exit 1
fi
echo "$cpc_list"

CLI logging

The zhmc CLI supports logging to the standard error stream, and to the system log.

By default, the zhmc CLI logs to the standard error stream. This can be changed via the global option --log-dest which specifies the log destination:

  • stderr - Standard error stream of the zhmc command.
  • syslog - System log of the local system.
  • none - No logging.

The global option --log allows specifying one or more combinations of log component and log level. For example, the command:

$ zhmc --log hmc=debug,api=info ...

sets log level debug for the hmc component, and log level info for the api component.

Valid log levels are: error, warning, info, debug. In case of logging to the system log, this will also set the syslog priority accordingly.

Valid log components are:

  • api - Enable the zhmcclient.api Python logger, which logs any API calls into the zhmcclient library that are made from the zhmc CLI.
  • hmc - Enable the zhmcclient.hmc Python logger, which logs the interactions with the HMC.
  • console - Enable the zhmccli.console Python logger, which logs the interactions with the console of the operating system running in a partition or LPAR.
  • all - Enable the root Python logger, which logs anything that is propagated up to it. In case of the zhmc CLI, this will mostly be the requests package, plus the api and hmc components.

Logging to the system log

When specifying the syslog log destination, the enabled Python loggers log to the system log of the local system.

In order to see something in the system log, one has to understand how the log records are marked in terms of facility and priority and the corresponding matching of these markers in the syslog demon, and the mechanism that is used to write a record to the syslog needs to be enabled.

The write mechanism used by the zhmc CLI depends on the platform, as follows:

  • On Linux: Via a Unix socket to /dev/log, or if that fails via a UDP socket to localhost port 514
  • On OS-X: Via a Unix socket to /var/run/syslog, or if that fails via a UDP socket to localhost port 514
  • On Windows (native): Via a UDP socket to localhost port 514
  • On CygWin: Via a Unix socket to /dev/log, or if that fails via a UDP socket to localhost port 514

The respective mechanism must be enabled on the platform for logging to work. If the required mechanism is not enabled on a system, the log record will simply be dropped silently.

The facility used for each log record can be specified with the global option --syslog-facility, to be one of: user (default), local<N> with N=[0..7].

This facility marker can be used in the configuration of the syslog demon on the local system to direct log records into different files.

For example, on RHEL 7 and CentOS 7, the syslog demon’s config file is /etc/rsyslog.conf and may contain this:

#### RULES ####
*.info;mail.none;authpriv.none;cron.none                /var/log/messages

The first string is a semicolon-separated list of <facility>.<priority> markers, where * can be used for wildcarding. The first list item *.info means that any facility with priority info or higher will match this line and will thus go into the /var/log/messages file.

Because the zhmc CLI uses the debug log level, one can see that only if its corresponding priority is enabled in the syslog configuration:

#### RULES ####
*.debug;mail.none;authpriv.none;cron.none                /var/log/messages

Development

This section only needs to be read by developers of the zhmccli package. People that want to make a fix or develop some extension, and people that want to test the project are also considered developers for the purpose of this section.

Code of Conduct

Help us keep the zhmccli package open and inclusive. Please read and follow our Code of Conduct.

Repository

The source code repository for the zhmccli package is on GitHub:

https://github.com/zhmcclient/zhmccli

Setting up the development environment

The development environment is pretty easy to set up.

Besides having a supported operating system with a supported Python version (see Supported environments), it is recommended that you set up a virtual Python environment.

Then, with a virtual Python environment active, clone the Git repo of this project and prepare the development environment with make develop:

$ git clone git@github.com:zhmcclient/zhmccli.git
$ cd zhmccli
$ make develop

This will install all prerequisites the package needs to run, as well as all prerequisites that you need for development.

Generally, this project uses Make to do things in the currently active Python environment. The command make help (or just make) displays a list of valid Make targets and a short description of what each target does.

Building the documentation

The ReadTheDocs (RTD) site is used to publish the documentation for the zhmccli package at http://zhmccli.readthedocs.io/

This page automatically gets updated whenever the master branch of the Git repo for this package changes.

In order to build the documentation locally from the Git work directory, issue:

$ make builddoc

The top-level document to open with a web browser will be build_doc/html/docs/index.html.

Testing

To run unit tests in the currently active Python environment, issue one of these example variants of make test:

$ make test                                  # Run all unit tests
$ TESTCASES=test_resource.py make test       # Run only this test source file
$ TESTCASES=TestInit make test               # Run only this test class
$ TESTCASES="TestInit or TestSet" make test  # py.test -k expressions are possible

To run the unit tests and some more commands that verify the project is in good shape in all supported Python environments, use Tox:

$ tox                              # Run all tests on all supported Python versions
$ tox -e py27                      # Run all tests on Python 2.7
$ tox -e py27 test_resource.py     # Run only this test source file on Python 2.7
$ tox -e py27 TestInit             # Run only this test class on Python 2.7
$ tox -e py27 TestInit or TestSet  # py.test -k expressions are possible

The positional arguments of the tox command are passed to py.test using its -k option. Invoke py.test --help for details on the expression syntax of its -k option.

Contributing

Third party contributions to this project are welcome!

In order to contribute, create a Git pull request, considering this:

  • Test is required.
  • Each commit should only contain one “logical” change.
  • A “logical” change should be put into one commit, and not split over multiple commits.
  • Large new features should be split into stages.
  • The commit message should not only summarize what you have done, but explain why the change is useful.
  • The commit message must follow the format explained below.

What comprises a “logical” change is subject to sound judgement. Sometimes, it makes sense to produce a set of commits for a feature (even if not large). For example, a first commit may introduce a (presumably) compatible API change without exploitation of that feature. With only this commit applied, it should be demonstrable that everything is still working as before. The next commit may be the exploitation of the feature in other components.

For further discussion of good and bad practices regarding commits, see:

Format of commit messages

A commit message must start with a short summary line, followed by a blank line.

Optionally, the summary line may start with an identifier that helps identifying the type of change or the component that is affected, followed by a colon.

It can include a more detailed description after the summary line. This is where you explain why the change was done, and summarize what was done.

It must end with the DCO (Developer Certificate of Origin) sign-off line in the format shown in the example below, using your name and a valid email address of yours. The DCO sign-off line certifies that you followed the rules stated in DCO 1.1. In short, you certify that you wrote the patch or otherwise have the right to pass it on as an open-source patch.

We use GitCop during creation of a pull request to check whether the commit messages in the pull request comply to this format. If the commit messages do not comply, GitCop will add a comment to the pull request with a description of what was wrong.

Example commit message:

cookies: Add support for delivering cookies

Cookies are important for many people. This change adds a pluggable API for
delivering cookies to the user, and provides a default implementation.

Signed-off-by: Random J Developer <random@developer.org>

Use git commit --amend to edit the commit message, if you need to.

Use the --signoff (-s) option of git commit to append a sign-off line to the commit message with your name and email as known by Git.

If you like filling out the commit message in an editor instead of using the -m option of git commit, you can automate the presence of the sign-off line by using a commit template file:

  • Create a file outside of the repo (say, ~/.git-signoff.template) that contains, for example:

    <one-line subject>

<detailed description>

Signed-off-by: Random J Developer <random@developer.org>

  • Configure Git to use that file as a commit template for your repo:

    git config commit.template ~/.git-signoff.template

Releasing a version

This section shows the steps for releasing a version to PyPI.

It covers all variants of versions that can be released:

  • Releasing a new major version (Mnew.0.0) based on the master branch
  • Releasing a new minor version (M.Nnew.0) based on the master branch
  • Releasing a new update version (M.N.Unew) based on the stable branch of its minor version

This description assumes that you are authorized to push to the remote repo at https://github.com/zhmcclient/zhmc-ansible-modules and that the remote repo has the remote name origin in your local clone.

Any commands in the following steps are executed in the main directory of your local clone of the zhmc-ansible-modules Git repo.

  1. Set shell variables for the version that is being released and the branch it is based on:

    • MNU - Full version M.N.U that is being released
    • MN - Major and minor version M.N of that full version
    • BRANCH - Name of the branch the version that is being released is based on

    When releasing a new major version (e.g. 1.0.0) based on the master branch:

    MNU=1.0.0
MN=1.0
BRANCH=master

    When releasing a new minor version (e.g. 0.9.0) based on the master branch:

    MNU=0.9.0
MN=0.9
BRANCH=master

    When releasing a new update version (e.g. 0.8.1) based on the stable branch of its minor version:

    MNU=0.8.1
MN=0.8
BRANCH=stable_${MN}

  2. Create a topic branch for the version that is being released:

    git checkout ${BRANCH}
git pull
git checkout -b release_${MNU}

  3. Edit the version file:

    vi zhmccli/_version.py

    and set the __version__ variable to the version that is being released:

    __version__ = 'M.N.U'

  4. Edit the change log:

    vi docs/changes.rst

    and make the following changes in the section of the version that is being released:

    • Finalize the version.
    • Change the release date to today’s date.
    • Make sure that all changes are described.
    • Make sure the items shown in the change log are relevant for and understandable by users.
    • In the “Known issues” list item, remove the link to the issue tracker and add text for any known issues you want users to know about.
    • Remove all empty list items.

  5. When releasing based on the master branch, edit the GitHub workflow file test.yml:

    vi .github/workflows/test.yml

    and in the on section, increase the version of the stable_* branch to the new stable branch stable_M.N created earlier:

    on:
  schedule:
    . . .
  push:
    branches: [ master, stable_M.N ]
  pull_request:
    branches: [ master, stable_M.N ]

  6. Commit your changes and push the topic branch to the remote repo:

    git status  # Double check the changed files
git commit -asm "Release ${MNU}"
git push --set-upstream origin release_${MNU}

  7. On GitHub, create a Pull Request for branch release_M.N.U. This will trigger the CI runs.

    Important: When creating Pull Requests, GitHub by default targets the master branch. When releasing based on a stable branch, you need to change the target branch of the Pull Request to stable_M.N.

  8. On GitHub, close milestone M.N.U.

  9. On GitHub, once the checks for the Pull Request for branch start_M.N.U have succeeded, merge the Pull Request (no review is needed). This automatically deletes the branch on GitHub.

  10. Add a new tag for the version that is being released and push it to the remote repo. Clean up the local repo:

    git checkout ${BRANCH}
git pull
git tag -f ${MNU}
git push -f --tags
git branch -d release_${MNU}

  11. When releasing based on the master branch, create and push a new stable branch for the same minor version:

    git checkout -b stable_${MN}
git push --set-upstream origin stable_${MN}
git checkout ${BRANCH}

    Note that no GitHub Pull Request is created for any stable_* branch.

  12. On GitHub, edit the new tag M.N.U, and create a release description on it. This will cause it to appear in the Release tab.

    You can see the tags in GitHub via Code -> Releases -> Tags.

  13. On ReadTheDocs, activate the new version M.N.U:

  14. Upload the package to PyPI:

    make upload

    This will show the package version and will ask for confirmation.

    Attention! This only works once for each version. You cannot release the same version twice to PyPI.

    Verify that the released version arrived on PyPI at https://pypi.python.org/pypi/zhmccli/

Starting a new version

This section shows the steps for starting development of a new version.

This section covers all variants of new versions:

  • Starting a new major version (Mnew.0.0) based on the master branch
  • Starting a new minor version (M.Nnew.0) based on the master branch
  • Starting a new update version (M.N.Unew) based on the stable branch of its minor version

This description assumes that you are authorized to push to the remote repo at https://github.com/zhmcclient/zhmc-ansible-modules and that the remote repo has the remote name origin in your local clone.

Any commands in the following steps are executed in the main directory of your local clone of the zhmc-ansible-modules Git repo.

  1. Set shell variables for the version that is being started and the branch it is based on:

    • MNU - Full version M.N.U that is being started
    • MN - Major and minor version M.N of that full version
    • BRANCH - Name of the branch the version that is being started is based on

    When starting a new major version (e.g. 1.0.0) based on the master branch:

    MNU=1.0.0
MN=1.0
BRANCH=master

    When starting a new minor version (e.g. 0.9.0) based on the master branch:

    MNU=0.9.0
MN=0.9
BRANCH=master

    When starting a new minor version (e.g. 0.8.1) based on the stable branch of its minor version:

    MNU=0.8.1
MN=0.8
BRANCH=stable_${MN}

  2. Create a topic branch for the version that is being started:

    git checkout ${BRANCH}
git pull
git checkout -b start_${MNU}

  3. Edit the version file:

    vi zhmccli/_version.py

    and update the version to a draft version of the version that is being started:

    __version__ = 'M.N.U.dev1'

  4. Edit the change log:

    vi docs/changes.rst

    and insert the following section before the top-most section:

    Version M.N.U.dev1
^^^^^^^^^^^^^^^^^^

This version contains all fixes up to version M.N-1.x.

Released: not yet

**Incompatible changes:**

**Deprecations:**

**Bug fixes:**

**Enhancements:**

**Cleanup:**

**Known issues:**

* See `list of open issues`_.

.. _`list of open issues`: https://github.com/zhmcclient/zhmccli/issues

  5. Commit your changes and push them to the remote repo:

    git status  # Double check the changed files
git commit -asm "Start ${MNU}"
git push --set-upstream origin start_${MNU}

  6. On GitHub, create a Pull Request for branch start_M.N.U.

    Important: When creating Pull Requests, GitHub by default targets the master branch. When starting a version based on a stable branch, you need to change the target branch of the Pull Request to stable_M.N.

  7. On GitHub, create a milestone for the new version M.N.U.

    You can create a milestone in GitHub via Issues -> Milestones -> New Milestone.

  8. On GitHub, go through all open issues and pull requests that still have milestones for previous releases set, and either set them to the new milestone, or to have no milestone.

  9. On GitHub, once the checks for the Pull Request for branch start_M.N.U have succeeded, merge the Pull Request (no review is needed). This automatically deletes the branch on GitHub.

  10. Update and clean up the local repo:

    git checkout ${BRANCH}
git pull
git branch -d start_${MNU}

Appendix

This section contains information that is referenced from other sections, and that does not really need to be read in sequence.

Glossary

This documentation uses a few special terms:

HMC
Hardware Management Console; the node the zhmcclient talks to.
session-id
an opaque string returned by the HMC as the result of a successful logon, for use by subsequent operations instead of credential data. The HMC gives each newly created session-id a lifetime of 10 hours, and expires it after that.

Change log

Version 0.21.0

Released: 2021-04-06

Enhancements:

  • Increased minimum version of zhmcclient to 0.30.0.
  • Added an option –secure-boot to lpar scsi-load command (issue #148).
  • Added an option –force to lpar scsi-dump command (issue #148).
  • Added support for DPM capacity groups with a new ‘capacitygroup’ command group. (issue #157)

Version 0.20.0

Released: 2021-03-25

Incompatible changes:

  • In the ‘cpc list’ command, removed the output of the ‘iml-mode’ and ‘is-ensemble-member’ properties, because ensemble support has been removed from the HMC by now.

Deprecations:

  • Deprecated several property control options in ‘list’ commands because the corresponding properties are now always shown:
    • --type option in the ‘adapter list’ command
    • --type option in the ‘cpc list’ command
    • --mach option in the ‘cpc list’ command
    • --type option in the ‘lpar list’ command
    • --type option in the ‘nic list’ command
    • --type option in the ‘partition list’ command
    • --adapter option in the ‘vswitch list’ command
  • Deprecated the options --boot-storage-hba/wwpn/lun of the ‘partition update’ command for booting from an FCP storage volume. Use the new --boot-storage-volume option instead with the “HBA/WWPN/LUN” format. (part of issue #130)

Bug fixes:

  • Fixed a log test failure in zhmccli caused by a change in logging output in zhmcclient 0.23.0.
  • Fixed an exception “No formatted text” on python 2.7 by pinning ‘prompt-toolkit’ to <2.0 on Python 2.7 (issue #53).
  • Mitigated the coveralls HTTP status 422 by pinning coveralls-python to <3.0.0.
  • Pinned Pygments to <2.4.0 on Python 3.4.
  • Pinned readme-renderer to <25.0 on Python 3.4.
  • Fixed AttributeError when listing hbas on CPCs that have the storage mgmt feature (z14 and later) (issue #113).
  • Fixed a KeyError when accessing the email-related options in the ‘storagegroup create’ and ‘storagegroup update’ commands. (issue #129)
  • Fixed a KeyError when accessing a no longer existing option in the ‘storagevolume create’ command. (issue #137)
  • Test: Fixed GitHub Actions test workflow failure by increasing the version of the ‘readme-renderer’ package to a minimum of 0.23.0 which moved the failing ‘cmarkgfm’ dependent package to an extra we are not using.

Enhancements:

  • Increased minimum version of zhmcclient package from 0.19.0 to 0.25.0 due to new LPAR related functions being used.

  • Added a ‘dump’ command for ‘zhmc partition’ that works for CPCs with and without the DPM storage management feature.

  • Added more ‘zhmc lpar’ commands for logical partitions in CPCs in classic mode:

    • zhmc lpar stop
    • zhmc lpar psw-restart
    • zhmc lpar scsi-load
    • zhmc lpar scsi-dump

  • Added support for usage related command line options to the partition list command that include additional fields in the output: –memory-usage for showing memory allocation to the partitions, –ifl-usage and –cp-usage for showing IFL and CP allocation, weighted capacity and actual usage.

  • Added more lpar load command options:

    • Added --clear-indicator and --no-clear-indicator flags to the lpar load command. It controls whether the memory should be cleared before performing the load operation or not.
    • Added --store-status-indicator flag to the lpar load command. It controls whether the status should be stored before performing the load operation or not.

  • Added os-ipl-token option to the lpar scsi-dump command.

  • Added support for the storage management feature, by adding new command groups storagegroup, storagevolume, and vstorageresource and by adding new storage management related sub-commands to the partition command group (issue #56).

  • Added support for Python 3.7.

  • Migrated from Travis and Appveyor to GitHub Actions. This required several changes in package dependencies for development.

  • Dropped the use of the pbr package. The package version is now managed in zhmccli/_version.py. (See issue #64)

  • Added Python 3.9 to the set of versions that is tested in the CI.

  • Test: Ensured that dependent packages are upgraded to their latest versions in ‘make install’ and ‘make develop’ by invoking Pip with ‘–upgrade-strategy eager’.

  • Added some more resource properties to ‘list’ commands, including name properties of the parent resources. All ‘list’ commands now support these options for controlling the properties shown (issue #93):

    • --names-only: Restrict properties shown to only the names of the resource and its parents
    • --uri: Add the resource URI to the properties shown
    • --all: Show all properties

  • Increased minimum version of Click from 6.6. to 7.0 to get support for ‘hidden’ property of options (related to issue #93).

  • Added support for setting a storage volume in a storage group as the boot volume for a partition, by adding an option --boot-storage-volume to the ‘partition update’ command (issue #130)

  • Conflicting boot options specified for the ‘partition update’ and ‘partition create’ command are now detected instead of silently applying an undocumented preference scheme. (part of issue #130)

  • Changed CPC and LPAR properties that were always hidden in the output of the cpc show and lpar show commands due to their length or object nesting depth, to now be hidden only in certain cases.

    Changed Partition properties in the output of the partition show command that have a significant length or object nesting depth to now be hidden in certain cases.

    The hidden properties are now always shown in the JSON output format, and they are shown in the table output formats if a newly added --all option is used on these show commands.

    Hidden CPC properties: - auto-start-list - available-features-list - cpc-power-saving-state - ec-mcl-description - network1-ipv6-info - network2-ipv6-info - stp-configuration

    Hidden LPAR properties: - program-status-word-information

    Hidden Partition properties: - crypto-configuration

    (related to issue #56, also issue #144).

  • Increased minimum version of zhmcclient to 0.29.0.

  • Docs: Changed documentation theme to Sphinx RTD Theme. (issue #155)

Cleanup:

  • Changed old-style string formatting to new-style (issue #89).
  • Removed build tools no longer needed on GitHub Actions.

Version 0.19.0

Released: 2019-02-20

Incompatible changes:

  • The lpar deactivate command is now non-forceful by default, but can be made to behave like previously by specifying the new --force option. In force mode, the deactivation operation is permitted when the LPAR status is “operating”.

Bug fixes:

  • Aligned the check for when to use pyreadline instead of readline in zhmcclient/_helper.py to be consistent with the platform check in requirements.txt: By checking for the win32 platform. Related to issue #47.

Enhancements:

  • Fixes and improvements in Makefile.

  • Added initial set of function tests for zhmc command.

  • Improved the table output of complex properties (arrays or nested objects), to use nested tables, where possible. See issue #9.

  • Added support for a --force option in the lpar activate, lpar deactivate, and lpar load commands. It controls whether the operation is permitted when the LPAR status is “operating”.

    Note that this changes lpar deactivate to be non-forceful by default (force=True was hard coded for deactivate, before this change).

  • Added support for a --activation-profile-name option in LPAR activate.

  • Added support for cpc set-power'save, cp set-power-capping and cpc get-em-data operations.

  • Improved support for logging to the system log in zhmccli.py: Added support for retrying multiple addresses if creating a Python system log handler fails. Added localhost:514 as a second choice for Linux and OS-X. This fixes the system log issue on the Travis CI with Ubuntu 14.04 (Issue 35). Added support for system log in CygWin, using /dev/log and localhost:514 as the addresses to try.
  • Removed the assertions in zhmccli.reset_logger() that verified the result of resetting the log handlers. It turned out that recently, a log capture logger is present that is caused by the test environment. These assertions were probably a bit overkill anyway (Issue #35).

Version 0.18.0

Released: 2017-10-19

This is the base version for this change log. The zhmccli project was split off of the python-zhmcclient project based upon its released version 0.17.0. For prior changes, see the change log of the python-zhmcclient project.

Additional changes:

  • Fixed the issue that the readline module is not available in standard python on Windows, by using the pyreadline module in that case.
  • Fixed a flawed setup of setuptools in Python 2.7 on the Travis CI, where the metadata directory of setuptools existed twice, by adding a script remove_duplicate_setuptools.py that removes the moot copy of the metadata directory (python-zhmcclient issue #434).
  • Added the version of the zhmcclient package to the output of zhmc --version.