1. Introduction

1.1. What this package provides

The zhmc-log-forwarder package provides a log forwarder for the IBM Z Hardware Management Console (HMC), written in pure Python.

It contains a command named zhmc_log_forwarder that collects security logs and audit logs from the Z HMC and forwards the log entries to various destinations, such as stdout, the local syslog, or a QRadar service.

The command can gather log entries from the past, since a specified date and time, or since specific points such as now or all available entries. The command can in addition subscribe for notifications from the HMC about new log entries, so that it can wait for any future log entries to appear.

The log forwarder supports the following destinations:

Standard output
Standard error
rsyslog server

and the following formats:

Single line format
Cloud Auditing Data Federation (CADF) format, represented as a JSON string

1.2. Supported environments

Operating systems: Linux, macOS, Windows
Python versions: 3.8 and higher
HMC versions: 2.11.1 and higher

1.3. Quickstart

If not yet available, install the “pipx” command as described in https://pipx.pypa.io/stable/installation/.
Without having any virtual Python environment active, install the log forwarder as follows:
```
$ pipx install zhmc-log-forwarder
```
That makes the zhmc_log_forwarder command available in the PATH, without having to activate any virtual Python environment.
Provide a config file for use by the log forwarder.

The config file tells the log forwarder which HMC to talk to for obtaining the logs, and which userid and password to use for logging on to the HMC.

It also defines which logs should be forwarded, and since when and whether the forwarder should remain running to wait for future log entries.

Finally, it defines where the logs should be forwarded to. It supports multiple destinations at the same time.

The following command displays help to create a config file, and shows an example config file:
```
$ zhmc_log_forwarder --help-config-file
```
For details, see Log forwarder config file.
Run the log forwarder as follows:
```
$ zhmc_log_forwarder -c config.yaml
```

1.4. Reporting issues

If you encounter a problem, please report it as an issue on GitHub.

1.5. License

This package is licensed under the Apache 2.0 License.