ksysvmmgr command
Purpose
The ksysvmmgr command provides a consistent interface for the VM agent to manage the virtual machine monitor (VMM) and the applications that are running in the virtual machine.
Syntax
ksysvmmgr [flags] ACTION CLASS [NAME] [ATTRIBUTES...]
Description
- VM monitor
- This subsystem tracks the health of the VM by communicating periodically with the host monitor in the VIOS.
- Application monitoring framework
- This subsystem is an application monitoring framework that registers, starts, stops, and monitors the applications.
Log file
All ksysvmmgr command operations are logged in the /var/ksys/log/ksysvmmgr.log file, including the name of the command that was executed, the start and stop time of the command, and the user name of the user who initiated the command. You can use the -l flag to change the amount of information that is written to the log files. The ksysvmmgr command sends user messages that are transformed by using the catalog messages.
Flags
You can use the following flags with the ksysvmmgr command:
- ACTION
- Describes the action to be performed. The ACTION flags are not case-sensitive. All ACTION flags provide synonyms, and each alias and synonym have shorter alias. For example, remove is an alias for delete, and remove can be abbreviated with rm. Aliases are provided for convenience from the command line and must not be used in scripts. The following ACTION flags are available:
- help (alias: h*)
- add (alias: a*, register, reg*)
- query (aliases: q*, list, get, li*, g*)
- modify (aliases: mod*, change, set, ch* se*)
- delete (aliases: unregister, remove, de*, unr* re*, rm)
- sync (alias: syn*)
- start (alias: on, enable, star*, en*)
- stop (alias: off, disable, sto*, di*)
- backup (alias: bac*)
- restore (alias: rest*)
- suspend (alias: unmonitor, sus*, unm*)
- resume (alias: monitor, resu*, mon*)
- snap (alias: snap, sna*)
- refresh (alias: refresh, ref*)
- CLASS
- Specifies the type of object on which the ACTION is performed. The following CLASS objects are supported:
- vmm (alias: v*): The vmm CLASS is used by default. If you do not specify any CLASS, the action is performed on the VM monitor by default.
- app (alias: a*): The app CLASS is used to perform ACTION on applications. You must specify a NAME attribute to apply the ACTION on a specific application.
- dependency (alias:dep*): The dependency CLASS establishes a dependency relationship between the applications. You must specify the list of applications and dependency type to apply a dependency between applications.
- process (alias:none): The process class is used to perform ACTION on processes. You must specify a NAME attribute to apply the ACTION on a specific process.
- NAME
- Specifies the particular object, of type CLASS, on which the ACTION must be performed. The NAME
flags are case-sensitive. You can use this flag only for the
appCLASS. - ATTRIBUTES
- Specifies an optional flag that has attribute pairs and value pairs that are specific to the
ACTION and CLASS combination. Use these pairs to specify configuration settings or to run particular
operations.
Both ATTRIBUTES and VALUE flags are case-sensitive. You cannot use the asterisk (*) character in the ACTION and CLASS names.
- -a
- Displays only the specified attributes. This flag is valid only with the query ACTION. Attribute names are not case-sensitive.
- -f
- Overrides any interactive prompts, forcing the current operation to be attempted, if allowed.
- -h/-?
- Displays help information.
- -l 0|1|2|3
- Activates the following trace log values for serviceability:
- 0: Updates the log file when an error is detected. This level of trace logging is the default value.
- 1: Logs warning messages also.
- 2: Logs basic information messages also that can be used for demonstrations.
- 3: Performs high tracing by logging the details about the routine function and the utility function. Traces the entry and exits for various functions.
- -s
- Synchronizes the VM monitor daemon immediately by sending a notification to the daemon. The VM
monitor daemon reloads the XML configuration when it receives this notification.
This flag is valid only with the
add,modify,delete,resume, andsuspendACTIONS. By default, no notification is sent. To send a notification, use the ksysvmmgr sync command.
Attributes
The ksysvmmgr command configures the following classes and attributes:
- vmm
- When you start the VM monitor, the VM monitor daemon sends heartbeats to the host monitor, when
requested by the host monitor, so that the KSYS subsystem can monitor the virtual machines. The VM
monitor can have the following attributes:
- version
- Specifies the version of XML. This mandatory attribute is set to 1.0 for the current version of VM monitor and cannot be modified.
- log
- Specifies the log level of the VM monitor daemon. This attribute can have the following values:
- 0: Only errors are logged. It is the default value.
- 1: Warnings are also logged.
- 2: Informational messages are also logged.
- 3: Details of the operation are logged. This information is used for debugging.
- period
- Specifies the time duration in seconds between two consecutive occurrences of checks that are performed by the Application Management Engine (AME). By default, the value of this attribute is 1 second. The value of this attribute must be in the range 0 - 6. For best monitoring performance, do not modify the default value.
- Application (app)
-
Note: Application limit on single VM: You can register and run a maximum of 8 applications on each VM. It's crucial to consider this constraint when planning and managing your application.
- Application dependency (dependency)
- The dependency class contains the following mandatory attributes:
- dependency_type
- Specifies the type of dependency between applications. This attribute can have the following values:
- start_sequence: Specifies the order in which the applications must be started as mentioned in the dependency_list attribute. The dependency_list attribute must have more than one application for this dependency type.
- stop_sequence: Specifies the order in which the applications must be stopped as mentioned in the dependency_list attribute. The dependency_list attribute must have more than one application for this dependency type.
- parent_child: Specifies the parent-child relationship of the two specified
applications in which one application is parent and the other is child. The parent application must
start first and then the child application starts. You must stop the child application first and
then stop the parent application. If the parent application fails, the child application also stops
automatically. If the parent application recovers and starts, the child application started
automatically. Note:
If you require the dependency at the VMM and KSYS levels, then you must initially create the dependency at the VMM level and then at KSYS node level.
- dependency_list
- Specifies the list of applications that have a dependency between them.
- strict
- Specifies whether to continue the script or command if the dependency policy cannot be followed.
If the strict attribute is set to Yes, the next application is
not started until the previous application starts and is in the
normalstate. If the strict attribute is set to No, the next application is started immediately after the first application is started irrespective of the state of the first application. This attribute is applicable only for the start_sequence dependency.
- Process
- The process class can have the following attributes:
- start_script
-
This script is used by the process monitor to restart a process in a virtual machine. The restart operation is performed by successively calling the stop_script and the start_script.
- stop_script
- This script is used by the process monitor to stop an application.
- monitor_period
- Duration between two successive process monitor operations. This duration is displayed in seconds. The default value is 30 seconds.
- stop_stabilization_time
- The period of time before which no answer from the stop_script script is considered as timeout. The default value is 25 seconds.
- stop_max_failures
- The number of successive failures of the stop_script script after which it is considered that the process cannot be stopped. The default value is 3 successive failures.
- start_stabilization_time
- The duration of time before which no answer from the start_script script is considered as timeout. This duration is displayed in seconds. The default value is 25 seconds.
- start_max_failures
- The number of successive failures of the start_script script after which it is considered that the process cannot be started. The default value is 3 successive failures.
- max_restart
- The maximum number of restart cycles, after which the process monitor is considered as failed. The default value is 3.
Comprehensive list of ksysvmmgr commands
Use the following information to find the syntax for all possible ksysvmmgr operations:
- VM monitor operations
-
- To display help information about the
vmmclass, run the following command:ksysvmmgr -h vmm - To start the VM monitor daemon, run the following
command:
ksysvmmgr start [vmm] [<ATTR#1>=<VALUE#1>][,<ATTR#n>=<VALUE#n>] - To stop the VM monitor daemon, run the following
command:
ksysvmmgr stop [vmm] - To query the details about the VM monitor daemon, run the following
command:
ksysvmmgr [-l {0|1|2|3}] [-a <ATTR#1>[,<ATTR#2>,...]] query [vmm] - To modify the VM monitor daemon attributes, run the following
command:
ksysvmmgr [-s] modify [vmm] <ATTR#1>=<VALUE#1>[,<ATTR#n>=<VALUE#n>] - To back up the VM monitor configuration settings, run the following
command:
ksysvmmgr backup vmm [<ATTR#1>=<VALUE#1>] - To restore the VM monitor configuration settings, run the following
command:
ksysvmmgr restore vmm <ATTR#1>=<VALUE#1> - To notify the VM monitor daemon to synchronize with the contents of the XML configuration file,
run the following command:
ksysvmmgr sync [vmm] - To compress all log files, run the following command:
This command creates a *.pax.gz file in the /var/ksys/log/snap directory. To read the contents of the file, you can unzip the file by using the following commands:ksysvmmgr snap [vmm]unzip *.pax.gz pax -r -f *.pax - To view the status of communication from VM monitor to host monitor, run the following command:
This command displays the VM monitor attributes along with the host monitor details such as UUID of the host monitor and the Heartbeat status of the host monitor.ksysvmmgr query vmm
- To display help information about the
- Application operations
-
- To display help information about the
appclass, run the following command:ksysvmmgr -h app - To add an application that must be monitored, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] add app <NAME> <ATTR#1>=<VALUE#1>[,<ATTR#n>=<VALUE#n>] - To add a critical application that must be monitored, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] add app <NAME> critical=yes - To modify the attributes of a registered application, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] modify app <NAME> <ATTR#1>=<VALUE#1>[,<ATTR#n>=<VALUE#n>] - To query the details about a registered application, run the following
command:
ksysvmmgr [-l {0|1|2|3}] [-a <ATTR#1>[,<ATTR#2>,...]] query app <NAME> - To delete specific or all applications from the VM agent configuration settings, run the
following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] delete app <NAME>|<NAME1,NAME2,NAME3...>|<ALL> - To suspend the monitoring of an application or all applications, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] suspend app [<NAME>] - To resume the monitoring of an application or all applications, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] resume app [<NAME>] - To start an application, run the following command:
ksysvmmgr start app <NAME> - To stop an application, run the following command:
ksysvmmgr stop app <NAME> - To group the applications, run the following command:
ksysvmmgr [-s] add group <NAME> <ATTR#1>=<VALUE#1> - To modify the applist in a group, run the following
command:
ksysvmmgr [-s] modify group <NAME> applist=<VALUE#1> - To ungroup (delete a group), run the following command:
ksysvmmgr [-s] delete group <NAME> - To refresh the configuration of VM agent applications, run the following command:
ksysvmmgr refresh app <NAME>
- To display help information about the
- Dependency operations
-
- To display help information about the dependency class, run the following
command:
ksysvmmgr -h dep - To add a dependency relationship between applications, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] add dependency <ATTR#1>=<VALUE#1>[,<ATTR#n>=<VALUE#n>] - To query the details about an existing dependency between applications, run the following
command:
ksysvmmgr [-l {0|1|2|3}] [-a <ATTR#1>[,<ATTR#2>,...]] query dep<DEPUUID> - To modify a specific dependency relationship between applications, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] modify dependency <NAME> <ATTR#1>=<VALUE#1>[,<ATTR#n>=<VALUE#n>] - To delete a specific dependency relationship, run the following
command:
ksysvmmgr [-s] [-l {0|1|2|3}] delete dep DEPUUID
- To display help information about the dependency class, run the following
command:
- Process operations
-
- To add a process for monitoring, run the following command:
ksysvmmgr [-s] add process process_name=<NAME> <ATTR#1>=<VALUE#1> [,<ATTR#n>=<VALUE#n>] - To query a process, run the following command:
ksysvmmgr query process [process_name=<NAME>] - To modify a process attribute, run the following command:
Ksysvmmgr [-s] modify process process_name=<NAME> <ATTR#1>=<VALUE#1> [,<ATTR#n>=<VALUE#n>] - To suspend a process, run the following command:
ksysvmmgr suspend process process_name=<NAME> - To resume monitoring a process, run the following
command:
ksysvmmgr resume process process_name=<NAME> - To delete a process (which is monitored), run the following
command:
ksysvmmgr [-s] delete process process_name=<NAME>
- To add a process for monitoring, run the following command:
An example scenario
The following examples show a scenario in which you start the VM monitor daemon, configure the VM agent by adding applications and dependencies:
- To display the help information about the vmm class, run one of the
following command:
1. ksysvmmgr -h vmm 2. ksysvmmgr help vmm - Start the VM monitor daemon by running the following
command:
ksysvmmgr start - To stop the VM monitor daemon, run the following command:
ksysvmmgr stop - Modify the VM monitor daemon attributes by running the following
command:
ksysvmmgr modify log=2 - Back up the VM monitor configuration settings by running the following
command:
ksysvmmgr backup vmm filepath=/var/ksys/configNote: Create the backup HAMonitoring 2019-08-30 00:11:08.xml in the /var/ksys/config path. - To restore the saved configuration settings, run the following command:
ksysvmmgr restore vmm filepath=/var/ksys/config/HAMonitoring_2019-08-30_00:11:08.xmlNote: Stores the current configuration settings to the /var/ksys/config/snapshot/HAMonitoring_backup.xml file and the current configuration file is updated with the specified configuration file path. - To collect the snapshot, run the following command:
ksysvmmgr snapNote: Install the pax rpm package before using theksysvmmgr snapcommand on your virtual machine. - To notify the VM monitor daemon to synchronize with the contents of the XML configuration file,
run the following command:
ksysvmmgr sync vmm - To query vmm parameters, run the following command:
ksysvmmgr query vmm - To add an application (say app1), run the following command:
ksysvmmgr -s add app app1 monitor_script=/tmp/monitor1.sh start_script=/tmp/start1.sh stop_script=/tmp/stop1.sh - To delete an application (say app1), run the following command:
ksysvmmgr -s delete app app1 - To suspend an application (say app1), run the following command:
ksysvmmgr suspend app app1 - To resume an application (say app1), run the following command:
ksysvmmgr resume app app1 - To start an application (say app1), run the following command:
ksysvmmgr start app app1 - To stop an application (say app1), run the following command:
ksysvmmgr stop app app1 - To query all applications, run the following command:
ksysvmmgr query app - To query application (say app1), run the following command:
ksysvmmgr query app app1 - To get the status of all applications, run the following command:
ksysvmmgr status app - To get the status of an application (say app1), run the following command:
ksysvmmgr status app app1 - To group the applications, run the following command:
ksysvmmgr -s add group grp1 applist=app1,app2,app3 - To modify the application list in the group, run the following command:
ksysvmmgr -s modify group grp1 applist=app2,app5 - To ungroup (delete the group), run the following command:
ksysvmmgr -s delete group grp1 - To display help information about the dependency class, run one of the
following command:
ksysvmmgr -h dep ksysvmmgr help dep - Notify the VM monitor daemon to synchronize with the contents of the XML configuration file, run
the following command:
ksysvmmgr sync vmm - Add an application
app1by running the following command:ksysvmmgr add app app1 monitor_script=/tmp/monitor1.sh start_script=/tmp/start1.sh stop_script=/tmp/stop1.sh - Modify the application attributes by running the following
commands:
ksysvmmgr modify app app1 new_name=newApp critical=yes ksysvmmgr modify app app1 monitor_script=/apps/new_monitor_script ksysvmmgr modify app app1 monitor_period=10 - Create a start_sequence dependency with 3 applications
app1,app2,app3in the dependency list by running the following command:ksysvmmgr -s add dependency dependency_list=app1,app2,app3 dependency_type=start_sequence - To create a stop_sequence dependency with 3 applications app4, app5, app6
in the dependency list, run the following command:
ksysvmmgr -s add dependency dependency_list=app4,app5,app6 dependency_type=stop_sequence - Create a parent_child dependency with applications
app1andapp2in the dependency list by running the following command:ksysvmmgr -s add dependency dependency_list=app1,app2 dependency_type=parent_child - Display the dependency UUIDs by running the following
command:
ksysvmmgr query dependency - To modify the details of the dependency that has UUID 1531835289870752764, run the following
command:
ksysvmmgr -s modify dependency 1531835289870752764 dependency_list=app3,app1,app2 dependency_type=start_sequence - Display the details of the dependency that has UUID 1531835289870752764 by running the following
command:
ksysvmmgr query dep 1531835289870752764 - To delete the dependency that has UUID 1531835289870752764, run the following command:
ksysvmmgr -s delete dep 1531835289870752764 - To display help information about the process class, run one of the following commands:
ksysvmmgr -h process ksysvmmgr help process - To add a process to monitor, run the following command:
ksysvmmgr -s add process process_name=proc1 start_script=/tmp/startproc1.sh stop_script=/tmp/stopproc1.sh - To query process proc1, run the following
command:
ksysvmmgr query process process_name=proc1 - To modify process attributes, run the following
command:
ksysvmmgr -s modify process process_name=proc1 start_script=/tmp/new_startproc1.sh - To suspend a process, run the following command:
ksysvmmgr suspend process process_name=proc1 - To resume a process, run the following
command:
ksysvmmgr resume process process_name=proc1 - To delete a process, run the following
command:
ksysvmmgr -s delete process process_name=proc1 - To refresh application APP1:
ksysvmmgr refresh app APP1