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.5, 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:

The Web Services API must be enabled on the HMC.
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
(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 names of 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 --names-only
Enter password (for user ... at HMC ...): .......
+----------+
| name     |
|----------+
| P000S67B |
+----------+

Versioning

This documentation applies to version 1.3.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).
  -n, --no-verify                 Do not verify the HMC certificate. (Default:
                                  ZHMC_NO_VERIFY environment variable, or
                                  verify the HMC certificate).
  -c, --ca-certs TEXT             Path name of certificate file or directory
                                  with CA certificates to be used for
                                  verifying the HMC certificate. (Default:
                                  Path name in ZHMC_CA_CERTS environment
                                  variable, or path name in REQUESTS_CA_BUNDLE
                                  environment variable, or path name in
                                  CURL_CA_BUNDLE environment variable, or the
                                  'certifi' Python package which provides the
                                  Mozilla CA Certificate List).
  -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 versions of this command and of the
                                  zhmcclient package and exit.
  --help                          Show this message and exit.

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

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).
    --no-verify       Do not verify the HMC certificate. (Default: ZHMC_NO_VERIFY ...
    --ca-certs        Path name of certificate file or directory with CA certificates ...
    --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 -n -h zhmc.example.com -u acsadmin session create
Enter password: <password>
export ZHMC_HOST=zhmc.example.com
export ZHMC_USERID=acsadmin
export ZHMC_SESSION_ID=<session-id>
export ZHMC_NO_VERIFY=TRUE
unset ZHMC_CA_CERTS
```
Note that the -n option is used to make this command work for demonstration purposes regardless of the actual HMC certificate setup. It is not recommended to use this option in production environments. See HMC certificate for details.

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 -n -h zhmc.example.com -u acsadmin session create)
Enter password: <password>

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

$ 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, ZHMC_PASSWORD, ZHMC_NO_VERIFY, and ZHMC_CA_CERTS environment variables act as defaults for the corresponding command line options.

HMC certificate

By default, the HMC is configured with a self-signed certificate. That is the X.509 certificate presented by the HMC as the server certificate during SSL/TLS handshake at its Web Services API.

Starting with version 0.22, the ‘zhmc’ command will reject self-signed certificates by default.

The HMC should be configured to use a CA-verifiable certificate. This can be done in the HMC task “Certificate Management”. See also the HMC Security book and Chapter 3 “Invoking API operations” in the HMC API book.

Starting with version 0.22, the zhmc command provides control knobs for the verification of the HMC certificate via the -c / --ca-certs and -n / --no-verify command line options, as follows:

None of the two options specified (default): Verify the HMC certificate using the CA certificates from the first of these locations:
- The certificate file or directory in the ZHMC_CA_CERTS environment variable, if set
- The certificate file or directory in the REQUESTS_CA_BUNDLE environment variable, if set
- The certificate file or directory in the CURL_CA_BUNDLE environment variable, if set
- The Python ‘certifi’ package (which contains the Mozilla Included CA Certificate List).
-c / --ca-certs specified: Verify the HMC certificate using the CA certificates in the specified certificate file or directory.
-n / --no-verify specified or ZHMC_NO_VERIFY environment variable set: Do not verify the HMC certificate. Not verifying the HMC certificate means that hostname mismatches, expired certificates, revoked certificates, or otherwise invalid certificates will not be detected. Since this mode makes the connection vulnerable to man-in-the-middle attacks, it is insecure and should not be used in production environments.

If a certificate file is specified (using any of the ways listed above), that file must be in PEM format and must contain all CA certificates that are supposed to be used. Usually they are in the order from leaf to root, but that is not a hard requirement. The single certificates are concatenated in the file.

If a certificate directory is specified (using any of the ways listed above), it must contain PEM files with all CA certificates that are supposed to be used, and copies of the PEM files or symbolic links to them in the hashed format created by the OpenSSL command c_rehash.

An X.509 certificate in PEM format is base64-encoded, begins with the line -----BEGIN CERTIFICATE-----, and ends with the line -----END CERTIFICATE-----. More information about the PEM format is for example on this www.ssl.com page or in this serverfault.com answer.

Note that setting the REQUESTS_CA_BUNDLE or CURL_CA_BUNDLE environment variables influences other programs that use these variables, too.

For more information, see the Security section in the documentation of the ‘zhmcclient’ package.

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.

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}
```

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

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

Edit the version file:
```
vi zhmccli/_version.py
```
and set the __version__ variable to the version that is being released:
```
__version__ = 'M.N.U'
```
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.
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 ]
```

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}

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.
On GitHub, close milestone M.N.U.
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.
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}
```
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.
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.
On ReadTheDocs, activate the new version M.N.U:
- Go to https://readthedocs.org/projects/zhmccli/versions/ and log in.
- Activate the new version M.N.U.
  
  This triggers a build of that version. Verify that the build succeeds and that new version is shown in the version selection popup at https://zhmccli.readthedocs.io/
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.

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}
```

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

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

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'
```

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

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}

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.
On GitHub, create a milestone for the new version M.N.U.

You can create a milestone in GitHub via Issues -> Milestones -> New Milestone.
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.
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.

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.

