ovm-ctl(1)

NAME
ovm-ctl - command line interface to OrionVM Online API

SYNOPSIS
ovm-ctl [-vq] [(-a|--authfile) filename] [--verbose] [--quiet] [(-u|--user|--username|--auth) user[:pass]] [(-f|--file) filename] [--debug] [command]

DESCRIPTION
This is a program designed to be a command line interface to the OrionVM Online API calls. It allows you to use simple commands to interact with and control your OrionVM account and resources. A single command can be specified on the command line, or you can run it without commands to start an interactive shell where commands can be typed.

The program has two output modes: verbose and quiet. In verbose mode, human readable output is given. In contrast, quiet mode is designed for scripts and the like. Most commands will not produce output in quiet mode. Errors must be detected by examining the program's exit code. Commands that return information, such as the show family of commands, return a simple, machine-readable format. See COMMANDS below for details.

By default (but see OPTIONS below) the program is in verbose mode. However, if input or output is not a terminal (for example, it is a file or a pipeline), quiet mode is used.

For help with commands, see section COMMANDS below.

  Authentication
When the program is started (in verbose or quiet mode), the user is prompted for their OrionVM login email and password. This step can be avoided by either giving a username on the command line (see OPTIONS) or by writing an authfile. The first time you give your credentials, the program will ask if you want to save them. This will write an authfile for you in the default authfile location (~/.orionauth). The following is details on writing an authfile yourself.

An authfile is a plain text file containing one or two lines. The first line is your OrionVM login email. The second is your password. If there is no second line or it is blank, your password will still be prompted for when the program is run. Please consider the security risks of keeping your password stored in plaintext in a file on your system.

The program by default searches for a file called .orionauth in your home directory - you should place your authfile here to have it be used automatically.

  Errors in interactive mode
When reading commands from input (ie. no command was supplied as an argument), the effects of an error occurring depend on whether the program is running in verbose mode. In verbose mode, the error is reported and execution continues. In quiet mode, execution is aborted and the program exits with the exit status of the command that failed.

OPTIONS

-a filename, --authfile filename
    Use the given file as the authfile (see Authentication) instead of the default.

-v, --verbose
    Force verbose mode even when stdin or stdout is not a tty. Causes the program to generate human-readable outputs.

-q, --quiet
    Force quiet mode even when stdin and stdout are a tty. Causes the program to generate little or no output.

-u user[:pass], --user user[:pass], --username user[:pass], --auth user[:pass]
    If given, specifies an OrionVM account to log in as. Optionally, the password can also be given, seperated from the username by a colon. This option overrides anything read from an authfile.

-f filename, --file filename
    Read a list of commands from a file, instead of stdin. Implies -q unless overriden with -v. Note that options are processed in the order they are given and any later option overrides an earlier one.

--debug
    Report the underlying exceptions in the python code. This option is intended only for debugging a problem after editing the code.

COMMANDS
Note: For commands that produce output in quiet mode, their entries contain formatting strings. These formatting strings describe the output as per the rules used by printf(3)

wizard vm NAME [with [ram MEMSIZE] [disk DISKSIZE] [image IMAGE]] [and boot]
    This command is a wizard to create a ready-to-run server with the given NAME. Any arguments not provided will be prompted. If the command has "and boot" on the end, the machine will be booted immediately after creation. Further details: Create a new VM and call it NAME. Create a disk and ip (of the same NAME) and attach them. The disk will have size DISKSIZE and image IMAGE. The VM will have ram MEMSIZE. If "and boot" is given, the VM is then booted. If "and boot" is not given, it is only prompted if no other arguments are provided.

    NAME
        The name to give to the VM, disk and ip address to be created.

    MEMSIZE
        The amount of RAM to give the VM. Format is a number followed by M for megabytes or G for gigabytes.

    DISKSIZE
        The size of the new disk. See the SIZE argument for "create disk".

    Output format string for quiet mode:
        If creating a windows vm, prints the inital password

show ips
    Print a list of IP addresses and their friendly names.

    Output format string for quiet mode:
        "%s\t%s\n ==> IP Address, Friendly Name,
         %s\t%s\n IP Address, Friendly Name,
         ..." etc...(one per line)

show ip IP
    Get information on a specific IP address, including up/down data totals, and (if in use) the vm using it.

    IP  The IP address or friendly name to get information on.

    Output format string for quiet mode:
        "%s\t%s\t%d\t%d\t%s\n" ==> IP Address, Friendly name,
                                Total Uploaded (bytes), Total Downloaded (bytes),
                                VM Name of VM using this IP (ommitted if not in use)

    Error cases with special return values:
         For non-existing IP address or friendly name: Returns exit code 3

show vms
    Print list of all vms, both running and shutdown.

    Output format string for quiet mode:
        "%s\t%s\t%d\t%d\t%d\t%s\n ==> VM Name, VM Type, Memory (in MB), Number of disks, Number of ips, VM State
         %s\t%s\t%d\t%d\t%d\t%s\n VM Name, VM Type, Memory (in MB), Number of disks, Number of ips, VM State
         ..." etc...(one per line)

show vm NAME
    Get information on a specific VM, including running state, attached disks and attached ips.

    NAME
        The name of the VM to get information on.

    Output format string for quiet mode:
        "%s\t%s\t%d\t%s\n ==> VM Name, Type, Memory (in MB), State
         disk\t%s\t%s\t%s\n Disk Name, Template, Device Name on VM
         disk\t%s\t%s\t%s\n Disk Name, Template, Device Name on VM
         ... etc (one disk per line)
         ip\t%s\n IP Address
         ip\t%s\n IP Address
         ..." etc (one ip per line)

    Error cases with special return values:
         For non-existing VM Name: Return exit code 3

show disks
    Print list of disks, their template image and their size.

    Output format string for quiet mode:
        "%s\t%s\t%d\n ==> Disk Name, Image Name, Size (in GB)
         %s\t%s\t%d\n Disk Name, Image Name, Size (in GB)
         ..." etc...(one per line)

show disk NAME
    Get information on a specific disk, including image name, size and whether the disk is locked (normally, attached to a vm)

    NAME
        The name of the disk to get information on.

    Output format string for quiet mode:
        "%s\t%s\t%d\t%s\t%s\n" ==> Disk Name, Image Name, Size (in GB),
                                "locked" if disk is locked, else "unlocked",
                                licence if disk a licenced windows disk, else omitted

    Error cases with special return values:
         Disk does not exist: Returns exit code 3

show usage
    Report amount of RAM and HDD Storage being used, and the number of IP addresses currently allocated.

    Output format string for quiet mode:
        "%d\t%d\t%d\n" ==> RAM in Megabytes, Storage in Gigabytes, Number of IPs

show balance
    Report account balance, current to the last hour.

    Output format string for quiet mode:
        "%.2f\n" ==> Balance in dollars (to the cent)

show images
    Get a list of available software distributions for creating new instances. Please note that the "blank" value is special, and is used to create a completely empty disk.

    Output format string for quiet mode:
        "%s\n ==> Image
         %s\n Image
         ..." etc (one per line)

show context key KEY on vm VM
    Retrieve the value for the given key from the key-value context information associated with the given vm.

    KEY The context key to look up in the vm context store

    VM  The name of the vm to look up context information on

    Output format string for quiet mode:
        "%s\n" ==> Value

    Error cases with special return values:
         If the given vm does not exist, exit code 3 is returned.
         If the given vm context store does not contain the given key, exit code 4 is returned.

create disk NAME with size SIZE [and image IMAGE]
    Create a new storage volume and load it with the given software distribution.

    NAME
        The name to give to the new disk.

    SIZE
        The size of the new disk. Can be given in MB, GB or TB. For example: "200G", "20g", "1.5T", "2048m". Value is rounded down to nearest GB.

    IMAGE
        The software distribution to put onto the new disk. For a list of valid image names, see the "show images" command. If not provided, creates a blank disk.

    Error cases with special return values:
         If the given image is not valid, exit code 3 is returned.
         If the size is not valid, exit code 4 is returned.
         If there already exists a disk with name NAME, exit code 5 is returned.
         If an error occurs before creation is complete, exit code 6 is returned.
             NOTE: The creation continues in the background, you must "show disks" to check
             when it is done.

create ip with friendly NAME
    Allocate a new IP address and call it NAME.

    NAME
        The friendly name to assign to the new address.

create vm NAME with ram SIZE [of type TYPE]
    Create a new VM and call it NAME. Give it SIZE amount of memory. Optionally, a VM Type can be provided. This is for advanced use only.

    NAME
        The name to give to the new VM.

    SIZE
        Amount of RAM to allocate to the new VM. Format is a number followed by M for megabytes or G for gigabytes.

    TYPE
        Either "paravirt" or "HVM". Note that not all distros support all types. "HVM" should be used when creating Microsoft Windows VMs. "paravirt" should otherwise be used and is the default if this argument is not given.

    Error cases with special return values:
         Incorrect format for SIZE: Return exit code 3
         Invalid VM Type: Return exit code 4

