gnt-backup(8)

📦
version 3.1.0~rc2 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute

💖 gnt-backup(8) 💖

okay bestie, welcome to the gnt-backup page — this is part of the Ganeti manual, section 8 (admin commands, the big-girl stuff), and it's sitting at Version 3.1.0~rc2. Grab a snack, we're going through it together. 🍓

✨ NAME ✨

gnt-backup — Ganeti instance import/export. that's the whole vibe. you're moving instances in and out. 💅

🦋 SYNOPSIS 🦋

gnt-backup {command} [arguments...]

like, you pick a command, you hand it some arguments, it does the thing. that's it, that's the shape of it. ✨

🌸 DESCRIPTION 🌸

So gnt-backup is the tool for importing and exporting instances and all their configuration from a Ganeti system. Two main-character uses, no cap:

  • backing up instances (obviously 💖)
  • migrating them between clusters

it's giving "portable little instance in a box". iconic. 👑

💫 COMMANDS 💫

🎀 EXPORT 🎀

export {-n node-name}
[--shutdown-timeout=N] [--noshutdown] [--remove-instance]
[--ignore-remove-failures] [--submit] [--print-jobid]
[--transport-compression=compression-mode]
[--zero-free-space] [--zeroing-timeout-fixed]
[--zeroing-timeout-per-mib] [--long-sleep]
{instance-name}

Exports an instance to the target node. All the instance data and its configuration get exported under the /var/lib/ganeti/export/$instance directory on the target node. yes, literally that path, $instance and all. 🫶

  • --transport-compression — tells us which compression mode to use to try and speed up moves during the export. Valid values are none, plus any values defined in the compression_tools cluster parameter.
  • --shutdown-timeout — how long (in seconds) to wait before forcing the shutdown (xl destroy in xen, killing the kvm process, for kvm). by default every instance gets two minutes to stop, so be nice.
  • --noshutdown — makes a snapshot disk of the instance without shutting it down first. faster, zero downtime, slay… but it cannot be guaranteed that the instance data will be in a consistent state in the exported dump. so like, fast and risky, choose your fighter. 😭
  • --remove — removes the instance after it was exported. genuinely useful for making one last backup right before you delete the instance forever. rip little guy 🥀
  • --zero-free-space — zeroes the free space of the instance before exporting it, which saves space if compression is used. and then --zeroing-timeout-fixed and --zeroing-timeout-per-mib control the timeout: the first one sets the minimum time to wait, the second one sets how much longer to wait per MiB of data the instance has. math but make it storage. 🧚
  • --long-sleep — lets Ganeti keep the instance shut down for the entire duration of the export if necessary. you need this when snapshots aren't supported by the underlying storage type, or when creating snapshots fails for some reason — e.g. lack of space.
⚠️ okay listen, this part matters: should the snapshotting or transfer of any of the instance disks fail, the backup will not complete, and any previous backups will be preserved. the exact details of the failures will be shown during the command execution (and will be stored in the job log). it is recommended that for any non-zero exit code, the backup is considered invalid, and retried. fr fr, don't gaslight yourself into thinking a failed backup is fine. 💀

See ganeti(7) for a description of --submit and other common options. 📚

Example:

# gnt-backup export -n node1.example.com instance3.example.com

🌈 IMPORT 🌈

import
{-n node[:secondary-node] | --iallocator name}
[--compress=compression-mode]
[--disk N:size=VAL [,vg=VG], [,mode=ro|rw]...]
[--net N [:options...]  | --no-nics]
[-B BEPARAMS]
[-H HYPERVISOR [: option=value...  ]]
[--src-node=source-node] [--src-dir=source-dir]
[-t [diskless | plain | drbd | file]]
[--identify-defaults]
[--ignore-ipolicy]
[--submit] [--print-jobid]
{instance-name}

Imports a new instance from an export residing on source-node in source-dir. instance-name must be in DNS and resolve to an IP in the same network as the nodes in the cluster. if you don't pass the source node and directory, the last backup in the cluster is used — the same one you can see with the list command. so convenient, honestly obsessed. ✨

💅 the --disk option

  • specifies the parameters for the disks of the instance.
  • disk numbering starts at zero. yes, zero. programmers, amirite.
  • for each disk you need at least the size, and optionally the access mode (read-only, or the default of read-write) and the LVM volume group can also be specified.
  • the size is interpreted (when no unit is given) in mebibytes.
  • you can also use one of the suffixes m, g or t to specify the exact units used; these suffixes map to mebibytes, gibibytes and tebibytes. 🎀

Alternatively, a single-disk instance can be created via the -s option, which takes a single argument: the size of the disk. this is similar to the Ganeti 1.2 version (but will only create one disk). nostalgic era. 🦋

If no disk information is passed, the disk configuration saved at export time will be used. easy.

So the minimum disk specification is therefore empty (export information will be used), a single disk can be specified as --disk 0:size=20G (or -s 20G when using the -s option), and a three-disk instance can be specified as --disk 0:size=20G --disk 1:size=4G --disk 2:size=100G. look at you, stacking disks like a legend. 🔥

🌸 the --net option

