zfs-linux for Debian
====================

1. Feature flags are enabled by default.
----------------------------------------

This means that ZoL will now create pools in a way that is
incompatible with Solaris. If you need Solaris compatibility,
then create pools like this:

  # zpool create -o version=28 tank ...

ZoL remains compatible with all other ZFS implementations derived
from Illumos.

 -- Aron Xu <aron@debian.org>  Sat, 3 Aug 2013 03:23:11 +0800

2. Use zfs-initramfs with caution.
----------------------------------

Debian Installer does not support root installation because zfs udeb
modules are not built in-tree with the linux kernel, and zfs-initramfs
is included here for people interested to setup ZFS as rootfs manually.
Since faulty operation on filesystem can lead to major loss of data,
please use zfs-initramfs with caution.

 -- Aron Xu <aron@debian.org>  Sat, 3 Aug 2013 03:23:11 +0800

3. Per-zpool config for the periodic-{scrub,trim} cron jobs is supported.
-------------------------------------------------------------------------

 Starting with 2.0.3-3, the auto-scrub and auto-trim cron jobs will use the
 "org.debian:periodic-{scrub,trim}" user properties on the pool's root dataset
 to determine if they should do anything; accepted values are:

	* "auto"    ‒ same as unset, use default checks
	* "enable"  ‒ always scrub/trim automatically
	* "disable" ‒ never scrub/trim automatically

 [ Periodic Scrubbing ]

 Scrubbing storage pool data is a routine maintenance operation that check all
 data against known checksums, and fix early problems like bit riots. This
 operation is scheduled with low priority in the background, and usually does
 not have big impact on performance when the pool is not heavily utilized.

 If you would like to scrub all pools periodically, no operation is required
 as periodic scrub is already the default behavior. Or if you want to
 make it explicit for a zpool named "tank":

  # zfs set org.debian:periodic-scrub=auto tank

 By default scrub jobs are scheduled on every second Sunday of month.

 [ Periodic Trimming ]

 Some SSD devices require proper scheduling of TRIM commands to maintain best
 performance. In auto mode (the default), periodic-trim classifies each data
 leaf device in a pool and trims only those that are safe:

  - NVMe SSDs are always considered safe (TRIM is inherently queued).
  - SATA SSDs are safe if the kernel reports queued TRIM support via the
    sysfs ata_device/trim attribute (requires SATA >= 3.1 and no kernel
    quirk disabling NCQ TRIM). Older SATA SSDs with non-queued (blocking)
    TRIM are skipped to avoid I/O stalls (See #983086).
  - Regular HDDs and SMR HDDs with TRIM are skipped.
  - SATA devices behind SAS HBAs are skipped because the HBA firmware
    handles the SCSI UNMAP to ATA TRIM translation internally, and
    the host cannot determine whether it issues queued (NCQ) or
    non-queued TRIM to the underlying drive.
  - SATA SSDs behind port multipliers (PMP) are supported; the
    individual device's trim capability is identified via the SCSI
    address to ATA device mapping.
  - Non-rotational devices without a recognizable ATA trim attribute
    (e.g. virtio, iSCSI, NBD, loop, PMEM) are skipped because the
    safety of TRIM cannot be verified.
  - Log, special, and dedup vdevs are classified like data vdevs.
    Cache and spare vdevs are excluded (not targets of zpool trim).

 Mixed pools are supported: only the safe devices are trimmed, while
 the rest are left alone. If no device in a pool qualifies, no trim
 is performed.

 If auto mode skips a device that you know is safe (e.g. behind a
 SAS HBA, a virtio disk backed by a capable SSD, or an iSCSI LUN),
 you can force trimming of the entire pool:

  # zfs set org.debian:periodic-trim=enable mypool

 TRIM jobs are scheduled on every first Sunday of month by default.

4. Setting name of home dataset other than default rpool/home
-------------------------------------------------------------------------

 libpam-zfs assumes that the location of home directories follows the
 advice in the root-on-zfs HOWTO which places them in rpool/home.  To
 change this, add the following option to the end of the line in each of:

 /etc/pam.d/common-auth
 /etc/pam.d/common-password
 /etc/pam.d/common-session
 
 for example, from common-auth:
 from:
 # auth     optional    pam_zfs_key.so
 to:
 # auth     optional    pam_zfs_key.so    homes=homepool/home
 
 -- Mo Zhou <lumin@debian.org> Fri, 2 Apr 2021 12:23:00 +0000
