May 16, 2007"> 8"> gnt-instance"> Debian"> GNU"> GPL"> ]> 2006 2007 Google Inc. &dhdate; &dhucpackage; &dhsection; ganeti 1.2 &dhpackage; ganeti instance administration &dhpackage; command arguments... The &dhpackage; is used for instance administration in the ganeti system. add -s disksize --swap-size disksize -m memsize -o os-type -b bridge --mac MAC-address --hvm-boot-order boot-order --kernel default kernel_path --initrd default none initrd_path -t diskless plain local_raid1 remote_raid1 drbd -n node:secondary-node instance Creates a new instance on the specified host. instance must be in DNS and resolve to a IP in the same network as the nodes in the cluster. The -s option specifies the disk size for the instance, in mebibytes (defaults to 20480MiB = 20GiB). You can also use one of the suffixes m, g or t to specificy the exact the units used; these suffixes map to mebibytes, gibibytes and tebibytes. The --swap-size option specifies the swap disk size (in mebibytes) for the instance (the one presented as /dev/sdb). The default is 4096MiB. As for the disk size, you can specify other suffixes. The -m option specifies the memory size for the instance, in mebibytes (defaults to 128 MiB). Again, you can use other suffixes (e.g. 2g). The -o options specifies the operating system to be installed. The available operating systems can be listed with gnt-os list. The -b option specifies the bridge to which the instance will be connected. (defaults to the cluster-wide default bridge specified at cluster initialization time). The --mac option specifies the MAC address of the ethernet interface for the instance. If this option is not specified, a new MAC address is generated randomly with the configured MAC prefix. The randomly generated MAC address is guaranteed to be unique among the instances of this cluster. The --hvm-boot-order option specifies the boot device order for Xen HVM instances. The boot order is a string of letters listing the boot devices, with valid device letters being: a floppy drive c hard disk d CDROM drive n network boot (PXE) The option is only relevant for Xen HVM instances and ignored by all other instances types. The --kernel options allows the instance to use a custom kernel (if a filename is passed) or to use the default kernel (@CUSTOM_XEN_KERNEL@), if the string default is passed. The --initrd option is similar: it allows the instance to use a custom initrd (if a filename is passed) or to use the default initrd (@CUSTOM_XEN_INITRD@), if the string default is passed, or to disable the use of an initrd, if the string none is passed. Note that in the case the instance is set to use the default initrd and it doesn't exist, it will be silently ignored; if the instance is set to use a custom initrd and it doesn't exist, this will be treated as an error and will prevent the startup of the instance. The -t options specifies the disk layout type for the instance. The available choices are: diskless This creates an instance with no disks. Its useful for testing only (or other special cases). plain Disk devices will be logical volumes. local_raid1 Disk devices will be md raid1 arrays over two local logical volumes. remote_raid1 Disk devices will be md raid1 arrays with one component (so it's not actually raid1): a drbd (0.7.x) device between the instance's primary node and the node given by the second value of the --node option. drbd Disk devices will be drbd (version 8.x) on top of lvm volumes. They are equivalent in functionality to remote_raid1, but are recommended for new instances (if you have drbd 8.x installed). The optional second value of the --node is used for the remote raid template type and specifies the remote node. If you do not want gnt-instance to wait for the disk mirror to be synced, use the --no-wait-for-sync option. Example: # gnt-instance add -t plain -s 30g -m 512 -o debian-etch \ -n node1.example.com instance1.example.com # gnt-instance add -t remote_raid1 -s 30g -m 512 -o debian-etch \ -n node1.example.com:node2.example.com instance2.example.com remove --ignore-failures instance Remove an instance. This will remove all data from the instance and there is no way back. If you are not sure if you use an instance again, use shutdown first and leave it in the shutdown state for a while. The --ignore-failures option will cause the removal to proceed even in the presence of errors during the removal of the instance (e.g. during the shutdown or the disk removal). If this option is not given, the command will stop at the first error. Example: # gnt-instance remove instance1.example.com list --no-headers --separator=SEPARATOR -o FIELD,... Shows the currently configured instances with memory usage, disk usage, the node they are running on, and the CPU time, counted in seconds, used by each instance since its latest restart. 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: name the instance name os the OS of the instance pnode the primary node of the instance snodes comma-separated list of secondary nodes for the instance; usually this will be just one node admin_state the desired state of the instance (either "yes" or "no" denoting the instance should run or not) admin_ram the desired memory for the instance disk_template the disk template of the instance oper_state the actual state of the instance; can take of the values "running", "stopped", "(node down)" oper_ram the actual memory usage of the instance as seen by the hypervisor ip the ip address ganeti recognizes as associated with the instance interface mac the instance interface MAC address bridge bridge the instance is connected to sda_size the size of the instance's first disk sdb_size the size of the instance's second disk vcpus the number of VCPUs allocated to the instance There is a subtle grouping about the available output fields: all fields except for oper_state and oper_ram are configuration value and not run-time values. So if you don't select any of the oper_* fields, the query will be satisfied instantly from the cluster configuration, without having to ask the remote nodes for the data. This can be helpful for big clusters when you only want some data and it makes sense to specify a reduced set of output fields. The default output field list is: name os pnode admin_state oper_state oper_ram . info instance Show detailed information about the (given) instances. This is different from list as it shows detailed data about the instance's disks (especially useful for remote raid templates). modify -m memsize -p vcpus -i ip -b bridge --mac MAC-address --hvm-boot-order boot-order --kernel default kernel_path --initrd default none initrd_path instance Modify the memory size, number of vcpus, ip address, MAC address and/or bridge for an instance. The memory size is given in MiB. Note that you need to give at least one of the arguments, otherwise the command complains. The --kernel, --initrd and --hvm-boot-order options are described in the add command. Additionally, the HVM boot order can be reset to the default values by using --hvm-boot-order=default. All the changes take effect at the next restart. If the instance is running, there is no effect on the instance. reinstall -o os-type -f force instance Reinstalls the operating system on the given instance. The instance must be stopped when running this command. If the --os-type is specified, the operating system is changed. rename --no-ip-check instance new_name Renames the given instance. The instance must be stopped when running this command. The requirements for the new name are the same as for adding an instance: the new name must be resolvable and the IP it resolves to must not be reachable (in order to prevent duplicate IPs the next time the instance is started). The IP test can be skipped if the --no-ip-check option is passed. startup --extra=PARAMS --force --instance --node --primary --secondary --all name Starts one or more instances, depending on the following options. The four available modes are: --instance will start the instances given as arguments (at least one argument required); this is the default selection --node will start the instances who have the given node as either primary or secondary --primary will start all instances whose primary node is in the list of nodes passed as arguments (at least one node required) --secondary will start all instances whose secondary node is in the list of nodes passed as arguments (at least one node required) --all will start all instances in the cluster (no arguments accepted) Note that although you can pass more than one selection option, the last one wins, so in order to guarantee the desired result, don't pass more than one such option. The --extra option is used to pass additional argument to the instance's kernel for this start only. Currently there is no way to specify a persistent set of arguments (beside the one hardcoded). Note that this may not apply to all virtualization types. Use --force to start even if secondary disks are failing. Example: # gnt-instance start instance1.example.com # gnt-instance start --extra single test1.example.com # gnt-instance start --node node1.example.com node2.example.com # gnt-instance start --all shutdown --instance --node --primary --secondary --all name Stops one or more instances. If the instance cannot be cleanly stopped during a hardcoded interval (currently 2 minutes), it will forcibly stop the instance (equivalent to switching off the power on a physical machine). The --instance, --node, --primary, --secondary and --all options are similar as for the startup command and they influence the actual instances being shutdown. Example: # gnt-instance shutdown instance1.example.com # gnt-instance shutdown --all reboot --extra=PARAMS --type=REBOOT-TYPE --ignore-secondaries --force-multiple --instance --node --primary --secondary --all name Reboots one or more instances. The type of reboot depends on the value of --type. A soft reboot does a hypervisor reboot, a hard reboot does a instance stop, recreates the hypervisor config for the instance and starts the instance. A full reboot does the equivalent of gnt-instance shutdown && gnt-instance startup. The default is soft reboot. For the hard reboot the option --ignore-secondaries ignores errors for the secondary node while re-assembling the instance disks. The --instance, --node, --primary, --secondary and --all options are similar as for the startup command and they influence the actual instances being rebooted. Use the --force-multiple option to keep gnt-instance from asking for confirmation when more than one instance is affected. Example: # gnt-instance reboot instance1.example.com # gnt-instance reboot --type=full instance1.example.com console instance Connects to the console of the given instance. If the instance is not up, an error is returned. Example: # gnt-instance console instance1.example.com replace-disks --new-secondary NODE instance replace-disks -s --new-secondary NODE instance replace-disks -s -p instance This command is a generalized form for adding and replacing disks. The first form is usable with the remote_raid1 disk template. This will replace the disks on both the primary and secondary node, and optionally will change the secondary node to a new one if you pass the --new-secondary option. The second and third forms are usable with the drbd disk template. The second form will do a secondary replacement, but as opposed to the remote_raid1 will not replace the disks on the primary, therefore it will execute faster. The third form will replace the disks on either the primary (-p) or the secondary (-s) node of the instance only, without changing the node. add-mirror -b sdX -n node instance Adds a new mirror to the disk layout of the instance, if the instance has a remote raid disk layout. The new mirror member will be between the instance's primary node and the node given with the -n option. removemirror -b sdX -p id instance Removes a mirror componenent from the disk layout of the instance, if the instance has a remote raid disk layout. You need to specifiy on which disk to act on using the -b option (either sda or sdb) and the mirror component, which is identified by the -p option. You can find the list of valid identifiers with the info command. activate-disks instance Activates the block devices of the given instance. If successful, the command will show the location and name of the block devices: node1.example.com:sda:/dev/md0 node1.example.com:sdb:/dev/md1 In this example, node1.example.com is the name of the node on which the devices have been activated. The sda and sdb are the names of the block devices inside the instance. /dev/md0 and /dev/md1 are the names of the block devices as visible on the node. Note that it is safe to run this command while the instance is already running. deactivate-disks instance De-activates the block devices of the given instance. Note that if you run this command for a remote raid instance type, while it is running, it will not be able to shutdown the block devices on the primary node, but it will shutdown the block devices on the secondary nodes, thus breaking the replication. failover -f --ignore-consistency instance Failover will fail the instance over its secondary node. This works only for instances having a remote raid disk layout. Normally the failover will check the consistency of the disks before failing over the instance. If you are trying to migrate instances off a dead node, this will fail. Use the --ignore-consistency option for this purpose. Note that this option can be dangerous as errors in shutting down the instance will be ignored, resulting in possibly having the instance running on two machines in parallel (on disconnected DRBD drives). Example: # gnt-instance failover instance1.example.com add-tags --from file instancename tag Add tags to the given instance. If any of the tags contains invalid characters, the entire operation will abort. If the --from option is given, the list of tags will be extended with the contents of that file (each line becomes a tag). In this case, there is not need to pass tags on the command line (if you do, both sources will be used). A file name of - will be interpreted as stdin. list-tags instancename List the tags of the given instance. remove-tags --from file instancename tag Remove tags from the given instance. If any of the tags are not existing on the node, the entire operation will abort. If the --from option is given, the list of tags will be extended with the contents of that file (each line becomes a tag). In this case, there is not need to pass tags on the command line (if you do, both sources will be used). A file name of - will be interpreted as stdin. &footer;