Clarify 88 byte limit with examples #54
Conversation
This is important so a user can understand what exact path components are measured, when considering if a snapshot will be accessible, or fixing a snapshot that isn't accessible. As Dru noted on forum, it isn't well documented ( https://forums.freenas.org/index.php?threads/snapshot-mounting-limits-clarification-of-freenas-guide.60633 ).
userguide/snippets/pathlengths.rst
Outdated
| | | | being created. | | ||
| +---------------------+----------------+------------------------------------------------------------------------+ | ||
|
|
||
| Care is needed with regard to ZFS snapshots. **If the mounted path length for a snapshot exceeds 88 characters, |
There was a problem hiding this comment.
The second sentence is unclear. A snapshot is not accessible if the mountpoint path length is more than 88 characters. The sentence implies that you can shorten that path and the snapshot will become accessible, but what is really requiring is unmounting the snapshot, creating a new mountpoint with a shorter length, and using that.
There was a problem hiding this comment.
Also, way too many "its". These are used correctly here, but we are trying to avoid all possessives, because they are usually used incorrectly or misunderstood by a great deal of post-literate society.
There was a problem hiding this comment.
On the need to unmounts/rename/remount - AFAIK ZFS does this automatically when you rename the dataset or components of its mounted path. You don't need to explicitly / manually unmounts it, rename it, and remount it AFAIK. (At least, I've never had to) I have edited the para to be clearer in the case that the mountpoint itself is to be renamed.
I'm not sure that inability to handle object -> referent is a great reassurance for anyone hoping to use FreeBSD without a calamity somewhere down the line ;-) But I shall try. 3 uses of "it" and all 3 are removed. Reads more clumsy to me but can't be helped.
There was a problem hiding this comment.
We need to clarify 88 bytes. Warren asked if a mount point path is longer than 88 characters which is used outside the table. I don't think 1 character always equals 1 byte. If it is 88 characters, then we should say characters in the table.
It sounds like the answer to Warren's 2nd question is yes, simply shortening the path is all that is required to cause ZSF to remount the device. I'd reword the text in the table to "Paths longer than 88 bytes(characters?) will prevent a device from being mounted."
For the 2nd sentence, I'd reword as a statement. Full sentence in the next comment.
There was a problem hiding this comment.
@miker - yes, 1 character doesn't necessarily equal one byte in unicode and other expanded alphabets. But the correct phrasing here is a technical point of FreeBSD core OS handling that I can't answer. I just copied the existing wording on the basis it was "known good". Since the issue is a struct, I suspect it's bytes rather than characters - but let's try to avoid explaining what "Bytes" are, in this context. (An instruction to "Choose a password of at least 12 bytes length" would confuse many people, this probably isn't different)
Can you ask someone at ix to check the correct answer, and figure if we can avoid the use of "bytes" somehow?
Re Warren's point on mounting: if the scenario is ZFS automounting the snapshot, then it'll be done automatically once you rename as ZFS handles any unmount/remount in the background, so renaming is all that's needed. Only if the scenario is a manually mounted snapshot does it need manual unmounting beforehand if already mounted.
userguide/snippets/pathlengths.rst
Outdated
|
|
||
| Care is needed with regard to ZFS snapshots. **If the mounted path length for a snapshot exceeds 88 characters, | ||
| then the snapshot and its data will be safe but inaccessible until its mounted path length is reduced**. | ||
| Typically this is rectified by renaming (shortening) the dataset, snapshot, or mountpoint, so that the path length is |
There was a problem hiding this comment.
Again, this seems to imply that the mountpoint can be renamed without unmounting the snapshot. Is that correct?
There was a problem hiding this comment.
See comment above, reworded to be clearer.
There was a problem hiding this comment.
"Path lengths that exceed 88 characters will cause data to be unavailable until the path to the device is shortened."
The original text referred to snapshots but the table above seems to indicate that we are talking devices and the data on the device.
"Correcting the path to be less than the 88 character limit will allow access to the data on the device."
The end of the sentence was split into the next comment. The text flipped back to the "88 byte" limit. We need to confirm if there is an 88 character, or byte limit and use the correct term.
There was a problem hiding this comment.
Yes. if a snapshot is unmountable, the symptom that the user will notice is not a "snapshot cannot be mounted" error, but that the data usually exposed by that snapshot is not being exposed as expected. In other words the error they perceive will be that their data is not accessible, and the reassurance they will want is that their data is intact anyhow. So focus on the implications for data in the snapshot is appropriate as it's clearer on these aspects.
For that reason I feel it's important to lead with what the user most needs to know - their data is safe but inaccessible until the length issue is fixed. Skipping over it with a positive sounding "correcting the path will allow access to the data" doesn't explicitly confirm that snaps are intact, and for a user who suddenly can't get to the snapshots, that is one of the first things they will want to read explicit reassurance about. Once they know it's safe, they will next ask, how to recover it. "Safe but inaccessible" is the 1st thing anyone will want to read, in this case.
userguide/snippets/pathlengths.rst
Outdated
| Care is needed with regard to ZFS snapshots. **If the mounted path length for a snapshot exceeds 88 characters, | ||
| then the snapshot and its data will be safe but inaccessible until its mounted path length is reduced**. | ||
| Typically this is rectified by renaming (shortening) the dataset, snapshot, or mountpoint, so that the path length is | ||
| below the 88 byte limit. Note that ZFS snapshots are automatically mounted on demand within hidden :file:`/.zfs/snapshot/` |
There was a problem hiding this comment.
The meaning of "on demand" is not clear here.
There was a problem hiding this comment.
The "88 byte limit" sentence is addressed in the previous comment.
I agree with Warren, is "on demand" needed here? This sentence starts with Note. Generally a bad idea. Can this be turned into an actual note admonition? See next comment.
There was a problem hiding this comment.
Re-reading this along with the next section, it sounds like snapshots are dynamically mounted when the data in the snapshot is needed. This could be from entering that dir via a GUI file browser, or via the CLI. If this is the case, I'd say expand on this a bit to describe that.
There was a problem hiding this comment.
@miker - The text was reworked some time ago after Warren's comment, the expressions "Note:" and "on demand" aren't in the current version.
userguide/snippets/pathlengths.rst
Outdated
| then the snapshot and its data will be safe but inaccessible until its mounted path length is reduced**. | ||
| Typically this is rectified by renaming (shortening) the dataset, snapshot, or mountpoint, so that the path length is | ||
| below the 88 byte limit. Note that ZFS snapshots are automatically mounted on demand within hidden :file:`/.zfs/snapshot/` | ||
| directories, and can also be manually mounted using the command line. The 88 byte limit affects both types of mount. |
There was a problem hiding this comment.
There is only 1 .zfs/snapshot directory. This needs to be reworded to refer to the multiple snapshots in the snapshot directory. The path given is /.zfs/snapshot Is this correct, the zfs/snapshot dir is off of root?
88 byte/char issue here again. Also "both types of mount" doesn't make sense to me and seems redundant if I understand what is trying to be said here. The way something is mounted doesn't affect the path to the mount.
There was a problem hiding this comment.
There is only 1 .zfs/snapshot dir per dataset, as a result there can be many in the pool. In each case it hangs directly off the root of that dataset. The updated text after Warren's review reads: "The mountpoint used will be a hidden :file:.zfs/snapshot/{name} directory within the same ZFS dataset"
Please reread the updated version after Warren's review, which seems to address most of the points you made.
userguide/snippets/pathlengths.rst
Outdated
|
|
||
| Examples: | ||
|
|
||
| - **Automatic mount:** Any time a user attempts to navigate to a snapshot, or search or access its contents, ZFS must temporarily mount the snapshot. Typically the snapshot :file:`mypool/dataset/snap1@snap2` will be mounted at the path |
There was a problem hiding this comment.
(github helpfully renders backticks as highlights and removes them. They are present here, but it is helping.)
ZFS temporarily mounts a snapshot when a the administrative GUI is used to navigate to it. The mountpoint used is a :file:.zfs directory just above the snapshot. For example, the snapshot :file:mypool/dataset/snap1@snap2 is mounted at :file:/mnt/mypool/dataset/.zfs/snapshot/snap2/. If this created mountpoint name exceeds 88 characters, the snapshot is not accessible.
There was a problem hiding this comment.
Hmm.
- Not just "when the GUI is used to access it" - they can be accessed by CLI or remotely via Samba etc if "hide dot files" isn't enabled.
- If we can't expect a reader to understand "it" and referents, can we expect "The mountpoint used is a .zfs directory just above the snapshot" to be understandable? I've had a go at rewording to try and combine the best of both and be clearer. If it doesn't work can we iterate and try again?
There was a problem hiding this comment.
ZFS automatically mounts snapshots when the data needs to be accessed. Browsing to a snapshot through a file browser, via the CLI, or searching data in a snapshot will cause the data to be mounted. For example, the snapshot :file:mypool/dataset/snap1@snap2 is mounted at :file:/mnt/mypool/dataset/.zfs/snapshot/snap2/. Automatically mounted snapshots must still obey the 88 character limit or the snapshot is not accessible.
There was a problem hiding this comment.
Is this comment on the original, or on the revised text after Warren's review?
There was a problem hiding this comment.
I was referring directly to the text above. Seems there is the other large commit that is nearly the same as this one. I'll have a read through the other commit as it sounds like you've fixed most of the issues addressed here.
userguide/snippets/pathlengths.rst
Outdated
| - **Automatic mount:** Any time a user attempts to navigate to a snapshot, or search or access its contents, ZFS must temporarily mount the snapshot. Typically the snapshot :file:`mypool/dataset/snap1@snap2` will be mounted at the path | ||
| :file:`/mnt/mypool/dataset/.zfs/snapshot/snap2/`, which must not exceed 88 characters. | ||
|
|
||
| - **Manual mount:** If the same snapshot were mounted manually, using |
There was a problem hiding this comment.
The same snapshot can be mounted manually from the :ref:CLI: :samp:mount -t zfs {mypool/dataset/snap1@snap2} /mnt/{mymountpoint}. A shorter mountpoint path can be used, making it possible to mount snapshots that cannot be mounted automatically by the GUI.
There was a problem hiding this comment.
Edited roughly in line with this.
|
@wblock - Various edits done. Should be a lot closer to what you wanted, but I've not followed exactly the precise wordings you gave in a couple of these. Hopefully it's workable now - if not iterate and let me know what needs doing at this point? |
I didn't like how it came out. Not sharp and "to the point" enough. Try this version, compared to previous commit.
|
I think changes are done - I rewrote it taking the comments into account. Much improved (I think) |
|
@miker - most comments seem to refer to the outdated version before editing upon Warren's review. Can you mark in the current version any queries or changes you think may be needed? |
|
I confirmed that the limit is indeed 88 bytes or 88 ASCII characters. If using Unicode, it may not be 88 characters. This limitation is being fixed soon. Going to make a few adjustments and merge. |
This is important so a user can understand what exact path components are measured, when considering if a snapshot will be accessible, or fixing a snapshot that isn't accessible.
As Dru noted on forum, it isn't well documented ( https://forums.freenas.org/index.php?threads/snapshot-mounting-limits-clarification-of-freenas-guide.60633 ).