Bibliography

HMC API: The Web Services API of the z Systems Hardware Management Console, described in the following books:
HMC API 2.11.1: IBM SC27-2616, z Systems Hardware Management Console Web Services API (Version 2.11.1)
HMC API 2.12.0: IBM SC27-2617, z Systems Hardware Management Console Web Services API (Version 2.12.0)
HMC API 2.12.1: IBM SC27-2626, z Systems Hardware Management Console Web Services API (Version 2.12.1)
HMC API 2.13.0: IBM SC27-2627, z Systems Hardware Management Console Web Services API (Version 2.13.0)
HMC API 2.13.1: IBM SC27-2634, z Systems Hardware Management Console Web Services API (Version 2.13.1)
HMC Operations Guide: The operations guide of the z Systems Hardware Management Console, described in the following books:
HMC Operations Guide 2.11.1: IBM SC28-6905, System z Hardware Management Console Operations Guide (Version 2.11.1)
HMC Operations Guide 2.13.1: IBM z Systems Hardware Management Console Operations Guide (Version 2.13.1)
HMC Security: Hardware Management Console Security
KVM for IBM z Systems V1.1.2 System Administration: IBM SC27-8237, KVM for IBM z Systems V1.1.2 System Administration

Change log

Version 1.3.0

This version contains all fixes up to version 1.2.3.

Released: 2022-10-23

Bug fixes:

