Virtual machine

Name

hypercloud vm - manages HyperCloud virtual machines.

Synopsis

hypercloud vm <command> [<args>] [<options>]

Options

--adjust x,y,z            Adjust size to not truncate selected columns
--admin                   lock admin actions
-a, --alias alias         Attach the NIC as an ALIAS
--all                     Show all template data
-a, --append              Append new attributes to the current template
--arch arch               Architecture of the VM
                            e.g.: i386 or x86_64
--boot device_list        Set boot device list 
                            e.g. disk0,disk2,nic0
--cache cache_mode        Hypervisor cache mode: default, none,
                          writethrough, writeback, directsync or unsafe.
                          (Only KVM driver)
--cmd cmd                 CMD to run when SSH
--context line1,line2,line3 Lines to add to the context section
--cpu cpu                 CPU percentage reserved for the VM (1=100% one
                          CPU)
--csv                     Write table in csv format
--csv-del del             Set delimiter for csv output
-d, --datastore id|name   Selects the datastore
--decrypt                 Get decrypted attributes
-d, --delay x             Sets the delay in seconds for top command
--delete                  No recover action possible, delete the VM
--delete-db               No recover action possible, delete the VM from
                          the DB. It does not trigger any action on the
                          hypervisor
--describe                Describe list columns
--discard discard_mode    Hypervisor discard mode: ignore or unmap. (Only
                          KVM driver)
--disk image0,image1      Disks to attach. To use an image owned by other
                          user use user[disk]. Add any additional
                          attributes separated by ':' and in the shape of
                          KEY=VALUE. 
                            For example, if the disk must be resized, use image0:size=1000 . 
                            Or, image0:size=1000:target=vda,image1:target=vdb
--dry                     Just print the template
--end number|TIME         ----
--endpoint endpoint       URL of HyperCloud xmlrpc frontend
-e, --enforce             Enforce that the host capacity is not exceeded
--expand [x=prop,y=prop]  Expands the columns size to fill the terminal.
                            For example: $hypercloud vm list --expand
                            name=0.4,group=0.6 will expand name 40% and
                            group 60%. 
                            $hypercloud vm list --expand name,group will
                            expand name and group based on its size. 
                            $hypercloud vm list --expand will expand all columns.
--extended                Show info extended (it only works with xml
                          output)
--failure                 Recover a VM by failing the pending action
-f, --file file           Selects the template file
--files_ds file1,file2    Add files to the contextualization CD from
                          thefiles datastore
-f, --filter x,y,z        Filter data. An array is specified with
                          column=value pairs. 
                          Valid operators: =,!=,<,<=,>,>=,~ 
                            e.g. NAME=test (match name with test) 
                            NAME~test (match every NAME containing the substring 'test')
--hard                    Does not communicate with the guest OS
-h, --help                Show this message
--hold                    Creates the new VM on hold state instead of
                          pending
--hourly hour             Repeats the schedule action each hours
                          specified,it can be a number between 0,168
                          separated with commas. 
                            For example: 
                            hypercloud vm resume 0 --schedule "09/23 14:15" --hourly 1,5
-i, --image id|name       Selects the image
--init script1,script2    Script or scripts to start in context
--interactive             Enables interactive recovery. Only works
                          alongside the --retry option.
-i, --ip ip               IP address for the new NIC
-j, --json                Show the resource in JSON format
--keep-backup             Keep previous backup when creating a new one
-k, --kilobytes           Show units in kilobytes
-l, --list x,y,z          Selects columns to display with list command
-c, --listconf conf       Selects a predefined column list
--live                    Do the action with the VM running
--logger logger           Set logger to STDOUT or FILE
--manage                  lock manage actions
--market market_id        Market to save one-shot
--memory memory           Memory amount given to the VM. 
                            By default the unit is megabytes. 
                            To use gigabytes add a 'g', floats can be used: 8g=8192, 0.5g=512
