ZED(8)

💖 ZED — ZFS Event Daemon 💖

okay so bestie, welcome to the System Manager's Manual, section 8 🎀 this is the whole vibe of the ZFS Event Daemon and I promise it's gonna be iconic.

---

✨ NAME ✨

ZED — the ZFS Event Daemon, your fave little background gremlin 🧚

---

✨ SYNOPSIS ✨

ZED [-fFhILMvVZ] [-d zedletdir] [-p pidfile] [-P path] [-s statefile]
    [-j jobs] [-b buflen]

---

✨ DESCRIPTION ✨

So like, the ZED (that's the ZFS Event Daemon bestie, keep up 💅) monitors events generated by the ZFS kernel module. The moment a zevent (aka a ZFS Event) gets posted, ZED runs whatever ZEDLETs — yes that stands for ZFS Event Daemon Linkage for Executable Tasks, a whole mouthful, I know 😭 — have been enabled for that zevent's class.

no cap, that's the entire job. she watches, she dispatches. main character energy fr fr 👑

---

✨ OPTIONS ✨

• -h — shows you a lil summary of all the command-line options. ur cheat sheet 🫶
• -L — displays the license info. legal girlies rise 🌸
• -V — displays version info. know ur era ✨
• -v — be verbose. she will talk 💬
• -f — force the daemon to run if at all possible: disables security checks and just throws caution to the wind. > not recommended for use in production, bestie, I'm so serious 😭
• -F — don't daemonize. she stays attached to the controlling terminal and logs to the standard I/O streams. clingy in the cutest way 🎀
• -M — locks all current and future pages in the virtual memory address space. this may help the daemon stay responsive when the system is under heavy memory pressure. she's holding on and not letting go 💪
• -I — requests that the daemon idle rather than exit when the kernel modules aren't loaded. processing of events will start, or resume, when the kernel modules are (re)loaded. heads up tho: under Linux the kernel modules cannot be unloaded while the daemon is running. she's got the door locked 🔒
• -Z — zeroes the daemon's state, which lets zevents still chillin' inside the kernel get reprocessed. fresh start era 🌈
• -d zedletdir — read the enabled ZEDLETs from the directory you specify. 📁
• -p pidfile — write the daemon's process ID into the specified file. 🪪
• -P path — a custom $PATH for zedlets to use. normally zedlets run in a locked-down environment with hardcoded paths to the ZFS commands ($ZFS, $ZPOOL, $ZED, …) and a hard-coded $PATH — this is done for security reasons, periodt. BUT, the ZFS test suite uses a custom PATH for its ZFS commands and passes it to ZED with -P. so in short: -P is only to be used by the ZFS test suite. > never use it in production! like, ever ever. 🚨
• -s statefile — write the daemon's state to the specified file. 📝
• -j jobs — allow at most jobs ZEDLETs to run concurrently, delaying execution of new ones until they finish. defaults to 16. she's got a queue and she respects it 🎟️
• -b buflen — cap kernel event buffer growth to buflen entries. this buffer grows when the daemon misses an event, but it results in unreclaimable memory use in the kernel 😬. a value of 0 removes the cap entirely. defaults to 1048576.

---

✨ ZEVENTS ✨

A zevent is made up of a list of nvpairs (name/value pairs). every single zevent contains an EID (Event IDentifier) that uniquely identifies it throughout the whole lifetime of the loaded ZFS kernel module. this EID is a monotonically increasing integer that resets to 1 every time the kernel module is loaded. 🔁

Each zevent also carries a class string that identifies the type of event. and for brevity, a subclass string is defined that omits the leading components of the class string. there are additional nvpairs hanging around too, to give you the event details. 🕵️

The kernel keeps a list of recent zevents that you can view (along with their associated lists of nvpairs) using the zpool events -v command. go peek 👀

---

✨ CONFIGURATION ✨

ZEDLETs that get invoked in response to zevents live in the enabled-zedlets directory (zedletdir). you can symlink them or copy them from the installed-zedlets directory — symlinks let you get automatic updates from the installed ZEDLETs, whereas copies preserve your local modifications. choose ur fighter 🥊

As a security measure — since ownership change is a privileged operation — ZEDLETs must be owned by root. they must have execute permissions for the user, but they must not have write permissions for group or other. dotfiles are ignored, sorry hidden girlies 🙈

ZEDLETs are named after the zevent class they should be invoked for. specifically, a ZEDLET gets invoked for a given zevent if either its class or subclass string is a prefix of its filename (and is followed by a non-alphabetic character). as a special case, the prefix all matches all zevents. and yes, multiple ZEDLETs may be invoked for a single zevent — it's a party 🎉

---

✨ ZEDLETS ✨

ZEDLETs are executables invoked by the ZED in response to a given zevent. they should be written under the presumption that they can be invoked concurrently, and they should use appropriate locking to access any shared resources. the one exception to this is "synchronous zedlets", which we get into later on this page 👇

Common variables used by ZEDLETs can be stored in the default rc file, which is sourced by scripts; those variables should be prefixed with ZED_.

The zevent nvpairs are passed to ZEDLETs as environment variables. each nvpair name is converted to an environment variable like this:

1. it is prefixed with ZEVENT_,
2. it is converted to uppercase, and
3. each non-alphanumeric character is converted to an underscore.

Some additional environment variables have been defined to present certain nvpair values in a more convenient form. an incomplete list of zevent environment variables is as follows:

• ZEVENT_EID — the Event IDentifier.
• ZEVENT_CLASS — the zevent class string.
• ZEVENT_SUBCLASS — the zevent subclass string.
• ZEVENT_TIME — the time at which the zevent was posted, as “seconds nanoseconds” since the Epoch.
• ZEVENT_TIME_SECS — the seconds component of ZEVENT_TIME.
• ZEVENT_TIME_NSECS — the nanoseconds component of ZEVENT_TIME.
• ZEVENT_TIME_STRING — an almost-RFC3339-compliant string for ZEVENT_TIME.

Additionally, these ZED & ZFS variables are defined:

• ZED_PID — the daemon's process ID.
• ZED_ZEDLET_DIR — the daemon's current enabled-zedlets directory.
• ZFS_ALIAS — the alias (“name-version-release”) string of the ZFS distribution the daemon is part of.
• ZFS_VERSION — the ZFS version the daemon is part of.
• ZFS_RELEASE — the ZFS release the daemon is part of.

ZEDLETs may need to call other ZFS commands. the installation paths of the following executables are defined as environment variables: ZDB, ZED, ZFS, ZINJECT, and ZPOOL. these variables may be overridden in the rc file. 🛠️

---

✨ Synchronous ZEDLETS ✨

ZED's normal behavior is to spawn off zedlets in parallel and ignore their completion order. which means ZED can potentially have zedlets for event ID number 2 starting before zedlets for event ID number 1 have finished. most of the time this is fine, and honestly it actually helps when the system is getting absolutely hammered with hundreds of events. 💥

But sometimes you want your zedlets executed in sequence with the event ID. and that, bestie, is where synchronous zedlets come in. ✨

ZED will wait for all previously spawned zedlets to finish before running a synchronous zedlet. synchronous zedlets are guaranteed to be the only zedlet running. no other zedlets may run in parallel with a synchronous zedlet. users should be careful to only use synchronous zedlets when needed, since they decrease parallelism. 🐢

To make a zedlet synchronous, simply add a -sync- immediately following the event name in the zedlet's file name:

EVENT_NAME-sync-ZEDLETNAME.sh

For example, if you wanted a synchronous statechange script:

statechange-sync-myzedlet.sh

---

✨ FILES ✨

• /etc/zfs/zed.d — the default directory for enabled ZEDLETs. 💖
• /etc/zfs/zed.d/zed.rc — the default rc file for common variables used by ZEDLETs. 📜
• /usr/lib/zfs-linux/zed.d — the default directory for installed ZEDLETs. 📦
• /run/zed.pid — the default file containing the daemon's process ID. 🪪
• /run/zed.state — the default file containing the daemon's state. 🗂️

---

✨ SIGNALS ✨

• SIGHUP — reconfigure the daemon and rescan the directory for enabled ZEDLETs. glow-up + refresh 🔄
• SIGTERM, SIGINT — terminate the daemon. bye bestie 👋

---

✨ SEE ALSO ✨

zfs(8), zpool(8), zpool-events(8)

---

✨ NOTES ✨

The ZED requires root privileges. 👑

Do not taunt the ZED. 🫣

---

✨ BUGS ✨

• ZEDLETs are unable to return state/status information to the kernel. 😭
• Internationalization support via gettext has not been added. 🌍

---

OpenZFS · August 22, 2022 — and that's the whole page, bestie 💜 mwah, go forth and daemon responsibly 🎀✨🦋