prlctl

prlctl − utility for managing R-Virtualization servers and virtual environments residing on them.

prlctl create <ve_name> [-t,--ostemplate <name> -o,--ostype <name list> -d,--distribution <name list>] [--vmtype ct vm] [--dst <path>] [--changesid] [--no-hdd] [--uuid <uuid>] [OPTIONS]

prlctl backup <ve_id ve_name> [-f,--full] [-i,--incremental] [-s,--storage <user[[:passwd]@server[:port] [--description <desc>]>] [--no-compression] [--no-tunnel] [--no-reversed-delta]

prlctl backup-list [ve_id ve_name] [-f,--full] [--localvms] [--vmtype ct vm all] [-s,--storage <user[[:passwd]@server[:port]>]

prlctl backup-delete {<ve_id> -t,--tag <backup_id>} [--keep-chain] [-s,--storage <user[[:passwd]@server[:port]>]

prlctl restore {<ve_id> -t,--tag <backup_id>} [-s,--storage <user[[:passwd]@server[:port]>] [-n,--name <new_name>] [--dst <path>] [--no-tunnel] [--live]

prlctl capture <ve_id ve_name> [--file <path>]

prlctl clone <ve_id ve_name> --name <new_name> [--template] [--dst <path>] [--changesid] [--linked] [--detach-external-hdd <yes no>] [OPTIONS]

prlctl delete <ve_id ve_name> [--force]

prlctl installtools <ve_id ve_name>

prlctl exec <ve_id ve_name> [--without-shell] <command>

prlctl enter <ve_id ve_name>

prlctl console <ve_id ve_name>

prlctl list [-a,--all] [-L] [-o,--output field[,field…]] [-s,--sort <field -field>] [-t,--template] [--vmtype <ct vm all>] [-j,--json]

prlctl list -i,--info [-f,--full] [ve_id ve_name] [-t,--template] [--vmtype ct vm all] [-j, --json]

prlctl migrate <[src_node/]ID> <dst_node[/NAME]> [--dst <path>] [--changesid] [--clone --remove-src] [--no-compression] [--no-tunnel] [--ssh <options>]

prlctl pause <ve_id ve_name> [OPTIONS]

prlctl problem-report <ve_id ve_name> <-d,--dump -s,--send [--proxy [user[:password]@proxyhost[:port]]] [--no-proxy]> [OPTIONS]

prlctl reinstall <ve_id ve_name> [--no-backup] [--resetpwdb] [--ostemplates <name>]

prlctl register <path> [--preserve-uuid --uuid <UUID>] [--regenerate-src-uuid] [--force] [OPTIONS]

prlctl reset <ve_id ve_name> [OPTIONS]

prlctl resume <ve_id ve_name> [OPTIONS]

prlctl restart <ve_id ve_name>

prlctl reset-uptime <ve_id ve_name>

prlctl set <ve_id ve_name> [--cpus <n>] [--cpu-sockets <n>] [--memsize <n>] [--videosize <n>]

• [--3d-accelerate <off highest dx9>] [--vertical-sync <on off>]
• [--cpuunits <n>] [--cpulimit <n>] [--cpumask <{n[,n,n1-n2] all}>] [--nodemask <{n[,n,n1-n2] all}>]
• [--cpu-hotplug <on off>]
• [--ioprio <priority>] [--iolimit <limit>] [--iopslimit <limit>]
• [--mem-hotplug <on off>]
• [--memguarantee <auto value>]
• [--description <desc>] [--autostart <on off auto>] [--autostart-delay <n>]
• [--autostop <stop suspend>]
• [--autocompact <on off>]
• [--tools-autoupdate <on off>]
• [--on-crash <pause restart>[:no-report]]
• [--vnc-mode <auto manual off>] [--vnc-port <port>] [{--vnc-passwd <passwd -> --vnc-nopasswd}] [--vnc-address <address>]
• [--name <name>] [--rename-ext-disks] [--userpasswd <user:passwd> [--host-admin <name>]]
• [--netfilter <disabled stateless stateful full>]
• [--swappages pages[:pages] --swap bytes] [--quotaugidlimit num]
• [--features name:on off[,…]]
• [--device-add <hdd cdrom net fdd serial usb> --device-del <name> [--destroy-image --destroy-image-force --detach-only] --device-set <name>]
• [--device-connect <name> --device-disconnect <name>]
• [--device-bootorder “<name1 name2 …>”]
• [--offline-management <on off>]
• [--hostname <hostname>] [--nameserver <addr>] [--searchdomain <addr>]
• [--rate <class:KBits>] [--ratebound <yes no>]
• [--applyconfig <conf>] [OPTIONS]
• [--nested-virt <on off>]
• [--efi-boot <on off>] [--select-boot-device <on off>] [--external-boot-device <name>]
• [--ha-enable <yes no>] [--ha-prio <number>]
• [--template <yes no>]
• [--backup-add <backup_id> [--disk <disk_name>]
• [--backup-del <backup_id all>]

prlctl start <ve_id ve_name> [OPTIONS]

prlctl stop <ve_id ve_name> [--kill] [OPTIONS]

prlctl snapshot <ve_id name> [-n,--name <name>]

prlctl snapshot-list <ve_id name> [{-t,--tree -i,--id <snapid>}]

prlctl snapshot-delete <ve_id name>“ -i,--id <snapid> [-c,--children]

prlctl snapshot-switch <ve_id name>” -i,--id <snapid>

prlctl suspend <ve_id ve_name> [OPTIONS]

prlctl unregister <ve_id ve_name> [OPTIONS]

prlctl mount <ve_id ve_name> [{-o <ro rw> --info}]

prlctl umount <ve_id ve_name>

prlctl move <ve_id ve_name> --dst <path>

prlctl statistics {<ve_id ve_name> -a,--all} [--filter <filter>] [--loop]

The prlctl utility is used to manage R-Virtualization servers and virtual environments (VEs) residing on them. A virtual environment can be referred to by its ID or name assigned to the VE during its creation.

The following flags can be used with the majority of prlctl commands.

• -l,--login user[[:passwd]@server - Connect to the remote R-Virtualization server using the IP address or hostname of server and the specified credentials (i.e. the user username and passwd password). If no connection parameters are specified, prlctl assumes that the command is run on the local server.
• -p,--read-passwd <file> - Use the password from the file file to log in to the remote R-Virtualization server whose connection parameters are specified after the --login option.
• -v,--verbose <n> - Configure the prlctl logging level.
• --timeout <sec> - Specify a custom operation timeout in seconds. By default, timeouts for all operation are unlimited.

• create <ve_name> -t,--ostemplate <name> [--vmtype ct vm] [--dst <path>] [--uuid <uuid>] [--changesid] - Create the virtual environment with the name of <ve_name> on the basis of the specified template. You can get the list of available templates using the prlctl list -t command.
  • Use the --changesid option to assign the new Windows-based virtual machine a new Windows security identifier (SID). Note: R-Virtualization Guest Tools must be installed in the virtual machine.
  • Use the --uuid option to manually specify the UUID to use.
• create <ve_name> [-o,--ostype <name list>] [--vmtype ct vm] [--dst <path>] [--uuid <uuid>] [--no-hdd] - Create the virtual environment with the name of <ve_name> and optimize it for use with the operating system (OS) family specified after the --ostype option, respectively. You can get the list of available os types using the prlctl create ve_name -o list command.
• create <ve_name> [-d,--distribution <name list>] [--vmtype ct vm] [--dst <path>] [--uuid <uuid>] [--no-hdd] - Create the virtual environment with the name of <ve_name> and optimize it for use with the operating system (OS) family specified after the --distribution option, respectively. You can get the list of available distributions using the prlctl create ve_name -d list command.
  • Use the --dst option to set the path to the directory on the R-Virtualization server where the <ve_uuid> directory with files of the newly created virtual environment will be stored.
  • Use the --no-hdd option to create virtual environment without hard disk drives.
  • After the virtual environment has been successfully created, you should install the corresponding operating system inside it.

• clone <ve_id ve_name> --name <new_name> [--template] [--dst <path>] [--changesid] [--linked] [--detach-external-hdd <yes no>] - Make a copy of a virtual environment and name it <new_name>. The difference between the original and the clone is that the clone is assigned a new MAC address.
  • Use the --template option to create a template of a virtual environment.
  • Use the --dst option to specify the path to the directory where the <ve_uuid> directory with files of the cloned virtual environment will be stored. If this option is omitted, the clone will be created in the default directory.
  • Use the --changesid option to assign the clone a new Windows security identifier (SID). Note: R-Virtualization Guest Tools must be installed in the original Windows-based virtual machine.
  • Use the --linked option is used to create a linked clone of the virtual environment.
  • Use the --detach-external-hdd <yes no> option to specify whether to keep or remove hard disks located outside of the original virtual environment. If you specify yes, outside hard disks will be removed from the resulting configuration. If you specify no, outside hard disks will remain in the resulting configuration. Note: In either case, outside hard disks will not be copied to the destination.
• delete <ve_id ve_name> - Remove the specified virtual environment from the R-Virtualization server by deleting all VE-related files and directories. You can use the --force option to forcibly stop the VE.
• installtools <ve_id ve_name> - Connect the R-Virtualization Guest Tools image to the VE using its CD/DVD-ROM device, so that the guest operating system is able to install or update the tools from it.
• exec <ve_id ve_name> <command> - Execute the command command in the virtual environment. For virtual machines, it requires R-Virtualization Guest Tools to be installed. Commands in Linux and Windows guests are run via bash -c “command” and cmd /c “command”, respectively. If the --without-shell option is specified, the command is run directly without bash or cmd shell.
• enter <ve_id ve_name> - Log in to the virtual environment. For virtual machines, it requires R-Virtualization Guest Tools to be installed.
• console <ve_id ve_name> - Attach to the Container’s console. To exit from the console, press “Esc” then “.” (Note: This sequence is only recognized after Enter). Note that you can even attach to a console if a Container is not yet running.
• capture <ve_id ve_name> [--file <path>] - Take a screenshot of a current virtual environment console in PNG format. If the --file option is specified, a screenshot is stored to the path path; otherwise, it is dumped to stdout.
• pause <ve_id ve_name> - Pause the specified virtual environment.
• problem-report <ve_id ve_name> <-d,--dump -s,--send [--proxy user[:password]@proxyhost[:port]]] [--no-proxy]> [OPTIONS] - Generate a problem report. If the -s,--send option is specified, the report is sent to R-Virtualization development team; otherwise, it is dumped to stdout.
• register <path> [--preserve-uuid --uuid <UUID>] [--regenerate-src-uuid] [--force] - Register the virtual environment whose configuration file has the path of path. If the --preserve-uuid option is specified, the virtual environment ID will not changed. If the --uuid option is specified, the provided UUID will be used for virtual environment ID, otherwise, it will be regenerated. If the --regenerate-src-uuid option is specified, the virtual environment source ID will be regenerated (SMBIOS product id will be changed as well). If the --force option is specified, all validation checks will be skipped.
• reinstall <ve_id ve_name> [--no-backup] [--resetpwdb] [--ostemplates <name>] - Recreates container’s root virtual disk, installs all applications previously installed from application templates, copies credentials from the old container (unless --resetpwdb is specified), and renames the old root directory ’/’ to ’/old’ (unless --no-backup is specified).
• reset <ve_id ve_name> - Reset the specified virtual environment.
• start <ve_id ve_name> - Start the specified virtual environment.
• restart <ve_id ve_name> - Restart the specified virtual environment.
• stop <ve_id ve_name> [--kill] - Stop the specified virtual environment. You can use the --kill option to forcibly stop the VE.
• status <ve_id ve_name> - Display the status of the specified virtual environment.
• unregister <ve_id ve_name> - Unregister the specified virtual environment.
• suspend <ve_id ve_name> - Suspend the specified virtual environment.
• resume <ve_id ve_name> - Resume the specified virtual environment.
• reset-uptime <ve_id ve_name> - Resets the specified virtual environment uptime counter (counter start date/time also will be reset with this action).
• mount <ve_id ve_name> [{-o <ro rw> --info}] - Mounts the specified virtual environment.
• umount <ve_id ve_name> - Unmounts the specified virtual environment.
• move <ve_id ve_name> --dst <path> - Moves the directory with files of the specified virtual environment to a new location on the same server.

Action scripts can be used to perform actions on containers at various stages of container operation. The following commands can trigger action scripts: start, stop, restart, mount, and umount.

Two types of scripts are supported: global, triggered for each container on host, and per-container, triggered for specific containers. Custom action scripts can be created manually and must be assigned specific file names to be triggered.

Custom action scripts can be of two types:

1. Global, executed for all containers on host. Such scripts must have the prefix ’vps’ (e.g., ’vps.mount’) and need to be placed in ’/etc/vz/conf/’.
2. per-container, executed for specific containers. Such scripts must not have the prefix ’vps’ and need to be placed in ’/vz/private/<CT_UUID>/scripts/’.

• vps.mount, mount - Executed after a container is mounted. Can be global or container-specific.
• start - Executed in container context on container start.
• stop - Executed in container context on container stop.
• vps.umount, umount - Executed before a container unmounted. Can be global or container-specific.

The environment passed to the mount and umount scripts is the standard environment of the parent (e.g., prlctl) with two additional variables: $VEID and $VE_CONFFILE. The first has the container UUID and the second has the full path to container’s configuration file. Other container configuration parameters required for the script (such as $VE_ROOT) can be obtained from the global and per-container configuration files.

• list [-a,--all] [-L] [-o,--output field[,field…]] [-s,--sort<field -field>] [-t,--template] [--vmtype <ct vm all>] [-j,--json] - List the virtual environments currently existing on the R-Virtualization server. By default, only running VEs are displayed.
  • -o, --output field[,field…] - Display only the specified field(s).
  • -s,--sort <field -field> - Sort by the value of field (arguments are the same as those for -o). Add - before the field name to reverse the sort order.
  • -L List fields which can be used for both the output (-o, --output) and sort order (-s, --sort) options. Use the --vmtype option to display fields pertaining to the specified virtual environment type.
  • --vmtype <ct vm all> - Display only virtual environments of the specified type.
  • -t, --template - Include templates in the output.
  • -j,--json - Produce output in the JSON format.
• list -i,--info [-f,--full] [ve_id ve_name] [-t,--template] [--vmtype ct vm all] [-j, --json] - Display the information on the VE configuration. By default, the information on all VEs currently existing on the R-Virtualization server is shown. Use the --full option to display additional information about virtual environments. You can also use the --json option to produce machine-readable output in JSON format.

• set <ve_id name> [SET_OPTIONS] - This command is used to set and configure various VE parameters.

The following options can be used with the set command.

• --cpus <num> - Set the number of CPU cores per CPU socket to be available to the VE.
• --cpu-sockets <num> - Set the number of CPU sockets to be available to the VE.
• --cpu-hotplug <on off> - Enable or disable CPU hot-plugging support in the virtual environment.
• --cpuunits <n> - Sets the CPU weight for the virtual environment. This is a positive integer number that defines how much CPU time the virtual environment can get as compared to the other virtual environments running on the server. The larger the number, the more CPU time the virtual environment can receive. Possible values range from 8 to 500000. If this parameter is not set, the default value of 1000 is used.
• --cpulimit <n> - Sets the CPU limit, in percent or megahertz (MHz), the virtual environment is not allowed to exceed. By default, the limit is set in percent. To specify the limit in MHz, specify “m” after the value. Note: If the computer has 2 CPUs, the total CPU time equals 200%.
• --cpumask <{n[,n,n1-n2] all}> - Defines the CPUs on the physical server to use for executing the virtual environment process. A CPU affinity mask can be a single CPU number or a CPU range separated by commas (0,2,3-10).
• --nodemask <{n[,n,n1-n2] all}> - Defines the NUMA node on the physical server to use for executing the virtual environment process. A node mask can be a single number or a range separated by commas, e.g., 0,2,3-10.

• --memsize <num> - Set the amount of memory that the virtual environment can consume.
• --mem-hotplug <on off> - Enable or disable memory (RAM) hot-plugging support in the virtual environment.
• --memguarantee <auto value> - Set the amount of memory (RAM) that will be guaranteed to a virtual machine or container. The guaranteed memory is a percentage of total RAM that is set for the virtual machine or container with the --memsize option. By default, memory guarantee is set to ’auto’ (depends on vcmmd policy for virtual machine and no guarantee for containter).

• --device-bootorder <“name1 name2 …”> - Used to specify the order of boot devices for a virtual environment. Supported devices are HDD, CD/DVD, FDD, Network. A device name can obtained using the ’prlctl list -i’ command.
• --efi-boot <on off> - Set EFI boot options:
  • on: The virtual environment is booting using the EFI firmware.
  • off: The virtual environment is booting using the BIOS firmware. This option is used by default.
• --select-boot-device <on off> - Enable or disable the selection of a boot device at the virtual environment startup.
• --external-boot-device <name> - Set an external device from which to boot the virtual environment.

• --videosize <num> - Set the amount of memory for the virtual environment graphic card.
• --3d-accelerate <off highest dx9> - Set 3d acceleration video mode.
• --vertical-sync <on off> - Set vertical synchronization video mode.

• --ioprio <priority> - Assigns I/O priority to VE. priority range is 0-7. The greater priority is, the more time for I/O activity VE has. By default each VE has priority of 4.
• --iolimit limit[B K M G] - Sets the I/O limit for the virtual environment. If no suffix is specified, the parameter is set in megabytes per second. The possible suffixes are listed below:
  • b, B -- bytes
  • k, K -- kilobytes
  • m, M -- megabytes
  • g, G -- gigabytes
  • By default, the I/O limit of each virtual environment is set to 0 (that is, not limited).

• --iopslimit <limit> - Assigns Input/Output Operations Per Second limit.

--apply-iponly <yes no> - If set to “yes”, the hostname, nameserver, and search domain settings from the virtual environment/Container configuration file are ignored.

• --netfilter <disabled stateless stateful full> - Restrict access to iptable modules inside the Container. The following modes are available:
  • disabled -- no modules are allowed.
  • stateless -- all modules except NAT and conntracks are allowed.
  • stateful -- all modules except NAT are allowed.
  • full -- (default) all modules are allowed.
  • Note: This parameter cannot be applied to running Containers.
• --swappages pages[:pages] --swap bytes - This parameter limits the amount of swap space that can be allocated to processes running in a Container.
• --quotaugidlimit num - Sets the maximum number of user/group IDs in a Container for which disk quota is calculated. If this value is set to 0, user and group disk quotas are not calculated. For ploop-based Containers, quotaugidlimit can be only enabled or disabled. Setting the num parameter to a value greater than 0 enables the quota, and 0 disables the quota.

• --features name:on off[,…] - Enables/disables feature for CT. Multiple comma-separated values can be specified. You can use the following values for name: bridge, ipgre, ipip, nfs, nfsd, ppp, sit, time.

• --vnc-mode <auto manual off> - Enables/disables access to the virtual environment via the VNC protocol. A password is required to enable VNC support, or the --vnc-nopasswd option must be used.
• --vnc-port <port> - Sets the VNC port.
• --vnc-passwd <passwd -> - Sets the VNC password to passwd. If - is specified, user is prompted to enter the password or, in case the standard input is redirected (e.g. by using command pipeline), the password is read from the standard input.
• --vnc-nopasswd - Do not require a password for VNC connections.
• --vnc-address <address> - Sets the VNC address.

• --ha-enable <yes no> - Adds the virtual environment to (yes) or removes it (no) from the High Availability Cluster. By default, the parameter is set to yes.
• --ha-prio <number> - Sets the virtual environment priority in the High Availability Cluster. Virtual environments with a higher priority are restarted first in the case of a system failure. If the parameter is not set for a virtual environment (default), it has the lowest priority and is restarted after all virtual environments with any priorities set.

• --nested-virt <on off> - Disable or enable nested virtualization.

• --applyconfig <path> - Apply the resource parameter values from the specified VE configuration file to the virtual environment. The parameters defining the OS family and OS version are left intact.
• --description <desc> - Set the VE description.
• --name <name> - Change the VE name.
• --rename-ext-disks - Rename bundles of the external disks on vm rename. That is move external disk from path /somewhere/old-vm-name.pvm/diskname to /somewhere/new-vm-name.pvm/diskname.
• --autostart <on off auto> - Set the virtual environment start-up options:
  • on: The virtual environment is started automatically on the R-Virtualization server boot. \
  • off: The virtual environment is left in the stopped state on the R-Virtualization server boot.
  • auto: The virtual environment is returned to the state it was in when the R-Virtualization server was turned off.
• --autostart-delay <n> - Delay some seconds at virtual environment autostart.
• --autostop <stop suspend> - Specifies the mode to set the virtual environment on the R-Virtualization Service shutdown.
• --autocompact <on off> - Turns on/off automatic virtual disk image compact.
• --tools-autoupdate <on off> - Turns on/off automatic updating of R-Virtualization Guest Tools in the guest operating system. If this option is set to on, R-Virtualization Guest Tools updates will be performed automatically every time an update is available for R-Virtualization software. If this option is set to off, no automatic R-Virtualization Guest Tools updates will be performed, so that you can do it manually at a convenient time.
• --on-crash <pause restart>[:no-report] - Specifies what to do with the virtual environment if it crashes: pause or restart. The problem report is sent by default. To omit, specify no-report.
• --userpasswd <user:passwd> - Sets the password for the specified user in the virtual environment. If the user account does not exist, it is created. R-Virtualization Guest Tools must be installed in the virtual environment for the command to succeed. If the --crypted parameter is specified, the system assumes that the passwords are encrypted (for Containers only).
• --host-admin <name> - Specifies a host OS administrator’s name if an administrator’s password is required to change the password for the specified user in the virtual environment.
• --template <yes no> - Convert the virtual environment to template and vice versa.

The following options can be used to manage VE devices: --device-add, --device-set, and --device-del, --device-connect, --device-disconnect. Only one option can be specified at a time.

--device-add <hdd cdrom net fdd serial usb pci> [device_options]

--device-add hdd [--image <image_name>] [--recreate] [--size <n>] [--iface <ide scsi virtio>] [--subtype <virtio-scsi hyperv>] [--position <n>] [--mnt <path>]

• image_name: the image file to be used to emulate the VE virtual hard disk. To use an existing image file, specify its name and path. To create a new image file, omit the --image option (a new file named harddiskN.hdd will be created in the VE directory) or use --recreate option.
• size: the size of the hard disk drive, in megabytes. If the --no-fs-resize option is specified, the last partition on the hard disk is not resized.
• iface: virtual hard disk interface type: either ide or scsi or virtio.
• subtype: SCSI controller subtype: virtio-scsi (default) or hyperv.
• position: the SCSI or IDE device identifier to be used for the disk drive. Allowed ranges:
  • 0-3 for IDE disk drives
  • 0-6 for SCSI disk drives
• mnt: the mount point to automount virtual hard disk inside the container’s guest OS

--device-add hdd --encryption-keyid <key_id> [other HDD options] --device-set hdd --encrypt --encryption-keyid <key_id> [--no-wipe] --device-set hdd --decrypt [--no-wipe] --device-set hdd --encryption-keyid <key_id> [--no-wipe] [--reencrypt]

• encrypt: encrypt the hard disk drive contents with an encryption key given in the --encryption-keyid option
• decrypt: decrypt the encrypted hard disk drive
• encryption-keyid: the identifier of a key used to encrypt the hard disk drive. When this option is used along with the --encrypt option, the provided key identifier is used to encrypt the non-encrypted virtual disk drive. When this option is used with the --device-set command, the already existing encryption key is changed to the provided one.
• \\reencrypt: re-encrypt the entire disk contents when changing the encryption key identifier. When the --device-set command is called with the --encryption-keyid option, only a small amount of encrypted data (i.e. LUKS header) is changed in the virtual disk drive. When the --reencrypt option is added to the command above, the entire disk contents are re-encrypted.
• no-wipe: remove the original virtual hard disk after it had been encrypted without securely erasing its data from the host disk drive. Without this option, after a virtual disk had been successfully encrypted, the original unencrypted data is securely erased from the host hard disk drive.

--device-add hdd --device <name> [--iface <ide scsi virtio>] [--position <n>]

• device: the name of the physical hard disk on the R-Virtualization server to be connected to the VE. You can use the server info command to view the name of all physical disks currently existing on the R-Virtualization server.
• iface: virtual hard disk interface type: either ide or scsi or virtio.
• position: the SCSI or IDE device identifier to be used for the disk drive. Allowed ranges:
  • 0-3 for IDE disk drives
  • 0-6 for SCSI disk drives

--device-add cdrom --image <name> [--iface <ide scsi>] [--subtype <virtio-scsi hyperv>] [--position <n>]

• image: connect the specified image file (either on the R-Virtualization server or on the client computer where you are running the prlctl utility) to the virtual environment. The following image file formats are supported: .iso, .cue, .ccd, and .dmg.
• iface: virtual CD/DVD-ROM interface type: either ide or scsi.
• subtype: SCSI controller subtype: virtio-scsi (default) or hyperv.
• position: the SCSI or IDE device identifier to be used for the DVD/CD-ROM drive. Allowed ranges:
  • 0-3 for IDE disk drives
  • 0-6 for SCSI disk drives

--device-add cdrom --device <name> [--iface <ide scsi>] [--position <n>]

• device: the name of the physical DVD/CD-ROM on the R-Virtualization server to be connected to the VE. You can use the server info command to view the name of all DVD/CD-ROM drives currently existing on the R-Virtualization server.
• iface: virtual CD/DVD-ROM interface type: either ide or scsi.
• position: the SCSI or IDE device identifier to be used for the DVD/CD-ROM drive. Allowed ranges:
  • 0-3 for IDE disk drives
  • 0-6 for SCSI disk drives

--device-add fdd

--device-add fdd --device <name>

--device-add net {--type routed --network <network_id>} [--mac <addr auto>] [--ipadd <ip> --ipdel <ip> --dhcp <yes no> --dhcp6 <yes no] [--gw <gw>] [--gw6 <gw>] [--nameserver <addr>] [--searchdomain <addr>] [--configure <yes no>] [--ipfilter <yes no>] [--macfilter <yes no>] [--preventpromisc <yes no>] [--adapter-type <virtio hyperv e1000 rtl>]

• type: the type of the network adapter to create in the virtual environment.
• network_id: the name of the virtual network on the R-Virtualization server where the VE virtual adapter will be connected.
• mac: the MAC address to be assigned to the virtual network adapter. If you omit this option, the MAC address will be automatically generated by the R-Virtualization software.
• ipadd: the IP address to be assigned to the network adapter in the virtual environment.
• ipdel: the IP address to be removed from the network adapter in the virtual environment.
• dhcp: specifies whether the virtual network adapter should get its IP settings through a DHCP server.
• dhcp6: specifies whether the virtual network adapter should get its IPv6 settings through a DHCP server. Use the --ipadd option to switch from DHCP to a static IP address.
• gw: the default gateway to be used by the virtual environment.
• gw6: the default IPv6 gateway to be used by the virtual environment.
• nameserver: the default DNS server to be used by the virtual environment.
• searchdomain: the default search domain to be used by the virtual environment.
• configure: if set to “yes”, the settings above are applied to the virtual network adapter instead of its original settings. Configuring any of the settings above automatically sets this option to “yes”.
• ipfilter: determines if the specified network adapter is configured to filter network packages by IP address. If set to “yes”, the adapter is allowed to send packages only from IPs in the network adapter’s IP addresses list.
• macfilter: determines if the specified network adapter is configured to filter network packages by MAC address. If set to “yes”, the adapter is allowed to send packages only from its own MAC address.
• preventpromisc: determines if the specified network adapter should reject packages not addressed to its virtual environment. If set to “yes”, the adapter will drop packages not addressed to its virtual environment.
• adapter-type: specifies network adapter emulation type.

--device-add serial {--device <name> --output <file> --socket <file> [--socket-mode <server client>] --socket-tcp <ip:port> [--socket-mode <server client>] --socket-udp <ip:port> [--socket-mode <server client>]}

• device: the number of the serial port on the R-Virtualization server to be used by the VE.
• output: the path to the file where the output of the virtual serial port will be sent.
• socket: the name of the physical socket on the R-Virtualization server where the serial port is to be connected. You can use the --socket-mode option to configure the port to operate in client or server mode. By default, server mode is enabled.
• socket-tcp: the address of the socket on the R-Virtualization server where the serial port is to be connected. This socket uses TCP protocol. You can use the --socket-mode option to configure the port to operate in client or server mode. By default, server mode is enabled.
• socket-udp: the address of the socket on the R-Virtualization server where the serial port is to be connected. This socket uses UDP protocol and operates in both client and server modes.

--device-add <usb>

• --device-add <pci> --device <name> - Connects the specified VT-d PCI device to the virtual environment. To list the available devices, use the prlsrvctl info command.
• --device-set <device_name> [--enable --disable] [--connect --disconnect] - Used to configure various parameters of the specified virtual device. After its adding to the virtual environment, any device gets its own name (<name>) and can be managed using this name. You can use any of the parameters available to --device-add with --device-set.
• --device-del <device_name> [--detach-only --destroy-image] - Removes the specified device from the virtual environment. If --detach-only is specified and the device is a virtual hard disk drive, the disk image is preserved. If --destroy-image is specified, the virtual HDD image is removed from the server. If --destroy-image-force is specified, the virtual HDD image is removed from all snapshots and from the server. The default action on deleting a virtual HDD is to preserve the HDD image as if --detach-image was specified.
• --device-connect <device_name> - Used to connect the specified device to a running VE. Supported device types: fdd, cdrom, net. The device name could be obtained using the ’prlctl list -i’ command.
• --device-disconnect <device_name> - Disconnect the specified device.
• --backup-add <backup_id> [[--disk <disk_name>] [--iface <ide scsi>] [--position <n>] - Attach a backup to a virtual environment.
  • backup_id: The identifier of the backup to attach. To list available backups, use the backup-list command. Please note that only backups on localhost can be attached.
  • disk_name: The name of the disk in the backup to attach. If a disk is not specified, all disks contained in the backup will be attached. To list disks contained in a backup, use the backup-list -f command.
  • iface: Virtual hard disk interface: ide, scsi.
  • position: The SCSI, IDE device identifier to be used for the disk drive. Allowed ranges:
    • 0-3 for IDE disk drives
    • 0-6 for SCSI disk drives
• --backup-del <backup_id all> - Detach either the backup with the identifier backup_id or detach all backups from the virtual environment.
  

The following command and options can be used to back up and restore a virtual environment. The --storage option allows you to specify the backup server. If this option is omitted, the local server is used.

• backup <ve_id ve_name> [-f,--full] [-i,--incremental] [-s,--storage <user[[:passwd]@server[:port]>] [--description <desc>] [--no-compression] [--no-tunnel] [--no-reversed-delta] - Backs up the specified virtual environment.
  • -f,--full - Create a full backup of the virtual environment. A full backup contains all virtual environment data.
  • -i,--incremental - Create an incremental backup of the virtual environment. An incremental backup contains only the files changed since the previous full or incremental backup. This is the default backup type.
  • --no-compression - Do not compress backup image.
  • --no-reversed-delta - Do not create an intermediate temporary image for reversed delta writes.
  • --no-tunnel - Do not use connection tunneling for backup. Connection tunneling is enabled for backup by default to provide secure data transmission.
• backup-list [ve_id ve_name] [-f,--full] [--vmtype ct vm all][--localvms] [-s,--storage <user[[:passwd]@server[:port]>] - Lists the existing backups. If the --localvms option is specified, list only backups that were created on the local server.
• restore {<ve_id> -t,--tag <backup_id>} [-s,--storage<user[[:passwd]@server[:port]>] [-n,--name <new_name>] [--dst <path>][--no-tunnel] - Restore the specified virtual environment. Only stopped virtual environments can be restored. If backup_ID is not specified, the latest backup version is restored.
  • -n,--name <new_name> - Restore the virtual environment and assign the name new_name to it.
  • --dst <path> - Restore the virtual environment data to the specified directory on the R-Virtualization server.
  • --no-tunnel - Do not use connection tunneling for restore. Connection tunneling is enabled for restore by default to provide secure data transmission.
  • --live - Live restore reduces VM downtime by starting the restored VM right after the restore process begins.=
• backup-delete {<ve_id> -t,--tag <backup_id>} [--keep-chain] - Delete the backup for specified virtual environment. If --keep-chain is specified, the rest of the backup chain is preserved.

The following options can be used to migrate a virtual environment from the source server src to the destination server dst. If the virtual environment is running, the migration is performed as follows. First, virtual environment data is copied to the destination server, then the virtual environment is suspended, and, finally, the remaining data is migrated. After the virtual environment has been successfully migrated, it is removed from the source server.

• migrate <[src/]ID> <dst[/NAME]> [--dst <path>] [--changesid] [--clone --remove-src] [--no-compression] [--ssh <options>] - Migrates the specified virtual environment from the source server src to the destination server dst. The source and destination servers must be specified in this format: [user[:password]@]server_IP_address_or_hostname[:port]. If the source server is omitted, the local server is assumed.
  • --changesid - This option is used to change the current Windows security identifier (SID) of a Windows-based virtual machine template. It requires R-Virtualization Guest Tools to be installed in the virtual machine template.
  • --clone - If this option is provided, the original virtual environment will be cloned to destination and left intact on the source server. The clone will have a different UUID, MAC address, and SID (Windows-based virtual machines only; if --changesid is used) and will have offline management disabled. If this option is omitted, the original virtual environment will be removed from the source server after migration.
  • --remove-src - If this option is provided, the source bundle will be removed after migration. Cannot be used together with --clone. This option is enabled for virtual machines by default.
  • --no-compression - Do not compress data during migration.
  • --no-tunnel - Do not use connection tunneling for migration. Connection tunneling is enabled for migration by default to provide secure data transmission.
  • --ssh <options> - Options to pass to ssh when it is used to establish a connection to the destination server. Any of the standard ssh options are allowed.

• snapshot <ve_id name> [-n,--name <name>] - This command is used to create VE snapshot. Note: Taking a snapshot of a running VE saves not only its filesystem state but in-memory state as well.
• snapshot-list <ve_id name> [{-t,--tree] [-i,--id <snapid>}] - This command is used to list the virtual environment’s snapshots tree. There are three modes of snapshot listing, if no option specified the snapshot tree represented in two columns “PARENT_SNAPSHOT_ID SNAPSHOT_ID”. If -t,--tree option is specified draw the tree. If -i,--id <snapid> option is specified, display the snapshot information
• snapshot-delete <ve_id name> -i,--id <snapid> [-c,--children] - Deletes snapshot with the specified snapid. If the -c,--children option is specified, all snapshot’s children are also deleted. Otherwise they become the children of the deleted snapshot’s parent.
• snapshot-switch <ve_id name> -i,--id <snapid> - Used to revert to selected snapshot.

• --hostname <hostname> - Sets the hostname for the virtual environment. For virtual machines, R-Virtualization Guest Tools must be installed in the virtual machine.

• --offline-management <on off> - Enable/disable the offline management feature. This feature defines whether the virtual environment can be managed using the services set by the --offline-management option.
• --offline-service <service_name> Defines whether the virtual environment can be managed by means of R-Virtualization Power Panel or Plesk or both. Valid only if the OFFLINE_MANAGEMENT parameter is set to “yes”. The names of the available services can be taken from the file names (excluding the .conf extension) in the /etc/vzredirect.d directory on the server.

• --rate <class:KBits> - Specifies the bandwidth guarantee of the virtual environment for the specified network class.
• --ratebound <yes no> - If set to “yes”, the bandwidth guarantee is also the limit for the virtual environment. If set to “no”, the bandwidth limit is defined by the TOTALRATE parameter in the /etc/vz/vz.conf file.

• statistics {<ve_id ve_name> -a,--all} [--filter <filter>] [--loop] - Print performance statistics for running virtual machines and containers on the server.
  • --filter <filter> - Specifies the subset of performance statistics to collect and print. If omitted, all available statistics are shown. Asterisks (“*”) can be used as wildcards for any number of arbitrary characters. The available filters are listed below (“#” is the device or filesystem index).

• devices.ide#.read_requests - Total count of read requests to IDE controller
• devices.ide#.read_total - Total count of bytes read through IDE controller
• devices.ide#.write_requests - Total count of write requests to IDE controller
• devices.ide#.write_total - Total count of bytes written through IDE controller
• devices.scsi#.read_requests - Total count of read requests to SCSI controller
• devices.scsi#.read_total - Total count of bytes read through SCSI controller
• devices.scsi#.write_requests - Total count of write requests to SCSI controller
• devices.scsi#.write_total - Total count of bytes written through SCSI controller
• devices.sata#.read_requests - Total count of read requests to SATA controller
• devices.sata#.read_total - Total count of bytes read through SATA controller
• devices.sata#.write_requests - Total count of write requests to SATA controller
• devices.sata#.write_total - Total count of bytes written through SATA controller

• net.nic#.pkts_in - Total number of packets incoming through network adapter
• net.nic#.pkts_out - Total number of packets outgoing through network adapter
• net.nic#.bytes_in - Total number of bytes incoming through network adapter
• net.nic#.bytes_out - Total number of bytes outgoing through network adapter

Result is provided in 5 columns:

• net.classful.traffic - Total counters for IPv4 and IPv6 traffic
• net.classful.traffic.ipv4 - Counters for IPv4 traffic
• net.classful.traffic.ipv6 - Counters for IPv6 traffic

• guest.cpu.usage - Guest OS CPU usage, in percent
• guest.cpu.time - Sum of guest CPU time differences since the last query for each vCPU averaged by the number of host CPUs, in microseconds
• host.cpu.time - Sum of host CPU time differences since the last query for each CPU averaged by the number of host CPUs, in microseconds
• guest.vcpu#.time - per-vCPU statistics, in nanoseconds

• guest.ram.usage - Guest OS used RAM, in MiB
• guest.ram.cached - Guest OS cached RAM, in MiB
• guest.ram.total - Guest OS total RAM, in MiB
• guest.ram.swap_in - Guest OS virtual memory stats, in counts
• guest.ram.swap_out - Guest OS virtual memory stats, in counts
• guest.ram.minor_fault - Guest OS minor page fault count
• guest.ram.major_fault - Guest OS major page fault count
• guest.ram.balloon_actual - Guest OS balloon size, in MiB

• guest.fs#.name - Device name for the filesystem as seen from inside guest
• guest.fs#.total - Total size of the filesystem, in bytes
• guest.fs#.free - Amount of free space on the filesystem, in bytes
• guest.fs#.disk.# - Disk indices

• --loop - Print statistics every second until the program is terminated.
• --all - Print statistics for all running virtual machines and containers on the server.

prlctl returns 0 upon successful command execution. If a command fails, it returns the appropriate error code.

To create and start a VM having the name of win2003 and based on the ’Windows XP’ template:

prlctl create win2003 --ostemplate ’Windows XP’ prlctl start win2003

To stop the win2003 VE:

prlctl stop win2003 

To remove the win2003 virtual environment from the R-Virtualization server:

prlctl delete win2003 

To list all virtual environments, displaying the real IP addresses instead of the configured ones:

prlctl list -a -o uuid,status,ip,type,name -s name 

prlsrvctl(8)

Copyright © 2012-2017 R-Platforma LLC, All rights reserved. Copyright © 2017-2019 R-Platforma LLC, All rights reserved.