3.1. Pywbemlistener commands
This section describes each of the pywbemlistener commands including examples.
The pywbemlistener commands are:
pywbemlistener list command - List the currently running named WBEM indication listeners.
pywbemlistener show command - Show a named WBEM indication listener.
pywbemlistener start command - Start a named WBEM indication listener in the background.
pywbemlistener stop command - Stop a named WBEM indication listener.
pywbemlistener test command - Send a test indication to a named WBEM indication listener.
pywbemlistener run command - Run as a named WBEM indication listener.
pywbemlistener help command - Show help for particular pywbemcli subjects
pywbemlistener docs command - Issue request to web browser to load pywbemcli documentation
3.1.1. pywbemlistener list
command
The pywbemlistener list
command lists the currently running WBEM indication
listeners on the local system. They are identified as the processes executing
the pywbemlistener run
command.
Example:
$ pywbemlistener list
+--------+--------+----------+-------------+--------+---------------------+
| Name | Port | Scheme | Bind addr | PID | Created |
|--------+--------+----------+-------------+--------+---------------------|
| lis1 | 25989 | http | none | 131870 | 2023-06-07 12:17:55 |
+--------+--------+----------+-------------+--------+---------------------+
The -o, --output-format
general option can be used to control the format of
the table that is displayed, for example:
Example:
$ pywbemlistener -o rst list
====== ====== ======== ===== ===================
Name Port Scheme PID Created
====== ====== ======== ===== ===================
lis1 25989 https 59327 2021-07-03 15:31:55
====== ====== ======== ===== ===================
See pywbemlistener list –help for the exact help output of the command.
3.1.2. pywbemlistener show
command
The pywbemlistener show
command shows details of a specific running WBEM
indication listener on the local system, by specifying the listener name.
The running listeners are identified as the processes executing the
pywbemlistener run
command. The listener name is also identified from
the process command line.
Example:
$ pywbemlistener show lis1
+------------------+---------------------+
| Attribute | Value |
|------------------+---------------------|
| Name | lis1 |
| Port | 25989 |
| Scheme | http |
| Bind addr | none |
| Certificate file | |
| Key file | |
| Indication call | |
| Indication file | |
| Log file | |
| PID | 131870 |
| Start PID | 131868 |
| Created | 2023-06-07 12:17:55 |
+------------------+---------------------+
See pywbemlistener show –help for the exact help output of the command.
3.1.3. pywbemlistener start
command
The pywbemlistener start
command starts a new WBEM indication listener on
the local system.
The listener is running as a normal user process in the background, inheriting
the group and user context from the process that runs the pywbemlistener start
command (usually the shell process in a terminal session).
Example:
$ pywbemlistener start lis1 --cert-file .../certs/server_cert.pem --key-file .../certs/server_key.pem
Running listener lis1 at https://localhost:25989
The previous example started a listener for HTTPS (the default) on the default port 25989. Because HTTPS was used, it was necessary to specify an X.509 server certificate and its key file.
The -p, --port
option specifies the port on which the listener will
receive indicaitons.
The use of HTTP instead of the default HTTPS can be used by specifying it with
the -s, --scheme
option defines whether HTTP or HTTPS schema will be used
as the bind url on which the listener is expecting indications. The default is
HTTPS.
The -b, --bind-addr
option specifies that the listener will be bound to a
single network interface and on linux systems, typically, to a single IP
address on that interface. When a listener is bound to a single network
interface/IP address it can receive indications only addressed to that network
interface/IP address. Thus if the listener is bound to localhost
(i.e. the
local network interface) it will be able to only receive indications addressed
to that network interface. The default when –bind-addr is not set is for the
the listener to received indications addressed to any valid IPV4 or IPV6 IP
address defined on the local system. (New in pywbemtools version 1.3.0).
When the listener receives an indication, by default it drops it and does nothing else.
The following actions can be configured to be performed on each received indication. Multiple actions can be specified.
Appending it as a line to a file:
This action is enabled by specifying the
--indi-file FILE
option.The format of the line can be configured using the
--indi-format FORMAT
option.FORMAT
is a Python new-style format string that can use the following keyword args:‘dt’ - datetime object of the time the listener received the indication, in local time. The object is timezone-aware on Python 3.6 or higher.
‘dt_tzname’ - timezone name of the datetime object if timezone-aware, else the empty string.
‘h’ - Host name or IP address of the host that sent the indication
‘i’ - pywbem.CIMInstance object with the indication instance
‘c’ - CIM classname of the indication instance
‘p’ - Case-insensitive dictionary of the indication properties, displayed as blank-separated name=value items
The default format is: “{dt} {h} {c} {p}”.
Calling a Python function, via the
--indi-call MODULE.FUNCTION
option.MODULE
must be a module name or a dotted package name in the module search path, e.g. ‘mymodule’ or ‘mypackage.mymodule’.The current directory is added to the front of the Python module search path, if needed. Thus, the module can be a single module file in the current directory, for example:
./mymodule.py
or a module in a package in the current directory, for example:
./mypackage/__init__.py ./mypackage/mymodule.py
FUNCTION
must be a function in that module with the following interface:def func(indication, host)
Parameters:
‘indication’ is a
pywbem.CIMInstance
object representing the CIM indication that has been received. Its ‘path’ attribute is None.‘host’ is a string with the host name or IP address of the indication sender (typically a WBEM server).
The return value of the function will be ignored.
Exceptions raised when importing the module cause the ‘pywbemlistener run’ command to terminate with an error. Exceptions raised by the function when it is called cause an error message to be displayed on stderr of the listener process and logged, if logging is enabled.
The started WBEM indication listener can log any issues it encounters, to a file.
This is enabled by using the -l, --logdir DIR
general option.
See pywbemlistener start –help for the exact help output of the command.
3.1.4. pywbemlistener stop
command
The pywbemlistener stop
command stops a running WBEM indication listener on
the local system.
Example:
$ pywbemlistener stop lis1
Shut down listener lis1 running at http://localhost:25989
On Windows, the listener process is stopped immediately without giving the process control to clean up. On other platforms, the listener process is stopped gracefully, giving the process control to clean up.
See pywbemlistener stop –help for the exact help output of the command.
3.1.5. pywbemlistener test
command
The pywbemlistener test
command sends a test indication to a running WBEM
indication listener on the local system.
This command has two options:
The -c, --count
option that defines the number of indications to set where
the default is to send a single indication.
The -l, --listener
option that defines a host name or IP address to which
the indications will be sent. The default --listener
is localhost
.
Example:
$ pywbemlistener test lis1
Sending the following test indication:
instance of CIM_AlertIndication {
IndicationIdentifier = NULL;
IndicationTime = "20210711160151.847111+000";
AlertingElementFormat = 2;
AlertingManagedElement = NULL;
AlertType = 2;
Message = "Test message";
MessageID = "TEST0000";
OwningEntity = "TEST";
PerceivedSeverity = 2;
ProbableCause = 0;
SystemName = NULL;
MessageArguments = { };
};
Sent test indication to listener lis1 at http://localhost:25989
See pywbemlistener test –help for the exact help output of the command.
3.1.6. pywbemlistener run
command
The pywbemlistener run
command runs the WBEM indication listener code
in a loop that never ends. It is possible to start this command in the
background or even run it in the foreground, but it is not recommended that
users do that directly. Instead, users should use the
pywbemlistener start command, which starts the pywbemlistener run
command as a background process. Use the pywbemlistener run
command only
when you need to have control over how exactly the process runs in the
background.
The argument and options for the run command are the same as for the
pywbemlistener start
command.
Note: The –start-pid option is needed because on Windows, the
pywbemlistener run
command is not the direct child process of the
pywbemlistener start
command starting it.
See pywbemlistener run –help for the exact help output of the command.
3.1.6.1. pywbemlistener help
command
The help
command provides information on a number of subjects where the
extra help might be needed on pywbemlistener: This includes subjects like
activating the shell tab-completion,
This is different from the --help
option that provides information on
command groups, and commands.
$ pywbemcli help
Help subjects:
Subject name ubject description
-------------- --------------------------------------------
activate How to activate tab-completion
tab-completion Using tab-completion
The help for each subject is retrieved by entering the subject name for the subject of interest as the argument to the help command:
Thus, for example:
$ pywbemcli help activate
. . . returns help on activating tab-completion
3.1.6.2. pywbemlistener docs
command
The docs
command provides a simple way to access the pywbemtools
documentation publically available on the WEB. This command calls the
system default WEB browser with the URL of the pywbemtools documentation
to open a new browser window with the top level page of that documentation and
immediatly terminates or returns to the repl command line.
This is experimental
as of pywbemtools 1.2.0.