1. Manuals
  2. Leap-15.6
  3. snipl
  4. snipl(8)

Scroll to navigation

SNIPL(8) SNIPL(8)

NAME

snipl - remotely controlling virtual System z hardware

SYNOPSIS FOR LPAR MODE

snipl <image> ... ACCESSDATA {-a [--profilename] [-F] | -d [-F] | -r [-F] | -o | -g}

snipl <image> ... ACCESSDATA -l LOADPARAMETERS [-F]

snipl <image> ... ACCESSDATA {-s|-D} SCSIPARAMETERS [-F]

snipl <image> ACCESSDATA -i [--msgtimeout <interval>] [-M <name>]

snipl [<image>] ACCESSDATA -x

SYNOPSIS FOR z/VM MODE

snipl <guest> ... -V <ipaddr> [-z <port>] -u <user> {-p <pw> | -P} [-e] [-f <file>] [--timeout <period>] {-a | -d [-F|-X <period>] | -r | -g | -x}

DESCRIPTION

snipl is a command line tool for remotely controlling virtual System z hardware. In particular, you can use snipl to activate and deactivate virtual System z hardware running Linux instances. You can set up a Linux instance on a mainframe system or on a different hardware platform for running snipl.

snipl helps you to automate tasks that are typically performed by human operators, for example, through the graphical interfaces of the SE or HMC. Automation is required, for example, for failover setups within Linux clusters.

snipl can run in one of two modes:

LPAR mode provides basic System z support element (SE) functions for LPARs. The Linux instance where snipl runs requires access to all SEs that control the LPARs you want to work with.

z/VM mode provides basic z/VM systems management functions for z/VM guest virtual machines. The Linux instance where snipl runs requires access to the systems management API of all z/VM systems that host z/VM guest virtual machines you want to work with. See section "OPTIONS FOR z/VM MODE" for details about snipl in z/VM mode.

ATTENTION: As of snipl version 3.0.0, the default behaviour changed: The default password was removed and encryption is enabled by default. To disable encryption, use the -e parameter.

WARNING: Careless use of snipl can result in unplanned downtime and loss of data.

GENERAL OPTIONS FOR LPAR MODE

<image>
specifies an LPAR. If snipl directly accesses the SE, this is the LPAR name as defined in the hardware setup. If snipl accesses the SE through an HMC, the specification has the format <mainframe_system>-<lpar_name> where <mainframe_system> is the name that identifies the System z mainframe on the HMC.

SE Example: lpar204
HMC Example: z02-lpar204

A snipl command applies to one or more LPARs that are controlled by the same SE or HMC. If multiple LPARs are specified, it is assumed that all LPARs are controlled by the same SE or HMC as the first LPAR. Other LPARs are ignored.

If multiple LPARs are specified along with at least one parameter specifying a load or dump device, the -F (--force) parameter must be used to confirm the operation.

activates the specified LPARs.
specifies an activation profile. If this parameter is omitted, the SE or an HMC default profile for the specified LPAR is used.
deactivates the specified LPARs.
resets the specified LPARs.
-o or --stop
stops all CPUs for the specified LPARs.
returns the status for the specified LPARs.
unconditionally forces the operation.
starts an emulation of the SE or HMC Operating System Message applet for the specified LPAR.
specifies the timeout for retrieving operating system messages in milliseconds. The default value is 5000 ms.
specifies a file to which the operating system messages are written in addition to stdout. If no file is specified, the operating system messages are written to stdout only.
retrieves a list of all LPARs from the specified SE or HMC. If an HMC is specified, all LPARs for all managed mainframe systems are listed.
see section "LOADPARAMETERS".
see section "SCSIPARAMETERS".
displays the version of snipl and exits.
displays a short usage description and exits.

ACCESSDATA

specifies the IP address (IPv4 or IPv6) or host name of the SE or HMC that controls the LPAR or LPARs you want to work with. This parameter can be omitted if specified through a configuration file. You must specify it for the -x (--listimages) operation.
specifies the password in the SNMP configuration settings on the SE that controls the LPAR or LPARs you want to work with. This parameter can also be specified through a configuration file. When encryption is enabled, the password parameter specifies the password for the SNMPv3 username from the -u (--userid) command line parameter or user keyword value in the snipl configuration file.
prompts for a password in protected entry mode.
specifies an SNMPv3 user identifier that is authorized to access an HMC or SE. This parameter can be omitted if defined in the snipl configuration file.
specifies that no encryption is used when connecting to the HMC or SE.
specifies the name of a configuration file that maps LPARs to the corresponding specifications for the SE or HMC address and password (community).

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 LPARs 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 a configuration file is neither specified nor available at the default locations, all required parameters must be specified on the command line.

