zfsadm

Purpose

This section introduces the zfsadm command suite. The zfsadm command is run from the z/OS® UNIX shell. It can also be invoked from TSO/E by using the program name IOEZADM or as a batch job by using PGM=IOEZADM. See Figure 1 for an example of invoking IOEZADM from a batch job.

Command syntax

The zfsadm commands have the same general structure:

command {-option1 argument... | -option2 {argument1 | argument2}...} [-optional_information]

The following example illustrates the elements of a zfsadm command:

zfsadm  detach {-all | -aggregate name} [-help]

The following list summarizes the elements of the zfsadm command:

Command: A command consists of the command suite (zfsadm in the previous example) and the command name (detach). The command suite and the command name must be separated by a space. The command suite specifies the group of related commands.
Options: Command options always appear in monospace type in the text, are always preceded by a - (dash), and are often followed by arguments. In the previous example, -aggregate is an option, with name as its argument. An option and its arguments tell the program which entities to manipulate when running the command (for example, which aggregate, or which file system). In general, the issuer should provide the options for a command in the order detailed in the format description. The { | } (braces separated by a vertical bar) indicate that the issuer must enter either one option or the other (-all or -aggregate in the previous example).
Command options are described in alphabetic order to make them easier to locate—this does not reflect the format of the command. The formats are presented the same as on your system.
Arguments: Arguments for options are highlighted in the text. The { | } indicate that the issuer must enter either one argument or the other (-all or -aggregate in the preceding example). The ... (ellipsis) indicates that the issuer can enter multiple arguments.
Options: Some commands have optional, as well as required, options and arguments. Optional information is enclosed in [ ] (brackets). All options except -all or -aggregate in the previous example are optional.

Options

The following options are used with many zfsadm commands. They are also listed with the commands that use them.

-aggregate name: Specifies the aggregate name of the aggregate to use with the command.
-filesystem name: Specifies the file system to use with the command.
-help: Prints the online help for this command. All other valid options specified with this option are ignored. For complete details about receiving help, see Receiving help.
-size kbytes: Specifies the size in K-bytes for the kbytes argument.
-system sysname: Specifies the name of the system that the request will be sent to.

When an option is specified multiple times on one command, the first will be honored and the subsequent ones will be ignored. This can cause a subsequent argument to be interpreted as an option and be diagnosed as unrecognized.

Usage

Most zfsadm commands are administrative-level commands used by system administrators to manage file systems and aggregates. You can issue commands from OMVS, TSO/E, or as a batch job. Use the IOEZADM format for TSO/E and batch. For an example, see Figure 1 . The description of the zfsadm attach command shows an example of issuing them as a batch job. The other zfsadm commands can be run as a batch job in a similar manner.

For a batch job, the zfsadm options are specified in the EXEC PARM as a single subparameter (a single character string enclosed in apostrophes with no commas separating the options). You cannot put the ending apostrophe in column 72. If it needs go to the next line, use a continuation character in column 72 (continuing in column 16 with the ending apostrophe on the second line). Remember that a JCL EXEC PARM is limited to 100 characters. See the topic on the EXEC PARM in z/OS MVS JCL Reference.

zfsadm commands are serialized with each other. That is, when a zfsadm command is in progress, a subsequent zfsadm command is delayed until the active zfsadm completes. This also includes MOUNT of a compatibility mode aggregate (because an implicit attach occurs). This does not include zfsadm grow or implicit aggregate grow. zfsadm commands do not delay normal file system activity (except when the zfsadm command requires it, such as zfsadm quiesce).

zfsadm commands only work on zFS file systems and aggregates. All zfsadm commands work across sysplex members that are in a shared file system environment.

When supplying an argument to a zfsadm command, the option (for example -aggregate) associated with the argument (for example, OMVS.PRV.AGGR001.LDS0001) can be omitted if:

All arguments supplied with the command are entered in the order in which they appear in the command's syntax. (The syntax for each command appears with its description in this chapter.)
Arguments are supplied for all options that precede the option to be omitted.
All options that precede the option to be omitted accept only a single argument.
No options, either those that accept an argument or those that do not, are supplied before the option to be omitted.
The first option cannot be followed by an additional option before the vertical bar.