--monthly days            Repeats the schedule action the days of the month
                          specified, it can be a number between 1,31
                          separated with commas. 
                            For example: 
                            hypercloud vm resume 0 --schedule "09/23 14:15" --monthly 1,14
-m, --multiple x          Instance multiple VMs
--name name               Name for the new VM
--net_context             Add network contextualization parameters
-n, --network id|name     Selects the virtual network
--nic network0,network1   Networks to attach. To use a network owned by
                          other user use user[network]. Additional
                          attributes are supported like with the --disk
                          option. Also you can use auto if you want that
                          HyperCloud select automatically the network
--nic-id nic_id           NIC to use when SSH
--nic_name name           Name of the NIC
--no-expand               Disable expand
--no-header               Hides the header of the table
--no-pager                Disable pagination
-n, --numeric             Do not translate user and group IDs
--oneshot                 Take an snapshot of the VM without saving backup
                          info
--operator operator       Logical operator used on filters: AND, OR.
                            Default: AND.
--password password       Password to authenticate with HyperCloud
--persistent              Make the new images persistent
--poff                    Do the migrate by poweringoff the vm
--poff-hard               Do the migrate by poweringoff hard the vm
--prefix prefix           Overrides the DEV_PREFIX of the image
--raw string              Raw string to add to the template. Not to be
                          confused with the RAW attribute
--recreate                No recover action possible, delete and recreate
                          the VM
--report_ready            Sends READY=YES to OneGate, useful for OneFlow
--retry                   Recover a VM by retrying the last failed action
--schedule TIME           Schedules this action to be executed afterthe
                          given time. 
                            For example: 
                            hypercloud vm resume 0 --schedule "09/23 14:15"
--search search           query in KEY=VALUE format
-s, --size x=size,y=size  Change the size of selected columns. 
                            For example:
                            $ hypercloud vm list --size "name=20" will make column
                            name size 20.
-s, --snapshot snapshot   ID of the Snapshot to save.
--spice                   Add spice server to the VM
--spice-keymap keymap     spice keyboard layout
--spice-listen ip         spice IP where to listen for connections. 
                            By default is 0.0.0.0 (all interfaces).
--spice-password password spice password
--ssh [file]              Add an ssh public key to the context. If the file
                          is omited then the user variable SSH_PUBLIC_KEY
                          will be used.
--ssh-options options     SSH options to use
--startscript [file]      Start script to be executed
--success                 Recover a VM by succeeding the pending action
-t, --target target       Device where the image will be attached
-t, --type type           Type of the new Image
--use                     lock use actions
--user name               User name used to connect to HyperCloud
--user-inputs ui1,ui2,ui3 Specify the user inputs values when instantiating
--vcenter_vm_folder path  In a vCenter environment sets the the VMs and
                          Template folder where the VM will be placed in.
                          The path uses slashes to separate folders. 
                            For example: --vcenter_vm_folder "/Management/VMs"
--vcpu vcpu               Number of virtualized CPUs
-v, --verbose             Verbose mode
-V, --version             Show version and copyright information
--vnc                     Add VNC server to the VM
--vnc-keymap keymap       VNC keyboard layout
--vnc-listen ip           VNC IP where to listen for connections. 
                            By default is 0.0.0.0 (all interfaces).
--vnc-password password   VNC password
--weekly days             Repeats the schedule action the days of the week
                          specified, it can be a number between 0 (Sunday)
                          to 6 (Saturday) separated with commas. 
                            For example: 
                            hypercloud vm resume 0 --schedule "09/23 14:15" --weekly 0,2,4
-x, --xml                 Show the resource in xml format
-y, --yaml                Show the resource in YAML format
--yearly days             Repeats the schedule action the days of the year
                          specified, it can be a number between 0,365
                          separated with commas. 
                            For example: 
                          hypercloud vm resume 0 --schedule "09/23 14:15" --yearly 30,60

Commands

• backup vmid Creates a VM backup and stores it in the marketplace.

  • Valid options: keep logger market oneshot