See section "STRUCTURE OF THE CONFIGURATION FILE" for more information about the configuration file.

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

LOADPARAMETERS

performs an IPL for the specified LPARs.
specifies the hexadecimal four-digit device number of the IPL device optionally prefixed with the subchannel set id of the device. The default is subchannel set 0. If this parameter is omitted, the IPL device of the most recent IPL of the LPAR is used.
specifies a parameter string for IPL. If this parameter is omitted, the string of the most recent IPL of the LPAR is used.
specifies the maximum time for load completion in seconds. The timeout must be between 60 and 600 seconds. The default timeout is 60 seconds.

If the timeout expires, control is returned without an indication about the success of the IPL operation.

prevents the memory from being cleared before loading.
stores status before performing the IPL. This option implies --noclear and also prevents the main memory from being cleared before loading.

SCSIPARAMETERS

performs an IPL from a SCSI device for the specified LPARs.
performs a dump for the specified LPAR to a SCSI device.
specifies the hexadecimal four-digit device number of the IPL device optionally prefixed with the subchannel set id of the device. The default is subchannel set 0. If this parameter is omitted, the IPL device of the most recent IPL of the LPAR is used.
specifies a parameter string for IPL. If this parameter is omitted, the string of the most recent IPL of the LPAR is used.
specifies the worldwide port name (WWPN) for the SCSI IPL device. If fewer than 16 characters are specified, the WWPN is padded with zeroes at the end. If this parameter is omitted, the WWPN of the most recent SCSI IPL of the LPAR is used.
specifies the logical unit number (LUN) for the SCSI IPL device. If fewer than 16 characters are specified, the LUN is padded with zeroes at the end. If this parameter is omitted, the LUN of the most recent SCSI IPL of the LPAR is used.
specifies the boot program required for the SCSI IPL device. Selector values range from 0 to 30. If this parameter is omitted, the boot program of the most recent SCSI IPL of the LPAR is used.
specifies an operating system-specific parameter string for IPL from a SCSI device. If this parameter is omitted, the string of the most recent SCSI IPL of the LPAR is used. This parameter string is ignored by the boot program and passed to the operating program or dump program to be loaded. For example, you can specify additional kernel parameters for Linux.
specifies the boot record logical block address for the SCSI IPL device. If fewer than 16 characters are specified, the address is padded with zeroes at the end. If this parameter is omitted, the address of the most recent SCSI IPL of the LPAR is used.

OPTIONS FOR z/VM MODE

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

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

specifies the IP address (IPv4 or IPv6) or host name of the SMAPI request server or VSMSERVE service machine through which the specified z/VM guest virtual machines are controlled. This parameter can be omitted if defined in the configuration file.
specifies the port on which the SMAPI request server listens.

This parameter does not apply to setups that use the VSMSERVE service machine to access the systems management API.

For setups that use a SMAPI request server this parameter is required unless it is defined in the configuration file.

specifies a z/VM user ID that is authorized to access the SMAPI request server or VSMSERVE service machine. This parameter can be omitted if defined in the configuration file.
specifies the password for the z/VM user ID specified with --userid. This parameter can be omitted if defined in the configuration file.
prompts for a password in protected entry mode.
specifies that no encryption is used when connecting to the SMAPI request server.
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, password, and the port (if applicable).

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.

See section "STRUCTURE OF THE CONFIGURATION FILE" for more information about the configuration file.

Specifies the timeout in milliseconds for general management API calls. The default is 60000 ms.
logs on the specified z/VM guest virtual machines.
logs off the specified z/VM guest virtual machines.
immediately issues CP FORCE commands to log off the specified z/VM guest virtual machines. This parameter is equivalent to -X 0.
-X <maxperiod> or --shutdowntime <maxperiod>
Specifies the maximum period, in seconds, granted for graceful completion before CP FORCE commands are issued against the z/VM guest virtual machines. By default, the maximum period is 300s.
logs off the specified z/VM guest virtual machines and then logs them back on.
returns the status for the specified z/VM guest virtual machines.
lists the z/VM guest virtual machines as specified in a configuration-file section (see section "STRUCTURE OF THE CONFIGURATION FILE"). 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.
displays the version of snipl and exits.
displays a short usage description and exits.

STRUCTURE OF THE CONFIGURATION FILE

Any required parameters that are not provided on the command line must be specified through the configuration file. Specifications on the command line override specifications in the configuration file.

