kamal-backup 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0b99d8270f625d97d1880cb3301d81aae8bcf201f77960a49fc84de7ade4667
-  data.tar.gz: d00ea2f74dd7b1060ea49c338841e10deb4cfaab2215e1ab4e553a74f211cdae
+  metadata.gz: a381b9f627864fc652f6d23b5109d5a670d0a4808f075d0d129fa2292da0eac3
+  data.tar.gz: aedbd53cb4486c1b2cc440e7825129d4823c948e1d8fc387b9742f3179363a80
 SHA512:
-  metadata.gz: a41f4e714f147d3216e90f96b7b66b7082f9b9914adbfef56abbb6177ddc8931375904a9d43610fba302a0fa5b70f3565411a898786259e55ef66f5fddb4d8f2
-  data.tar.gz: 46eeba2ce40db29124c149eeb632b59ef48462bbc5fa27c6d660e3636fc703aebb4c67edac775d6f7ad17c9cd443ede06884aaaeee614398f21918f2c0b4005c
+  metadata.gz: ca9c294db8d9d5445ca395f80d23d7cfa2d9eaaf26ab28e628f5ee264ef268758e7c03d504eea2cb98e54c72e3ba0f3cd999ececfe3c0475bbd434327f8244b5
+  data.tar.gz: 05b9046e125145ce936ab33812046aff5a69cc7286bafb355c12d323f91615b948689e6db11ec365e41457addceab11aeff1aaf38b99898793d1e743a6900d44

data/README.md

