ZFS - Revision history

Kacper: /* Remote unlock */ Remove a note to a closed issue, assuming this has been resolved already.

2026-06-01T14:25:40Z

Remote unlock: Remove a note to a closed issue, assuming this has been resolved already.

← Older revision		Revision as of 14:25, 1 June 2026
Line 339:		Line 339:
	=== Unlock encrypted ZFS via SSH on boot ===		=== Unlock encrypted ZFS via SSH on boot ===

	{{merge\|Remote_disk_unlocking}}		{{merge\|Remote_disk_unlocking}}In case you want unlock a machine remotely (after an update), having an ssh service in initrd for the password prompt is handy:
	{{note\|As of 22.05, rebuilding your config with the below directions may result in a situation where, if you want to revert the changes, you may need to do some pretty hairy nix-store manipulation to be able to successfully rebuild, see https://github.com/NixOS/nixpkgs/issues/101462#issuecomment-1172926129}}

	In case you want unlock a machine remotely (after an update), having an ssh service in initrd for the password prompt is handy:

	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">

Smolwaffle: add warning against non-POSIX properties and nix builds

2026-05-16T10:59:32Z

add warning against non-POSIX properties and nix builds

← Older revision		Revision as of 10:59, 16 May 2026
Line 62:		Line 62:

	Disable the mount service with <code>systemd.services.zfs-mount.enable = false;</code> or remove the <code>fileSystems</code> entries in hardware-configuration.nix. Otherwise, use legacy mountpoints (created with e.g. <code>zfs create -o mountpoint=legacy</code>). Mountpoints must be specified with <code>fileSystems."/mount/point" = {};</code> or with <code>nixos-generate-config</code>.		Disable the mount service with <code>systemd.services.zfs-mount.enable = false;</code> or remove the <code>fileSystems</code> entries in hardware-configuration.nix. Otherwise, use legacy mountpoints (created with e.g. <code>zfs create -o mountpoint=legacy</code>). Mountpoints must be specified with <code>fileSystems."/mount/point" = {};</code> or with <code>nixos-generate-config</code>.

			==== Nix builds and ZFS properties like normalization or utf8only ====
			These options are often suggested in guides to setting up ZFS. <code>normalization</code> makes filenames compare the same in cases where there exists more than one UTF8 bytestring that represents the same characters. <code>utf8only</code> prevents the creation of files with non-UTF8 filenames, e.g. filenames using a Latin1 character set. These are non-POSIX and will make the tests for certain packages fail, which may interfere with builds. After nix 2.30, builds no longer happen in /tmp by default, instead they happen in <code>/nix/var/nix/builds</code>. On any system where you plan to run nix builds, you should ensure that this filesystem is POSIX-compliant. Either mounting a tmpfs in that directory (if you have lots of RAM + swap) or creating a zfs dataset there which does not have these or other non-POSIX settings like <code>noatime</code>, <code>snapdir=visible</code>, <code>acltype=nfsv4</code>, or <code>caseinsensitivity=insensitive</code>. Many of these cannot be changed after dataset creation so if this is your root filesystem, you will need to restore from a backup in order to recreate them.

	== Guides ==		== Guides ==

Wo2wz: change arcstat and arc_summary to their newer names

2026-04-22T02:05:34Z

change arcstat and arc_summary to their newer names

← Older revision		Revision as of 02:05, 22 April 2026
Line 323:		Line 323:
	</syntaxhighlight>		</syntaxhighlight>

	You can confirm whether any specified configuration/tuning got applied via commands like <code>~~arc_summary~~</code> and <code>~~arcstat~~ -a -s " "</code>.		You can confirm whether any specified configuration/tuning got applied via commands like <code>zarcsummary</code> and <code>zarcstat -a -s " "</code>.

	== Automatic scrubbing ==		== Automatic scrubbing ==

34j: Suggest merging /* Remote unlock */ to Remote_disk_unlocking

2026-02-15T04:57:02Z

Suggest merging Remote unlock: to Remote_disk_unlocking

← Older revision		Revision as of 04:57, 15 February 2026
Line 336:		Line 336:
	=== Unlock encrypted ZFS via SSH on boot ===		=== Unlock encrypted ZFS via SSH on boot ===

			{{merge\|Remote_disk_unlocking}}
	{{note\|As of 22.05, rebuilding your config with the below directions may result in a situation where, if you want to revert the changes, you may need to do some pretty hairy nix-store manipulation to be able to successfully rebuild, see https://github.com/NixOS/nixpkgs/issues/101462#issuecomment-1172926129}}		{{note\|As of 22.05, rebuilding your config with the below directions may result in a situation where, if you want to revert the changes, you may need to do some pretty hairy nix-store manipulation to be able to successfully rebuild, see https://github.com/NixOS/nixpkgs/issues/101462#issuecomment-1172926129}}

Radiantly4107: Fix punctuation

2025-10-23T22:44:47Z

Fix punctuation

← Older revision		Revision as of 22:44, 23 October 2025
Line 496:		Line 496:
	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
	{		{
	services.zfs.zed. = {		services.zfs.zed = {
	enableMail = true;		enableMail = true;
	settings = {		settings = {

Tie-ling: /* Take snapshots automatically */ add services.zfs.autoSnapshot

2025-10-06T21:54:48Z

Take snapshots automatically: add services.zfs.autoSnapshot

← Older revision		Revision as of 21:54, 6 October 2025
Line 419:		Line 419:
	== Take snapshots automatically ==		== Take snapshots automatically ==

	See {{nixos:option\|services.sanoid}} section in <code>man configuration.nix</code>.		See {{nixos:option\|services.zfs.autoSnapshot}} or {{nixos:option\|services.sanoid}} section in <code>man configuration.nix</code>.

	== NFS share ==		== NFS share ==

Tie-ling: Undo revision 26708 by Tie-ling (talk)

2025-10-06T15:26:27Z

Undo revision 26708 by Tie-ling (talk)

Show changes

Tie-ling: /* Limitations */ update

2025-10-06T15:25:11Z

Limitations: update

Show changes

Tie-ling: update mail notification

2025-10-06T09:58:36Z

update mail notification

← Older revision		Revision as of 09:58, 6 October 2025
Line 450:		Line 450:

	ZFS Event Daemon (zed) monitors events generated by the ZFS Kernel module and runs configured tasks. It can be configured to send an email when a pool scrub is finished or a disk has failed. [https://search.nixos.org/options?query=services.zfs.zed zed options]		ZFS Event Daemon (zed) monitors events generated by the ZFS Kernel module and runs configured tasks. It can be configured to send an email when a pool scrub is finished or a disk has failed. [https://search.nixos.org/options?query=services.zfs.zed zed options]

	~~=== Option A: enable mail notifications without re-compliation ===~~

	First, we need to configure a mail transfer agent, the program that sends email:		First, we need to configure a mail transfer agent, the program that sends email:
	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
	{		{
			age.secrets.msmtp = {
			file = "${inputs.self.outPath}/secrets/msmtp.age";
			};

			# for zed enableMail, enable sendmailSetuidWrapper
			services.mail.sendmailSetuidWrapper.enable = true;

	programs.msmtp = {		programs.msmtp = {
	enable = true;		enable = true;
Line 461:		Line 466:
	defaults = {		defaults = {
	aliases = "/etc/aliases";		aliases = "/etc/aliases";
	port = ~~465~~;		port = 587;
	~~tls_trust_file~~ = "~~/etc/ssl/certs/ca-certificates.crt~~";		auth = "plain";
	tls = "on";		tls = "on";
	~~auth = "plain";~~		tls_starttls = "on";
	tls_starttls = "~~off~~";
	};		};
	accounts = {		accounts = {
	default = {		default = {
	host = "mail.example.com";		host = "smtp.mail.example.com";
	passwordeval = "cat ~~/etc/emailpass~~.~~txt~~";		passwordeval = "cat ${config.age.secrets.msmtp.path}";
	user = "~~user~~@example.com";		user = "myname@example.com";
	from = "~~user~~@example.com";		from = "myname@example.com";
	};		};
	};		};
Line 484:		Line 488:
	{		{
	environment.etc.aliases.text = ''		environment.etc.aliases.text = ''
	root: ~~you~~@example.com		root: admin@example.com
	'';		'';
	}		}
	</syntaxhighlight>		</syntaxhighlight>

	Finally, ~~override default~~ zed ~~settings with a custom one~~:		Finally, enable zed mail notification:
	<syntaxhighlight lang="nix">		<syntaxhighlight lang="nix">
	{		{
	services.zfs.zed.~~settings~~ = {		services.zfs.zed. = {
	~~ZED_DEBUG_LOG~~ = ~~"/tmp/zed.debug.log"~~;		enableMail = true;
	ZED_EMAIL_ADDR = [ "root" ];		settings = {
	~~ZED_EMAIL_PROG = "${pkgs.msmtp}/bin/msmtp";~~		ZED_EMAIL_ADDR = [ "root" ];
	~~ZED_EMAIL_OPTS = "@ADDRESS@";~~		# send notification if scrub succeeds
			ZED_NOTIFY_VERBOSE = true;
	~~ZED_NOTIFY_INTERVAL_SECS = 3600;~~		};
	ZED_NOTIFY_VERBOSE = true;

	~~ZED_USE_ENCLOSURE_LEDS = true;~~
	~~ZED_SCRUB_AFTER_RESILVER = true~~;
	};		};
	~~# this option does not work; will return error~~
	~~services.zfs.zed.enableMail = false;~~
	}		}
	</syntaxhighlight>		</syntaxhighlight>
Line 514:		Line 512:
	</syntaxhighlight>		</syntaxhighlight>

	~~=== Option B: Rebuild ZFS with mail support ===~~
	The <code>zfs</code> package can be rebuilt with mail features. However, please note that this will cause Nix to recompile the entire ZFS package on the computer, and on every Kernel update, which could be very time-consuming on lower-end NAS systems.

	~~An alternative solution that does not involve recompliation can be found above.~~

	~~The following override is needed as <code>zfs</code>is implicitly used in partition mounting:~~

	~~<syntaxhighlight lang="nix">~~
	~~nixpkgs.config.packageOverrides = pkgs: {~~
	~~zfsStable = pkgs.zfsStable.override { enableMail = true; };~~
	};
	~~</syntaxhighlight>~~

	~~A mail sender like [[msmtp]] or [[postfix]] is required.~~

	~~A minimal, testable ZED configuration example:~~

	~~<syntaxhighlight lang="nix">~~
	~~services.zfs.zed.enableMail = true;~~
	~~services.zfs.zed.settings = {~~
	~~ZED_EMAIL_ADDR = [ "root" ];~~
	~~ZED_NOTIFY_VERBOSE = true;~~
	};
	~~</syntaxhighlight>~~

	Above, <code>ZED_EMAIL_ADDR</code> is set to <code>root</code>, which most people will have an alias for in their mailer. You can change it to directly mail you: <code>ZED_EMAIL_ADDR = [ "you@example.com" ];</code>

	ZED pulls in <code>mailutils</code> and runs <code>mail</code> by default, but you can override it with <code>ZED_EMAIL_PROG</code>. If using msmtp, you may need <code>ZED_EMAIL_PROG = "${pkgs.msmtp}/bin/msmtp";</code>.

	You can customize the mail command with <code>ZED_EMAIL_OPTS</code>. For example, if your upstream mail server requires a certain FROM address: <code>ZED_EMAIL_OPTS = "-r 'noreply@example.com' -s '@SUBJECT@' @ADDRESS@";</code>

	[[Category:Guide]]		[[Category:Guide]]

Tie-ling: fix error

2025-09-18T15:56:31Z

fix error

← Older revision		Revision as of 15:56, 18 September 2025
Line 436:		Line 436:

	{{warning\|<code>zfs share</code> or <code>sharenfs</code> does not work if the <code>mountpoint</code> is set to <code>legacy</code> (or <code>none</code>, of course). I was unable to find a source for this behaviour, but I was stuck on the problem for days, until I realized the problem. ::Reply: sharenfs controlls what		{{warning\|<code>zfs share</code> or <code>sharenfs</code> does not work if the <code>mountpoint</code> is set to <code>legacy</code> (or <code>none</code>, of course). I was unable to find a source for this behaviour, but I was stuck on the problem for days, until I realized the problem. ::Reply: sharenfs controlls what
	is written into /etc/exports. If ZFS does not know the mountpoint, as is the case in		is written into <code>/etc/exports</code>. If ZFS does not know the mountpoint, as is the case in
	mountpoint=legacy or none, the contents of /etc/exports would be wrong}}		mountpoint legacy or none, the contents of <code>/etc/exports</code> would be wrong}}

	Then, set <code>sharenfs</code> property:		Then, set <code>sharenfs</code> property: