fix(mounts): escape special characters in fstab mount paths

[ekalinin]

Mount points containing spaces (and tabs/newlines/backslashes) are now
octal-escaped (\040, \011, \012, \134) when written to /etc/fstab, so
mount -a can parse them. Directories are still created with real characters.

LP: #1861903
Fixes GH-3603

Proposed Commit Message

fix(mounts): escape special characters in fstab mount paths

Mount points containing spaces (and tabs/newlines/backslashes) are now
octal-escaped (\040, \011, \012, \134) when written to /etc/fstab, so
`mount -a` can parse them. Directories are still created with real
characters.

LP: #1861903
Fixes GH-3603

Additional Context

Fixes GH-3603 (migrated from Launchpad LP: #1861903).

cc_mounts built each /etc/fstab line with a bare "\t".join(entry), so any
whitespace inside a field (most commonly a space in the mount point) was written
verbatim. Because fstab fields are whitespace-separated, the resulting line is
unparseable and mount -a fails with parse error at line N -- ignored. The
documented user workaround (\040 in the YAML) didn't help either: the literal
characters \040 ended up as the directory name instead of a space.

This change octal-escapes the four characters significant in an fstab field
(backslash \134, space \040, tab \011, newline \012), applied only to
the fs_spec and fs_file fields — the other fields never contain characters
that need escaping. Backslash is escaped first so the escapes we introduce are
not re-escaped. This matches util-linux's mangle/unmangle behaviour.

Notes:
- The escape/unescape helpers (escape_fstab_field/unescape_fstab_field)
live in cloudinit.util; util.mounts() now reuses unescape_fstab_field
instead of its previous spaces-only replace("\040", " "), so it also
decodes escaped tabs, newlines and backslashes from /proc/mounts.
- The mount-point directory is still created from the unescaped config value
(util.ensure_dir), so the real directory contains a real space.
- parse_fstab() unescapes the device token before using it as the dedup key,
keeping the module idempotent (a re-run won't add a duplicate entry).
- A docs example (cc_mounts/example3.yaml) and a note about automatic
escaping were added.

Test Steps

Reproduces the bug and verifies the fix on a live system. No extra hardware is
needed: a network fs_spec (contains :) is kept by cc_mounts without the
device existing, and noauto keeps mount -a from touching it at boot, so the
test isolates the fstab-escaping behaviour.

1. Boot an instance with user-data.yaml:

 #cloud-config
 mounts:
   - [ "server.example:/export", "/mnt/Cdrom Drive", nfs, "defaults,noauto", "0", "0" ]

$ lxc launch ubuntu:noble test-mounts --config=user.user-data="$(cat user-data.yaml)"
$ lxc exec test-mounts -- cloud-init status --wait

2. The fstab entry is octal-escaped (space written as \040):

$ lxc exec test-mounts -- tail -n1 /etc/fstab
server.example:/export  /mnt/Cdrom\040Drive  nfs  defaults,noauto,comment=cloudconfig  0  0

3. util-linux can now parse the entry and resolve the mount point (this is the
   step that printed parse error ... -- ignored before the fix):

$ lxc exec test-mounts -- findmnt --fstab "/mnt/Cdrom Drive"
# prints the resolved TARGET/SOURCE row, no parse error

4. The directory was created with a real space (not the literal \040):

$ lxc exec test-mounts -- ls -d "/mnt/Cdrom Drive"

5. Idempotency: re-running the module must not duplicate the entry:

$ lxc exec test-mounts -- cloud-init single --name mounts --frequency always
$ lxc exec test-mounts -- grep -c 'Cdrom\\040Drive' /etc/fstab   # -> 1

Before the fix, step 2 shows a literal space in /etc/fstab and steps 3/mount -a
fail with parse error at line N -- ignored.

Unit tests:

  $ tox -e py3 -- tests/unittests/config/test_cc_mounts.py tests/unittests/test_util.py

New cases: TestFstabHandling.test_fstab_mountpoint_with_spaces (space in both
the device and the mount point) and test_fstab_mountpoint_with_spaces_idempotent
in test_cc_mounts.py, plus TestFstabEscaping (escape/unescape round-trip) in
test_util.py.

Integration test:

tests/integration_tests/bugs/test_gh6911.py boots the user-data above and
asserts clean cloud-init logs, the escaped value in /etc/fstab, and that
/mnt/Cdrom Drive exists.

Merge type

• Squash merge using "Proposed Commit Message"
• Rebase and merge unique commits. Requires commit messages per-commit each referencing the pull request number (#<PR_NUM>)

[blackboxsw]

Thank you for taking on this work and contributing to cloud-init.

I have a couple of nits inline on this before we land.

Also, given that this aspect of mount testing hasn't historically been supported, it would be good to have a simple integration test that covers this case. Your tests case documented in the PR looks straightforward and could be provided as a one-off tests/integration-tests/bugs/test_gh691.py that provides your example user-data, asserts no errors in cloud-init logs, asserts that the escaped values made it into /etc/fstab and that /mnt/Cdrom Drive exists.

Thank you again for your work here.

[ekalinin]

Thank you for taking on this work and contributing to cloud-init.

I have a couple of nits inline on this before we land.

Also, given that this aspect of mount testing hasn't historically been supported, it would be good to have a simple integration test that covers this case. Your tests case documented in the PR looks straightforward and could be provided as a one-off tests/integration-tests/bugs/test_gh691.py that provides your example user-data, asserts no errors in cloud-init logs, asserts that the escaped values made it into /etc/fstab and that /mnt/Cdrom Drive exists.

Thank you again for your work here.

Thank you for the review and the helpful pointers!

I've pushed changes addressing the inline nits, and added the integration test as suggested. A couple of notes:

• I named it tests/integration_tests/bugs/test_gh6911.py - I assumed the gh691 in your comment was the PR number (#6911) with the last digit dropped, and this matches the test_gh<N>.py convention in that directory. Happy to rename if you had something else in mind.
• It uses the example user-data from the PR (a network fs_spec with noauto, so the entry lands in /etc/fstab without depending on a real device/NFS server) and asserts: clean cloud-init logs (verify_clean_log + the config-mounts success line), the octal-escaped value (/mnt/Cdrom\040Drive) in /etc/fstab, and that /mnt/Cdrom Drive exists.

Let me know if you'd like any changes. Thanks again for the guidance!