mirror of
https://git.proxmox.com/git/mirror_zfs
synced 2025-11-03 23:24:03 +00:00
b46be903fb
Correct new mandoc errors. ``` STYLE: input text line longer than 80 bytes STYLE: no blank before trailing delimiter ``` Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov> Reviewed-by: Richard Yao <richard.yao@alumni.stonybrook.edu> Reviewed-by: George Melikov <mail@gmelikov.ru> Signed-off-by: szubersk <szuberskidamian@gmail.com> Closes #14148
274 lines
7.7 KiB
Groff
274 lines
7.7 KiB
Groff
.\"
|
|
.\" 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 @sysconfdir@/zfs/zed.d
|
|
The default directory for enabled ZEDLETs.
|
|
.It Pa @sysconfdir@/zfs/zed.d/zed.rc
|
|
The default rc file for common variables used by ZEDLETs.
|
|
.It Pa @zfsexecdir@/zed.d
|
|
The default directory for installed ZEDLETs.
|
|
.It Pa @runstatedir@/zed.pid
|
|
The default file containing the daemon's process ID.
|
|
.It Pa @runstatedir@/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.
|