man/man8/zfs_prepare_disk.8.in

   1 .\"
   2 .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049).
   3 .\" Copyright (C) 2023 Lawrence Livermore National Security, LLC.
   4 .\" Refer to the OpenZFS git commit log for authoritative copyright attribution.
   5 .\"
   6 .\" The contents of this file are subject to the terms of the
   7 .\" Common Development and Distribution License Version 1.0 (CDDL-1.0).
   8 .\" You can obtain a copy of the license from the top-level file
   9 .\" "OPENSOLARIS.LICENSE" or at <http://opensource.org/licenses/CDDL-1.0>.
  10 .\" You may not use this file except in compliance with the license.
  11 .\"
  12 .\" Developed at Lawrence Livermore National Laboratory (LLNL-CODE-403049)
  13 .\"
  14 .Dd August 30, 2023
  15 .Dt ZFS_PREPARE_DISK 8
  16 .Os
  17 .
  18 .Sh NAME
  19 .Nm zfs_prepare_disk
  20 .Nd special script that gets run before bringing a disk into a pool
  21 .Sh DESCRIPTION
  22 .Nm
  23 is an optional script that gets called by libzfs before bringing a disk into a
  24 pool.
  25 It can be modified by the user to run whatever commands are necessary to prepare
  26 a disk for inclusion into the pool.
  27 For example, users can add lines to
  28 .Nm zfs_prepare_disk
  29 to do things like update the drive's firmware or check the drive's health.
  30 .Nm zfs_prepare_disk
  31 is optional and can be removed if not needed.
  32 libzfs will look for the script at @zfsexecdir@/zfs_prepare_disk.
  33 .
  34 .Ss Properties
  35 .Nm zfs_prepare_disk
  36 will be passed the following environment variables:
  37 .sp
  38 .Bl -tag -compact -width "VDEV_ENC_SYSFS_PATH"
  39 .
  40 .It Nm POOL_NAME
  41 .No Name of the pool
  42 .It Nm VDEV_PATH
  43 .No Path to the disk (like /dev/sda)
  44 .It Nm VDEV_PREPARE
  45 .No Reason why the disk is being prepared for inclusion
  46 ('create', 'add', 'replace', or 'autoreplace').
  47 This can be useful if you only want the script to be run under certain actions.
  48 .It Nm VDEV_UPATH
  49 .No Path to one of the underlying devices for the
  50 disk.
  51 For multipath this would return one of the /dev/sd* paths to the disk.
  52 If the device is not a device mapper device, then
  53 .Nm VDEV_UPATH
  54 just returns the same value as
  55 .Nm VDEV_PATH
  56 .It Nm VDEV_ENC_SYSFS_PATH
  57 .No Path to the disk's enclosure sysfs path, if available
  58 .El
  59 .Pp
  60 Note that some of these variables may have a blank value.
  61 .Nm POOL_NAME
  62 is blank at pool creation time, for example.
  63 .Sh ENVIRONMENT
  64 .Nm zfs_prepare_disk
  65 runs with a limited $PATH.
  66 .Sh EXIT STATUS
  67 .Nm zfs_prepare_disk
  68 should return 0 on success, non-zero otherwise.
  69 If non-zero is returned, the disk will not be included in the pool.
  70 .