Class: Pvectl::Commands::RestoreBackup

Inherits:
Object
  • Object
show all
Defined in:
lib/pvectl/commands/restore_backup.rb,
sig/pvectl/commands/restore_backup.rbs

Overview

Handler for the pvectl restore backup command.

Restores a backup identified by its full volume ID (volid) to a new or existing VM/container. Requires --vmid and --yes flags.

Examples:

Restore a backup to new VM

pvectl restore backup local:backup/vzdump-qemu-100-xxx.vma.zst --vmid 200 --yes

Restore with overwrite

pvectl restore backup local:backup/vzdump-qemu-100-xxx.vma.zst --vmid 100 --force --yes

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(resource_type, volid, options, global_options) ⇒ RestoreBackup

Initializes a restore backup command.

Parameters:

  • resource_type (String, nil) —

    resource type (backup)

  • volid (String, nil) —

    backup volume ID

  • options (Hash) —

    command options

  • global_options (Hash) —

    global CLI options



121
122
123
124
125
126
 
# File 'lib/pvectl/commands/restore_backup.rb', line 121

def initialize(resource_type, volid, options, global_options)
  @resource_type = resource_type
  @volid = volid
  @options = options
  @global_options = global_options
end

Class Method Details

.execute(resource_type, volid, options, global_options) ⇒ Integer

Executes the restore backup command.

Parameters:

  • resource_type (String, nil) —

    resource type (backup)

  • volid (String, nil) —

    backup volume ID

  • options (Hash) —

    command options

  • global_options (Hash) —

    global CLI options

Returns:

  • (Integer) —

    exit code



111
112
113
 
# File 'lib/pvectl/commands/restore_backup.rb', line 111

def self.execute(resource_type, volid, options, global_options)
  new(resource_type, volid, options, global_options).execute
end

.register(cli) ⇒ void

This method returns an undefined value.

Registers the restore command with the CLI.

Parameters:

  • cli (GLI::App) —

    the CLI application object



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/pvectl/commands/restore_backup.rb', line 22

def self.register(cli)
  cli.desc "Restore a resource from backup"
  cli.long_desc <<~HELP
    Restore a virtual machine or container from a backup (vzdump) volume.
    Creates a new or overwrites an existing VM/container with the backup data.

    EXAMPLES
      Restore to a new VMID:
        $ pvectl restore backup local:backup/vzdump-qemu-100-2026_01_01.vma.zst --vmid 200 --yes

      Restore to specific storage:
        $ pvectl restore backup local:backup/vzdump-qemu-100-2026_01_01.vma.zst --vmid 200 --storage local-lvm --yes

      Overwrite existing VM:
        $ pvectl restore backup local:backup/vzdump-qemu-100-2026_01_01.vma.zst --vmid 100 --force --yes

      Restore and start immediately:
        $ pvectl restore backup local:backup/vzdump-qemu-100-2026_01_01.vma.zst --vmid 200 --start --yes

      Regenerate unique properties (MAC, UUID):
        $ pvectl restore backup local:backup/vzdump-qemu-100-2026_01_01.vma.zst --vmid 200 --unique --yes

    NOTES
      --vmid is required to specify the target VM/container ID.

      --force overwrites an existing VM/container with the same VMID.
      Without it, restore fails if the VMID already exists.

      --unique regenerates MAC addresses and other unique properties,
      useful when restoring alongside the original VM.

      Use 'pvectl get backups' to find backup volume IDs.

    SEE ALSO
      pvectl help create backup   Create a new backup
      pvectl help get backups     List available backups
      pvectl help delete backup   Delete backup volumes
  HELP
  cli.arg_name "RESOURCE_TYPE VOLID"
  cli.command :restore do |c|
    c.desc "Target VMID (required)"
    c.flag [:vmid], arg_name: "VMID", type: Integer

    c.desc "Target storage"
    c.flag [:storage], arg_name: "STORAGE"

    c.desc "Overwrite existing VM/container"
    c.switch [:force], negatable: false

    c.desc "Start after restore"
    c.switch [:start], negatable: false

    c.desc "Regenerate unique properties (MAC, UUID)"
    c.switch [:unique], negatable: false

    c.desc "Skip confirmation prompt (REQUIRED)"
    c.switch [:yes, :y], negatable: false

    c.desc "Timeout in seconds"
    c.flag [:timeout], type: Integer, arg_name: "SECONDS"

    c.desc "Force async mode"
    c.switch [:async], negatable: false

    c.action do |global_options, options, args|
      resource_type = args.shift
      volid = args.first

      exit_code = case resource_type
      when "backup"
        Commands::RestoreBackup.execute(resource_type, volid, options, global_options)
      else
        $stderr.puts "Error: Unknown resource type: #{resource_type}"
        $stderr.puts "Valid types: backup"
        ExitCodes::USAGE_ERROR
      end

      exit exit_code if exit_code != 0
    end
  end
