2. Installation

This section describes how to install the zhmccli Python package and set up the HMC.

2.1. Steps

The installation steps are described using Unix/Linux/macOS commands. When installing on Windows, use the equivalent Windows commands (e.g. “md” instead of “mkdir”).

Install the zhmccli Python package using any of the following approaches:
- Installation using pipx (recommended approach)
- Installation into a virtual Python environment
- Installation into a system Python
- Installation on a system without Internet access
You can verify that the zhmccli package and its dependent packages are installed correctly by invoking:
```
$ zhmc --version
zhmc, version 1.13.0
zhmcclient, version 1.21.0
```
Make sure the HMC is set up correctly.
- The Web Services API is enabled on the HMC
- The HMC should have a CA-verifiable certificate installed
- The HMC userid has permission for the Web Services API
- The HMC userid has the required object and task permissions
For details, see Setting up the HMC.
Make sure the HMC can be reached from the system that runs the zhmc command.

When using firewalls or proxies, see Setting up firewalls or proxies.

2.2. Installation using pipx

The recommended way to use the zhmccli Python package is by installing it with pipx.

Pipx creates a virtual Python environment under the covers and installs the zhmccli Python package into that environment and makes the zhmc command available in a directory that is in the PATH. The zhmc command will be available that way, regardless of whether or not you have a virtual Python environment active (that you may need for other purposes).

Prerequisite: Install pipx as an OS-level package

Follow the steps at https://pipx.pypa.io/stable/installation/ to install pipx as an OS-level package to your local system.
Without having any virtual Python environment active, install zhmccli using pipx

To install the latest released version of zhmccli:
```
$ pipx install zhmccli
```
To install a specific released version of zhmccli, e.g. 1.2.0:
```
$ pipx install zhmccli==1.2.0
```
To install a specific development branch of zhmccli, e.g. master:
```
$ pipx install git+https://github.com/zhmcclient/zhmccli.git@master
```
To install zhmccli with a non-default Python version, e.g. 3.10:
```
$ pipx install zhmccli --python python3.10
```

2.3. Installation into a virtual Python environment

In some cases it may be useful to install zhmccli into your own virtual Python environment. That avoids the dependency to pipx, but it requires you to activate the virtual environment every time you want to use the zhmc command.

There are a number of ways how virtual Python environments can be created. This documentation describes the use of “virtualenv”:

Prerequisite: Install the Python virtualenv package as an OS-level package or into the system Python.

Follow the steps at https://virtualenv.pypa.io/en/latest/installation.html to install virtualenv.

Create and activate a virtual Python environment:

$ virtualenv ~/.virtualenvs/zhmc
$ source ~/.virtualenvs/zhmc/bin/activate

Install zhmccli into the virtual Python environment:

To install the latest released version of zhmccli so that it uses your default Python version:
```
(zhmc) $ pip install zhmccli
```
To install a specific released version of zhmccli, e.g. 1.2.0:
```
(zhmc) $ pip install zhmccli==1.2.0
```
To install a specific development branch of zhmccli, e.g. master:
```
(zhmc) $ pip install git+https://github.com/zhmcclient/zhmccli.git@master
```

2.4. Installation into a system Python

Your system Python version(s) are installed using OS-level packages for all the Python functionality.

Adding packages to your system Python using Python packages from Pypi may create issues. This is why recent versions of pip raise a warning when attempting to install into the system Python. Even if you install a Python package from Pypi into your user’s space, this may create issues.

The main issue is that the more Python packages you install into the system Python, the more likely there will be incompatible Python package dependencies.

Another issue is when you replace OS-level packages with Python packages.

In order to avoid these issues, you should install zhmccli into the system Python only in cases where the system has a well-defined scope and you have full control over the set of OS-level and Python-level packages, for example when building a Docker container.

2.5. Installation on a system without Internet access

When installing Python packages using pip or pipx, Internet access is needed to access the Pypi repository.

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. This also downloads any dependent Python packages. Then, these packages are made available to the target system. e.g. via a shared file system or by transferring the files, and then you can install the zhmccli package from these files on the target system.

Important: The downloaded package files need to be compatible with the OS/HW platform, Python version and Python implementation that will be used on the target system. Pip by default uses the current Python and OS/HW platform to determine these parameters. If the OS/HW platform, Python version or Python implementation on the download system are not compatible with the target system, you can use the pip options --platform, --python-version and --implementation to select parameters that are compatible with the target system.

For simplicity, the following example uses a shared file system between the download and target systems, and has OS/HW platform, Python version and Python implementation that are compatible between download system and target system.

On the download system:

[download]$ python -c "import platform; print(platform.platform())"
macOS-14.7.2-arm64-arm-64bit

[download]$ python -c "import platform; print(platform.python_version())"
3.13.0

[download]$ python -c "import platform; print(platform.python_implementation())"
CPython

[download]$ mkdir download; cd download

[download]$ python -m pip download zhmccli

[download]$ ls -1
PyYAML-6.0.2-cp312-cp312-macosx_11_0_arm64.whl
. . . (more packages)
setuptools-80.7.1-py3-none-any.whl
. . . (more packages)
zhmccli-1.13.0-py3-none-any.whl
zhmcclient-1.21.0-py3-none-any.whl

On the target system, with an active virtual Python environment:

[target](zhmc)$ python -c "import platform; print(platform.platform())"
macOS-13.6.3-arm64-arm-64bit

[target](zhmc)$ python -c "import platform; print(platform.python_version())"
3.13.1

[target](zhmc)$ python -c "import platform; print(platform.python_implementation())"
CPython

[target](zhmc)$ ls -1
PyYAML-6.0.2-cp312-cp312-macosx_11_0_arm64.whl
. . . (more packages)
setuptools-80.7.1-py3-none-any.whl
. . . (more packages)
zhmccli-1.13.0-py3-none-any.whl
zhmcclient-1.21.0-py3-none-any.whl

[target](zhmc)$ python -m pip install -f . --no-index zhmccli-1.13.0-py3-none-any.whl

Note: Installation using pipx does not seem to work from a downloaded package file.

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

You can do that in the HMC GUI by selecting “HMC Management” in the left pane, then opening the “Configure API Settings” icon on the pain pane, then selecting the “Web Services” tab on the page that comes up, and finally enabling the Web Services API on that page.

The above is on a z16 HMC, it may be different on older HMCs.

If you cannot find this icon, then your userid does not have permission for the respective task on the HMC. In that case, there should be some other HMC admin you can go to to get the Web Services API enabled.
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.

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

See Using HMC certificates for how to use HMC certificates with the zhmc command.
The HMC userid that is used by the zhmc command must have the following flag enabled:
- “Allow access to Web Services management interfaces” flag of the user in the HMC GUI, or “allow-management-interfaces” property of the user at the WS-API.
In order to be able to perform all commands, the HMC userid that is used by the zhmc command 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 userid that is used by the zhmc command 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 userid 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 Help.

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