ZIPL-EDITENV(8)

NAME
zipl-editenv - zIPL environment editor.

SYNOPSIS
zipl-editenv [OPTION] [ARGUMENT]

DESCRIPTION
zipl-editenv is a tool to manipulate with zIPL environment of partitions, prepared for initial program load (IPL) by zipl(8) utility. This tool performs atomic updates of boot data without modifying the boot record referencing that data. The following operations are supported:

-   Print environment

-   Assign a specified value to any environment variable

-   Remove a specified variable from the environment

-   Remove all variables from the environment

zIPL environment (don't confuse with shell environment!) is a method of evaluation of zIPL environment variables, which is used at boot time. Names of zIPL environment variables have to satisfy POSIX requirements for shell environment variables (IEEE Std 1003.1-2001). That is, such names should consist solely of uppercase letters, digits, and underscores ('_') from the characters defined in Portable Character Set and should not begin with a digit. zIPL environment is defined per boot partition by a special boot component called zIPL environment block. This component is used for evaluation of zIPL environment variables present in another boot component, kernel command line, where the mentioned variables have to be specified by their names as ${NAME}. During boot, such variables are replaced with values, as defined by the active namespace in the installed environment block. zIPL environment is installed every time when preparing a device for initial program load (IPL) by zipl(8) utility. At installation time the environment by default is imported from user-editable file '/etc/ziplenv'. That default location can be overridden by respective zipl(8) option. Installed zIPL environment (AKA zIPL environment block) can be accessed (modified, printed) by this zipl-editenv(8) tool. All modifications made with this tool don't affect the file '/etc/ziplenv'. Hence, those modifications will be lost after the next boot record re-installation, unless '/etc/ziplenv' was updated respectively. At boot time any zIPL environment variable can be evaluated by different preinstalled ways. An individual method of evaluation of all environment variables is called an environment namespace. zIPL supports 10 identified namespaces called sites and one so-called common (or default) namespace per boot partition. Maximum number of values defined by all installed namespaces is 512. Sites are identified by positive integer numbers from 0 to 9. In contrast with sites, common namespace doesn't have any identifier. User can set anyone of the installed site namespaces to be used for evaluation of zIPL environment variables (in the kernel command line) at boot time. This operation is also called namespace activation. Namespace can be activated either "in advance" by chreipl(8) utility for the next boot session, or directly at boot time by the boot command. In both ways ID of the active site should be properly encoded in the LOADPARM. If no site ID is identified in the LOADPARM, then the common namespace gets activated. If some variable is missed (undefined) in the active namespace, then it gets evaluated by the common namespace. If some variable is missed in both, active and common namespaces, then it gets removed from the command line by the boot process.

OPTIONS

-h or --help
    Print usage information, then exit.

-v or --version
    Print version information, then exit.

-t <TARGET DIRECTORY> or --target <TARGET DIRECTORY>
    Specify a directory, where the environment is installed. This directory should contain boot data (bootmap file). If this option is not specified, then the tool assumes that the environment is installed in "/boot". A similar option with the same name exists also for zipl(8) utility.

-l or --list
    Prints a list of zIPL environment variables with their values as found in the installed environment block. In a combination with the option -S (--site) it prints only values defined in the respective site namespace. In a combination with the option -E (--effective-site) it prints the way of evaluation of zIPL environment variables that would take place, if the specified site was encoded in the LOADPARM for the boot session. By default it simply dumps all the installed namespaces.

-s <NAME=VALUE> or --set <NAME=VALUE>
    Assign VALUE to the variable NAME. NAME has to satisfy the requirements above. VALUE may consist of any printable characters different from the new line symbol. If variable with such name didn't exist in the environment, then it will be added. In a combination with the option -S (--site) the value is assigned in the specified namespace. By default - in the common namespace.

-u <NAME> or --unset <NAME>
    Remove the variable with name NAME from zIPL environment. In a combination with the option -S (--site) the variable gets removed from the specified namespace. By default - from the common namespace.

-r or --reset
    Remove all variables from zIPL environment. In a combination with the option -S (--site) the variables get removed only from the specified site. By default - from all namespaces.

-S or --site <SITE_ID>
    Specifies a particular site namespace to operate on. Can be used in a combination with options -s (--set), -u (--unset), -r (--reset) and -l (--list). This option makes the tool operate on a specified namespace only. Specifically, when using in a combination with -s, -u, or -r, changes are applied only to the specified namespace. When using in a combination with -l, only specified namespace is displayed. SITE_ID is a site identifier - any decimal positive number from 0 till 9.

-E or --effective-site <SITE_ID>
    When using in a combination with option -l (--list), it displays the way of evaluation of zIPL environment variables that would take place, if the specified site was activated for the boot session. SITE_ID is a site identifier - any decimal positive number from 0 till 9.

FILES
/etc/ziplenv - "initial environment" (or "environment file"). A regular file containing zIPL environment to be installed every time when preparing a device for initial program load (IPL) by zipl(8) utility. Don't confuse environment file with environment block! In contrast with environment block, environment file is not a boot component and is not used at boot time by any boot processes. This file contains pairs NAME=VALUE delimited by new line symbols (i.e. each pair on a separate line). NAME is identified as a sequence of characters before the leftmost '=' in the line. NAME has to satisfy the requirements above. Lines beginning from "#" are ignored. Lines with not identified NAME are ignored. Namespaces in an environment file are specified by sections. Sections are indicated by titles - lines, starting with a keyword '[site X]', where X is a namespace ID. Rectangle brackets in any such keyword are mandatory. The word "site" is case insensitive. Any keyword may be followed with a comment on the same line. Any lines between neighboring section titles do form a section, defined by the upper title. If the environment file doesn't begin from a section title, then the area at the beginning, not indicated by a title, defines the "common" namespace. Sections with identical titles are considered as parts of the same "compound" section. If a section (simple or compound) contains lines with identical names, then only the last one takes an effect. If the file defines more than 512 effective values (summed over all sections) or if all namespaces defined by that file don't fit to the environment block, then zipl(8) will fail to import such file. This file can be modified, using any suitable text editor.

NOTES
Site namespace corresponds to a fail-over site which is a set of block devices, participating in hardware replication, and used for planned/unplanned swap. Any installed zIPL environment (environment block) should be accessed only by this zipl-editenv tool. Using other ways to access the environment block is not allowed. Any modification of installed zIPL environment block doesn't affect the environment file. The user is responsible for keeping the environment file up to date.

SEE ALSO
zipl(8),
    zipl.conf(5) chreipl(8) lsreipl(8)