• chgrp <range|vmid_list> <groupid> Changes the VM group.

• chmod <range|vmid_list> <octet> Changes the VM permissions.

• chown <range|vmid_list> <userid> [<groupid>] Changes the VM owner and group.

• create [<file>] Creates a new VM from the given description instead of using a previously defined template (see hypercloud template create and hypercloud template instantiate).

  • Valid options: arch boot context cpu disk dry files_ds hold init memory multiple name net_context nic raw report_ready spice spice_keymap spice_listen spice_password ssh startscript user_inputs vcenter_vm_folder vcpu vnc vnc_keymap vnc_listen vnc_password

Examples

Using a template description file:

hypercloud VM create vm_description.tmpl

New VM named arch vm with a disk and a NIC:

hypercloud vm create --name "arch vm" --memory 128 --cpu 1 --disk arch \
                        --network private_lan

A VM with two disks:

hypercloud vm create --name "test vm" --memory 128 --cpu 1 --disk arch,data

• create-chart <vmid> Adds a charter to the VM, these are some consecutive scheduled actions.
  You can configure the actions in /etc/one/cli/hypercloud vm.yaml

• delete-chart <vmid> <sched_id> Deletes a charter from the VM.

• deploy <range|vmid_list> <hostid> [<datastoreid>] Deploys the given VM in the specified Host. This command forces the deployment, in a standard installation the Scheduler is in charge of this decision.

  • States: PENDING, HOLD, STOPPED, UNDEPLOYED
  • Valid options: enforce file

