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. If PARM is coded in the JCL to pass options or arguments to IOEZADM and any of the options or arguments contain a slash (for example, R/O), you must specify a leading slash as the first character in the PARM string. 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 that are 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 is sent to.
-trace file_name
Specifies the name of the file that will have the trace records written into it. The trace file can be a z/OS UNIX file, an existing MVS sequential data set, or a member of either an existing partitioned data set (PDS) or partitioned data set extended (PDSE). Use this option only at the direction of IBM Support.

For information about preallocation instructions for debugging, see Step 5 (Optional) Preallocate data sets for debugging in zFS installation and configuration steps.

Because MVS data set names must be fully qualified, z/OS UNIX has special rules for specifying MVS data set names in the shell environment. For more information, see Specifying MVS data set names in the shell environment in z/OS UNIX System Services Command Reference.

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

Usage notes

  1. Most zfsadm commands are administrative-level commands that are 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.
  2. 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 to 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 EXEC PARM in z/OS MVS JCL Reference.
  3. 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. This also does not include long-running zfsadm commands such as zfsadm shrink or zfsadm encrypt. zfsadm commands do not delay normal file system activity (except when the zfsadm command requires it, such as zfsadm quiesce).
  4. 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.
  5. 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 that are supplied with the command are entered in the order in which they appear in the command's syntax. (The syntax for each command is provided.)
    • 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
  6. The ability to abbreviate or omit options is intended for interactive use. If you embed commands in a shell script, do not omit options nor abbreviate them. If an option is added to a command in the future, it might increase the minimum unique abbreviation that is required for an existing option or change the order of options.
  7. 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 canceled, 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 canceled) command completes. The zfsadm fsinfo command does not have either of these possible processing delays.

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.

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) usually do not require the issuer to have any special authority. zfsadm commands that modify (for example, grow) usually require the issuer to have one of the following authorizations:
  • 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 chaggr
  • zfsadm compress
  • zfsadm config
  • zfsadm configquery
  • zfsadm convert
  • zfsadm decompress
  • zfsadm decrypt
  • zfsadm define
  • zfsadm delete
  • zfsadm detach
  • zfsadm encrypt
  • zfsadm fileinfo
  • zfsadm format
  • zfsadm grow
  • zfsadm help
  • zfsadm lsaggr
  • zfsadm lsfs
  • zfsadm lssys
  • zfsadm query
  • zfsadm quiesce
  • zfsadm salvage
  • zfsadm setauditfid
  • zfsadm shrink
  • zfsadm unquiesce
File:
  • IOEFSPRM