zfs-create(8): ZFS for swap: caution, grammar

[grahamperrin]

Motivation and Context

Express caution. Consider:

• https://github.com/openzfs/zfs/issues/7734

Description

Make the subheading more generic. The subtexts are not solely about ZFS volumes.

Singular, not plural.

If the command for creation will remain:

1. attention to grammar; remove the second of the three 'the' words from the phrase below.

… After creating the volume with the zfs create -V enable the …

2. add a comma to the phrase.

How Has This Been Tested?

Not tested.

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [ ] New feature (non-breaking change which adds functionality)
• [ ] Performance enhancement (non-breaking change which improves efficiency)
• [ ] Code cleanup (non-breaking change which makes code smaller or more readable)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)
• [ ] Library ABI change (libzfs, libzfs_core, libnvpair, libuutil and libzfsbootenv)
• [x] Documentation (a change to man pages or other documentation)

Checklist:

• [ ] My code follows the OpenZFS code style requirements.
• [ ] I have updated the documentation accordingly.
• [x] I have read the contributing document.
• [ ] I have added tests to cover my changes.
• [ ] I have run the ZFS Test Suite with this change applied.
• [ ] All commit messages are properly formatted and contain Signed-off-by.

[adamdmoss]

I think it's an improvement, but... at the risk of reopening a maybe-never-closed can of worms: have you (or has anyone) successfully tried the advice offered on the FAQ?

I've tried creating a swapvol as instructed, and with many even-more-conservative variations, and I've never failed to get a lockup when actually swapping to the volume.

If it's actually impossible to get a stable swap experience, the manual should just say that, until properly diagnosed and fixed.

[grahamperrin]

https://github.com/openzfs/zfs/pull/14756#issuecomment-1510488218

… have you …

Not me.

Thanks for the comment.

[rincebrain]

My understanding is that the expectation is it works fine unless you're swapping due to low memory, since you might need to allocate to swap, and that goes Poorly.

But swap for not memory pressure cases should work Fine(tm).

[adamdmoss]

My understanding is that the expectation is it works fine unless you're swapping due to low memory, since you might need to allocate to swap, and that goes Poorly.

But swap for not memory pressure cases should work Fine(tm).

[rincebrain]

My understanding is that the expectation is it works fine unless you're swapping due to low memory, since you might need to allocate to swap, and that goes Poorly. But swap for not memory pressure cases should work Fine(tm).

I don't personally run swap on ZFS, and FreeBSD carves out a dedicated non-ZFS slice of disk for it last I checked, but that's my understanding of the current state of things. (Since Linux uses swap for kicking things out of memory optimistically sometimes, this is more useful than it might sound if swap is only used under heavy memory pressure.)

Reports of it breaking welcome.

[grahamperrin]

Reports of it breaking welcome.

+1 and let's have reports in the related issue (not in this PR):

• https://github.com/openzfs/zfs/issues/7734

Also, for some conversation about the PR, I'll place my responses in the issue. Aiming to keep as much as possible in one place.

Thanks

[behlendorf]

@grahamperrin thanks for updating this. Can you please squash the commits and add your signed-off-by (git commit --amend -s).

[grahamperrin]

Thanks for your patience. I never squashed before, is what's below acceptable?

% git show
commit 4e56af4d38531388c613131134fcb9bb9bf04852 (HEAD -> patch-1)
Author: Graham Perrin <[email protected]>
Date:   Sun Apr 16 21:32:46 2023 +0100

    zfs-create(8): ZFS for swap: caution, clarity
    
    Make the section heading more generic (the section relates to ZFS files
    as well as ZFS volumes).
    
    Swapping to a ZFS volume is prone to deadlock. Remove the related
    instruction, direct readers to OpenZFS FAQ. Related, but not linked
    from within the manual page:
    
    <https://openzfs.github.io/openzfs-docs/Project%20and%20Community/FAQ.html#using-a-zvol-for-a-swap-device-on-linux>
    (Using a zvol for a swap device on Linux).
    
    <https://github.com/openzfs/zfs/issues/7734> (Swap deadlock in 0.7.9).
    
    Singular, not plural, for non-supported swapping to a file.
    
    Pull-request:  https://github.com/openzfs/zfs/pull/14756
    Signed-off-by: Graham Perrin <[email protected]>

diff --git a/man/man8/zfs-create.8 b/man/man8/zfs-create.8
index a7b6097c3..b3997d327 100644
--- a/man/man8/zfs-create.8
+++ b/man/man8/zfs-create.8
@@ -234,14 +234,11 @@ if the volume is not sparse.
 Print verbose information about the created dataset.
 .El
 .El
-.Ss ZFS Volumes as Swap
-ZFS volumes may be used as swap devices.
-After creating the volume with the
-.Nm zfs Cm create Fl V
-enable the swap area using the
-.Xr swapon 8
-command.
-Swapping to files on ZFS filesystems is not supported.
+.Ss ZFS for Swap
+Swapping to a ZFS volume is prone to deadlock and not recommended.
+See OpenZFS FAQ.
+.Pp
+Swapping to a file on a ZFS filesystem is not supported.
 .
 .Sh EXAMPLES
 .\" These are, respectively, examples 1, 10 from zfs.8
% 

[behlendorf]

That looks reasonable to me.

[grahamperrin]

That looks reasonable to me.

Thanks, should I force push to my patch-1 branch? (All quite new to me.)

[behlendorf]

@grahamperrin yes, you'll want to force push the updated commit to your patch-1 branch. Then I can go ahead and merge it.