A snipl configuration file contains one or more sections. Each section consists of multiple lines with specifications of the form <keyword>=<value> for either a z/VM system or an SE.

The following rules apply to the configuration file:

Lines that begin with a number sign (#) are comment lines. A number sign in the middle of a line makes the remaining line a comment.
Empty lines are permitted.
The specifications are not case sensitive.
The same configuration file can contain sections for snipl in both LPAR mode and z/VM mode.
In a <keyword>=<value> pair, one or more blanks are allowed before or after the equal sign (=).

The following list maps the configuration file keywords to command line equivalents:

Starts a configuration file section by specifying the IP address of an SE or HCM (LPAR mode), or a SMAPI request server or VSMSERVE service machine (z/VM mode).

The server and type keywords jointly correspond to the command line option -L (LPAR mode) or -V (z/VM mode).

specifies the mode, "LPAR" or "VM".

specifies a z/VM or SNMPv3 user identifier that is authorized for the HMC or SE, SMAPI request server or the VSMSERVE service machine.

This keyword corresponds to the -u or --user command line option.

The user ID can be omitted and specified on the command line instead.


For LPAR mode:
specifies the value for community in the SNMPv2 (unencrypted) settings of the HMC or SE or the value for password in the SNMPv3 (encrypted) settings of the HMC or SE.

For z/VM mode:
specifies the password for the z/VM user ID specified with the user keyword.


This keyword corresponds to the -p or --password command line option.

The password can be omitted and specified on the command line instead. Do not include passwords in the snipl configuration file unless the security policy at your installation permits you to do so.


For LPAR mode:
"yes" specifies an SNMPv3 encrypted connection.
"no" specifies an SNMPv2 unencrypted connection.
For z/VM mode:
"yes" specifies an OpenSSL-protocol encrypted connection to the SMAPI request server.
"no" specifies unencrypted connection to the SMAPI request server.
sslfingerprint
For LPAR mode:
will be ignored
For z/VM mode:
if encryption is enabled, the fingerprint mechanism is used to detect man-in-the-middle attacks. Specified in the configuration file, the fingerprint value must be equal to the server certificate fingerprint for each new snipl connection. The sslfingerprint parameter can be specified in the configuration file only.

port (z/VM mode only)
specifies the port on which the SMAPI request server listens.

The port specification is required if the server keyword specifies the IP address or host name of a SMAPI request server. The port keyword can be omitted if the port is specified on the command line instead.

This keyword corresponds to the -z or --port command line option.


For LPAR mode:
specifies an LPAR name as defined in the mainframe hardware configuration.

If the server keyword specifies an HMC, the specification begins with the name that identifies the System z mainframe on the HMC, followed by a hyphen (-), followed by the LPAR name.

For z/VM mode:
specifies a z/VM user ID that identifies a z/VM guest virtual machine.

You can define an alias name for the LPAR or z/VM user ID by appending a forward slash (/) to the ID and specifying the alias following the slash.

Sample configuration file:
-----------------------------------------------------------
# z/VM system for Linux training sessions
Server = sandbox.www.example.com
type = VM
password = pw42play
encryption = yes
sslfingerprint = a2:ea:81:ed:e9: ... 84:cf:87:98:fe:38:54:c7
port = 44444
user = sndadm01
image = sndlnx01
image = sndlnx02
image = sndlnx03/tutor

# z/VM system for testing
Server = fd31:207b:30ee:7e57::9
type = VM
port = 44446
encryption = no
user = vmadmin
password = admpw
image = vmlnx07
image = vmlnx09

# SE for production SZ01
Server=192.0.2.4
type=LPAR
encryption = yes
user = sz01adm
image=SZ01LP00
image=SZ01LP01
image=SZ01LP02

# HMC for SZ03 - SZ05
server = 192.0.2.10
type = LPAR
encryption = no
image = SZ03-SZ03LP00
image = SZ03-SZ03LP01
image = SZ04-SZ04LP01
image = SZ05-SZ05LP02

# HMC for SZ06 - SZ09
server = fd31:207b:30ee:7e57::6b9
type = LPAR
encryption = no
image = SZ06-SZ06LP01
image = SZ07-SZ07LP03
image = SZ08-SZ08LP00
image = SZ09-SZ09LP09

# Production VM 05 - uses VSMSERVE so no port
server = 192.0.2.20
type = VM
encryption = no
user = VM05MAIN
image = VM05G001
image = VM05G002

<EOF>
-----------------------------------------------------------

RETURN CODES AND CONNECTION ERRORS

Successful snipl commands return 0. If an error occurs, snipl writes a short message to stderr and completes with a return code other than 0.

The following return codes indicate snipl syntax errors or specifications that are not valid:

1
An unknown command option has been specified.
2
A command option with an invalid value has been specified.
3
A command option has been specified more than once.
4
Conflicting command options have been specified.
5
No command option has been specified.
6
No SE, HMC, SMAPI request server or VSMSERVE service machine has been specified on the command line or through a configuration file.
7
No LPAR or z/VM guest virtual machine has been specified.
8
No z/VM user ID has been specified on the command line or through a configuration file.
9
No password has been specified on the command line or through a configuration file.
10
A specified LPAR does not exist on the specified SE.
22
More than one LPAR has been specified for option --dialog.
24
No user name was specified in the command line or configuration file. User name is required when encryption is selected.
25
User name must not be specified when encryption is disabled.

The following return codes indicate setup errors or program errors:

30
An error occurred while loading one of the systems management API libraries libhwmcaapi.so or libvmsmapi.so.
40
Operation --dialog encounters a problem while starting another process.
41
Operation --dialog encounters a problem with stdin attribute setting.
50
A response from the SE or HMC could not be interpreted.
60
The response buffer is too small for a response from the SE or HMC.
90
A storage allocation failure occurred.
99
A program error occurred.

If a connection error occurs (for example, a timeout), snipl sends a message to stderr.

To recover connection errors try again to issue the command. Should the problem persist, a networking failure is most likely. In this case, increase the timeout value.

Error messages from the SE have the following format:

<LPAR_name>: <message> - rc is <rc>

where <rc> is a numeric return code from the network management application programming interfaces (HWMCAAPI) on the SE.

Example: LPARLNX1: not acknowledged - command was not successful - rc is 135921664

To interpret these return codes, see System z Application Programming Interfaces, SB10-7030. You can obtain this publication from IBM Resource Link at www.ibm.com/servers/resourcelink.

Error messages from the Systems Management Application Programming Interface (SMAPI) server have the following format:

* Error during SMAPI server communication: return code <rc>, reason code <rs>

where <rc> is a numeric return code and <rs> is a numeric reason code from the SMAPI.

Example: * Error during SMAPI server communication: return code 24, reason code 813

To interpret these return and reason codes, see z/VM Systems Management Application Programming, SC24-6234.

EXAMPLES

To deactivate an LPAR SZ01LP02 with the force option:
snipl SZ01LP02 -L 192.0.2.4 -u sz01adm -P -d -F

To deactivate an LPAR SZ09LP09:
snipl SZ09LP09 -L fd31:207b:30ee:7e57::9 -e -P -d

To perform an IPL from a CCW device with bus ID 0.0.5119 for an LPAR SZ03LP00 on a System z mainframe SZ03:
snipl SZ03-SZ03LP00 -L 192.0.2.4 -e -P -l -A 5119

To perform an IPL from a CCW device in subchannel set 1 with the bus ID 0.1.5119 for an LPAR SZ03LP00:
snipl SZ03LP00 -L 192.0.2.4 -e -P -l -A 15119

To perform a SCSI IPL for an LPAR SZ01LP00:
snipl SZ01LP00 -L 192.0.2.4 -u sz01adm -P -s -A 3d0f --wwpn_scsiload 500507630303c562 --lun_scsiload 4010404900000000

To log on two z/VM guest virtual machines, vmlnx07 and vmlnx09:
snipl vmlnx07 vmlnx09 -V fd31:207b:30ee:7e57::9 -z 44446 -e -u vmadmin -p admpw -a

With a suitable configuration file at /etc/xcfg the previous command can be shortened to:
snipl vmlnx07 vmlnx09 -f /etc/scfg -a

With a suitable default configuration file the command can be further shortened to:
snipl vmlnx07 vmlnx09 -a

AUTHOR

This man page was written by
Peter Tiedemann <ptiedem@de.ibm.com> and
Ursula Braun <ursula.braun@de.ibm.com>.
Copyright IBM Corp. 2002, 2016
Published under the terms and conditions of the CPL
(common public license).

SEE ALSO

Device Drivers, Features and Commands, SC33-8411.

For information about the management APIs of the Support Element and the Hardware Management Console, see System z Application Programming Interfaces which is available at the IBM Resource Link site (http://www.ibm.com/servers/resourcelink).

For information about the systems management APIs of z/VM see z/VM Systems Management Programming, SC24-6234 for connecting through a SMAPI request server or see z/VM Systems Management Programming, SC24-6122-02 or earlier, for RPC-based access through a VSMSERVE service machine. PDF versions of these documents are available from the z/VM website at http://www.ibm.com/vm.

April 14 2016