The snipl configuration file

Edit online

Use the snipl configuration file to provide parameter values to snipl instead of specifying all values on the command line.

You specify the configuration file with the snipl command.

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 (=).

Table 1 summarizes the keywords for the configuration file and the command -line equivalents for LPAR mode and z/VM mode.

Table 1. snipl configuration file keywords
Keyword	Value for LPAR mode	Value for z/VM mode	Command-line equivalent
server (required)	Starts a configuration file section by specifying the IP address or host name of an HMC or SE. You can use IPv6 or IPv4 connections.	Starts a configuration file section by specifying the IP address or host name of a SMAPI request server or VSMSERVE service machine. You can use IPv6 or IPv4 connections.	(See note 1)
type (required)	LPAR	VM	(See note 1)
user (See note 2)	n/a	A z/VM user ID that is authorized for the SMAPI request server or VSMSERVE service machine.	-u or --user
password (See note 3)	The value for `community` in the SNMP settings of the SE. If not specified through either the configuration file or the command, the default, `public`, is used.	The password for the z/VM user ID specified with the user keyword. (See note 2)	-p or --password
encryption	"no" specifies an SNMPv2 unencrypted connection. "yes" specifies an SNMPv3 encrypted connection.	"no" specifies unencrypted connection to the SMAPI request server. "yes" specifies use of the OpenSSL protocol when connecting to the SMAPI request server.	-e or --noencryption
sslfingerprint	n/a	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 connection parameter can be specified only in a configuration file.
port	n/a	Required if the server keyword specifies the IP address or host name of a SMAPI request server.	-z or --port
image A valid section must have one or more lines with this keyword.	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 mainframe on the HMC, followed by a hyphen (-), followed by the LPAR name. You can define an alias name for the LPAR by appending a forward slash (/) to the LPAR name and specifying the alias after the slash.	A z/VM user ID that specifies a target z/VM guest virtual machine. You can define an alias name for the z/VM user ID by appending a forward slash (/) to the ID and specifying the alias after the slash.	A list of one or more items that are separated by blanks and specified without a switch.

Note:

Jointly, the server and type keywords are equivalent to the command-line option -L for LPAR mode or to -V for z/VM mode.
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.

Figure 1 shows a configuration file example with multiple sections, including sections for LPAR mode and for z/VM mode.

Figure 1. Example of a snipl 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
image = sndlnx04
image = sndlnx05
image = sndcms01/c1

# SE for production SZ01
Server=192.0.2.4
type=LPAR
image=SZ01LP00
image=SZ01LP01
image=SZ01LP02
image=SZ01LP03

# HMC for test SZ02
Server = 2001:0db8::11a0
type=LPAR
encryption = yes 
user = sz01adm
image=Z02-SZ02LP00/Z0200
image=Z02-SZ02LP01
image=Z02-SZ02LP02
image=Z02-SZ02LP03

# Production VM 04 - uses SMAPI
server = 2001:0db8::1a:0015
type = VM
encryption = no 
port = 77899
user = VM04MAIN
image = VM04LNXA
image = VM04LNXC
image = VM04LNXD

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

Examples

The examples that follow assume that the configuration file of Figure 1 is used.

The following command logs on two z/VM guest virtual machines, sndlnx01 and sndlnx03 (with alias tutor). In the example, the command output shows that sndlnx03 is already logged on.

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

Assuming that the configuration file of Figure 1 is available at /etc/xcfg, an equivalent command would be:

# snipl sndlnx01 tutor -a -f /etc/xcfg
Server sandbox.www.example.com from config file /etc/xcfg is used
* ImageActivate : Image sndlnx01 Request Successful
* ImageActivate : Image sndlnx03 Image Already Active

Assuming that the configuration file of Figure 1 is used by default, an equivalent command would be:

# snipl sndlnx01 tutor -a
Server sandbox.www.example.com from config file /etc/snipl.conf is used
* ImageActivate : Image sndlnx01 Request Successful
* ImageActivate : Image sndlnx03 Image Already Active

The following command performs an IPL for an LPAR SZ01LP03:

# snipl SZ01LP03 -L 192.0.2.4 -u sz01adm -l -P -A 5000
Enter password: 
Warning : No default configuration file could be found/opened.
processing......
SZ01LP03: acknowledged.

Assuming that the configuration file of Figure 1 is available at /etc/xcfg, an equivalent command would be:

# snipl SZ01LP03 -l -P -A 5000 -f /etc/xcfg
Enter password: 
Server 192.0.2.4 from config file /etc/xcfg is used
SZ01LP03: acknowledged.

Assuming that the configuration file of Figure 1 is used by default, an equivalent command would be:

# snipl SZ01LP03 -l -P -A 5000
Enter password: 
Server 192.0.2.4 from config file /etc/snipl.conf is used
SZ01LP03: acknowledged.

Assuming that the configuration file of Figure 1 is available at /etc/xcfg, the following command lists the z/VM guest virtual machines as specified in the section for sandbox.www.example.com:

# snipl -V sandbox.www.example.com -f /etc/xcfg -x
available images for server sandbox.www.example.com and userid SNDADM01 :

        sndlnx01         sndlnx02         sndlnx03         sndlnx04 
        sndlnx05         sndcms01

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

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

Assuming that the configuration file of Figure 1 is used by default, an equivalent command would be:

# snipl vm04lnxd -d
Enter password: 
Server 2001:0db8::1a:0015 from config file /etc/snipl.conf is used
processing......
* ImageDeactivate : Image vm04lnxd Request Successful

Draft comment: maria
Not 100% sure about the output, Uschi, correct?