1. Introduction

1.1. 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.

1.2. Supported environments

The zhmccli package is supported in these environments:

  • Operating systems: Linux, Windows, OS-X

  • Python versions: 3.6 and higher

  • HMC versions: 2.11.1 and higher

1.3. 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.

Note that an installation of Python packages using setup.py install is no longer recommended by the Python packaging community. For details, see https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html. Installation with setup.py install is no longer supported by this package.

1.3.1. 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

1.3.2. 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

1.3.3. 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

1.3.4. 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

1.4. 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.

1.5. Setting up firewalls or proxies

If you have to configure firewalls or proxies between the client system and the HMC, the following ports need to be opened:

  • 6794 (TCP) - for the HMC API HTTP server

  • 61612 (TCP) - for the HMC API message broker via JMS over STOMP

For details, see sections “Connecting to the API HTTP server” and “Connecting to the API message broker” in the HMC API book.

1.6. 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 |
+----------+

1.7. Versioning

This documentation applies to version 1.10.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.

1.8. 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.

1.9. 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'.

1.10. 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.

1.11. License

This package is licensed under the Apache 2.0 License.