clone disk NAME from SOURCE [with size SIZE]
    Create a new disk called NAME, with contents copied from the disk called SOURCE.

    NAME
        The name of the new disk.

    SOURCE
        The name of the disk to copy from. Must not be locked.

    SIZE
        The size of the new disk (see the same arg for command "create disk"). Must be at least the size of the source disk. If not provided, defaults to the size of the source disk.

    Error cases with special return values:
         If the given source disk does not exist or is busy, exit code 3 is returned.
         If the size is too small or otherwise not valid, exit code 4 is returned.
         If there already exists a disk with name NAME, exit code 5 is returned.
         If an error occurs before creation is complete, exit code 6 is returned.
             NOTE: The creation continues in the background, you must "show disks" to check
             when it is done.

attach disk DISK to VM with target TARGET
    Attach a given disk to a given VM, locking the disk and making it appear as a device on the VM.

    DISK
        The name of the disk to attach.

    VM  The name of the VM to attach to.

    TARGET
        The name of the device (the device will appear as /dev/TARGET). For a linux vm: Must be of form: "xvd%s%d" ==> ((a, b, c, ..., aa, ab, etc), positive integer), eg: "xvda1", "xvda2", "xvdb1", "xvdb25". Note: "xvdz" is reserved. Valid range is "xvda"-"xvdy", then "xvdaa", etc. For a windows vm: Must be of form: "hd%s" ==> (a, b, c, ..., aa, ab, ...) eg. "hda", "hdb", "hdog", "hdzzz"

    Error cases with special return values:
         For non-existing or invalid (eg. running) VM: Returns exit code 3
         For non-existing or invalid Disk: Returns exit code 4
         For invalid target: Returns exit code 5

attach ip IP to vm VM
    Attach a given IP to a given VM, creating an ethernet interface on the VM.

    IP  The IP Address or Friendly Name of the IP to attach.

    VM  The name of the VM to attach it to.

    Error cases with special return values:
         For non-existing or invalid VM: Return exit code 3
         For non-existing or invalid IP: Return exit code 4

detach disk DISK from VM
    Detach the given disk from the instance its attached to, removing it from that system but freeing it to be destroyed or attached elsewhere.

    DISK
        Name of the disk to detach.

    VM  Name of the instance that the disk is currently attached to.

    Error cases with special return values:
         VM does not exist or is not shut down: Returns exit code 3
         Disk not attached to VM, or disk does not exist: Returns exit code 4

detach ip IP from VM
    Detach the given IP from the instance its attached to, allowing it to be freed or attached to a different instance instead.

    IP  The IP address or friendly name you want to detach.

    VM  The name of the instance that the ip is currently attached to.

    Error cases with special return values:
         VM does not exist: Returns exit code 3
         Invalid IP or no matching friendly IP name found: Returns exit code 4

boot vm VM
    Begin running the given instance.

    VM  Name of the instance to boot up.

    Error cases with special return values:
         If VM name is invalid or VM does not exist: Returns exit code 3
         If VM is not ready to be booted (eg. is already running): Returns exit code 4
         If VM fails to correctly boot (booting is aborted): Returns exit code 5
         If an error occurs while booting: Returns exit code 6
             NOTE: In this case, the VM may still boot correctly.
             Try "show vm" to check if the VM is now running or still booting.

shutdown vm VM
    Stop running the given instance. While an instance is not running, no RAM usage charges are incurred. Note: Do not attempt to shut down your instance using the standard shut down feature of its operating system. Your instance will be restarted immediately and usage charges will continue.

    VM  Name of the instance to stop running.

    Error cases with special return values:
         VM name is invalid or VM does not exist: Return exit code 3
         VM not in a state to be shut down (eg. not running): Return exit code 4
         An error occurred while waiting for VM to shut down: Return exit code 5
             Note: In this case, the VM may have not shut down correctly.
             You should check with "show vm" and the out-of-band console ("console")
             If the VM remains uncontactable and is still running after several minutes,
             please contact OrionVM technical support.
         VM failed to shut down: Return exit code 6
             This is a serious error. Plesae contact OrionVM technical support
             and we will resolve the issue.