The NICs of the instances can be specified via the --net option. By default, the NIC configuration of the original (exported) instance will be reused. Each NIC can take up to three parameters — all optional:

  • mac — either a value, or generate to generate a new unique MAC, or auto to reuse the old MAC.
  • ip — specifies the IP address assigned to the instance from the Ganeti side (this is not necessarily what the instance will use, but what the node expects the instance to use).
  • mode — specifies the connection mode for this NIC: routed, bridged or openvswitch.
  • link — in bridged and openvswitch mode this specifies the interface to attach this NIC to; in routed mode it's intended to differentiate between different routing tables/instance groups (but the meaning is dependent on the network script in use, see gnt-cluster(8) for more details).

Of these, mode and link are NIC parameters, and inherit their default at cluster level. 🫶

If no network is desired for the instance, you should create a single empty NIC and delete it afterwards via gnt-instance modify --net delete. it's giving "ghost NIC". 👻

🧚 the -B option

The -B option specifies the backend parameters for the instance. If no such parameters are specified, the values are inherited from the export. possible parameters are:

  • maxmem — the maximum memory size of the instance; as usual, suffixes can be used to denote the unit, otherwise the value is taken in mebibytes.
  • minmem — the minimum memory size of the instance; as usual, suffixes can be used to denote the unit, otherwise the value is taken in mebibytes.
  • vcpus — the number of VCPUs to assign to the instance (if this value makes sense for the hypervisor).
  • auto_balance — whether the instance is considered in the N+1 cluster checks (enough redundancy in the cluster to survive a node failure).
  • always_failover — True or False, whether the instance must be failed over (shut down and rebooted) always, or whether it may be migrated (briefly suspended).

⭐ the -t option

The -t option specifies the disk layout type for the instance. If not passed, the configuration of the original instance is used. the available choices are:

  • diskless — this creates an instance with no disks. it's useful for testing only (or other special cases). the void instance. 💀
  • plain — disk devices will be logical volumes.
  • drbd — disk devices will be drbd (version 8.x) on top of lvm volumes.
  • file — disk devices will be backed up by files, under the cluster's default file storage directory. by default, each instance will get a directory (as its own name) under this path, and each disk is stored as individual files in this (instance-specific) directory. 📁

💜 other import things

The --iallocator option specifies the instance allocator plugin to use. If you pass in this option, the allocator will select nodes for this instance automatically, so you don't need to pass them with the -n option. for more information please refer to the instance allocator documentation. let the allocator cook. 👑

The optional second value of the --node is used for the drbd template and specifies the remote node.

The --compress option specifies which compression mode is used for moves during the import. Valid values are none (the default) and gzip.

The --src-dir option allows importing instances from a directory below /var/lib/ganeti/export.

If --ignore-ipolicy is given, any instance policy violations occurring during this operation are ignored. 🙈

Since many of the parameters are by default read from the exported instance information and used as such, the new instance will have all parameters explicitly specified — the opposite of a newly added instance, which has most parameters specified via cluster defaults. To change the import behaviour to recognize parameters whose saved value matches the current cluster default and mark it as such (default value), pass the --identify-defaults option. This will affect the hypervisor, backend and NIC parameters, both read from the export file and passed in via the command line. very "let me just normalize you real quick". 💅

See ganeti(7) for a description of --submit and other common options.

Example for identical instance import:

# gnt-backup import -n node1.example.com instance3.example.com

Explicit configuration example:

# gnt-backup import -t plain --disk 0:size=1G -B memory=512 \
> -n node1.example.com \
> instance3.example.com

🦋 LIST 🦋

list [--node=NODE] [--no-headers] [--separator=SEPARATOR]
[-o [+]FIELD,...]

Lists the exports currently available in the default directory in all the nodes of the current cluster, or optionally only a subset of them specified using the --node option (which can be used multiple times). stacking --node flags is a lifestyle, iykyk. ✨

  • The --no-headers option will skip the initial header line.
  • The --separator option takes an argument which denotes what will be used between the output fields.

Both these options are to help scripting. 🤖

The -o option takes a comma-separated list of output fields. The available fields and their meaning are:

  • export — Export name.
  • node — Node name.

If the value of the option starts with the character +, the new fields will be added to the default list. This allows one to quickly see the default list plus a few other fields, instead of retyping the entire list of fields. lazy-girl efficiency, we love to see it. 💖

Example:

# gnt-backup list --node node1 --node node2

🎀 LIST-FIELDS 🎀

list-fields [field...]

Lists available fields for exports. short, sweet, does exactly what it says. 🌸

💅 REMOVE 💅

remove {instance-name}

Removes the backup for the given instance name, if any. If the backup was for a deleted instance, it is needed to pass the FQDN of the instance, and not only the short hostname. yes, the whole long name, don't be lazy about it. 😭

🐛 REPORTING BUGS 🐛

Report bugs to the project's issue tracker or contact the developers using the Ganeti mailing list. they're nice, promise. 🫶

🌈 and that's part 1, bestie — there's more coming, so don't go anywhere. ✨

💖 SEE ALSO 💖

ok so like. the whole Ganeti universe is BIG and interconnected, bestie. here's the full squad, organized by vibe:

🌈 Ganeti overview and specifications

💅 Ganeti commands

🧚 Ganeti daemons

👑 Ganeti htools

ok legal era, let's get into it, no cap:

Copyright (C) 2006-2015 Google Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

and that's a wrap bestie 🫶 this page lives in the Ganeti manual set as gnt-backup(8) — go forth and back up responsibly, mwah 💋

📦 where this page comes from