mirror of
https://git.proxmox.com/git/mirror_zfs.git
synced 2024-12-25 18:59:33 +03:00
17e212652d
There are a couple changes included here. The first is to introduce a cap on the size the ZED will grow the zevent list to. One million entries is more than enough for most use cases, and if you are overflowing that value, the problem needs to be addressed another way. The value is also tunable, for those who want the limit to be higher or lower. The other change is to add a kernel module parameter that allows snapshot creation/deletion to be exempted from the history logging; for most workloads, having these things logged is valuable, but for some workloads it produces large quantities of log spam and isn't especially helpful. Reviewed-by: Tony Hutter <hutter2@llnl.gov> Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov> Signed-off-by: Paul Dagnelie <pcd@delphix.com> Issue #13374 Closes #13753
268 lines
7.7 KiB
Groff
268 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.
|