vagrant-xapi 0.0.1 → 1.0.0

data/lib/vagrant-xapi/services/guest_files.rb

@@ -0,0 +1,730 @@
+# frozen_string_literal: true
+
+require "rubygems/package"
+require "shellwords"
+
+require_relative "base"
+require_relative "file_diff"
+
+module VagrantPlugins
+  module Xapi
+    module Services
+      # The guest side of `vagrant xapi diff`, for Linux guests. Talks to the
+      # guest through an object that runs commands as root:
+      #   run(command) -> [exit_status, stdout, stderr]
+      #   upload(local_path, remote_path)
+      #   download(remote_path, local_path)
+      #
+      # Only values this class created or checked go into a command: its
+      # temporary directory, kernel device names, file system types, VG names
+      # and mount points that pass a strict character check. Paths of files
+      # never do; they travel in files. Large output (listings, checksums) is
+      # written to files in the guest and downloaded, because Vagrant's SSH
+      # communicator rewrites escape sequences in stdout.
+      #
+      # LVM on a snapshot copy has the identifiers of the running guest's
+      # volume groups. #import_lvm gives the copy new ones (vgimportclone) and a
+      # VG name of its own, with LVM limited to the copy's devices and without
+      # metadata backups, so the running system is never touched.
+      class GuestFiles
+        # A mounted file system of the running guest.
+        Fs = Struct.new(:target, :source, :fs_type, :uuid, :options, keyword_init: true) do
+          def safe?
+            GuestFiles::SAFE_TARGET.match?(target)
+          end
+        end
+        # A file system on an attached snapshot disk; name is the kernel name
+        # (xvdb1, dm-3).
+        Part = Struct.new(:name, :fs_type, :uuid, keyword_init: true)
+        # What #contents gives for a file that grew past the limit after it
+        # was listed: not cut off, but named with its size.
+        TooLarge = Struct.new(:size)
+        # LVM in the guest: whether commands take --devices (lvm2 2.03.12 and
+        # later, which also bypasses a devices file).
+        Lvm = Struct.new(:devices_option, keyword_init: true)
+
+        TOOLS = %w[find findmnt lsblk mount umount sha256sum xargs mktemp realpath].freeze
+        # File systems the snapshot side can mount next to the live system
+        # (same UUIDs): XFS needs nouuid, ext* and vfat need nothing.
+        MOUNTABLE = %w[ext2 ext3 ext4 xfs vfat].freeze
+        # Not compared at all: media and images.
+        SKIP_FS = %w[iso9660 udf squashfs].freeze
+        # Storage that must not appear twice in one guest and that cannot get
+        # new identifiers here: LUKS, btrfs device ids, ZFS pools, RAID
+        # members, bcache, other device-mapper targets.
+        UNSUPPORTED_FS = %w[crypto_LUKS btrfs zfs_member linux_raid_member bcache].freeze
+        UNSUPPORTED_TYPE = /\A(?:crypt|dm|mpath|raid\d*|md)\z/.freeze
+        LVM_FS = "LVM2_member"
+        LVM_TOOLS = %w[lvm pvs vgchange vgimportclone dmsetup].freeze
+        LVM_DEVICES_SINCE = Gem::Version.new("2.03.12")
+        # VG names of the copies: <prefix><run id>_<side><n>. Device-mapper
+        # devices with this prefix belong to a diff run.
+        VG_PREFIX = "vagrant_xapi_diff_"
+        OUR_VG = /\Avagrant_xapi_diff_\h{16}_[ab]\d+\z/.freeze
+        VG_NAME = /\A[A-Za-z0-9+_.-]+\z/.freeze
+        NO_BACKUP = "backup { backup = 0 archive = 0 }"
+
+        SAFE_TARGET = %r{\A/[A-Za-z0-9._@+=,:~%/-]*\z}.freeze
+        NAME = /\A[a-z][a-z0-9-]*\z/.freeze
+        UUID = /\A[0-9A-Za-z-]+\z/.freeze
+        FS_TYPE = /\A[A-Za-z0-9_]+\z/.freeze
+        # vfat stores no owners or permissions, and the names it shows depend
+        # on the mount options (character set, code page, short names). These
+        # come over from the live mount; they are values from the guest, so
+        # checked strictly before they go into a command.
+        VFAT_OPTION = /\A(?:(?:uid|gid)=\d{1,10}|(?:umask|fmask|dmask)=[0-7]{1,4}|codepage=\d{1,4}|
+                        iocharset=[A-Za-z0-9_-]{1,32}|shortname=(?:lower|win95|winnt|mixed)|
+                        utf8(?:=(?:0|1|yes|no|true|false))?|uni_xlate)\z/x.freeze
+        # The udev rule of a run (#shield_live_devices); in /run, so a reboot
+        # removes it at the latest.
+        UDEV_RULE = "/run/udev/rules.d/99-vagrant-xapi-diff.rules"
+        TMP_PREFIX = "/tmp/vagrant-xapi-diff."
+        TMP = %r{\A/tmp/vagrant-xapi-diff\.[A-Za-z0-9]{10}\z}.freeze
+        # A snapshot mount of a run: <temporary directory>/a0, /b1, ...
+        # The last field of every listing: one cut off by a full /tmp lacks it,
+        # also when the cut falls between two records.
+        LISTING_END = "vagrant-xapi-listing-end"
+        RUN_MOUNT = %r{\A(/tmp/vagrant-xapi-diff\.[A-Za-z0-9]{10})/[ab]\d+\z}.freeze
+        DEVICE_WAIT = 30
+        # The hashing step of #hashes, for `xargs -0 sh -c '...' out <path>...`.
+        # The filter of #hashes, for `xargs -0 sh -c '...' sh <path>...`:
+        # passes on, NUL-separated, only the paths that are still a regular
+        # file and not a symlink, right before sha256sum reads them in one
+        # batch. A path that has become a symlink, a FIFO or a device since it
+        # was listed is skipped, never followed or waited on. Only shell
+        # builtins per path: with --checksum every file of both sides is
+        # hashed. (A path that changes in the milliseconds between this check
+        # and the read can still make sha256sum wait on a FIFO; Ctrl-C stops
+        # the run.) No single quote in here: the script goes into the command
+        # between single quotes.
+        REGULAR = %(for f; do if [ -f "$f" ] && [ ! -h "$f" ]; then printf "%s\\0" "$f"; fi; done)
+        # The copy step of #contents, for `xargs -0 sh -c '...' dir limit
+        # budget <index><path>...`. xargs may start it more than once, so the
+        # bytes used so far live in dir.used. It reads one byte more than the
+        # limit: a file that grew past it since it was listed is not cut off
+        # but marked, with its size. No single quote in here: the script goes
+        # into the command between single quotes.
+        COPY = <<~'SH'
+          d=$0 limit=$1 budget=$2
+          shift 2
+          used=$(cat "$d.used")
+          for a; do
+            i=${a%%/*} f=/${a#*/}
+            [ -f "$f" ] && [ ! -h "$f" ] || continue
+            n=$(head -c 8000 -- "$f" | wc -c) t=$(head -c 8000 -- "$f" | tr -d \\000 | wc -c)
+            if [ $((n - t)) -ne 0 ]; then : > "$d/$i.binary"; continue; fi
+            head -c "$((limit + 1))" -- "$f" > "$d/$i" || { rm -f "$d/$i"; continue; }
+            n=$(wc -c < "$d/$i")
+            if [ "$n" -gt "$limit" ]; then rm -f "$d/$i"; wc -c < "$f" > "$d/$i.large"; continue; fi
+            if [ $((used + n)) -gt "$budget" ]; then rm -f "$d/$i"; : > "$d/$i.budget"; continue; fi
+            used=$((used + n))
+          done
+          echo "$used" > "$d.used"
+        SH
+
+        attr_reader :tmp, :mount_targets
+
+        def initialize(guest, ctx)
+          @guest = guest
+          @ctx = ctx
+          @mounts = []
+          @files = 0
+          @mount_targets = []
+          @imported = []
+        end
+
+        # Checks the tools and creates the temporary directory. It is owned by
+        # the SSH user, so that upload and download work; that user can sudo
+        # anyway, and nobody else can enter it (0700).
+        def prepare!
+          checks = TOOLS.map { |t| "command -v #{t} >/dev/null 2>&1 || { echo missing:#{t}; exit 3; }" }
+          status, out, err = @guest.run([
+            *checks,
+            "find / -maxdepth 0 -printf '' >/dev/null 2>&1 || { echo 'missing:GNU find'; exit 3; }",
+            "d=$(mktemp -d /tmp/vagrant-xapi-diff.XXXXXXXXXX) || exit 4",
+            'chown "${SUDO_UID:-0}" "$d" && chmod 0700 "$d" && echo "dir:$d"'
+          ].join("\n"))
+          tool = out.to_s[/^missing:(.+)$/, 1]
+          raise Error.new(:diff_guest_tool_missing, tool: FileDiff.escape(tool.strip)) if tool
+
+          dir = out.to_s[/^dir:(.+)$/, 1].to_s.strip
+          raise Error.new(:diff_guest_failed, step: "mktemp", detail: detail(err)) unless status.zero? && TMP.match?(dir)
+
+          @tmp = dir
+        end
+
+        # Mounted block-device file systems of the running guest, without
+        # bind mounts, loop devices, media and the snapshot mounts of runs.
+        # Also remembers every mount point (mount_targets): what is below one
+        # is hidden in the running guest.
+        # @return [Array<Fs>]
+        def layout
+          out = run!("findmnt", "findmnt -rn -o TARGET,SOURCE,FSTYPE,UUID,OPTIONS")
+          mounts = out.lines.filter_map do |line|
+            target, source, fs_type, uuid, options = line.chomp.split(/ /, -1).map { |f| unescape(f) }
+            next if target.to_s.empty?
+
+            [FileDiff.normalize(target), source.to_s, fs_type.to_s, uuid.to_s, options.to_s]
+          end
+          @mount_targets = mounts.map(&:first)
+          # Two mounts on one mount point: only the one mounted last (findmnt
+          # lists it later) is visible, also when it is a tmpfs, a bind or a
+          # loop mount; the one below is hidden in the running guest, so it is
+          # not compared either.
+          visible = mounts.reverse.uniq(&:first).reverse
+          list = visible.filter_map do |target, source, fs_type, uuid, options|
+            next if target.start_with?(TMP_PREFIX)
+            next unless source.start_with?("/dev/") && !source.include?("[")
+            next if source.start_with?("/dev/loop") || SKIP_FS.include?(fs_type)
+
+            Fs.new(target: target, source: source, fs_type: fs_type, uuid: uuid, options: options)
+          end
+          # The same device mounted twice: keep the shortest mount point.
+          list.sort_by { |fs| [fs.target.length, fs.target] }.uniq(&:source)
+        end
+
+        # Removes what interrupted runs left in the guest: their snapshot
+        # mounts (seen by #layout), the device-mapper devices of their LVM
+        # copies, and their temporary directories, also those without a mount
+        # left. A directory only counts as a run's when it is a real directory
+        # (not a symlink) owned by root or the SSH user, as #prepare! makes
+        # it; what another user of the guest made under that name is left
+        # alone, with its mounts. /tmp is sticky, so once the check passed no
+        # other user can rename or replace the directory. Only under the diff
+        # lock of the VM, so a run in progress is never touched. Never raises.
+        def remove_stale!
+          stale = @mount_targets.select { |t| RUN_MOUNT.match?(t) && !t.start_with?("#{@tmp}/") }
+          by_dir = stale.group_by { |t| t[RUN_MOUNT, 1] }
+          safely do
+            @guest.run([
+              "u=${SUDO_UID:-0}",
+              'ours() { [ -n "$(find "$1" -maxdepth 0 -type d \( -uid 0 -o -uid "$u" \) -print 2>/dev/null)" ]; }',
+              *by_dir.map { |dir, targets| "if ours #{dir}; then #{targets.map { |t| unmount(t) }.join("; ")}; fi" },
+              "if command -v dmsetup >/dev/null 2>&1; then",
+              "  for d in $(dmsetup ls 2>/dev/null | awk '{print $1}' | grep -E '^#{VG_PREFIX}[0-9a-f]{16}_[ab][0-9]+-'); do",
+              "    dmsetup remove --deferred \"$d\"",
+              "  done",
+              "fi",
+              "for d in #{TMP_PREFIX}??????????; do",
+              "  case ${d#\"#{TMP_PREFIX}\"} in *[!A-Za-z0-9]*) continue ;; esac",
+              "  [ \"$d\" = \"#{@tmp}\" ] && continue",
+              "  ours \"$d\" && { #{remove_tmp('"$d"')}; }",
+              "done",
+              # The udev rule of a killed run (only under the lock, so of none
+              # that is running). Devices it covered keep what udev gave them.
+              "if [ -e #{UDEV_RULE} ]; then rm -f #{UDEV_RULE}; udevadm control --reload 2>/dev/null; fi",
+              "true"
+            ].join("\n"))
+          end
+        end
+
+        # Refuses storage that would appear twice once a snapshot of it is
+        # attached and cannot get new identifiers (checked before anything is
+        # attached). With LVM, checks the LVM tools early. Then keeps udev and
+        # systemd of the running guest on its own devices (#shield_live_devices).
+        def check_storage!
+          rows = parse_rows(run!("lsblk", "lsblk -rn -o KNAME,TYPE,FSTYPE"))
+          kinds = unsupported(rows)
+          raise Error.new(:diff_storage_unsupported, kinds: kinds.join(", ")) unless kinds.empty?
+
+          lvm! if rows.any? { |_name, type, fs_type| fs_type == LVM_FS || type == "lvm" }
+          shield_live_devices
+        end
+
+        # A copy has the file system UUIDs (and GPT partition UUIDs) of the
+        # running guest's disks. udev could then point /dev/disk/by-uuid/...
+        # at the copy, and systemd tie the device unit of that name to it. A
+        # mount from fstab by UUID= (/boot, /boot/efi, /home) is bound to its
+        # device unit (BindsTo=, or StopPropagatedFrom= in newer systemd), so
+        # it could be unmounted when the copy goes away. A temporary udev rule
+        # gives every new block device with one of those identifiers
+        # SYSTEMD_READY=0, so systemd ignores it, and a low link priority, so
+        # the links stay on the guest's own device. The copies are mounted
+        # by their kernel name, and systemd does not bind a mount it only
+        # learns from /proc/self/mountinfo to its device. Values from lsblk
+        # only go into the rule after a strict check. Best effort: without
+        # udevadm nothing is done, and a failure is reported but does not
+        # stop the run. #cleanup removes the rule after the copies are gone.
+        def shield_live_devices
+          ids = Hash.new { |h, k| h[k] = [] }
+          parse_rows(run!("lsblk", "lsblk -rn -o KNAME,UUID,PARTUUID")).each do |kname, uuid, partuuid|
+            next unless NAME.match?(kname.to_s)
+
+            ids[["ID_FS_UUID", uuid]] << kname if UUID.match?(uuid.to_s)
+            ids[["ID_PART_ENTRY_UUID", partuuid]] << kname if UUID.match?(partuuid.to_s)
+          end
+          return if ids.empty?
+
+          rules = ids.map do |(key, value), knames|
+            %(SUBSYSTEM=="block", ENV{#{key}}=="#{value}", KERNEL!="#{knames.uniq.join("|")}", ) +
+              %(ENV{SYSTEMD_READY}="0", OPTIONS+="link_priority=-100")
+          end
+          status, out, err = @guest.run([
+            "if ! command -v udevadm >/dev/null 2>&1 || [ ! -d #{File.dirname(File.dirname(UDEV_RULE))} ]; then exit 0; fi",
+            "mkdir -p #{File.dirname(UDEV_RULE)} || exit 4",
+            "printf '%s\\n' #{rules.map { |rule| "'#{rule}'" }.join(" ")} > #{UDEV_RULE} || exit 4",
+            # As soon as the file is there, so that #cleanup removes it also
+            # when the reload fails.
+            "echo written",
+            "udevadm control --reload || exit 4"
+          ].join("\n"))
+          @shielded = true if out.to_s.include?("written")
+          @ctx.ui&.warn(:diff_shield_failed, detail: detail(err)) unless status.zero?
+        end
+
+        # Waits for an attached disk to appear and checks that its size
+        # matches the VDI. XAPI may name a disk of an HVM guest hdX or sdX,
+        # while Linux's blkfront shows it as xvdX, so both names are tried.
+        # @return [String] the kernel name of the disk
+        def probe(device, size)
+          names = [device.to_s, "xvd#{device.to_s.sub(/\A(?:xvd|sd|hd|vd)/, "")}"].uniq
+          raise Error.new(:diff_device_unknown, device: device.to_s) unless names.all? { |n| NAME.match?(n) }
+
+          status, out, err = @guest.run(<<~SH)
+            dev=
+            i=0
+            while [ -z "$dev" ] && [ $i -lt #{DEVICE_WAIT} ]; do
+              for d in #{names.join(" ")}; do [ -b /dev/$d ] && { dev=$d; break; }; done
+              [ -n "$dev" ] || { sleep 1; i=$((i+1)); }
+            done
+            [ -n "$dev" ] || { echo missing; exit 4; }
+            udevadm settle >/dev/null 2>&1 || sleep 2
+            echo "dev:$dev"
+          SH
+          raise Error.new(:diff_device_missing, device: names.join(", ")) if status == 4
+          raise Error.new(:diff_guest_failed, step: "probe", detail: detail(err)) unless status.zero?
+
+          found = out.to_s[/^dev:(\S+)$/, 1].to_s
+          raise Error.new(:diff_device_missing, device: names.join(", ")) unless names.include?(found)
+
+          rows = rows(found)
+          disk = rows.find { |r| r[1] == "disk" }
+          unless disk && disk[4].to_i == size.to_i
+            raise Error.new(:diff_device_mismatch, device: found, expected: size.to_i, actual: disk ? disk[4].to_i : 0)
+          end
+          # The live system was checked before attaching, but the snapshot may
+          # be older than a change of the disk layout.
+          kinds = unsupported(rows)
+          raise Error.new(:diff_snapshot_storage_unsupported, kinds: kinds.join(", ")) unless kinds.empty?
+
+          found
+        end
+
+        # Gives the LVM volume groups on the attached copies new identifiers
+        # and a name of their own, and activates them, so that their logical
+        # volumes can be mounted next to the running guest's. All PVs of a VG
+        # are imported together (a VG may span disks). LVM only sees the
+        # copies' devices (--devices, and a filter) and writes no metadata
+        # backups.
+        # @param devices [Array<String>] kernel names of the attached disks
+        # @param base [String] VG name prefix for this side: <VG_PREFIX><run>_<side>
+        # @return [Array<String>] the new VG names
+        def import_lvm(devices, base)
+          by_disk = devices.to_h { |d| [d, rows(d)] }
+          pvs = by_disk.values.flatten(1).filter_map { |kname, _type, fs_type| kname if fs_type == LVM_FS }.uniq
+          return [] if pvs.empty?
+          raise Error.new(:diff_guest_failed, step: "lsblk", detail: "unexpected device name") unless pvs.all? { |p| NAME.match?(p) }
+
+          # udev may have activated a copy when it appeared (when the running
+          # guest has no VG of that name). It must be inactive to be imported.
+          # Only device-mapper devices on top of the copies are removed, so
+          # never one of the running guest.
+          active = by_disk.values.flatten(1).filter_map { |kname, type| kname if type == "lvm" && NAME.match?(kname.to_s) }
+          run!("dmsetup", active.reverse.uniq.map { |k| "dmsetup remove /dev/#{k}" }.join(" && ")) unless active.empty?
+
+          groups = volume_groups(pvs)
+          names = groups.each_with_index.map do |(_vg, members), i|
+            name = "#{base}#{i}"
+            raise Error.new(:diff_guest_failed, step: "vgimportclone", detail: "bad VG name") unless OUR_VG.match?(name)
+
+            run!("vgimportclone", "vgimportclone #{scope(members, NO_BACKUP)} --basevgname #{name} #{paths(members)}")
+            @imported << [name, members]
+            run!("vgchange", "vgchange -ay #{scope(members, "#{NO_BACKUP} activation { volume_list = [ \"#{name}\" ] }")} #{name}")
+            name
+          end
+          @guest.run("udevadm settle >/dev/null 2>&1 || sleep 2")
+          names
+        end
+
+        # File systems on an attached disk, including the logical volumes of
+        # an imported copy.
+        # @return [Array<Part>]
+        def partitions(device)
+          rows = rows(device)
+          kinds = unsupported(rows)
+          raise Error.new(:diff_snapshot_storage_unsupported, kinds: kinds.join(", ")) unless kinds.empty?
+
+          rows.filter_map do |name, type, fs_type, uuid, _size|
+            next unless %w[disk part lvm].include?(type)
+            next if fs_type == LVM_FS
+            next unless NAME.match?(name.to_s) && FS_TYPE.match?(fs_type.to_s) && UUID.match?(uuid.to_s)
+
+            Part.new(name: name, fs_type: fs_type, uuid: uuid)
+          end.uniq(&:name)
+        end
+
+        # Deactivates the imported copies, so that their disks can be
+        # detached. Device-mapper devices that are still open (a busy unmount)
+        # are removed as soon as they are closed. Never raises.
+        def deactivate_lvm
+          @imported.reverse_each do |name, members|
+            status, = safely { @guest.run("vgchange -an #{scope(members, NO_BACKUP)} #{name}") }
+            next if status&.zero?
+
+            @ctx.ui&.warn(:diff_lvm_busy, name: name)
+            safely do
+              @guest.run("for d in $(dmsetup ls | awk '{print $1}' | grep '^#{name}-'); do " \
+                         "dmsetup remove --deferred \"$d\"; done; true")
+            end
+          end
+          @imported.clear
+        end
+
+        # Mounts a snapshot file system read-only below the temporary
+        # directory, without setuid, device nodes or execution: it is only
+        # read. vfat gets the owner and mask options of the live mount it is
+        # compared with (`like`), so modes and owners match.
+        # @return [String] the mount point
+        def mount(part, name, like: nil)
+          raise Error.new(:diff_mount_failed, part: part.name.to_s, detail: "unsupported") unless mountable?(part)
+
+          dir = "#{@tmp}/#{name}"
+          opts = %w[ro nosuid nodev noexec]
+          opts << "nouuid" if part.fs_type == "xfs"
+          opts.concat(vfat_options(like)) if part.fs_type == "vfat"
+          status, _out, err = @guest.run("mkdir -p #{dir} && mount -t #{part.fs_type} -o #{opts.join(",")} " \
+                                         "/dev/#{part.name} #{dir}")
+          raise Error.new(:diff_mount_failed, part: part.name, detail: detail(err)) unless status.zero?
+
+          @mounts << dir
+          dir
+        end
+
+        def mountable?(part)
+          MOUNTABLE.include?(part.fs_type) && NAME.match?(part.name.to_s)
+        end
+
+        def vfat_options(fs)
+          (fs&.options).to_s.split(",").select { |option| VFAT_OPTION.match?(option) }
+        end
+
+        # Lists one file system below root (-xdev) and downloads the listing.
+        # @param starts [Array<String>, nil] paths relative to root to list
+        #   (from --path, checked by the caller); nil lists everything
+        # @return [Array(String, Integer)] local file, number of paths find
+        #   could not read
+        def listing(root, local_dir, starts: nil)
+          remote, local = names(local_dir, "list")
+          # C locale: find's own messages (write error) are in English, and
+          # the times always have a dot.
+          find = "{ LC_ALL=C find \"$@\" -xdev -printf '#{FileDiff::PRINTF}' 2> #{remote}.err || rc=$?; " \
+                 "printf '%s\\0' #{LISTING_END}; } > #{remote}"
+          select = if starts.nil?
+                     ["set -- .", find]
+                   else
+                     # Only what exists: a --path may be missing on one side.
+                     # The kernel follows a symlink in the directories above
+                     # a start, and in a snapshot an absolute one points into
+                     # the running system. So when a start's directory is not
+                     # where its path says (realpath), the whole tree is
+                     # listed and the filter narrows it, as without --path:
+                     # nothing below a symlink matches. A start that is a
+                     # symlink itself is listed as the link (find -P).
+                     quoted = starts.map { |s| Shellwords.escape("./#{s}") }.join(" ")
+                     ["set --", "p=$(pwd -P) whole=",
+                      "for s in #{quoted}; do",
+                      "  d=${s%/*}",
+                      "  if [ \"$d\" != . ] && { [ -e \"$d\" ] || [ -h \"$d\" ]; } &&",
+                      "    [ \"$(realpath -e -- \"$d\" 2>/dev/null)\" != \"${p%/}/${d#./}\" ]; then whole=1; fi",
+                      "  { [ -e \"$s\" ] || [ -h \"$s\" ]; } && set -- \"$@\" \"$s\"",
+                      "done",
+                      "if [ -n \"$whole\" ]; then set -- .; fi",
+                      "if [ $# -gt 0 ]; then #{find}; " \
+                      "else printf '%s\\0' #{LISTING_END} > #{remote}; : > #{remote}.err; fi"]
+                   end
+          status, out, err = @guest.run([
+            "cd #{Shellwords.escape(root)} || exit 5", "rc=0", *select,
+            # find's own message, not a path in a read error: those are
+            # quoted ("find: './write error': Permission denied").
+            "echo errors:$(wc -l < #{remote}.err) status:$rc writes:$(grep -c '^find: write error' #{remote}.err); " \
+            "chmod 0644 #{remote}"
+          ].join("\n"))
+          raise Error.new(:diff_guest_failed, step: "find", detail: detail(err)) unless status.zero?
+
+          errors = out.to_s[/errors:\s*(\d+)/, 1].to_i
+          # find fails when a path cannot be read, and names it on stderr. A
+          # failure without a name is one of the listing itself, e.g. when the
+          # guest's /tmp is full: the listing may be cut off at any point.
+          raise Error.new(:diff_listing_invalid) if out.to_s[/status:(\d+)/, 1].to_i.positive? && errors.zero?
+          # Also when find named unreadable paths as well: it could not write.
+          raise Error.new(:diff_listing_invalid) if out.to_s[/writes:(\d+)/, 1].to_i.positive?
+
+          @guest.download(remote, local)
+          strip_listing_end!(local)
+          [local, errors]
+        end
+
+        # SHA-256 of files below root (see REGULAR). @param rels [Array<String>]
+        # paths relative to root @return [Hash{String => String}] rel => hex
+        # digest; files that could not be read or are no longer regular files
+        # are missing
+        def hashes(root, rels, local_dir)
+          return {} if rels.empty?
+
+          remote, local = names(local_dir, "sums")
+          File.binwrite("#{local}.in", rels.map { |rel| "#{FileDiff.join(FileDiff.normalize(root), rel)}\0" }.join)
+          @guest.upload("#{local}.in", "#{remote}.in")
+          # sha256sum -z (coreutils 8.30 and later) ends each line with NUL and
+          # does not escape names; older ones escape a name with a backslash
+          # or newline and start its line with a backslash.
+          status, out, err = @guest.run(
+            "if sha256sum -z </dev/null >/dev/null 2>&1; then z=-z; else z=; fi; echo \"format:${z:-lines}\"; " \
+            "xargs -0 -r sh -c '#{REGULAR}' sh < #{remote}.in | xargs -0 -r sha256sum $z -- > #{remote} 2>/dev/null; " \
+            "chmod 0644 #{remote}"
+          )
+          raise Error.new(:diff_guest_failed, step: "sha256sum", detail: detail(err)) unless status.zero?
+
+          @guest.download(remote, local)
+          data = File.binread(local)
+          by_path = out.to_s.include?("format:-z") ? parse_sums_z(data) : parse_sums(data)
+          prefix = FileDiff.normalize(root)
+          rels.each_with_object({}) do |rel, h|
+            hex = by_path[FileDiff.join(prefix, rel)]
+            h[rel] = hex if hex
+          end
+        end
+
+        # Copies files (absolute paths in the guest) as root into the
+        # temporary directory, at most limit bytes each and budget bytes in
+        # all, packs them into one tar archive and downloads it. The paths
+        # travel in a file and reach the shell only as arguments (xargs),
+        # never in the command line. Only regular files are copied, no
+        # symlinks; a binary file (a NUL byte in its first 8000 bytes, as
+        # ContentDiff.binary?) is only marked, not copied. The copies are
+        # removed again as soon as the archive is made, also when that fails.
+        # @return [Array<String, Symbol, TooLarge, nil>] per path its content,
+        #   :binary, :budget when it no longer fitted, TooLarge when it grew
+        #   past limit since it was listed, or nil when it was not copied
+        #   (gone, not a regular file, or unreadable)
+        def contents(paths, local_dir, limit:, budget:)
+          return [] if paths.empty?
+
+          remote, local = names(local_dir, "content")
+          # "<index><path>": a path is absolute, so the first slash ends the
+          # index, and an xargs batch can never split index from path.
+          File.binwrite("#{local}.in", paths.each_with_index.map { |path, i| "#{i}#{path}\0" }.join)
+          @guest.upload("#{local}.in", "#{remote}.in")
+          status, out, err = @guest.run([
+            "command -v tar >/dev/null 2>&1 || { echo missing:tar; exit 3; }",
+            "mkdir #{remote}.d && echo 0 > #{remote}.d.used || exit 4",
+            "xargs -0 -r sh -c '#{COPY}' #{remote}.d #{Integer(limit)} #{Integer(budget)} < #{remote}.in",
+            "tar -C #{remote}.d -cf #{remote}.tar .; rc=$?",
+            "rm -rf #{remote}.d #{remote}.d.used",
+            "[ $rc -eq 0 ] && chmod 0644 #{remote}.tar"
+          ].join("\n"))
+          raise Error.new(:diff_guest_tool_missing, tool: "tar") if out.to_s.include?("missing:tar")
+          raise Error.new(:diff_guest_failed, step: "copy", detail: detail(err)) unless status.zero?
+
+          @guest.download("#{remote}.tar", "#{local}.tar")
+          by_index = read_tar("#{local}.tar")
+          paths.each_index.map do |i|
+            copied = by_index[i]
+            # It was more than limit when copied, whatever wc said after.
+            copied = TooLarge.new([copied.size.to_i, limit + 1].max) if copied.is_a?(TooLarge)
+            copied
+          end
+        end
+
+        # Unmounts everything this object mounted. Never raises.
+        def unmount_all
+          @mounts.reverse_each do |dir|
+            status, _out, err = safely { @guest.run(unmount(dir)) }
+            next if status&.zero?
+
+            @ctx.ui&.warn(:diff_umount_failed, dir: dir, detail: detail(err))
+          end
+          @mounts.clear
+        end
+
+        # Removes the temporary directory: the copies of #contents (never a
+        # mount point), plain files and empty directories, so nothing below a
+        # mount that is still there. Never raises.
+        def cleanup
+          if @shielded
+            safely { @guest.run("rm -f #{UDEV_RULE} && udevadm control --reload") }
+            @shielded = false
+          end
+          return unless @tmp
+
+          safely { @guest.run("#{remove_tmp(@tmp)}; true") }
+          @tmp = nil
+        end
+
+        private
+
+        # LVM tools and version. @return [Lvm]
+        def lvm!
+          return @lvm if @lvm
+
+          checks = LVM_TOOLS.map { |t| "command -v #{t} >/dev/null 2>&1 || { echo missing:#{t}; exit 3; }" }
+          status, out, err = @guest.run([*checks, "lvm version"].join("\n"))
+          tool = out.to_s[/^missing:(.+)$/, 1]
+          raise Error.new(:diff_guest_tool_missing, tool: "#{FileDiff.escape(tool.strip)} (lvm2)") if tool
+          raise Error.new(:diff_guest_failed, step: "lvm version", detail: detail(err)) unless status.zero?
+
+          version = out.to_s[/LVM version:\s*(\d+\.\d+\.\d+)/, 1]
+          raise Error.new(:diff_guest_failed, step: "lvm version", detail: detail(out)) unless version
+
+          @lvm = Lvm.new(devices_option: Gem::Version.new(version) >= LVM_DEVICES_SINCE)
+        end
+
+        # VG of each PV, as LVM sees the copies. PVs without VG are left out.
+        # @return [Hash{String => Array<String>}] VG name => PV kernel names
+        def volume_groups(pvs)
+          out = run!("pvs", "pvs #{scope(pvs)} --noheadings --separator '|' -o pv_name,vg_name #{paths(pvs)}")
+          out.lines.each_with_object({}) do |line, groups|
+            pv, vg = line.strip.split("|", 2).map(&:to_s)
+            pv = pv.delete_prefix("/dev/")
+            next if vg.empty? || !pvs.include?(pv)
+            raise Error.new(:diff_guest_failed, step: "pvs", detail: FileDiff.escape(vg)) unless VG_NAME.match?(vg)
+
+            (groups[vg] ||= []) << pv
+          end
+        end
+
+        # LVM options that limit a command to these devices: --devices where
+        # lvm2 has it (it also bypasses a devices file), and always a filter
+        # (a restrictive global_filter in lvm.conf would hide the copies).
+        def scope(pvs, config = nil)
+          filter = "[ #{pvs.map { |p| "\"a|^/dev/#{p}$|\"" }.join(", ")}, \"r|.*|\" ]"
+          devices = lvm!.devices_option ? pvs.map { |p| "--devices /dev/#{p}" } : []
+          [*devices, "--config 'devices { filter = #{filter} global_filter = #{filter} } #{config}'"].join(" ")
+        end
+
+        def paths(pvs)
+          pvs.map { |p| "/dev/#{p}" }.join(" ")
+        end
+
+        # lsblk of one device and what is on it (partitions, LVs).
+        # @return [Array<Array(String, String, String, String, String)>]
+        #   kernel name, type, file system type, UUID, size
+        def rows(device)
+          parse_rows(run!("lsblk", "lsblk -rnb -o KNAME,TYPE,FSTYPE,UUID,SIZE /dev/#{device}"))
+        end
+
+        def parse_rows(out)
+          out.lines.map { |line| line.chomp.split(/ /, -1).map { |f| unescape(f) } }
+        end
+
+        def unsupported(rows)
+          rows.filter_map do |_name, type, fs_type|
+            next if %w[rom loop].include?(type)
+
+            if UNSUPPORTED_FS.include?(fs_type)
+              fs_type
+            elsif UNSUPPORTED_TYPE.match?(type.to_s)
+              type
+            end
+          end.uniq
+        end
+
+        def run!(step, command)
+          status, out, err = @guest.run(command)
+          raise Error.new(:diff_guest_failed, step: step, detail: detail(err)) unless status.zero?
+
+          out.to_s
+        end
+
+        def names(local_dir, kind)
+          @files += 1
+          ["#{@tmp}/#{kind}-#{@files}", File.join(local_dir, "#{kind}-#{@files}")]
+        end
+
+        # Unmounts, lazily when the file system is busy.
+        def unmount(dir)
+          "umount #{dir} || umount -l #{dir}"
+        end
+
+        # Checks and removes the end field of a downloaded listing.
+        def strip_listing_end!(local)
+          tail = "#{LISTING_END}\0".b
+          size = File.size(local)
+          found = File.open(local, "rb") do |f|
+            f.seek([size - tail.bytesize, 0].max)
+            f.read.to_s.b
+          end
+          raise Error.new(:diff_listing_invalid) unless size >= tail.bytesize && found == tail
+
+          File.truncate(local, size - tail.bytesize)
+        end
+
+        def remove_tmp(dir)
+          "rm -rf #{dir}/content-*.d; find #{dir} -maxdepth 1 -type f -delete; rmdir #{dir}/* #{dir} 2>/dev/null"
+        end
+
+        # index => content of the files in a tar archive of #contents, or
+        # :binary / :budget for a marker, TooLarge for a file that grew past
+        # the limit (the marker holds its size).
+        def read_tar(file)
+          File.open(file, "rb") do |io|
+            Gem::Package::TarReader.new(io).each_with_object({}) do |entry, by_index|
+              m = /\A(\d+)(?:\.(binary|budget|large))?\z/.match(File.basename(entry.full_name))
+              next unless entry.file? && m
+
+              data = (entry.read || "").b
+              by_index[m[1].to_i] = case m[2]
+                                    when nil then data
+                                    when "large" then TooLarge.new(data[/\d+/].to_i)
+                                    else m[2].to_sym
+                                    end
+            end
+          end
+        end
+
+        # sha256sum -z: "<hex>  <name>\0" per file, names as they are.
+        def parse_sums_z(data)
+          data.b.split("\0").each_with_object({}) do |entry, h|
+            hex = entry[0, 64]
+            next unless hex.match?(/\A\h{64}\z/) && entry[64] == " " && [" ", "*"].include?(entry[65])
+
+            h[entry[66..].to_s] = hex.downcase
+          end
+        end
+
+        # GNU sha256sum without -z: "<hex>  <name>"; a name with a backslash,
+        # newline or carriage return is escaped and the line starts with a
+        # backslash.
+        def parse_sums(data)
+          data.b.split("\n").each_with_object({}) do |line, h|
+            escaped = line.start_with?("\\")
+            line = line[1..] if escaped
+            hex = line[0, 64]
+            next unless hex.match?(/\A\h{64}\z/) && line[64] == " " && [" ", "*"].include?(line[65])
+
+            name = line[66..].to_s
+            name = name.gsub(/\\([\\nr])/) { { "\\" => "\\", "n" => "\n", "r" => "\r" }[Regexp.last_match(1)] } if escaped
+            h[name.b] = hex.downcase
+          end
+        end
+
+        # findmnt and lsblk -r escape unsafe characters as \xHH.
+        def unescape(field)
+          return nil if field.nil?
+
+          field.b.gsub(/\\x(\h{2})/) { Regexp.last_match(1).hex.chr }
+        end
+
+        def detail(err)
+          FileDiff.escape(err.to_s.strip[0, 300])
+        end
+
+        def safely
+          yield
+        rescue StandardError => e
+          @ctx.logger&.warn("vagrant xapi diff cleanup in the guest failed: #{e.message}")
+          nil
+        end
+      end
+    end
+  end
+end