Command line syntax (z/VM mode)

Edit online

In z/VM® mode, the snipl command requires specification for a guest virtual machine, credentials, and other access data for the systems management API. There are also several optional parameters.

For command return codes, see the man page.

Figure 1. snipl command syntax (z/VM mode)

zvm-access-data

Notes:

¹ Required for connections through a SMAPI request server, unless the port is specified through a configuration file.
² -V, -u, and -p can be omitted if the required data is specified through a configuration file.

Where:

<guest_id>

specifies the z/VM guest virtual machine you want to work with. Specify multiple z/VM user IDs to perform the same action for multiple z/VM guest virtual machines.

If you are using a snipl configuration file that defines an alias for a z/VM guest virtual machine, you can specify the alias.

You can omit this parameter for the -x option if other specifications on the command line identify a section in the configuration file.

-V <ip_address> or --vmserver <ip_address>

specifies the IP address or host name of the SMAPI request server or VSMSERVE service machine through which the specified z/VM guest virtual machines are controlled. You can use IPv6 or IPv4 connections.

This option can be omitted if defined in the configuration file.

-z <portnumber> or --port <portnumber>

specifies the port at which the SMAPI request server listens.

-u <user_id> or --userid <user_id>

specifies a z/VM user ID that is authorized to access the SMAPI request server or VSMSERVE service machine. This option can be omitted if defined in the configuration file.

-e or --noencryption

specifies that no encryption is used when connecting to the server. This parameter can also be specified through a configuration file. To use encryption, you require a configuration file with an SSL fingerprint defined.

-p <password> or --password <password>

specifies the password for the z/VM user ID specified with --userid. This option can be omitted if defined in the configuration file.

-P or --promptpassword

prompts for a password in protected entry mode.

-f <filename> or --configfilename <filename>

specifies the name of a configuration file that maps z/VM guest virtual machines to the corresponding specifications for the SMAPI request server or VSMSERVE service machine, the authorized z/VM user ID, and the password.

If no configuration file is specified, the user-specific default file ~/.snipl.conf is used. If this file does not exist, the system default file /etc/snipl.conf is used.

Be sure that the command line parameters you provide uniquely identify the configuration-file section you want to work with. If you specify multiple z/VM guest virtual machines on the command line, only the first specification is used to identify the section. If your specifications map to multiple sections, the first match is processed.

If conflicting specifications are provided through the command line and the configuration file, the command line specification is used. If no configuration file is used, all required parameters must be specified on the command line.

--timeout <timeout>

specifies the timeout in milliseconds for general management API calls. The default is 60000 ms.

-a or --activate

logs on the specified z/VM guest virtual machines.

-d or --deactivate

logs off the specified z/VM guest virtual machines.

-X <maxperiod> or --shutdowntime <maxperiod>

specifies the maximum period, in seconds, granted for graceful completion before CP FORCE commands are issued against the specified z/VM guest virtual machines. By default, the maximum period is 300 s.

-F or --force

immediately issues CP FORCE commands to log off the specified z/VM guest virtual machines. This parameter is equivalent to -X 0.

-r or --reset

logs off the specified z/VM guest virtual machines and then logs them back on.

-g or --getstatus

returns the status for the specified z/VM guest virtual machines.

-x or --listimages

lists the z/VM guest virtual machines as specified in a configuration-file section. You can identify the configuration file section with the -V parameter, by specifying a z/VM guest virtual machine, or by specifying a z/VM guest virtual machine and the -u parameter.

-v or --version

displays the version of snipl and exits.

-h or --help

displays a short usage description and exits. To view the man page enter man snipl.

Examples

The following command logs on two z/VM guest virtual machines:

# snipl sndlnx04 sndlnx05 -V sandbox.www.example.com -e \
                          -z 44444 -u sndadm01 -p pw42play -a
Warning : No default configuration file could be found/opened.
* ImageActivate : Image sndlnx04 Request Successful
* ImageActivate : Image sndlnx05 Request Successful

The following command logs off a z/VM guest virtual machine:

# snipl vm04lnxd -V 2001:0db8::1a:0015 -e -z 77899 -u vm04main -p mainpw -d
Warning : No default configuration file could be found/opened.
processing......
* ImageDeactivate : Image vm04lnxd Request Successful