console VM
    Log into the out-of-band management console on the given instance. This is roughly equivilent to directly connecting to the serial port on the machine. This command requires the programs "grep" and "ssh" be installed and accessible in a folder listed in the PATH environment variable. See NOTES section of the man page for extra notes.

    VM  The instance to connect to.

    Error cases with special return values:
         VM does not exist: Return exit code 3
         Fail to run ssh: Return exit code 4
         ssh exits with non-zero code (generic error): Return exit code 5
         ssh exits with code 255 (connection or protocol error): Return exit code 6

destroy ip IP
    Unallocate the given IP, which must not be locked (in use by a VM). Once an IP has been unallocated, there is no guarentee you can get the same one back again. Note that unlocked IPs still incur a charge until they have been destroyed.

    IP  The IP address or friendly name to unallocate.

    Error cases with special return values:
         IP is invalid, or no matching friendly name found: Returns exit code 3

destroy disk DISK
    Destroys the given disk that is not locked (attached to a VM). All data on the disk is lost. OrionVM is not responsible for any data lost this way. Please be very careful when dealing with unlocked disks.

    DISK
        Name of the disk to destroy.

    Error cases with special return values:
         An error occurs while waiting for disk to be destroyed: Returns exit code 3
             NOTE: When this occurs, the disk may or may not be destroyed.
             Please run "show disks" and check if the disk is on the list.

destroy vm VM
    Destroy given non-running instance. Note that any attached disks or IPs will still exist and continue to incur charges.

    VM  Name of the instance to delete.

    Error cases with special return values:
         VM does not exist: Return exit code 3

add context to vm VM with KEY = VALUE
    Add a new context item into the key value context storage for the given VM. Valid keys must not contain whitespace but values may. If a key already exists, it will be overwritten.

    VM  Name of the vm to attach the key value data to.

    KEY The key to map the given value to. May not contain whitespace.

    VALUE
        The value to attach to the given key.

    Error cases with special return values:
         If the VM does not exist: Return exit code 3

clear context key KEY from vm VM
    Remove the given key value data from the given VM context store. THIS FUNCTION IS NOT YET IMPLEMENTED

    KEY Key of the data to remove from the key value store

    VM  The name of the VM to clear the key value data from.

    Error cases with special return values:
         If the given vm does not exist, exit code 3 is returned
         If the given key does not exist in the context store, exit code 4 is returned

set password on vm VM[ to PASSWORD]
    On next boot, vm will have password set to the given password. Note that this requires we store the password in our system, in plaintext. As such you may wish to instead use a temporary password here then change it manually. To this end, a random password is chosen if none is provided.

    VM  The vm to set the password of. Note that while a change may be made while the vm is running, changes will not take effect until the next boot.

    PASSWORD
        Optional. The new password to set. May contain whitespace. If not given, a random 8 character password is generated.

    Output format string for quiet mode:
        "%s " -> New password

    Error cases with special return values:
         If the VM does not exist: Return exit code 3

# COMMENT
    A line beginning with a "#" is a comment line. This line will be ignored. This can be useful when writing scripts to be used with the -f option.

quit
    Exit the program. Has no effect if given in command line options. Note that an EOF (Ctrl-D) can also be used to exit.

set ram on vm NAME to SIZE
    Update the ram of a VM. VM Must be stopped.

    NAME
        The name of the VM.

    SIZE
        Amount of RAM to set on the VM. Format is a number followed by M for megabytes or G for gigabytes. Value must be between 512M and 64G (65536M) errors:

help [COMMAND]
    Print help on the given command. If no command is given, prints a list of commands.

    COMMAND
        Optional arg. If given, it specifies a command to print detailed help on.

    Error cases with special return values:
         Command not found: Returns exit code 3

EXIT STATUS

0   Command completed successfully (for a command given as an argument).

0   Program reached quit command or end of input (for reading commands from input).

1   Error in parsing command line arguments, or command not found.

2   Unknown error. Common causes include but are not limited to incorrect authentication, internet connectivity issues or an invalid operation (such as trying to delete a locked disk).

3-64
    Reserved for command-specific errors. See section COMMANDS for details.

FILES

~/.orionauth
    Default authentication file. See subsection Authentication for details.

NOTES
In the current implementation of ovm-ctl console, the user's OrionVM password is passed to ssh(1) as a command line argument. This means that the password is readable, in plaintext, to all users of the computer. Please avoid using the command on a computer where other people may have access to the process list. Note that this applies only to ovm-ctl, and the web panel in-browser console is completely safe.