end

Instance Method Details

#determine_exit_code(results) ⇒ Integer

Determines exit code based on results.

Parameters:

Returns:

  • (Integer) —

    exit code



219
220
221
222
223
224
 
# File 'lib/pvectl/commands/restore_backup.rb', line 219

def determine_exit_code(results)
  return ExitCodes::SUCCESS if results.all?(&:successful?)
  return ExitCodes::SUCCESS if results.all?(&:pending?)

  ExitCodes::GENERAL_ERROR
end

#execute ⇒ Integer

Executes the restore backup command.

Returns:

  • (Integer) —

    exit code



131
132
133
134
135
136
137
138
 
# File 'lib/pvectl/commands/restore_backup.rb', line 131

def execute
  return usage_error("Resource type required (backup)") unless @resource_type == "backup"
  return usage_error("Backup volid is required") if @volid.nil? || @volid.empty?
  return usage_error("--vmid is required") unless @options[:vmid]
  return usage_error("Confirmation required: use --yes to confirm restore") unless @options[:yes]

  perform_operation
end

#load_config ⇒ void

This method returns an undefined value.

Loads configuration from file or environment.



185
186
187
188
189
 
# File 'lib/pvectl/commands/restore_backup.rb', line 185

def load_config
  service = Pvectl::Config::Service.new
  service.load(config: @global_options[:config])
  @config = service.current_config
end

#output_results(results) ⇒ void

This method returns an undefined value.

Outputs operation results using the configured formatter.

Parameters:



205
206
207
208
209
210
211
212
213
 
# File 'lib/pvectl/commands/restore_backup.rb', line 205

def output_results(results)
  presenter = Pvectl::Presenters::SnapshotOperationResult.new
  format = @global_options[:output] || "table"
  color_flag = @global_options[:color]

  formatter = Pvectl::Formatters::Registry.for(format)
  output = formatter.format(results, presenter, color: color_flag)
  puts output
end

#perform_operation ⇒ Integer

Performs the backup restore operation.

Returns:

  • (Integer) —

    exit code



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/pvectl/commands/restore_backup.rb', line 145

def perform_operation
  load_config
  connection = Pvectl::Connection.new(@config)

  backup_repo = Pvectl::Repositories::Backup.new(connection)
  resolver = Pvectl::Utils::ResourceResolver.new(connection)
  task_repo = Pvectl::Repositories::Task.new(connection)

  service = Pvectl::Services::Backup.new(
    backup_repo: backup_repo,
    resource_resolver: resolver,
    task_repo: task_repo,
    options: service_options
  )

  result = service.restore(
    @volid,
    vmid: @options[:vmid],
    storage: @options[:storage],
    force: @options[:force] || false,
    start: @options[:start] || false,
    unique: @options[:unique] || false
  )

  output_results([result])
  determine_exit_code([result])
rescue Pvectl::Config::ConfigNotFoundError,
       Pvectl::Config::InvalidConfigError,
       Pvectl::Config::ContextNotFoundError,
       Pvectl::Config::ClusterNotFoundError,
       Pvectl::Config::UserNotFoundError
  raise
rescue StandardError => e
  $stderr.puts "Error: #{e.message}"
  ExitCodes::GENERAL_ERROR
end

#service_options ⇒ Hash

Builds service options from command options.

Returns:

  • (Hash) —

    service options



194
195
196
197
198
199
 
# File 'lib/pvectl/commands/restore_backup.rb', line 194

def service_options
  opts = {}
  opts[:timeout] = @options[:timeout] if @options[:timeout]
  opts[:async] = true if @options[:async]
  opts
end

#usage_error(message) ⇒ Integer

Outputs usage error and returns exit code.

Parameters:

  • message (String) —

    error message

Returns:

  • (Integer) —

    exit code



230
231
232
233
 
# File 'lib/pvectl/commands/restore_backup.rb', line 230

def usage_error(message)
  $stderr.puts "Error: #{message}"
  ExitCodes::USAGE_ERROR
end