• disk-attach <vmid> Attaches a disk to a running VM. When using `--file`` add only one DISK instance.

  • States: RUNNING, POWEROFF
  • Valid options: cache discard file image prefix target

• disk-detach <vmid> <diskid> Detaches a disk from a running VM.

  • States: RUNNING, POWEROFF

• disk-resize <vmid> <diskid> <size> Resizes a VM disk. The new size should be larger than the old one.
  The valid units are:

  • T: TiB
  • G: GiB
  • M: MiB
    • The default is MiB.

  States: RUNNING, POWEROFF

• disk-saveas <vmid> <diskid> <img_name> Saves the specified VM disk as a new Image. The Image is created immediately, and the contents of the VM disk will be saved to it.

  • States: ANY
  • Valid options: snapshot type

• disk-snapshot-create <vmid> <diskid> <name> Takes a new snapshot of the given disk. This operation needs support from the Datastore drivers: QCOW2 or Ceph.

  • States: RUNNING, POWEROFF, SUSPENDED
  • Valid options: end hourly monthly schedule weekly yearly

• disk-snapshot-delete <vmid> <diskid> <disk_snapshot_id> Deletes a disk snapshot.

  • States: RUNNING, POWEROFF, SUSPENDED
  • Valid options: end hourly monthly schedule weekly yearly

• disk-snapshot-rename <vmid> <diskid> <disk_snapshot_id> <new_snapshot_name> Renames a disk snapshot.

• disk-snapshot-revert <vmid> <diskid> <disk_snapshot_id> Reverts disk state to a previously taken snapshot.

  • States: POWEROFF, SUSPENDED
  • Valid options: end hourly monthly schedule weekly yearly

• hold <range|vmid_list> Sets the given VM on hold. A VM on hold is not scheduled until it is released. It can; however, be deployed manually; see hypercloud vm deploy

  • States: PENDING
  • Valid options: end hourly monthly schedule weekly yearly

• list [<filterflag>] Lists VMs in the pool

  • Valid options: adjust csv csv_del delay describe expand extended filter json kilobytes list listconf no_expand no_header no_pager numeric operator search size xml yaml

• lock <range|vmid_list> Locks a VM to prevent certain actions defined by different levels. The show and monitoring action will never be locked.

  • Valid states are: All.
  • [Use]: locks Admin, Manage and Use actions.
  • [Manage]: locks Manage and Use actions.
  • [Admin]: locks only Admin actions.
  • Valid options: admin all manage use

• migrate <range|vmid_list> <hostid> [<datastoreid>] Migrates the given running VM to another Host. If used with --live parameter the migration is done without downtime.

  • States: RUNNING
  • Valid options: enforce live poweroff poweroff_hard

• nic-attach <vmid> Attaches a NIC to a running VM. When using --file add only one NIC instance.
  To attach a NIC alias, use --file or --alias option.

  • States: RUNNING, POWEROFF
  • Valid options: alias file ip network nic_name

• nic-detach <vmid> <nicid> Detaches a NIC from a running VM.

  • States: RUNNING, POWEROFF

• port-forward <vmid> [<port>] Get port forwarding from a NIC, e.g:

  1.2.3.4@4000 -> 1
  

  Means that to connect to VM port 1, you need to connect to IP 1.2.3.4 in port 4000
  • Valid options: nic_id

• poweroff <range|vmid_list> Powers off the given VM. The VM will remain in the poweroff state, and can be powered on with the hypercloud vm resume command.

  • States: RUNNING
  • Valid options: end hard hourly monthly schedule weekly yearly

• reboot <range|vmid_list> Reboots the given VM, this is equivalent to execute the reboot command from the VM console.
  The VM will be ungracefully rebooted if --hard is used.

  • States: RUNNING
  • Valid options: end hard hourly monthly schedule weekly yearly

• recover <range|vmid_list> Recovers a stuck VM that is waiting for a driver operation. The recovery may be done by failing, succeeding, or retrying the current operation. YOU NEED TO MANUALLY CHECK THE VM STATUS ON THE HOST, to decide if the operation was successful or not, or if it can be retried.

  • Valid options: delete deletedb failure interactive recreate retry success

Example

A VM is stuck in "migrate" because of a hardware failure. You need to check if the VM is running in the new host or not to recover the VM with --success or --failure, respectively.

• States for success/failure recovers: Any ACTIVE state.
• States for a retry recover: Any *FAILURE state
• States for delete: Any
• States for delete-recreate: Any but STOP/UNDEPLOYED
• States for delete-db: Any

• release <range|vmid_list> Releases a VM on hold. See hypercloud vm hold

  • States: HOLD
  • Valid options: end hourly monthly schedule weekly yearly

• rename <vmid> <name> Renames the VM.

• resched <range|vmid_list> Sets the rescheduling flag for the VM.

  • States: RUNNING, POWEROFF

• resize <vmid> Resizes the capacity of a Virtual Machine (offline, the VM cannot be RUNNING).

  • Valid options: cpu enforce file memory vcpu

• restore <vmid> Restores a VM from a previous backup.

  • Valid options: datastore logger

• resume <range|vmid_list> Resumes the execution of a saved VM.

  • States: STOPPED, SUSPENDED, UNDEPLOYED, POWEROFF, UNKNOWN
  • Valid options: end hourly monthly schedule weekly yearly

• save <vmid> <name> Clones the VM's source Template, replacing the disks with live snapshots of the current disks. The VM capacity and NICs are also preserved.

  • States: POWEROFF
  • Valid options: persistent

• sg-attach <vmid> <nicid> <sgid> Attaches a Security Group to a VM.

  • States: All, except BOOT, MIGRATE and HOTPLUG_NIC

• sg-detach <vmid> <nicid> <sgid> Detaches a Security Group from a VM.

  • States: All, except BOOT, MIGRATE and HOTPLUG_NIC

• show <vmid> Shows information for the given VM.

  • Valid options: all decrypt json xml yaml

• snapshot-create <range|vmid_list> [<name>] Creates a new VM snapshot.

  • Valid options: end hourly monthly schedule weekly yearly

• snapshot-delete <vmid> <snapshot_id> Deletes a snapshot of a VM.

  • Valid options: end hourly monthly schedule weekly yearly

• snapshot-revert <vmid> <snapshot_id> Reverts a VM to a saved snapshot.

  • Valid options: end hourly monthly schedule weekly yearly

• ssh <vmid> [<login>] SSH into VM.

  • Valid options: cmd nic_id ssh_opts

Options example

'-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'

• stop <range|vmid_list> Stops a running VM. The VM state is saved and transferred back to the front-end along with the disk files.

  • States: RUNNING
  • Valid options: end hourly monthly schedule weekly yearly

• suspend <range|vmid_list> Saves a running VM. It is the same as hypercloud vm stop, but the files are left in the remote machine to later restart the VM there (i.e. the resources are not freed and there is no need to re-schedule the VM).

  • States: RUNNING
  • Valid options: end hourly monthly schedule weekly yearly

• terminate <range|vmid_list> Terminates the given VM. The VM life cycle will end.
  With --hard it unplugs the VM.

  • States: valid if no operation is being performed on the VM
  • Valid options: end hard hourly monthly schedule weekly yearly

• top [<filterflag>] Lists Images continuously.

  • Valid options: adjust csv csv_del delay expand extended filter json kilobytes list listconf no_expand no_header no_pager numeric operator size xml yaml

• undeploy <range|vmid_list> Shuts down the given VM. The VM is saved in the system Datastore.
  With --hard it unplugs the VM.

  • States: RUNNING
  • Valid options: end hard hourly monthly schedule weekly yearly

• unlock <range|vmid_list> Unlocks a Virtual Machine.

  • Valid states are: All.

• unresched <range|vmid_list> Clears the rescheduling flag for the VM.

  • States: RUNNING, POWEROFF

• update <vmid> [<file>] Update the user template contents. If a path is not provided the editor will be launched to modify the current content.

  • Valid options: append

• update-chart <vmid> <sched_id> [<file>] Updates a charter from a VM.

• updateconf <vmid> [<file>] Updates the configuration of a VM.

  • Valid states are: running pending failure poweroff undeploy hold or cloning.
    In RUNNING state only changes in CONTEXT take effect immediately, other values may need a VM restart.

  This command accepts a template file or opens an editor, the full list of configuration attributes are:

  - OS        = ["ARCH", "MACHINE", "KERNEL", "INITRD", "BOOTLOADER", "BOOT", "UUID"]
  - FEATURES  = ["ACPI", "PAE", "APIC", "LOCALTIME", "HYPERV", "GUEST_AGENT", "IOTHREADS"]
  - INPUT     = ["TYPE", "BUS"]
  - GRAPHICS  = ["TYPE", "LISTEN", "PASSWD", "KEYMAP" ]
  - RAW       = ["DATA", "DATA_VMX", "TYPE", "VALIDATE"]
  - CPU_MODEL = ["MODEL"]
  - CONTEXT (any value, **variable substitution will be made**)
  

  • Valid options: append

• vnc <vmid> Opens a VNC session to the VM

  • Valid options: vnc

Argument Formats

• datastoreid HyperCloud DATASTORE name or ID.

• disk_snapshot_id Disk_snapshot identifier.

• diskid Integer.

• file Path to a file.

• filterflag

  • a, all all the known VMs
  • m, mine the VM belonging to the user in ONE_AUTH
  • g, group 'mine' plus the VM belonging to the groups the user is member of
  • G, primary group the VM owned by the user's primary group
  • uid VM of the user identified by this uid
  • user VM of the user identified by the username

• groupid HyperCloud GROUP name or ID.

• hostid HyperCloud HOST name or ID.

• range List of id's in the form 1,8..15.

• size Disk size in MiB.

• snapshot_id Snapshot identifier.

• text String.

• userid HyperCloud USER name or ID.

• vmid HyperCloud VM name or ID.

• vmid_list Comma-separated list of HyperCloud VM names or IDs.

Version

HyperCloud Orchestrator 6.4.0.1

Copyright © SoftIron