In the case where two options are presented in { | } (braces separated by a vertical bar), the option associated with the first argument can be omitted if that argument is provided; however, the option associated with the second argument is required if that argument is provided.

If it must be specified, an option can be abbreviated to the shortest possible form that distinguishes it from other options of the command. For example, the -aggregate option found in many zfsadm commands can typically be omitted or abbreviated to be simply -a. (One exception is the zfsadm attach command because it has an -aggrfull option.)

It is also valid to abbreviate a command name to the shortest form that still distinguishes it from the other command names in the suite. For example, it is acceptable to shorten the zfsadm grow command to zfsadm g because no other command names in the zfsadm command suite begin with the letter g. However, there are two zfsadm commands that begin with l: zfsadm lsaggr and zfsadm lsfs. To remain unambiguous, they can be abbreviated to zfsadm lsa and zfsadm lsf.

The following examples illustrate three acceptable ways to enter the same zfsadm grow command:

Complete command:

zfsadm grow -aggregate omvs.prv.aggr001.lds0001 -size 50000

Abbreviated command name and abbreviated options:
```
zfsadm g -a omvs.prv.aggr001.lds0001 -s 50000
```
Abbreviated command name and omitted options:
```
zfsadm g omvs.prv.aggr001.lds0001 50000
```

The ability to abbreviate or omit options is intended for interactive use. If you imbed commands in a shell script, you should not omit options nor abbreviate them. If an option is added to a command in the future, it might increase the minimum unique abbreviation required for an existing option or change the order of options.

In general, zfsadm commands are processed on a worker thread while the zfsadm thread waits. If you cancel a zfsadm command that is taking a long time (for example, zfsadm grow or zfsadm config (to shrink a cache),the zfsadm (waiting) thread is cancelled, but the worker thread continues to process the request to completion. In addition, most zfsadm commands require a common zfsadm lock while they are processing. If the zfsadm command cannot get the lock, it waits for it to become available. This means, if you issue another zfsadm command (after canceling a previous one), it can be delayed by this common zfsadm lock, until the previous (possibly cancelled) command completes.

Receiving help

There are several different ways to receive help about zfsadm commands. The following examples summarize the syntax for the different help options available:

zfsadm help: Displays a list of commands in a command suite.
zfsadm help -topic command: Displays the syntax for one or more commands.
zfsadm apropos -topic string: Displays a short description of any commands that match the specified string.

As of z/OS V1R13, when the zfsadm command displays help text or a syntax error message, it will show the name of the command as IOEZADM, instead of zfsadm. This occurs because the zfsadm command is not a binary module in the z/OS UNIX file system; rather, it is a shell script that invokes IOEZADM. IOEZADM is an entry that has the sticky bit on in the permissions. The sticky bit means that the IOEZADM module is found and executed from the user's STEPLIB, link pack area, or link list concatenation. (IOEZADM is usually located in SYS1.SIEALNKE.) However, you cannot run IOEZADM from the shell because IOEZADM is not normally in your PATH.

Privilege required

zfsadm commands that query information (for example, lsfs, aggrinfo) require the issuer to have READ authority to the data set that contains the IOEFSPRM file if you are using an IOEFSPRM file in your zFS PROC, or require no special authorization if you are using parmlib (IOEPRMxx). zfsadm commands that modify (for example format) additionally require that the issuer must have one of the following:

UID of 0. If you are permitted READ to the BPX.SUPERUSER resource in the RACF® FACILITY class, you can become a UID of 0 by issuing the su command.
READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS UNIXPRIV class.

Specific privilege information is listed within each command’s description.

Related information

Commands:

zfsadm aggrinfo
zfsadm apropos
zfsadm attach
zfsadm config
zfsadm configquery
zfsadm convert
zfsadm define
zfsadm delete
zfsadm detach
zfsadm fileinfo
zfsadm format
zfsadm grow
zfsadm help
zfsadm lsaggr
zfsadm lsfs
zfsadm lssys
zfsadm query
zfsadm quiesce
zfsadm setauditfid
zfsadm unquiesce

Files:

IOEFSPRM