1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
|
s390-tools
==========
The s390-tools package contains the source tree of a set of user space
utilities for use with the s390 Linux kernel and device drivers.
The package also contains the following files:
* [CONTRIBUTING](CONTRIBUTING.md): Contribution guidelines
* [LICENSE](LICENSE): The MIT license that applies to this package
* [CHANGELOG](CHANGELOG.md): The history of s390-tools versions
* [AUTHORS](AUTHORS.md): A list of all authors of the s390-tools package
* [CODINGSTYLE](CODINGSTYLE.md): Recommendations for writing s390-tools code
Package contents
----------------
* rust:
all s390-tools that are written in rust and require external crates.
Disable the compilation of all tools in `rust/` using HAVE_CARGO=0
See the `rust/README.md` for Details
- pvattest:
Create, perform, and verify IBM Secure Execution attestation measurements.
- pvapconfig:
Automatic configure APQNs within an SE KVM guest
- pvsecret:
Manage secrets for IBM Secure Execution guests
* dasdfmt:
Low-level format ECKD DASDs with the classical Linux disk layout or the new
z/OS compatible disk layout.
* fdasd:
Create or modify partitions on ECKD DASDs formatted with the z/OS
compatible disk layout.
* dasdview:
Display DASD and VTOC information or dump the contents of a DASD to the
console.
* dasdinfo:
Display unique DASD ID, either UID or volser.
* genprotimg:
Create a protected virtualization image.
* udev rules:
- 59-dasd.rules: rules for unique DASD device nodes created in /dev/disk/.
- 57-osasnmpd.rules: udev rules for osasnmpd.
- 60-readahead.rules: udev rules to set increased "default max readahead".
- 40-z90crypt.rules: udev rules for z90crypt driver
- 90-cpi.rules: udev rule to update Control-Program-Information when KVM is
used.
- 70-chreipl-fcp-mpath.rules: udev rules to monitor multipath events for
re-IPL path failover and to adjust the re-IPL
device in case needed.
* systemd units:
- cpi.service: Unit to apply CPI settings
- dumpconf.service: Unit to configure dump on panic for s390
- mon_fsstatd.service: Unit for mon_fsstatd
- mon_procd.service: Unit for mon_procd
- iucvtty-login@.service: Instance unit to manage iucvtty instances
- ttyrun-getty@.service: Instance unit to manage ttyrun
* zipl:
Make DASDs, SCSIs, NVMes or tapes bootable for system IPL or system dump.
* zgetdump:
Retrieve system dumps from either tapes, DASDs, SCSIs or NVMes.
Decrypt Protected Virtualization (PV) dumps from IBM Secure Execution guests.
* qetharp:
Read and flush the ARP cache on OSA Express network cards.
* tape390_display:
Display information on the message display facility of a s390 tape
device.
* tape390_crypt:
Control and query crypto settings for 3592 tape devices.
* osasnmpd:
NET-SNMP subagent implementing MIBs provided by OSA-Express
features Fast Ethernet, Gigabit Ethernet, 10 Gigabit Ethernet.
* qethconf:
bash shell script simplifying the usage of qeth IPA (IP address
takeover), VIPA (Virtual IP address) and Proxy ARP.
* dbginfo.sh:
Shell script collecting useful information about the current system for
debugging purposes.
* zfcpdump:
Dump tool to create system dumps on fibre channel attached SCSI disk
partitions. It is installed using the "zipl -d" command.
* ip_watcher:
Provides HiperSockets Network Concentrator functionality.
It looks for addresses in the HiperSockets and sets them as Proxy ARP
on the OSA cards. It also adds routing entries for all IP addresses
configured on active HiperSockets devices.
Use start_hsnc.sh to start HiperSockets Network Concentrator.
* tunedasd:
Adjust tunable parameters on DASD devices.
* vmcp:
Send commands from Linux as a z/VM guest to the z/VM control program (CP).
Call vmcp with the CP command as an argument. The response of z/VM is
written to the standard output.
* vmur:
Work with z/VM spool file queues (reader, punch, printer).
* zfcpdbf:
Display debug data of zfcp. zfcp provides traces via the s390 debug
feature. Those traces are filtered with the zfcpdbf script, i.e. merge
several traces, make it more readable etc.
* sclpdbf:
Display debug data for the sclp kernel component.
* scsi_logging_level:
Create, get or set the logging level for the SCSI logging facility.
* zconf:
Set of scripts to configure and list status information of Linux on s390
devices.
- chccwdev: Modify generic attributes of channel attached devices.
- lscss: List channel subsystem devices.
- lsdasd: List channel attached direct access storage devices (DASD).
- lsqeth: List all qeth-based network devices with their corresponding
settings.
- lstape: List tape devices, both channel and FCP attached.
- lszfcp: Show sysfs information about zfcp adapters, ports and units
that are online.
- lschp: List information about available channel-paths.
- lsscm: List information about available Storage Class Memory
Increments.
- chchp: Modify channel-path state.
- lsluns: List LUNs discovered in the FC SAN,
or show encryption state of attached LUNs.
- lszcrypt: Show Information about zcrypt devices and configuration.
- chzcrypt: Modify the zcrypt configuration.
- zcryptstats: Display usage statistics of IBM Crypto Express adapters.
- znetconf: List and configure network devices for s390 network adapters.
- cio_ignore: Query and modify the contents of the CIO device driver
blacklist.
- dasdstat: Configure and format the debugfs based DASD statistics data.
* zkey:
Use the zkey tool to generate secure AES keys that are enciphered
with a master key of an IBM cryptographic adapter in CCA coprocessor mode.
You can also use the zkey tool to validate and re-encipher secure
AES keys.
* dumpconf:
Configure the dump device used for system dump in case a kernel
panic occurs. This tool can also be used by the "dumpconf" systemd unit
or as System V init script in /etc/init.d.
Prerequisite for dumpconf is a Linux kernel with the "dump on panic"
feature.
* mon_statd:
Linux - z/VM monitoring daemons.
- mon_fsstatd: Daemon that writes file system utilization data to the
z/VM monitor stream.
- mon_procd: Daemon that writes process information data to the z/VM
monitor stream.
* cpuplugd:
Manages CPU and memory resources based on a set of rules. Depending on
the workload, CPUs can be enabled or disabled. The amount of memory can
be increased or decreased exploiting the CMM1 feature.
* ipl_tools:
Tool set to configure and list re-IPL and shutdown actions.
- lsreipl: List information of re-IPL device.
- chreipl: Change re-IPL device settings.
- lsshut: List the actions that are configured as responses to of halt,
poff, reboot or panic.
- chshut: Change the actions that are to result from of halt, poff,
reboot or panic.
* ziomon tools:
Tool set to collect data for zfcp performance analysis and report.
* iucvterm:
z/VM IUCV terminal applications.
A set of applications to provide terminal access via the z/VM Inter-User
Communication Vehicle (IUCV). The terminal access does not require an
active TCP/IP connection between two Linux guest operating systems.
- iucvconn: Application to establish a terminal connection via z/VM IUCV.
- iucvtty: Application to provide terminal access via z/VM IUCV.
- ts-shell: Terminal server shell to authorize and control IUCV terminal
connections for individual Linux users.
* ttyrun:
Depending on your setup, Linux on s390 might or might not provide a
particular terminal or console. The ttyrun tool safely starts getty
programs and prevents respawns through the init program, if a terminal
is not available.
* cmsfs-fuse:
Read and write files stored on a z/VM CMS disk. The cmsfs-fuse file system
translates the record-based EDF file system on the CMS disk to UNIX
semantics. It is possible to mount a CMS disk and use common Linux tools
to access the files on the disk.
* hmcdrvfs:
Provide (read-only) access to files stored on a (assigned) DVD inserted
in a HMC drive. The command creates a FUSE.HMCDRVFS filesystem at the
specified mount point. The feature works with either the LPAR or the
z/VM hypervisor. But note especially for z/VM that the DVD must be
assigned to the associated system image (LPAR).
* hyptop:
Provide a dynamic real-time view of a s390 hypervisor environment.
The tool works with the z/VM and LPAR hypervisor. Depending on the available
data it shows e.g. CPU and memory consumption of active LPARs or z/VM
virtual guests. The tool provides a curses based user interface similar
to the popular Linux 'top' command.
* qethqoat:
Query the OSA address table and display physical and logical device
information.
* zdsfs:
Mount a z/OS DASD as Linux file system.
* CPU-measurement facilities (CPU-MF) tools:
Use the lscpumf tool to display information about the CPU-measurement
counter and sampling facilities. Use the chcpumf tool to control the
sampling facility support. Use lshwc to extract complete counter sets from
the CPU Measurement Facilities.
* cpacfstats:
The cpacfstats tools provide a client/server application set to monitor
and maintain CPACF activity counters.
* zdev:
Provides two tools to modify (chzdev) and display (lszdev) the persistent
configuration of devices and device drivers that are specific to the s390
platform.
* dump2tar:
dump2tar is a tool for creating a tar archive from the contents of
arbitrary files. It works even when the size of the actual file content
is not known beforehand (e.g. FIFOs, sysfs files).
* netboot:
Provides simple tools to create a binary that can be used to implement
simple network boot setups following the PXELINUX conventions.
* libekmfweb:
A shared library that provides functions to communicate with an EKMF Web
server via REST calls over HTTPS. EKMF Web stands for IBM Enterprise Key
Management Foundation - Web Edition, and is used to manage keys in an
enterprise.
* libkmipclient:
A shared library that provides an KMIP client to communicate with an KMIP
server. KMIP stands for Key Management Interoperability Protocol, and is an
extensible communication protocol that defines message formats for the
manipulation of cryptographic keys on a key management server.
* hsci:
Manage HiperSockets Converged Interfaces (HSCI).
* hsavmcore:
hsavmcore is designed to make the dump process with kdump more efficient.
With hsavmcore, the HSA memory that contains a part of the production
kernel's memory can be released early in the process. Depending on the size
of the production kernel's memory, writing the dump to persistent storage
can be time consuming and prevent the HSA memory from being reused
by other LPARs.
* chreipl-fcp-mpath:
Use multipath information to change the configured FCP re-IPL path on
detecting issues with the current path.
* ap-check:
A utility called by mdevctl to assist in managing vfio_ap-passthrough
devices.
For more information refer to the following publications:
* "Device Drivers, Features, and Commands" chapter "Useful Linux commands"
* "Using the dump tools"
Dependencies
------------
The s390-tools package has several build and runtime requirements. If your
build system does not have the required support, you can disable parts of
the s390-tools build with "`make HAVE_<LIBRARY>=0`", for example "`make
HAVE_FUSE=0`".
The following table provides an overview of the used libraries and
build options:
| __LIBRARY__ | __BUILD OPTION__ | __TOOLS__ |
|----------------|:------------------:|:-------------------------------------:|
| fuse3 | `HAVE_FUSE` | cmsfs-fuse, zdsfs, hmcdrvfs, zgetdump,|
| | | hsavmcore |
| zlib | `HAVE_ZLIB` | zgetdump, dump2tar |
| ncurses | `HAVE_NCURSES` | hyptop |
| net-snmp | `HAVE_SNMP` | osasnmpd |
| glibc-static | `HAVE_LIBC_STATIC` | zfcpdump |
| openssl | `HAVE_OPENSSL` | genprotimg, zkey, libekmfweb, |
| | | libkmipclient, pvattest, zgetdump, |
| | | rust/pvsecret, |
| cryptsetup | `HAVE_CRYPTSETUP2` | zkey-cryptsetup |
| json-c | `HAVE_JSONC` | zkey-cryptsetup, libekmfweb, |
| | | libkmipclient |
| glib2 | `HAVE_GLIB2` | genprotimg, pvattest, zgetdump |
| libcurl | `HAVE_LIBCURL` | genprotimg, libekmfweb, libkmipclient,|
| | | pvattest, rust/pvsecret, |
| libxml2 | `HAVE_LIBXML2` | libkmipclient |
| systemd | `HAVE_SYSTEMD` | hsavmcore |
| libudev | `HAVE_LIBUDEV` | cpacfstatsd |
This table lists additional build or install options:
| __COMPONENT__ | __OPTION__ | __TOOLS__ |
|------------------|:----------------------------:|:------------------------:|
| dracut | `HAVE_DRACUT` | zdev, chreipl-fcp-mpath, |
| | | zipl |
| initramfs-tools | `HAVE_INITRAMFS` | zdev, zipl |
| | `ZDEV_ALWAYS_UPDATE_INITRD` | zdev |
| rust | `HAVE_CARGO` | rust/* |
The s390-tools build process uses "pkg-config" and therefore it must be
available.
Build and runtime requirements for specific tools
-------------------------------------------------
In the following more details on the build an runtime requirements of
the different tools are provided:
* rust/pvsecret:
For building pvsecret you need OpenSSL version 1.1.1 or newer
installed (openssl-devel.rpm). Also required is cargo and libcurl.
Tip: you may skip the pvsecret build by adding
`HAVE_OPENSSL=0`, `HAVE_LIBCURL=0`, or `HAVE_CARGO=0`.
The runtime requirements are: openssl-libs (>= 1.1.1).
* dbginfo.sh:
The tar package is required to archive collected data.
* genprotimg:
For building genprotimg you need OpenSSL version 1.1.0 or newer
installed (openssl-devel.rpm). Also required is glib2
(glib2-devel.rpm). Tip: you may skip the genprotimg build by adding
`HAVE_OPENSSL=0` or `HAVE_GLIB2=0`.
The runtime requirements are: openssl-libs (>= 1.1.0) and glib2.
* rust/pvattest:
For building pvattest you need OpenSSL version 1.1.1 or newer
installed (openssl-devel.rpm). Also required is cargo and libcurl.
Tip: you may skip the pvattest build by adding
`HAVE_OPENSSL=0`, `HAVE_LIBCURL=0`, or `HAVE_CARGO=0`.
The runtime requirements are: openssl-libs (>= 1.1.1) and
glib2.56 or newer.
* osasnmpd:
You need at least the NET-SNMP 5.1.x package (net-snmp-devel.rpm)
installed, before building the osasnmpd subagent.
For more information on NET-SNMP refer to:
http://net-snmp.sourceforge.net
* lsluns:
For executing the lsluns script the sg_luns and sg_inq commands must
be available. The sg_luns and sg_inq executables are part of the
SCSI generic device driver package (sg3 utils/sg utils).
* ziomon tools:
For running the ziomon tools the following tools/packages are required:
- Packages: blktrace, multipath-tools, sg3-utils
- Tools: rsync, tar, lsscsi
* zipl
For CCW-type DASD dump, zlib compression can be used to compress the dump
data before writing it to the DASD partition. It can benefit from
s390 on-chip compression accelerator (DFLTCC) and provide a faster dumping
process, hence lower system downtime.
The zlib version integrated with zipl (zipl/boot/zlib) is based on the Linux
kernel zlib (kernel version 6.3) which represents zlib version 1.1.3 with a
limited number of functions and a number of updates on top including s390
hardware compression (DFLTCC) support. Also, all memory allocations are
performed in advance, which aligns with zipl requirements.
The CCW-type standalone dumper is built as a single binary and must be
loaded to stage2 during boot. Hence, all required zlib functions must be
integrated into it, and its size is restricted. To limit the size, only
deflate-related parts are integrated (no decompression is required during
dumping).
Removing the inflate modules and function prototypes are the only major
modifications made to the kernel version of zlib.
* zgetdump
For building zgetdump you need OpenSSL version 1.1.0 or newer
installed (openssl-devel.rpm). Also required is glib2
(glib2-devel.rpm) and zlib (zlib-devel.rpm).
Tip: you may skip the zgetdump build by adding
`HAVE_OPENSSL=0`, `HAVE_GLIB2=0`, or `HAVE_ZLIB=0`.
* cmsfs-fuse/zdsfs/hmcdrvfs/zgetdump:
The tools cmsfs-fuse, zdsfs, hmcdrvfs, and zgetdump depend on FUSE.
FUSE is provided by installing the fuse3 and libfuse3 packages and by a
kernel compiled with `CONFIG_FUSE_FS`. For compiling the s390-tools package
the fuse3-devel package is required.
The cmsfs-fuse tool requires FUSE version 3.0 or newer for full
functionality.
For further information about FUSE see: https://github.com/libfuse/libfuse
* hyptop:
The ncurses-devel package is required to build hyptop.
The libncurses package is required to run hyptop.
IMPORTANT: When running hyptop on a System z10 LPAR, the required minimum
microcode code level is the following:
Driver 79 MCL N24404.008 in the SE-LPAR stream
* ip_watcher/xcec-bridge:
As of s390-tools-1.10.0, the minimum required kernel level is 2.6.26.
For running ip_watcher these programs are required:
- qetharp (s390-tools)
- qethconf (s390-tools)
- route (net-tools)
* zfcpdbf:
As of s390-tools-1.13.0, the minimum required kernel level is 2.6.38.
* cpacfstats:
For building the cpacfstats tools you need libudev installed
(systemd-devel.rpm). Tip: you may skip the cpacfstats build by
adding `HAVE_LIBUDEV=0` to the make invocation. To run the
cpacfstats daemon the kernel needs to have performance events
enabled (check for `CONFIG_PERF_EVENTS=y`). A new group 'cpacfstats'
needs to be created and all users intending to use the tool should
be added to this group.
* zdev:
Depending on the boot loader and initial RAM-disk mechanism used by a
Linux distribution, specific steps may be required to make changes to
the root device configuration persistent. zdev encapsulates this root
device logic in a helper script called 'zdev-root-update': This script
is invoked whenever the root device configuration is changed and it must
ensure that the persistent root device configuration is put into effect
during boot. zdev provides a sample implementation for zdev-root-update
which can be selected during the 'make install' step using the `HAVE_DRACUT`
variable:
- `HAVE_DRACUT=1` installs a zdev-root-update helper that works with zipl
as boot loader and dracut as initial RAM-disk provider.
Distributors with different boot or RAM-disk mechanisms should provide
a custom zdev-root-update helper script.
- `ZDEV_ALWAYS_UPDATE_INITRD=1` upon modification of any persistent device
configuration, chzdev updates the initial RAM-disk by default, without any
additional user interaction.
For some distributions, all the configuration attributes must be copied to
the initial RAM-disk. Because the device configuration directives applied
in the initial RAM-disk takes precedence over those stored in the root file-
system. This copying is done usually by explicitly invoking a command. This
build option makes it user-friendly and does this copying without any manual
intervention.
Some functions of zdev require that the following programs are available:
- modprobe (kmod)
- udevadm (systemd)
The following programs are not required but when available will improve
the functionality of the zdev tools:
- lsblk (util-linux)
- findmnt (util-linux)
- vmcp (s390-tools)
- ip (iproute2)
* znetconf:
For running znetconf these programs are required:
- modprobe (kmod)
- vmcp (s390-tools)
* zkey:
For building the zkey tools you need openssl version 0.9.7 or newer installed
(openssl-devel.rpm). Also required are cryptsetup version 2.0.3 or newer
(cryptsetup-devel.rpm), and json-c version 0.12 or newer (json-c-devel.rpm).
Tip: you may skip the zkey build by adding `HAVE_OPENSSL=0`, and you may
may skip the zkey-cryptsetup build by adding `HAVE_CRYPTSETUP2=0`, or
`HAVE_JSONC=0` to the make invocation.
A new group 'zkeyadm' needs to be created and all users intending to use the
tool must be added to this group. The owner of the default key repository
'/etc/zkey/repository' must be set to group 'zkeyadm' with write permission
for this group.
* libekmfweb:
For building the libekmfweb shared library you need openssl version 1.1.1 or
newer installed (openssl-devel.rpm). Also required are json-c version 0.13 or
newer (json-c-devel.rpm), and libcurl version 7.59 or newer
(libcurl-devel.rpm).
Tip: you may skip the libekmfweb build by adding `HAVE_OPENSSL=0`,
`HAVE_JSONC=0`, or `HAVE_LIBCURL=0` to the make invocation.
* hsavmcore:
For building the hsavmcore tool you need fuse version 3.0 and optionally
systemd which is enabled by default, to disable systemd support,
add `HAVE_SYSTEMD=0` to the make invocation.
Tip: you may skip the hsavmcore build by adding `HAVE_FUSE=0`
to the make invocation.
* libkmipclient:
For building the libkmipclient shared library you need openssl version 1.1.1
or newer installed (openssl-devel.rpm). Also required are json-c version 0.13
or newer (json-c-devel.rpm), libxml2 version 2.9.10 or newer
(libxml2-devel.rpm), and libcurl version 7.59 or newer (libcurl-devel.rpm).
Tip: you may skip the libkmipclient build by adding `HAVE_OPENSSL=0`,
`HAVE_JSONC=0`, `HAVE_LIBXML2=0`, or `HAVE_LIBCURL=0` to the make invocation.
* chreipl-fcp-mpath:
For a complete list and documentation of the requirements, installation and
uninstallation, please see
[chreipl-fcp-mpath/README.md](chreipl-fcp-mpath/README.md).
Summarized: chreipl-fcp-mpath requires GNU Bash, GNU Core Utilities,
util-linux, udev, and multipath-tools. When using `HAVE_DRACUT=1` with the
make invocation, it also requires dracut. When using `ENABLE_DOC=1` with the
make invocation to build a fresh man page (instead of using the pre-cooked
version) and render the README.md as HTML, make further requires pandoc and
GNU awk for the build process.
* ap-check:
For building the ap-check mdevctl callout utility you need json-c version
0.13 or newer (json-c-devel.rpm).
Tip: you may skip ap-check build by adding `HAVE_JSONC=0` to the make
invocation.
|