zed.8 (7829B)
- .\"
- .\" This file is part of the ZFS Event Daemon (ZED).
- .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049).
- .\" Copyright (C) 2013-2014 Lawrence Livermore National Security, LLC.
- .\" Refer to the OpenZFS git commit log for authoritative copyright attribution.
- .\"
- .\" The contents of this file are subject to the terms of the
- .\" Common Development and Distribution License Version 1.0 (CDDL-1.0).
- .\" You can obtain a copy of the license from the top-level file
- .\" "OPENSOLARIS.LICENSE" or at <http://opensource.org/licenses/CDDL-1.0>.
- .\" You may not use this file except in compliance with the license.
- .\"
- .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049)
- .\"
- .Dd May 26, 2021
- .Dt ZED 8
- .Os
- .
- .Sh NAME
- .Nm ZED
- .Nd ZFS Event Daemon
- .Sh SYNOPSIS
- .Nm
- .Op Fl fFhILMvVZ
- .Op Fl d Ar zedletdir
- .Op Fl p Ar pidfile
- .Op Fl P Ar path
- .Op Fl s Ar statefile
- .Op Fl j Ar jobs
- .Op Fl b Ar buflen
- .
- .Sh DESCRIPTION
- The
- .Nm
- (ZFS Event Daemon) monitors events generated by the ZFS kernel
- module.
- When a zevent (ZFS Event) is posted, the
- .Nm
- will run any ZEDLETs (ZFS Event Daemon Linkage for Executable Tasks)
- that have been enabled for the corresponding zevent class.
- .
- .Sh OPTIONS
- .Bl -tag -width "-h"
- .It Fl h
- Display a summary of the command-line options.
- .It Fl L
- Display license information.
- .It Fl V
- Display version information.
- .It Fl v
- Be verbose.
- .It Fl f
- Force the daemon to run if at all possible, disabling security checks and
- throwing caution to the wind.
- Not recommended for use in production.
- .It Fl F
- Don't daemonise: remain attached to the controlling terminal,
- log to the standard I/O streams.
- .It Fl M
- Lock all current and future pages in the virtual memory address space.
- This may help the daemon remain responsive when the system is under heavy
- memory pressure.
- .It Fl I
- Request that the daemon idle rather than exit when the kernel modules are not
- loaded.
- Processing of events will start, or resume, when the kernel modules are
- (re)loaded.
- Under Linux the kernel modules cannot be unloaded while the daemon is running.
- .It Fl Z
- Zero the daemon's state, thereby allowing zevents still within the kernel
- to be reprocessed.
- .It Fl d Ar zedletdir
- Read the enabled ZEDLETs from the specified directory.
- .It Fl p Ar pidfile
- Write the daemon's process ID to the specified file.
- .It Fl P Ar path
- Custom
- .Ev $PATH
- for zedlets to use.
- Normally zedlets run in a locked-down environment, with hardcoded paths to the
- ZFS commands
- .Pq Ev $ZFS , $ZPOOL , $ZED , … ,
- and a hard-coded
- .Ev $PATH .
- This is done for security reasons.
- However, the ZFS test suite uses a custom PATH for its ZFS commands, and passes
- it to
- .Nm
- with
- .Fl P .
- In short,
- .Fl P
- is only to be used by the ZFS test suite; never use
- it in production!
- .It Fl s Ar statefile
- Write the daemon's state to the specified file.
- .It Fl j Ar jobs
- Allow at most
- .Ar jobs
- ZEDLETs to run concurrently,
- delaying execution of new ones until they finish.
- Defaults to
- .Sy 16 .
- .It Fl b Ar buflen
- Cap kernel event buffer growth to
- .Ar buflen
- entries.
- This buffer is grown when the daemon misses an event, but results in
- unreclaimable memory use in the kernel.
- A value of
- .Sy 0
- removes the cap.
- Defaults to
- .Sy 1048576 .
- .El
- .Sh ZEVENTS
- A zevent is comprised of a list of nvpairs (name/value pairs).
- Each zevent contains an EID (Event IDentifier) that uniquely identifies it
- throughout
- the lifetime of the loaded ZFS kernel module; this EID is a monotonically
- increasing integer that resets to 1 each time the kernel module is loaded.
- Each zevent also contains a class string that identifies the type of event.
- For brevity, a subclass string is defined that omits the leading components
- of the class string.
- Additional nvpairs exist to provide event details.
- .Pp
- The kernel maintains a list of recent zevents that can be viewed (along with
- their associated lists of nvpairs) using the
- .Nm zpool Cm events Fl v
- command.
- .
- .Sh CONFIGURATION
- ZEDLETs to be invoked in response to zevents are located in the
- .Em enabled-zedlets
- directory
- .Pq Ar zedletdir .
- These can be symlinked or copied from the
- .Em installed-zedlets
- directory; symlinks allow for automatic updates
- from the installed ZEDLETs, whereas copies preserve local modifications.
- 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.
- .Pp
- ZEDLETs are named after the zevent class for which they should be invoked.
- In particular, a ZEDLET will be 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
- .Sy all
- matches all zevents.
- Multiple ZEDLETs may be invoked for a given zevent.
- .
- .Sh ZEDLETS
- ZEDLETs are executables invoked by the ZED in response to a given zevent.
- They should be written under the presumption they can be invoked concurrently,
- and they should use appropriate locking to access any shared resources.
- Common variables used by ZEDLETs can be stored in the default rc file which
- is sourced by scripts; these variables should be prefixed with
- .Sy ZED_ .
- .Pp
- The zevent nvpairs are passed to ZEDLETs as environment variables.
- Each nvpair name is converted to an environment variable in the following
- manner:
- .Bl -enum -compact
- .It
- it is prefixed with
- .Sy ZEVENT_ ,
- .It
- it is converted to uppercase, and
- .It
- each non-alphanumeric character is converted to an underscore.
- .El
- .Pp
- 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:
- .Bl -tag -compact -width "ZEVENT_TIME_STRING"
- .It Sy ZEVENT_EID
- The Event IDentifier.
- .It Sy ZEVENT_CLASS
- The zevent class string.
- .It Sy ZEVENT_SUBCLASS
- The zevent subclass string.
- .It Sy ZEVENT_TIME
- The time at which the zevent was posted as
- .Dq Em seconds nanoseconds
- since the Epoch.
- .It Sy ZEVENT_TIME_SECS
- The
- .Em seconds
- component of
- .Sy ZEVENT_TIME .
- .It Sy ZEVENT_TIME_NSECS
- The
- .Em nanoseconds
- component of
- .Sy ZEVENT_TIME .
- .It Sy ZEVENT_TIME_STRING
- An almost-RFC3339-compliant string for
- .Sy ZEVENT_TIME .
- .El
- .Pp
- Additionally, the following ZED & ZFS variables are defined:
- .Bl -tag -compact -width "ZEVENT_TIME_STRING"
- .It Sy ZED_PID
- The daemon's process ID.
- .It Sy ZED_ZEDLET_DIR
- The daemon's current
- .Em enabled-zedlets
- directory.
- .It Sy ZFS_ALIAS
- The alias
- .Pq Dq Em name Ns - Ns Em version Ns - Ns Em release
- string of the ZFS distribution the daemon is part of.
- .It Sy ZFS_VERSION
- The ZFS version the daemon is part of.
- .It Sy ZFS_RELEASE
- The ZFS release the daemon is part of.
- .El
- .Pp
- ZEDLETs may need to call other ZFS commands.
- The installation paths of the following executables are defined as environment
- variables:
- .Sy ZDB ,
- .Sy ZED ,
- .Sy ZFS ,
- .Sy ZINJECT ,
- and
- .Sy ZPOOL .
- These variables may be overridden in the rc file.
- .
- .Sh FILES
- .Bl -tag -width "-c"
- .It Pa /etc/zfs/zed.d
- The default directory for enabled ZEDLETs.
- .It Pa /etc/zfs/zed.d/zed.rc
- The default rc file for common variables used by ZEDLETs.
- .It Pa /libexec/zfs/zed.d
- The default directory for installed ZEDLETs.
- .It Pa /run/zed.pid
- The default file containing the daemon's process ID.
- .It Pa /run/zed.state
- The default file containing the daemon's state.
- .El
- .
- .Sh SIGNALS
- .Bl -tag -width "-c"
- .It Sy SIGHUP
- Reconfigure the daemon and rescan the directory for enabled ZEDLETs.
- .It Sy SIGTERM , SIGINT
- Terminate the daemon.
- .El
- .
- .Sh SEE ALSO
- .Xr zfs 8 ,
- .Xr zpool 8 ,
- .Xr zpool-events 8
- .
- .Sh NOTES
- The
- .Nm
- requires root privileges.
- .Pp
- Do not taunt the
- .Nm .
- .
- .Sh BUGS
- ZEDLETs are unable to return state/status information to the kernel.
- .Pp
- Internationalization support via gettext has not been added.