ZIPL-EDITENV(8)

📦 version 2.44.1, in opensuse-leap 16.0

💅 ZIPL-EDITENV(8) — the zIPL environment editor, bestie edition ✨

okay so real talk, this is zipl-editenv from section 8 of the System Manager's Manual, and it's genuinely one of the most underrated little tools out there. let me put you on 💖

🌸 NAME 🌸

zipl-editenv — the zIPL environment editor. that's it, that's the vibe.

🎀 SYNOPSIS 🎀

zipl-editenv [OPTION] [ARGUMENT]

🦋 DESCRIPTION 🦋

so zipl-editenv is the tool that manipulates the zIPL environment of partitions — the ones already prepped for initial program load (IPL) by the zipl(8) utility. the absolute icon behavior here? it performs atomic updates of boot data without modifying the boot record referencing that data. no cap, that's the whole selling point. 💅

here's what it can do for you:

  • print the environment
  • assign a specified value to any environment variable
  • remove a specified variable from the environment
  • remove all variables from the environment

now, listen — the zIPL environment (do NOT confuse it with your shell environment, bestie 😭) is a method of evaluation of zIPL environment variables, and it's what gets used at boot time. names of zIPL environment variables have to satisfy POSIX requirements for shell environment variables (IEEE Std 1003.1-2001). so like, such names should consist solely of uppercase letters, digits, and underscores ('_') from the characters defined in the Portable Character Set — and they should not begin with a digit. periodt. 👑

the zIPL environment is defined per boot partition by a special boot component called the zIPL environment block. that component is used for evaluation of zIPL environment variables present in another boot component, the kernel command line, where those mentioned variables have to be specified by their names as ${NAME}. during boot, such variables get replaced with values, as defined by the active namespace in the installed environment block. cute, right? 🌈

the zIPL environment gets installed every single time a device is prepared for initial program load (IPL) by the zipl(8) utility. at installation time the environment is by default imported from the user-editable file /etc/ziplenv. that default location can be overridden by the respective zipl(8) option. iykyk ✨

the installed zIPL environment (AKA the zIPL environment block) can be accessed — modified, printed — by this very zipl-editenv(8) tool. but heads up: 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. yes this is a warning. yes i'm serious. 🙈

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, the 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 the chreipl(8) utility for the next boot session, or directly at boot time by the boot command. in both ways the 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. and if some variable is missed in both the active and common namespaces, then it gets removed from the command line by the boot process. slay, efficiency. 🧚

✨ OPTIONS ✨

  • -h or --help — print usage information, then exit. the classic.
  • -v or --version — print version information, then exit. also the classic.
  • -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 the 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 a 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 the 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 the zIPL environment. in a combination with the option -S (--site) the variables get removed only from the specified site. by default — from all namespaces. full send 🔥
  • -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 the 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 — the "initial environment" (or "environment file").

it's a regular file containing the zIPL environment to be installed every time a device is prepared for initial program load (IPL) by the zipl(8) utility. don't confuse the environment file with the environment block! in contrast with the environment block, the 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. so like, keep it tidy bestie 💀

this file can be modified, using any suitable text editor. yes, even that one. 😌

💅 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. i don't make the rules, i just think they're iconic. 🚨

any modification of the installed zIPL environment block doesn't affect the environment file. the user is responsible for keeping the environment file up to date. that's you. you're the user. 🫵

🌟 SEE ALSO 🌟

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

okay that's the whole page, you ate that 💖 this was s390-tools, Feb 2020, section 8 of the System Manager's Manual — go forth and edit those environments, bestie, and remember: the environment block is not the environment file, no cap 🦋✨🎀

📦 where this page comes from