@@ -114,6 +114,7 @@ Run the first backup, check the repository, and print evidence. From an app chec
 ```sh
 bundle exec kamal-backup backup
 bundle exec kamal-backup list
+bundle exec kamal-backup dump latest -o tmp/app.pgdump
 bundle exec kamal-backup check
 bundle exec kamal-backup unlock
 bundle exec kamal-backup evidence
@@ -144,13 +145,13 @@ Start here:
 
 ## Releasing
 
-Run the release helper from a clean `master` checkout:
+Commit hand-written release notes as `packaging/release-notes/vX.Y.Z.md`, then run the release helper from a clean `master` checkout:
 
 ```sh
 bin/release 1.0.1
 ```
 
-It updates `lib/kamal_backup/version.rb`, syncs `Gemfile.lock`, commits the release, and pushes `master`. CI runs the test suite and docs build, publishes the RubyGem and Docker image tags, then creates the version tag, GitHub release, and docs deployment from the release commit.
+It updates `lib/kamal_backup/version.rb`, syncs `Gemfile.lock`, commits the release, and pushes `master`. CI runs the test suite and docs build, publishes the RubyGem and Docker image tags, then creates the version tag, GitHub release, and docs deployment from the release commit. The GitHub release uses the committed notes, and CI stops before publishing anything when they are missing.
 
 Add `--no-push` to prepare the release commit locally without publishing.
 

data/lib/kamal_backup/app.rb

@@ -100,6 +100,84 @@ module KamalBackup
       end
     end
 
+    def locate_database_dump(snapshot: 'latest', database_name: nil, validate_credentials: true)
+      if validate_credentials
+        config.validate_restic
+      else
+        config.required_app_name
+        unless config.restic_repository || config.restic_repository_file
+          raise ConfigurationError,
+                'RESTIC_REPOSITORY or RESTIC_REPOSITORY_FILE is required to dump from the backup accessory'
+        end
+      end
+
+      # Dump reads a stored snapshot. It needs the selected database's name and
+      # adapter, not live connection secrets or the current SQLite file.
+      raise ConfigurationError, 'databases must contain at least one database' if databases.empty?
+
+      adapter = select_database(database_name)
+      resolved_snapshot = resolve_snapshot(snapshot, tags: database_snapshot_tags(adapter))
+      database = database_config_name(adapter)
+      filename = restic.database_file(
+        resolved_snapshot,
+        adapter.adapter_name,
+        database_name: database
+      )
+      raise ConfigurationError, "could not find database backup file in snapshot #{resolved_snapshot}" unless filename
+
+      {
+        snapshot: resolved_snapshot,
+        database: database,
+        adapter: adapter.adapter_name,
+        filename: filename,
+        dump_extension: adapter.dump_extension
+      }
+    end
+
+    def dump_database(snapshot: 'latest', database_name: nil, output_path: nil, io: nil, overwrite: false)
+      located = locate_database_dump(snapshot: snapshot, database_name: database_name)
+
+      if output_path
+        expanded = require_dump_output_path!(output_path)
+        warn_dump_extension!(expanded, located.fetch(:dump_extension))
+        restic.write_dump_to_path(
+          located.fetch(:snapshot),
+          located.fetch(:filename),
+          expanded,
+          overwrite: overwrite
+        )
+        located.merge(output: expanded)
+      elsif io
+        restic.pipe_dump_to_io(located.fetch(:snapshot), located.fetch(:filename), io)
+        located.merge(output: 'io')
+      else
+        raise ConfigurationError, 'output path is required; pass -o PATH'
+      end
+    end
+
+    def require_dump_output_path!(output_path)
+      path = output_path.to_s.strip
+      raise ConfigurationError, 'output path is required; pass -o PATH' if path.empty?
+      raise ConfigurationError, 'output path must be a file, not a directory' if path.end_with?('/', '\\')
+
+      expanded = File.expand_path(path)
+      raise ConfigurationError, "output path must be a file, not a directory: #{expanded}" if File.directory?(expanded)
+
+      parent = File.dirname(expanded)
+      raise ConfigurationError, "output path directory does not exist: #{parent}" unless File.directory?(parent)
+
+      expanded
+    end
+
+    def warn_dump_extension!(output_path, expected_extension)
+      expected = ".#{expected_extension}"
+      actual = File.extname(output_path.to_s)
+      return if actual.casecmp?(expected)
+
+      actual_label = actual.empty? ? 'no extension' : actual.inspect
+      warn("warning: output path has #{actual_label}; expected #{expected.inspect} for this database dump")
+    end
+
     def snapshots
       config.validate_restic
       restic.snapshots.stdout
@@ -524,6 +602,22 @@ module KamalBackup
                      end
     end
 
+    def select_database(database_name)
+      names = databases.map { |adapter| database_config_name(adapter) }
+
+      unless database_name.to_s.strip.empty?
+        return databases.find { |adapter| database_config_name(adapter) == database_name } ||
+               raise(
+                 ConfigurationError,
+                 "database #{database_name.inspect} is not configured; configured names: #{names.join(', ')}"
+               )
+      end
+
+      return databases.first if databases.one?
+
+      raise ConfigurationError, "multiple databases configured (#{names.join(', ')}); pass --database NAME"
+    end
+
     def resolve_snapshot(argument, tags:)
       if argument == 'latest'
         snapshot = restic.latest_snapshot(tags: tags)
@@ -532,8 +626,67 @@ module KamalBackup
 
         snapshot['short_id'] || snapshot['id']
       else
-        argument
+        resolve_explicit_snapshot(argument, tags: tags)
       end
     end
+
+    # Each backup run writes one snapshot per database and then one file
+    # snapshot, each with its own ID. An explicit ID names one of them, so the
+    # other types come from the same run.
+    def resolve_explicit_snapshot(argument, tags:)
+      anchor = find_snapshot(argument)
+      snapshot = backup_run_for(anchor).find { |candidate| snapshot_tagged?(candidate, tags) }
+
+      unless snapshot
+        raise ConfigurationError,
+              "the backup containing snapshot #{argument} has no snapshot for #{tags.join(', ')}"
+      end
+
+      snapshot['short_id'] || snapshot['id']
+    end
+
+    def find_snapshot(argument)
+      matches = backup_snapshots.select do |snapshot|
+        snapshot['short_id'] == argument || snapshot['id'].to_s.start_with?(argument)
+      end
+
+      raise ConfigurationError, "no restic snapshot found for #{argument}" if matches.empty?
+      raise ConfigurationError, "snapshot ID #{argument} is ambiguous; use a longer ID" if matches.size > 1
+
+      matches.first
+    end
+
+    # Snapshots from one host, in time order, split into backup runs. A run
+    # ends after its file snapshot (always written last) or when a database
+    # snapshot group repeats, so a run that failed partway stays on its own.
+    def backup_run_for(anchor)
+      host_snapshots = backup_snapshots.select { |snapshot| snapshot['hostname'] == anchor['hostname'] }
+      runs = host_snapshots.sort_by { |snapshot| Time.parse(snapshot.fetch('time')) }.each_with_object([]) do |snapshot, grouped|
+        current = grouped.last
+        if current.nil? || current.any? { |other| run_boundary?(other, snapshot) }
+          grouped << [snapshot]
+        else
+          current << snapshot
+        end
+      end
+
+      runs.find { |run| run.include?(anchor) }
+    end
+
+    def run_boundary?(earlier, later)
+      snapshot_tagged?(earlier, ['type:files']) || snapshot_group(earlier) == snapshot_group(later)
+    end
+
+    def snapshot_group(snapshot)
+      Array(snapshot['tags']).select { |tag| tag.start_with?('type:', 'database:', 'adapter:') }.sort
+    end
+
+    def snapshot_tagged?(snapshot, tags)
+      (tags - Array(snapshot['tags'])).empty?
+    end
+
+    def backup_snapshots
+      @backup_snapshots ||= restic.snapshots_json
+    end
   end
 end

data/lib/kamal_backup/cli/helpers.rb

@@ -5,6 +5,7 @@ require 'json'
 require 'shellwords'
 require 'thor'
 require_relative '../app'
+require_relative '../private_tempfile'
 require_relative '../command_output'
 require_relative '../config'
 require_relative '../kamal_bridge'
@@ -111,6 +112,103 @@ module KamalBackup
         result
       end
 
+      def require_dump_output_path!(output_path)
+        path = output_path.to_s.strip
+        raise ConfigurationError, 'output path is required; pass -o PATH' if path.empty?
+        raise ConfigurationError, 'output path must be a file, not a directory' if path.end_with?('/', '\\')
+
+        expanded = File.expand_path(path)
+        raise ConfigurationError, "output path must be a file, not a directory: #{expanded}" if File.directory?(expanded)
+
+        parent = File.dirname(expanded)
+        raise ConfigurationError, "output path directory does not exist: #{parent}" unless File.directory?(parent)
+
+        expanded
+      end
+
+      def warn_dump_extension!(output_path, expected_extension)
+        expected = ".#{expected_extension}"
+        actual = File.extname(output_path.to_s)
+        return if actual.casecmp?(expected)
+
+        actual_label = actual.empty? ? 'no extension' : actual.inspect
+        warn("warning: output path has #{actual_label}; expected #{expected.inspect} for this database dump")
+      end
+
+      def dump_overwrite?(output_path)
+        return true if options[:yes]
+        return false unless File.exist?(output_path)
+
+        confirm!("Overwrite #{output_path}? This will replace the existing file.")
+        true
+      end
+
+      def dump_remote(snapshot, output_path:, overwrite:)
+        ensure_remote_version_match!
+        config = remote_dump_config
+        location = remote_restic_location(config)
+        located = remote_dump_app(config, location).locate_database_dump(
+          snapshot: snapshot,
+          database_name: options[:database],
+          validate_credentials: false
+        )
+        filename = located.fetch(:filename)
+        expanded = require_dump_output_path!(output_path)
+        warn_dump_extension!(expanded, located.fetch(:dump_extension))
+        temp = nil
+
+        begin
+          temp = PrivateTempfile.open(expanded)
+          bridge.stream_restic_dump(
+            accessory_name: accessory_name,
+            snapshot: located.fetch(:snapshot),
+            filename: filename,
+            io: temp,
+            **location
+          )
+          PrivateTempfile.publish(temp, expanded, overwrite: overwrite)
+          warn("wrote #{filename.sub(%r{\A/+}, '')} from snapshot #{located.fetch(:snapshot)} to #{expanded}")
+        ensure
+          PrivateTempfile.discard(temp)
+        end
+      end
+
+      def remote_dump_config
+        Config.new(
+          env: bridge.accessory_environment(accessory_name: accessory_name),
+          config_paths: [Config::SHARED_CONFIG_PATH],
+          load_project_defaults: false
+        )
+      end
+
+      def remote_restic_location(config)
+        if (repository = config.restic_repository)
+          { repository: repository }
+        elsif (repository_file = config.restic_repository_file)
+          { repository_file: repository_file }
+        else
+          raise ConfigurationError,
+                'RESTIC_REPOSITORY or RESTIC_REPOSITORY_FILE is required to dump from the backup accessory'
+        end
+      end
+
+      def remote_dump_app(config, location)
+        runner = lambda do |args, **|
+          stdout = bridge.capture_restic_command(
+            accessory_name: accessory_name,
+            argv: args,
+            **location
+          )
+          CommandResult.new(stdout: stdout, stderr: '', status: 0)
+        end
+
+        App.new(
+          config: config,
+          redactor: redactor,
+          restic: Restic.new(config, redactor: redactor, runner: runner)
+        )
+      end
+
       def ensure_remote_version_match!
         return if remote_version == VERSION
 

data/lib/kamal_backup/cli.rb

@@ -130,6 +130,7 @@ module KamalBackup
 
     package_name 'kamal-backup'
     map %w[-v --version] => :version
+    stop_on_unknown_option! :run_restic
     class_option :config_file, aliases: '-c', type: :string, desc: 'Path to Kamal deploy config file'
     class_option :destination, aliases: '-d', type: :string, desc: 'Kamal destination to use'
     remove_command :tree
@@ -182,6 +183,39 @@ module KamalBackup
       end
     end
 
+    method_option :output, aliases: '-o', type: :string,
+                           desc: 'Write the dump to this path (required; parent directory must exist)'
+    method_option :database, type: :string,
+                             desc: 'Name from config/kamal-backup.yml when multiple databases are configured'
+    method_option :yes, aliases: '-y', type: :boolean, default: false,
+                        desc: 'Replace the output file if it exists, including one created while the dump downloads'
+    desc 'dump [SNAPSHOT]', 'Download a database dump to a file (not file or Active Storage backups)'
+    def dump(snapshot = 'latest')
+      output_path = require_dump_output_path!(options[:output])
+      overwrite = dump_overwrite?(output_path)
+
+      if remote_command_mode?
+        dump_remote(snapshot, output_path: output_path, overwrite: overwrite)
+      else
+        result = direct_app.dump_database(
+          snapshot: snapshot,
+          database_name: options[:database],
+          output_path: output_path,
+          overwrite: overwrite
+        )
+        warn("wrote #{result[:filename]} from snapshot #{result[:snapshot]} to #{result[:output]}")
+      end
+    end
+
+    desc 'run-restic ARGS...', 'Run restic with the loaded backup configuration', hide: true
+    def run_restic(*args)
+      raise ConfigurationError, 'restic arguments are required' if args.empty?
+
+      config = Config.new(env: command_env)
+      config.validate_restic
+      exec(Restic.environment_for(config), 'restic', *args)
+    end
+
     desc 'check', 'Run restic check and record the latest result'
     def check
       if remote_command_mode?

data/lib/kamal_backup/databases/sqlite.rb

@@ -71,7 +71,7 @@ module KamalBackup
       def restore_database(restic, snapshot, filename, target:)
         Tempfile.create(['kamal-backup-restore-', '.sqlite3']) do |tempfile|
           tempfile.close
-          restic.write_dump_to_path(snapshot, filename, tempfile.path)
+          restic.write_dump_to_path(snapshot, filename, tempfile.path, overwrite: true)
           validate_database_file(tempfile.path)
           FileUtils.mkdir_p(File.dirname(File.expand_path(target)))
           Command.capture(

data/lib/kamal_backup/kamal_bridge.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require 'open3'
 require 'shellwords'
+require 'tempfile'
 require 'yaml'
 require_relative 'command'
 require_relative 'yaml_access'
@@ -11,6 +13,9 @@ module KamalBackup
 
     DEFAULT_CONFIG_FILE = 'config/deploy.yml'
     VERSION_LINE_PATTERN = /\A\d+(?:\.\d+)+(?:[-.][A-Za-z0-9]+)*\z/
+    # Query keys such as auth are credentials even when the URL pattern does not
+    # name them. A diagnostic that prints only the value still has to be redacted.
+    CREDENTIAL_KEY_PATTERN = /(?:pass|password|secret|token|key|credential|authorization)|(?:\A|_)(?:auth|pwd)(?:\z|_)/i
 
     class FilteringIO
       def initialize(io, &reject)
@@ -84,6 +89,38 @@ module KamalBackup
       end
     end
 
+    # Run restic on the live accessory over SSH + docker exec without Kamal's
+    # log wrapper. Kamal accessory exec mixes INFO lines into stdout.
+    def capture_restic_command(accessory_name:, argv:, repository: nil, repository_file: nil)
+      stdout = +''
+      run_restic_on_accessory(
+        accessory_name: accessory_name,
+        repository: repository,
+        repository_file: repository_file,
+        argv: argv
+      ) do |stream|
+        stdout << stream.read
+      end
+      stdout
+    end
+
+    # Stream a restic dump over SSH + docker exec without Kamal's log wrapper.
+    # Kamal accessory exec mixes INFO lines into stdout, which corrupts binary dumps.
+    def stream_restic_dump(accessory_name:, snapshot:, filename:, io:, repository: nil, repository_file: nil)
+      run_restic_on_accessory(
+        accessory_name: accessory_name,
+        repository: repository,
+        repository_file: repository_file,
+        argv: ['dump', snapshot.to_s, filename.to_s],
+        snapshot: snapshot,
+        filename: filename
+      ) do |stdout|
+        IO.copy_stream(stdout, io)
+      end
+
+      true
+    end
+
     def remote_version(accessory_name:)
       result = execute_on_accessory(accessory_name: accessory_name, command: %w[kamal-backup version])
       version = parse_version_line(result.stdout)
@@ -95,12 +132,388 @@ module KamalBackup
 
     private
 
-    def config
-      @config ||= begin
-        result = capture_kamal(kamal_config_argv)
-        load_method = YAML.respond_to?(:unsafe_load) ? :unsafe_load : :load
-        YAML.public_send(load_method, result.stdout)
+    def run_restic_on_accessory(accessory_name:, argv:, snapshot: nil, filename: nil, repository: nil,
+                                repository_file: nil)
+      config
+      target = live_accessory_target(accessory_name)
+      unless target
+        raise ConfigurationError,
+              "could not find a live backup accessory #{accessory_name.inspect} to dump from"
+      end
+
+      docker_argv = accessory_restic_docker_argv(
+        target.fetch(:service_name),
+        argv,
+        repository: repository,
+        repository_file: repository_file
+      )
+      remote = docker_argv.shelljoin
+
+      with_ssh_identity_files do |identity_files, config_file|
+        spec = CommandSpec.new(
+          argv: ssh_argv(target.fetch(:host), remote, identity_files: identity_files, config_file: config_file)
+        )
+        Open3.popen3(*spec.argv) do |stdin, stdout, stderr, wait_thread|
+          stdin.close
+          err_reader = Thread.new { stderr.read }
+          yield stdout
+          err = err_reader.value
+          status = wait_thread.value
+          unless status.success?
+            raise_restic_accessory_error(
+              spec,
+              status.exitstatus,
+              err,
+              snapshot: snapshot,
+              filename: filename,
+              docker_argv: docker_argv,
+              redactor: diagnostic_redactor(repository)
+            )
+          end
+        end
+      end
+    end
+
+    # The accessory command loads config/kamal-backup.yml itself. Repository URLs,
+    # repository files, password files, and password commands stay in that process
+    # and are not repeated on the SSH command line.
+    def accessory_restic_docker_argv(service_name, argv, repository:, repository_file:)
+      command = ['docker', 'exec', service_name, 'kamal-backup', 'run-restic', '--', *Array(argv).map(&:to_s)]
+      forbidden = [repository, repository_file].compact.map(&:to_s).reject(&:empty?)
+      leaked = forbidden.intersect?(command) || command.any? { |arg| arg.include?('RESTIC_REPOSITORY') }
+      raise ConfigurationError, 'refusing to place repository settings on the accessory command' if leaked
+
+      command
+    end
+
+    def raise_restic_accessory_error(spec, status, stderr, snapshot:, filename:, docker_argv: nil, redactor: nil)
+      reporter = redactor || @redactor
+      redacted = reporter.redact_string(stderr.to_s)
+      dump_context = snapshot && filename
+      message =
+        if dump_context && stderr.to_s.match?(/no matching ID found|failed to find snapshot|no snapshot found/i)
+          "backup not found for snapshot #{snapshot.inspect}"
+        elsif dump_context && missing_requested_dump_file?(stderr, filename)
+          "backup file #{filename.inspect} not found in snapshot #{snapshot.inspect}"
+        else
+          "command failed (#{status}): #{redacted_restic_command(spec, docker_argv, reporter)}\n#{redacted}"
+        end
+
+      raise CommandError.new(
+        message,
+        command: spec,
+        status: status,
+        stderr: redacted
+      )
+    end
+
+    # A missing password file or repository file also says "no such file". Only
+    # the requested dump path is a missing backup.
+    def missing_requested_dump_file?(stderr, filename)
+      text = stderr.to_s
+      return false unless text.match?(/not found|does not exist|no such file/i)
+
+      [filename.to_s, filename.to_s.sub(%r{\A/+}, '')].uniq.reject(&:empty?).any? do |path|
+        text.include?(path)
+      end
+    end
+
+    # Shell-escaping hides query credentials from a later redactor pass.
+    # Redact each argument first, then escape that copy.
+    def redacted_restic_command(spec, docker_argv, redactor)
+      return spec.display(redactor) unless docker_argv
+
+      prefix = spec.argv[0..-2].map { |arg| redactor.redact_string(arg) }.shelljoin
+      remote = docker_argv.map { |arg| redactor.redact_string(arg) }.shelljoin
+      "#{prefix} #{remote}"
+    end
+
+    def diagnostic_redactor(repository)
+      @redactor.with_additional_secrets(configured_credential_values(repository))
+    end
+
+    def configured_credential_values(repository)
+      [repository, ssh_proxy_command(ssh_options[:proxy])].flat_map { |source| credential_values_in(source) }
+    end
+
+    def credential_values_in(source)
+      text = source.to_s
+      return [] if text.strip.empty?
+
+      url_credential_values(text) + option_credential_values(text)
+    end
+
+    def url_credential_values(text)
+      values = []
+      text.scan(%r{://[^/\s@:]+:([^/\s@]+)@}) { values << Regexp.last_match(1) }
+      text.scan(/[?&]([A-Za-z0-9][\w.-]*)=([^&#\s]+)/) do |key, value|
+        values << value if key.match?(CREDENTIAL_KEY_PATTERN)
+      end
+      values
+    end
+
+    # Shellwords removes quotes, so --token 'secret' and --token "secret" register
+    # the secret itself. A nested sh -c command is parsed again. A broken quote
+    # must not raise while an error is being reported.
+    def option_credential_values(text, depth: 0)
+      return [] if depth > 4 || text.strip.empty?
+
+      words = split_proxy_command(text)
+      values = []
+      words.each_with_index do |word, index|
+        values.concat(option_values_at(words, word, index))
+        values.concat(url_credential_values(word)) if word.match?(%r{://|[?&][\w.-]+=})
+        next if word == text || !word.match?(/--/) || !word.match?(/[\s'"]/)
+
+        values.concat(option_credential_values(word, depth: depth + 1))
       end
+      values
+    end
+
+    def option_values_at(words, word, index)
+      if (assignment = word.match(/\A--([A-Za-z0-9][\w-]*)=(.*)\z/m))
+        return [] unless assignment[1].match?(CREDENTIAL_KEY_PATTERN)
+
+        value = assignment[2]
+        return value.empty? ? [] : [value]
+      end
+
+      flag = word.match(/\A--([A-Za-z0-9][\w-]*)\z/)
+      return [] unless flag && flag[1].match?(CREDENTIAL_KEY_PATTERN)
+
+      value = words[index + 1]
+      return [] if value.nil? || value.empty? || value.start_with?('-')
+
+      [value]
+    end
+
+    def split_proxy_command(text)
+      Shellwords.split(text)
+    rescue ArgumentError
+      lenient_shell_split(text)
+    end
+
+    def lenient_shell_split(text)
+      words = []
+      word = +''
+      quoted = nil
+      started = false
+      index = 0
+      while index < text.length
+        char = text[index]
+        if quoted
+          if char == quoted
+            quoted = nil
+          elsif quoted == '"' && char == '\\' && index + 1 < text.length
+            index += 1
+            word << text[index]
+          else
+            word << char
+          end
+          started = true
+        elsif char == '\\' && index + 1 < text.length
+          index += 1
+          word << text[index]
+          started = true
+        elsif ["'", '"'].include?(char)
+          quoted = char
+          started = true
+        elsif char.match?(/\s/)
+          if started
+            words << word
+            word = +''
+            started = false
+          end
+        else
+          word << char
+          started = true
+        end
+        index += 1
+      end
+      words << word if started
+      words
+    end
+
+    # Match Kamal's SSH defaults: user root, port 22, plus ssh.user, port, proxy,
+    # keys, and config from the rendered deploy config. -T overrides RequestTTY
+    # force so a config file cannot translate dump bytes or merge stderr into stdout.
+    def ssh_argv(host, remote_command, identity_files:, config_file:)
+      options = ssh_options
+      argv = ['ssh', '-T', '-p', options.fetch(:port), '-l', options.fetch(:user)]
+      argv.concat(ssh_proxy_args(options[:proxy]))
+      Array(options[:keys]).each { |key| argv.concat(['-i', key]) }
+      identity_files.each { |path| argv.concat(['-i', path]) }
+      argv.concat(['-o', 'IdentitiesOnly=yes']) if options[:keys_only]
+      argv.concat(['-F', '/dev/null']) if options[:config] == false && config_file.nil?
+      argv.concat(['-F', config_file]) if config_file
+      case options[:forward_agent]
+      when true
+        argv.concat(['-o', 'ForwardAgent=yes'])
+      when false
+        argv.concat(['-o', 'ForwardAgent=no'])
+      end
+      argv << host
+      argv << remote_command
+      argv
+    end
+
+    def ssh_options
+      raw = fetch(config, :ssh_options) || {}
+      {
+        user: (ssh_config_value(raw, :user) || 'root').to_s,
+        port: (ssh_config_value(raw, :port) || 22).to_s,
+        proxy: ssh_config_value(raw, :proxy),
+        keys: Array(ssh_config_value(raw, :keys)).map { |key| File.expand_path(key.to_s) },
+        keys_only: ssh_config_value(raw, :keys_only),
+        config: ssh_config_value(raw, :config),
+        forward_agent: ssh_config_value(raw, :forward_agent),
+        key_data: Array(ssh_config_value(raw, :key_data)).map(&:to_s).reject(&:empty?)
+      }
+    end
+
+    def ssh_config_value(raw, key)
+      [key, key.to_s, key.to_sym].each do |candidate|
+        return raw[candidate] if raw.key?(candidate)
+      end
+      nil
+    end
+
+    def ssh_proxy_args(proxy)
+      return [] if proxy.nil? || proxy == false
+      return [] unless (jump = ssh_jump_target(proxy))
+
+      jump = "root@#{jump}" unless jump.include?('@') || jump.include?(',')
+      ['-J', jump]
+    end
+
+    def ssh_jump_target(proxy)
+      raw = if proxy.is_a?(String)
+              proxy
+            elsif proxy.respond_to?(:jump_proxies)
+              proxy.jump_proxies
+            elsif proxy.is_a?(Hash)
+              fetch(proxy, :jump_proxies)
+            end
+      value = raw.to_s.strip
+      return if value.empty? || value.include?(' ')
+
+      value
+    end
+
+    def ssh_proxy_command(proxy)
+      raw = if proxy.is_a?(String)
+              proxy
+            elsif proxy.respond_to?(:command_line_template) && !proxy.respond_to?(:jump_proxies)
+              proxy.command_line_template
+            elsif proxy.is_a?(Hash)
+              fetch(proxy, :command_line_template) || fetch(proxy, :command)
+            end
+      value = raw.to_s.strip
+      return if value.empty?
+
+      value
+    end
+
+    def with_ssh_identity_files
+      identity_files = []
+      config_file = ssh_config_file
+      ssh_options.fetch(:key_data).each do |data|
+        file = Tempfile.new(['kamal-backup-ssh-', '.key'])
+        file.chmod(0o600)
+        file.write(data)
+        file.close
+        identity_files << file
+      end
+      yield identity_files.map(&:path), config_file&.path
+    ensure
+      (Array(identity_files) + [config_file]).compact.each do |file|
+        file.close! if file.respond_to?(:close!)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def ssh_config_file
+      lines = []
+      # First value wins. Keep ProxyCommand ahead of Include so a credential in
+      # the deploy config is not replaced by a later file, and so it never
+      # appears in the ssh process arguments.
+      if (command = ssh_proxy_directive)
+        raise ConfigurationError, 'SSH proxy command cannot contain a newline' if command.match?(/[\r\n]/)
+
+        lines << "ProxyCommand #{command}"
+      end
+      lines.concat(ssh_config_include_lines)
+      return if lines.empty?
+
+      file = Tempfile.new(['kamal-backup-ssh-config-', '.conf'])
+      file.chmod(0o600)
+      file.write("#{lines.join("\n")}\n")
+      file.close
+      file
+    end
+
+    def ssh_proxy_directive
+      proxy = ssh_options[:proxy]
+      return if proxy.nil? || proxy == false
+      return if ssh_jump_target(proxy)
+
+      ssh_proxy_command(proxy)
+    end
+
+    def ssh_config_include_lines
+      paths = explicit_ssh_config_paths
+      # -F hides the files OpenSSH would read on its own. Put them back when the
+      # deploy config left ssh.config on and the only reason for -F is the proxy.
+      paths = default_ssh_config_paths if paths.empty? && ssh_options[:config] != false && ssh_proxy_directive
+
+      paths.map { |path| File.expand_path(path) }.reject(&:empty?).map do |path|
+        %(Include "#{path.gsub(/["\\]/) { |char| "\\#{char}" }}")
+      end
+    end
+
+    def explicit_ssh_config_paths
+      case ssh_options[:config]
+      when String
+        [ssh_options[:config]]
+      when Array
+        ssh_options[:config].map(&:to_s)
+      else
+        []
+      end
+    end
+
+    def default_ssh_config_paths
+      home = ENV.fetch('HOME', '').to_s
+      candidates = []
+      candidates << File.join(home, '.ssh', 'config') unless home.empty?
+      candidates << '/etc/ssh/ssh_config'
+      candidates << '/etc/ssh_config'
+      candidates.select { |path| File.file?(path) }
+    end
+
+    def config
+      @config ||= load_kamal_config(capture_kamal(kamal_config_argv).stdout)
+    end
+
+    # kamal config renders ssh.proxy and ssh.proxy_command as Net::SSH::Proxy
+    # objects. kamal-backup does not load net-ssh, so read any object whose
+    # class is not loaded as a Hash of its instance variables.
+    def load_kamal_config(yaml)
+      document = Psych.parse_stream(yaml).children.first
+      return false unless document
+
+      document.each { |node| node.tag = nil if unloaded_ruby_object?(node) }
+      document.to_ruby
+    end
+
+    def unloaded_ruby_object?(node)
+      return false unless node.is_a?(Psych::Nodes::Mapping) && node.tag&.start_with?('!ruby/object:')
+
+      Object.const_get(node.tag.delete_prefix('!ruby/object:'))
+      false
+    rescue NameError
+      true
     end
 
     def accessories
@@ -296,8 +709,6 @@ module KamalBackup
     end
 
     def live_accessory_target(accessory_name)
-      return unless defined?(@config)
-
       accessory_config = accessory(accessory_name)
       host = single_accessory_host(accessory_config)
       service_name = fetch(accessory_config, :service) || default_accessory_service_name(accessory_name)

data/lib/kamal_backup/private_tempfile.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+require_relative 'errors'
+
+module KamalBackup
+  # Same-directory dump output that is created exclusively and kept owner-only.
+  # A predictable path opened with truncation follows a pre-created symlink and
+  # inherits the process umask.
+  class PrivateTempfile
+    MODE = 0o600
+    UNSUPPORTED_LINK_ERRORS = [Errno::EPERM, Errno::ENOTSUP, Errno::EOPNOTSUPP, Errno::EXDEV].uniq.freeze
+
+    def self.open(target_path)
+      directory = File.dirname(target_path)
+      file = Tempfile.create(
+        ["#{File.basename(target_path)}.kamal-backup-", '.tmp'],
+        directory,
+        mode: File::BINARY
+      )
+      file.chmod(MODE)
+      file
+    end
+
+    # File.rename always replaces the destination. Without overwrite authorization,
+    # File.link fails with EEXIST if that name already exists, including a file
+    # created after the earlier confirmation check.
+    def self.publish(file, target_path, overwrite:)
+      file.flush
+      file.close
+      if overwrite
+        File.rename(file.path, target_path)
+      else
+        link_exclusively(file.path, target_path)
+      end
+    end
+
+    def self.discard(file)
+      return unless file
+
+      file.close unless file.closed?
+      FileUtils.rm_f(file.path) if file.path
+    end
+
+    def self.link_exclusively(source, target_path)
+      File.link(source, target_path)
+      File.unlink(source)
+    rescue Errno::EEXIST
+      raise ConfigurationError, "output file already exists: #{target_path}; pass --yes to overwrite"
+    rescue *UNSUPPORTED_LINK_ERRORS
+      copy_exclusively(source, target_path)
+    end
+
+    # Exclusive create still refuses a name that appeared during the download.
+    # A failed or interrupted copy removes that new file so a partial dump is not
+    # left behind. copied is set only after the file closes, so a close error is
+    # cleaned up too. Interrupt is not a StandardError, so this uses ensure.
+    def self.copy_exclusively(source, target_path)
+      created = false
+      copied = false
+      File.open(target_path, File::WRONLY | File::CREAT | File::EXCL | File::BINARY, MODE) do |out|
+        created = true
+        out.chmod(MODE)
+        File.open(source, File::RDONLY | File::BINARY) { |input| IO.copy_stream(input, out) }
+      end
+      copied = true
+      File.unlink(source)
+    rescue Errno::EEXIST
+      raise ConfigurationError, "output file already exists: #{target_path}; pass --yes to overwrite"
+    ensure
+      remove_partial_copy(target_path) if created && !copied
+    end
+
+    def self.remove_partial_copy(path)
+      File.unlink(path)
+    rescue Errno::ENOENT
+      nil
+    end
+    private_class_method :link_exclusively, :copy_exclusively, :remove_partial_copy
+  end
+end

data/lib/kamal_backup/redactor.rb

@@ -32,6 +32,10 @@ module KamalBackup
       redacted
     end
 
+    def with_additional_secrets(values)
+      self.class.new(secret_values: @secret_values + Array(values), env: @env)
+    end
+
     private
 
     def known_secret_values
@@ -40,7 +44,8 @@ module KamalBackup
           values << value.to_s if key.to_s.match?(SECRET_KEY_PATTERN)
         end
 
-        (@secret_values + env_secrets).compact.uniq.reject { |value| value.empty? || value.length < 4 }
+        secrets = (@secret_values + env_secrets).compact.uniq
+        secrets.reject { |value| value.empty? || value.length < 4 }.sort_by { |value| -value.length }
       end
     end
 

data/lib/kamal_backup/restic.rb

@@ -6,6 +6,7 @@ require 'json'
 require 'open3'
 require 'time'
 require_relative 'command'
+require_relative 'private_tempfile'
 
 module KamalBackup
   class Restic
@@ -13,9 +14,10 @@ module KamalBackup
 
     attr_reader :config, :redactor
 
-    def initialize(config, redactor:)
+    def initialize(config, redactor:, runner: nil)
       @config = config
       @redactor = redactor
+      @runner = runner
     end
 
     def ensure_repository
@@ -173,34 +175,57 @@ module KamalBackup
       pipe_commands(restic_command, command, producer_label: 'restic dump', consumer_label: command.argv.first)
     end
 
-    def write_dump_to_path(snapshot, filename, target_path)
+    def write_dump_to_path(snapshot, filename, target_path, overwrite: false)
       command = CommandSpec.new(argv: ['restic', 'dump', snapshot, filename], env: restic_env)
       target_path = File.expand_path(target_path)
-      FileUtils.mkdir_p(File.dirname(target_path))
-      temp_path = "#{target_path}.kamal-backup-#{$PROCESS_ID}.tmp"
+      raise ConfigurationError, "output path must be a file, not a directory: #{target_path}" if File.directory?(target_path)
 
+      parent = File.dirname(target_path)
+      raise ConfigurationError, "output path directory does not exist: #{parent}" unless File.directory?(parent)
+
+      temp = nil
       output = Command.output
       context = output&.command_start(command, redactor: redactor)
+      temp = PrivateTempfile.open(target_path)
       Open3.popen3(command.env, *command.argv) do |stdin, stdout, stderr, wait_thread|
         stdin.close
         stderr_reader = Thread.new do
           Command.collect_stream(stderr, command_output: output, context: context, stream: :stderr, redactor: redactor)
         end
-        File.open(temp_path, 'wb') { |file| IO.copy_stream(stdout, file) }
+        IO.copy_stream(stdout, temp)
         err = stderr_reader.value
         status = wait_thread.value
         output&.command_exit(context, status.exitstatus)
         raise_command_error(command, status, '', err) unless status.success?
       end
-      File.rename(temp_path, target_path)
+      PrivateTempfile.publish(temp, target_path, overwrite: overwrite)
       target_path
     rescue Errno::ENOENT => e
-      FileUtils.rm_f(temp_path) if temp_path
       raise CommandError.new("command not found: #{command.argv.first}", command: command, status: 127,
                                                                          stderr: e.message)
-    rescue StandardError
-      FileUtils.rm_f(temp_path) if temp_path
-      raise
+    ensure
+      PrivateTempfile.discard(temp)
+    end
+
+    def pipe_dump_to_io(snapshot, filename, io)
+      command = CommandSpec.new(argv: ['restic', 'dump', snapshot, filename], env: restic_env)
+      output = Command.output
+      context = output&.command_start(command, redactor: redactor)
+      Open3.popen3(command.env, *command.argv) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+        stderr_reader = Thread.new do
+          Command.collect_stream(stderr, command_output: output, context: context, stream: :stderr, redactor: redactor)
+        end
+        IO.copy_stream(stdout, io)
+        err = stderr_reader.value
+        status = wait_thread.value
+        output&.command_exit(context, status.exitstatus)
+        raise_command_error(command, status, '', err) unless status.success?
+      end
+      true
+    rescue Errno::ENOENT => e
+      raise CommandError.new("command not found: #{command.argv.first}", command: command, status: 127,
+                                                                         stderr: e.message)
     end
 
     def restore_snapshot(snapshot, target)
@@ -208,9 +233,17 @@ module KamalBackup
       run(['restore', snapshot, '--target', target])
     end
 
+    def self.environment_for(config)
+      config.env.each_with_object({}) do |(key, value), env|
+        env[key] = value if key.to_s.match?(RESTIC_ENV_PATTERN)
+      end
+    end
+
     private
 
     def run(args, log_output: true, env: restic_env)
+      return @runner.call(args, log_output: log_output, env: env) if @runner
+
       Command.capture(
         CommandSpec.new(argv: ['restic'] + args, env: env),
         redactor: redactor,
@@ -284,9 +317,7 @@ module KamalBackup
     end
 
     def restic_env
-      config.env.each_with_object({}) do |(key, value), env|
-        env[key] = value if key.to_s.match?(RESTIC_ENV_PATTERN)
-      end
+      self.class.environment_for(config)
     end
 
     def pipe_commands(producer, consumer, producer_label:, consumer_label:)

data/lib/kamal_backup/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KamalBackup
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/lib/kamal_backup.rb

@@ -6,6 +6,7 @@ require_relative 'kamal_backup/errors'
 require_relative 'kamal_backup/yaml_access'
 require_relative 'kamal_backup/command'
 require_relative 'kamal_backup/command_output'
+require_relative 'kamal_backup/private_tempfile'
 require_relative 'kamal_backup/redactor'
 require_relative 'kamal_backup/config_file'
 require_relative 'kamal_backup/config'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kamal-backup
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - crmne
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -134,6 +134,7 @@ files:
 - lib/kamal_backup/errors.rb
 - lib/kamal_backup/evidence.rb
 - lib/kamal_backup/kamal_bridge.rb
+- lib/kamal_backup/private_tempfile.rb
 - lib/kamal_backup/rails_app.rb
 - lib/kamal_backup/redactor.rb
 - lib/kamal_backup/restic.rb