Fixed that –vlan-id could not be ommitted in ‘zhmc nic create’ and ‘zhmc nic update’. (issue #291)
Added a ‘–vlan-type’ option to ‘zhmc nic create’ and ‘zhmc nic update’ to set the VLAN type. (issue #292)
Fixed a flake8 AttributeError when using importlib-metadata 5.0.0 on Python >=3.7, by pinning importlib-metadata to <5.0.0 on these Python versions.
Fixed that ‘user create’ passed the ‘mfa-types’ and ‘multi-factor-authentication-required’ properties to the HMC even when no MFA-related options were specified. This caused rejection of the command on HMC versions 2.14.0 and older. (issue #286)
Fixed that the –boot-iso option of the ‘partition update’ command took a TEXT argument (which was not used). Changed that to a flag option. (issue #287)
Fixed a TypeError raised by ‘zhmc vstorageresource list’ when a candidate adapter had not yet been discovered. (part of issue #307)

Enhancements:

Help messages now use the actual terminal width up to 160 characters, and require a minimum terminal width of 80. The automatic detection of the terminal width can be overridden by setting the env var ZHMCCLI_TERMWIDTH to the desired terminal width.
Added support for specifying the ‘acceptable-status’ property in the zhmc commands ‘partition create’ and ‘partition update’ via a new –acceptable-status option. Multiple status values can be specified as a comma-separated list. (issue #285)
Extended the –acceptable-status option of the zhmc commands ‘cpc update’ and ‘lpar update’ to support multiple status values as a comma-separated list. (issue #285)
Added artificial properties to all ‘show’ commands that show the name of resources referenced via an URI. (issue #307)
Added artificial properties to the ‘zhmc nic show’ command for the backing adapter and port if the NIC is backed by a vswitch (i.e. for OSA, Hipersockets). (issue #307)

Version 1.2.0

This version contains all fixes up to version 1.1.1.

Released: 2022-04-02

Bug fixes:

Fixed that the “lpar scsi-load” and “lpar scsi-dump” commands defined their –disk-partition-id option value incorrectly as a string, when it should have been an integer. (issue #270)
Fixed that “lpar list –names-only” had an empty “cpc” column. (issue #269)
Increaed minimum vbersion of zhmcclient to 1.2.1 to pick up several fixes, including the fix for ‘lpar scsi-dump’ failing due to missing ‘secure_boot’ parameter (issue #280)

Enhancements:

Properties in JSON output are now always sorted by property name. (issue #267)
Added support for the “console” command group, with the following commands:
- get-audit-log - Get the audit log of the targeted HMC.
- get-security-log - Get the security log of the targeted HMC.
- show - Show properties of the console of the targeted HMC.
Issue #277

Version 1.1.0

This version contains all fixes up to version 1.0.3.

Released: 2021-12-23

Bug fixes:

Changed development status of zhmccli on Pypi from 4 (Beta) to 5 (Production/Stable). (issue #221)
Fixed new issues reported by Pylint 2.10.
Disabled new Pylint issue ‘consider-using-f-string’, since f-strings were introduced only in Python 3.6.
Fixed install error of wrapt 1.13.0 on Python 2.7 on Windows due to lack of MS Visual C++ 9.0 on GitHub Actions, by pinning it to <1.13.
Fixed confusing CR in Aborted message when breaking a prompt.
Fixed an error in the ‘partition dump’ command when –operation-timeout was specified, and in ‘storagegroup delete’ when the email options were used. (issue #250)

Enhancements:

Added support for managing the auto-start list of a CPC (in DPM mode) via a new command group ‘cpc autostart’. (issue #33)
Improved error handling so that exceptions raised by zhmcclient now always result in displaying a proper error message instead of a Python traceback.
Added support for managing HMC users, user roles, and password rules via new command groups ‘user’, ‘userrole’, ‘passwordrule’, and ‘passwordrule characterrule’. (part of issue #96)
Added support for exporting and importing a DPM configuration from / to a CPC via new ‘dpm-export’ and ‘dpm-import’ commands of the ‘cpc’ command group. (issue #243)
Increased minimum version of zhmcclient to 1.1.0, and added the jsonschema, PyYAML and yamllloader packages as new dependencies, as part of issue #243.
Support for Python 3.10: Added Python 3.10 in GitHub Actions tests, and in package metadata.
Added support for a ‘–like’ option when creating users. This will use certain properties of the like user as defaults for the new user.

Cleanup:

Removed import of the pyreadline package on Windows for enabling history in interactive mode, and import of the built-in readline module since it no longer seems to be needed and interactive mode history is available without them.
Removed building of the Windows binary install program, since that is no longer supported by pip/setuptools. It was not used in the package anyway.

Version 1.0.0

Released: 2021-08-18

Incompatible changes:

Dropped support for Python 3.4. Python 3.4 has had its last release as 3.4.10 on March 18, 2019 and has officially reached its end of life as of that date. Current Linux distributions no longer support Python 3.4. (issue #185)
Changed default for option ‘–usage’ of ‘storagevolume update’ command to not be changed. Prior default was to set usage to ‘data’, which required specifying it with the old value if it was supposed not to be changed. (part of issue #125)

Bug fixes:

Fixed HTTP errors raised as traceback during various ‘list’ commands. These errors are now shown as proper error messages. (issue #215)

Enhancements:

Increased minimum version of zhmcclient to 1.0.0.
Added defaults to help text of command options with value, where missing. (issue #125)
Added a ‘–secure-boot’ option to the ‘lpar scsi-dump’ and ‘partition update’ commands. It had already been supported by the ‘lpar scsi-load’ command. (issue #206)
Added support for setting some properties of lpar, partition and nic resources to null when specifying an empty string as the option value in create and update commands. The option help text has been updated accordingly. (issue #2)
Clarified in help text of ‘–ssc-dns-servers’ option of the ‘partition create’ and ‘partition update’ commands that multiple DNS servers are specified using a comma-separated list. (issue #216)

Version 0.22.0

This version contains all fixes up to version 0.21.2.

Released: 2021-07-02

Incompatible changes:

The zhmc command now verifies HMC server certificates by default, using the CA certificates in the ‘certifi’ Python package. This verification will reject the self-signed certificates the HMC is set up with initially. To deal with this, install a CA-verifiable certificate in the HMC and specify the correct CA certificates with the new ‘-c / –ca-certs’ option. As a temporary quick fix, you can disable the verification with the new ‘-n / –no-verify’ option.

Bug fixes:

Fixed install error on Python>=3.6 caused by click-repl being incompatible with click 8.0.
Fixed the issue that some commands (e.g. cpc list) stopped the spinner too early. (issue #142)
Docs: Added statement that the command group for HBAs can be used only on z13 and earlier. (issue #199)
Docs: Clarified which command groups can only be used in DPM mode or in classic mode. (issue #200)

Enhancements:

The zhmc command now supports verification of the HMC server certificate. There are two new command line options ‘-n / –no-verify’ and ‘-c / –ca-certs’ that control the verification behavior.
Increased the minimum version of zhmcclient to 0.32.0. Adjusted code to accomodate the immutable properties of resource objects.
Added a ‘-T’ / ‘–operation-timeout’ general option to the following commands, that specifies the operation timeout when waiting for completion of asynchronous HMC operations. (issue #126)
- lpar activate
- lpar deactivate
- lpar load
- lpar stop
- lpar psw_restart
- lpar scsi-load
- lpar scsi-dump
- partition start
- partition stop
- partition dump
- storagegroup discover-fcp
Partition commands: On HMC 2.14.0 and later, the partition commands now use the “List Permitted Partitions” operation instead of going through the CPC, which improves the response time, and no longer requires that the user has object access permission to the targeted CPC. In addition, the CPC on the ‘partition list’ command is now optional. If not specified, permitted partitions on all managed CPCs are listed. (issue #192)
Lpar commands: On HMC 2.14.0 and later, the lpar commands now use the “List Permitted Logical Partitions” operation instead of going through the CPC, which improves the response time. In addition, on HMC API version 3.6 or later (an update to HMC 2.15.0), the lpar commands no longer require that the user has object access permission to the targeted CPC. In addition, the CPC on the ‘lpar list’ command is now optional. If not specified, permitted LPARs on all managed CPCs are listed. (issue #192)
The ‘nic create’ and ‘nic update’ commands can now specify the backing port with the –adapter and –port options for all types of network adapters. Previously, they could be used only for OSA and Hipersocket adapters. The –virtual-switch option has been deprecated but for compatibility reasons is still supported for OSA and Hipersocket adapters. (issues #201, #198)

Cleanup:

Added the missing closing of the image file in the ‘partition mount-iso’ command.
Disabled a Pylint ‘consider-using-with’ issue on a Popen in test code that was properly terminated again.

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.