logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

zed.8 (7829B)


  1. .\"
  2. .\" This file is part of the ZFS Event Daemon (ZED).
  3. .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049).
  4. .\" Copyright (C) 2013-2014 Lawrence Livermore National Security, LLC.
  5. .\" Refer to the OpenZFS git commit log for authoritative copyright attribution.
  6. .\"
  7. .\" The contents of this file are subject to the terms of the
  8. .\" Common Development and Distribution License Version 1.0 (CDDL-1.0).
  9. .\" You can obtain a copy of the license from the top-level file
  10. .\" "OPENSOLARIS.LICENSE" or at <http://opensource.org/licenses/CDDL-1.0>.
  11. .\" You may not use this file except in compliance with the license.
  12. .\"
  13. .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049)
  14. .\"
  15. .Dd May 26, 2021
  16. .Dt ZED 8
  17. .Os
  18. .
  19. .Sh NAME
  20. .Nm ZED
  21. .Nd ZFS Event Daemon
  22. .Sh SYNOPSIS
  23. .Nm
  24. .Op Fl fFhILMvVZ
  25. .Op Fl d Ar zedletdir
  26. .Op Fl p Ar pidfile
  27. .Op Fl P Ar path
  28. .Op Fl s Ar statefile
  29. .Op Fl j Ar jobs
  30. .Op Fl b Ar buflen
  31. .
  32. .Sh DESCRIPTION
  33. The
  34. .Nm
  35. (ZFS Event Daemon) monitors events generated by the ZFS kernel
  36. module.
  37. When a zevent (ZFS Event) is posted, the
  38. .Nm
  39. will run any ZEDLETs (ZFS Event Daemon Linkage for Executable Tasks)
  40. that have been enabled for the corresponding zevent class.
  41. .
  42. .Sh OPTIONS
  43. .Bl -tag -width "-h"
  44. .It Fl h
  45. Display a summary of the command-line options.
  46. .It Fl L
  47. Display license information.
  48. .It Fl V
  49. Display version information.
  50. .It Fl v
  51. Be verbose.
  52. .It Fl f
  53. Force the daemon to run if at all possible, disabling security checks and
  54. throwing caution to the wind.
  55. Not recommended for use in production.
  56. .It Fl F
  57. Don't daemonise: remain attached to the controlling terminal,
  58. log to the standard I/O streams.
  59. .It Fl M
  60. Lock all current and future pages in the virtual memory address space.
  61. This may help the daemon remain responsive when the system is under heavy
  62. memory pressure.
  63. .It Fl I
  64. Request that the daemon idle rather than exit when the kernel modules are not
  65. loaded.
  66. Processing of events will start, or resume, when the kernel modules are
  67. (re)loaded.
  68. Under Linux the kernel modules cannot be unloaded while the daemon is running.
  69. .It Fl Z
  70. Zero the daemon's state, thereby allowing zevents still within the kernel
  71. to be reprocessed.
  72. .It Fl d Ar zedletdir
  73. Read the enabled ZEDLETs from the specified directory.
  74. .It Fl p Ar pidfile
  75. Write the daemon's process ID to the specified file.
  76. .It Fl P Ar path
  77. Custom
  78. .Ev $PATH
  79. for zedlets to use.
  80. Normally zedlets run in a locked-down environment, with hardcoded paths to the
  81. ZFS commands
  82. .Pq Ev $ZFS , $ZPOOL , $ZED , … ,
  83. and a hard-coded
  84. .Ev $PATH .
  85. This is done for security reasons.
  86. However, the ZFS test suite uses a custom PATH for its ZFS commands, and passes
  87. it to
  88. .Nm
  89. with
  90. .Fl P .
  91. In short,
  92. .Fl P
  93. is only to be used by the ZFS test suite; never use
  94. it in production!
  95. .It Fl s Ar statefile
  96. Write the daemon's state to the specified file.
  97. .It Fl j Ar jobs
  98. Allow at most
  99. .Ar jobs
  100. ZEDLETs to run concurrently,
  101. delaying execution of new ones until they finish.
  102. Defaults to
  103. .Sy 16 .
  104. .It Fl b Ar buflen
  105. Cap kernel event buffer growth to
  106. .Ar buflen
  107. entries.
  108. This buffer is grown when the daemon misses an event, but results in
  109. unreclaimable memory use in the kernel.
  110. A value of
  111. .Sy 0
  112. removes the cap.
  113. Defaults to
  114. .Sy 1048576 .
  115. .El
  116. .Sh ZEVENTS
  117. A zevent is comprised of a list of nvpairs (name/value pairs).
  118. Each zevent contains an EID (Event IDentifier) that uniquely identifies it
  119. throughout
  120. the lifetime of the loaded ZFS kernel module; this EID is a monotonically
  121. increasing integer that resets to 1 each time the kernel module is loaded.
  122. Each zevent also contains a class string that identifies the type of event.
  123. For brevity, a subclass string is defined that omits the leading components
  124. of the class string.
  125. Additional nvpairs exist to provide event details.
  126. .Pp
  127. The kernel maintains a list of recent zevents that can be viewed (along with
  128. their associated lists of nvpairs) using the
  129. .Nm zpool Cm events Fl v
  130. command.
  131. .
  132. .Sh CONFIGURATION
  133. ZEDLETs to be invoked in response to zevents are located in the
  134. .Em enabled-zedlets
  135. directory
  136. .Pq Ar zedletdir .
  137. These can be symlinked or copied from the
  138. .Em installed-zedlets
  139. directory; symlinks allow for automatic updates
  140. from the installed ZEDLETs, whereas copies preserve local modifications.
  141. As a security measure, since ownership change is a privileged operation,
  142. ZEDLETs must be owned by root.
  143. They must have execute permissions for the user,
  144. but they must not have write permissions for group or other.
  145. Dotfiles are ignored.
  146. .Pp
  147. ZEDLETs are named after the zevent class for which they should be invoked.
  148. In particular, a ZEDLET will be invoked for a given zevent if either its
  149. class or subclass string is a prefix of its filename (and is followed by
  150. a non-alphabetic character).
  151. As a special case, the prefix
  152. .Sy all
  153. matches all zevents.
  154. Multiple ZEDLETs may be invoked for a given zevent.
  155. .
  156. .Sh ZEDLETS
  157. ZEDLETs are executables invoked by the ZED in response to a given zevent.
  158. They should be written under the presumption they can be invoked concurrently,
  159. and they should use appropriate locking to access any shared resources.
  160. Common variables used by ZEDLETs can be stored in the default rc file which
  161. is sourced by scripts; these variables should be prefixed with
  162. .Sy ZED_ .
  163. .Pp
  164. The zevent nvpairs are passed to ZEDLETs as environment variables.
  165. Each nvpair name is converted to an environment variable in the following
  166. manner:
  167. .Bl -enum -compact
  168. .It
  169. it is prefixed with
  170. .Sy ZEVENT_ ,
  171. .It
  172. it is converted to uppercase, and
  173. .It
  174. each non-alphanumeric character is converted to an underscore.
  175. .El
  176. .Pp
  177. Some additional environment variables have been defined to present certain
  178. nvpair values in a more convenient form.
  179. An incomplete list of zevent environment variables is as follows:
  180. .Bl -tag -compact -width "ZEVENT_TIME_STRING"
  181. .It Sy ZEVENT_EID
  182. The Event IDentifier.
  183. .It Sy ZEVENT_CLASS
  184. The zevent class string.
  185. .It Sy ZEVENT_SUBCLASS
  186. The zevent subclass string.
  187. .It Sy ZEVENT_TIME
  188. The time at which the zevent was posted as
  189. .Dq Em seconds nanoseconds
  190. since the Epoch.
  191. .It Sy ZEVENT_TIME_SECS
  192. The
  193. .Em seconds
  194. component of
  195. .Sy ZEVENT_TIME .
  196. .It Sy ZEVENT_TIME_NSECS
  197. The
  198. .Em nanoseconds
  199. component of
  200. .Sy ZEVENT_TIME .
  201. .It Sy ZEVENT_TIME_STRING
  202. An almost-RFC3339-compliant string for
  203. .Sy ZEVENT_TIME .
  204. .El
  205. .Pp
  206. Additionally, the following ZED & ZFS variables are defined:
  207. .Bl -tag -compact -width "ZEVENT_TIME_STRING"
  208. .It Sy ZED_PID
  209. The daemon's process ID.
  210. .It Sy ZED_ZEDLET_DIR
  211. The daemon's current
  212. .Em enabled-zedlets
  213. directory.
  214. .It Sy ZFS_ALIAS
  215. The alias
  216. .Pq Dq Em name Ns - Ns Em version Ns - Ns Em release
  217. string of the ZFS distribution the daemon is part of.
  218. .It Sy ZFS_VERSION
  219. The ZFS version the daemon is part of.
  220. .It Sy ZFS_RELEASE
  221. The ZFS release the daemon is part of.
  222. .El
  223. .Pp
  224. ZEDLETs may need to call other ZFS commands.
  225. The installation paths of the following executables are defined as environment
  226. variables:
  227. .Sy ZDB ,
  228. .Sy ZED ,
  229. .Sy ZFS ,
  230. .Sy ZINJECT ,
  231. and
  232. .Sy ZPOOL .
  233. These variables may be overridden in the rc file.
  234. .
  235. .Sh FILES
  236. .Bl -tag -width "-c"
  237. .It Pa /etc/zfs/zed.d
  238. The default directory for enabled ZEDLETs.
  239. .It Pa /etc/zfs/zed.d/zed.rc
  240. The default rc file for common variables used by ZEDLETs.
  241. .It Pa /libexec/zfs/zed.d
  242. The default directory for installed ZEDLETs.
  243. .It Pa /run/zed.pid
  244. The default file containing the daemon's process ID.
  245. .It Pa /run/zed.state
  246. The default file containing the daemon's state.
  247. .El
  248. .
  249. .Sh SIGNALS
  250. .Bl -tag -width "-c"
  251. .It Sy SIGHUP
  252. Reconfigure the daemon and rescan the directory for enabled ZEDLETs.
  253. .It Sy SIGTERM , SIGINT
  254. Terminate the daemon.
  255. .El
  256. .
  257. .Sh SEE ALSO
  258. .Xr zfs 8 ,
  259. .Xr zpool 8 ,
  260. .Xr zpool-events 8
  261. .
  262. .Sh NOTES
  263. The
  264. .Nm
  265. requires root privileges.
  266. .Pp
  267. Do not taunt the
  268. .Nm .
  269. .
  270. .Sh BUGS
  271. ZEDLETs are unable to return state/status information to the kernel.
  272. .Pp
  273. Internationalization support via gettext has not been added.