Parallels Desktop Pro Edition - 15.0 Command-Line Reference

Parallels Desktop for Mac Pro Edition

Command-Line Reference

v15

Parallels International GmbH Vordergasse 59 8200 Schaffhausen Switzerland Tel: + 41 52 672 20 30 www.parallels.com

This product is protected by United States and international copyright laws. The product’s underlying technology, patents, and trademarks are listed at http://www.parallels.com/about/legal/.

Microsoft, Windows, Windows Server, Windows Vista are registered trademarks of Microsoft Corporation. Apple, Mac, the Mac logo, OS X, macOS, iPad, iPhone, iPod touch are trademarks of Apple Inc., registered in the US and other countries. Linux is a registered trademark of Linus Torvalds. All other marks and names mentioned herein may be trademarks of their respective owners.

Contents

Introduction ............................................................................................................... 4

Command-Line Reference ........................................................................................ 5

Parallels Desktop Management ....................................................................................... 5

Display Parallels Desktop Info ...................................................................................................5

License Management ...............................................................................................................6

Parallels Desktop Preferences ..................................................................................................8

User List and Virtual Machine Location .................................................................................. 10

Virtual Network Info ............................................................................................................... 10

Virtual Network Settings ........................................................................................................ 10

USB Devices ......................................................................................................................... 12

Send Problem Report ............................................................................................................ 12

Shut Down Parallels Desktop ................................................................................................ 13

Parallels Desktop Plugin Commands ..................................................................................... 13

Error Handling ....................................................................................................................... 13

Virtual Machine Management ......................................................................................... 13

General Virtual Machine Management ................................................................................... 14

Virtual Machine Configuration Tasks ...................................................................................... 22

Snapshot Management ......................................................................................................... 39

Miscellaneous Commands .................................................................................................... 41

Error Handling ....................................................................................................................... 42

Index ........................................................................................................................ 43

C HAPTER 1

Introduction

This guide is intended for users of Parallels Desktop for Mac Pro Edition. It documents the command-line interface that can be used to manage Parallels Desktop and virtual machines. The interface supports the majority of Parallels Desktop management tasks that can be performed using the Parallels Desktop graphical user interface.

The command-line interface includes the following utilities:

• prlsrvctl — the utility is used to manage Parallels Desktop. The tasks include getting general

information about Parallels Desktop, modifying Parallels Desktop preferences, getting a list of users, obtaining statistics, installing a license, and others.

• prlctl — the utility is used to manage virtual machines. The tasks include creating and

configuring virtual machines, snapshot management, cloning operations, installing Parallels Tools, obtaining statistics, generating problem reports, and many others.

The command-line utilities are installed on a Mac as part of Parallels Desktop installation. You can run the utilities in Terminal.

C HAPTER 2

Command-Line Reference

In This Chapter

Parallels Desktop Management ............................................................................... 5

Virtual Machine Management .................................................................................. 13

Parallels Desktop Management

The prlsrvctl command-line utility is used to perform management tasks on Parallels Desktop. The tasks include getting the Parallels Desktop information, modifying Parallels Desktop preferences, installing a license, obtaining statistics and problem reports, and others.

The general syntax is as follows:

prlsrvctl command [options] [-v, --verbose number]

The parameters are:

• command: one of the available commands.

• options: command options.

• -v, --verbose number: Show verbose output. The greater the number, the more verbose

output will be produced.

The subsequent sections describe the available prlsrvctl commands grouped by functionality.

Display Parallels Desktop Info

prsrvctl info

Displays the detailed information about the Parallels Desktop configuration.

Optional parameters

--license

If included, only the Parallels Desktop license information is displayed.

--activation-id

Command-Line Reference

If included, only the license activation ID is displayed.

--deactivation-id

If included, only the license deactivation ID is displayed.

--json

Produces the machine-readable output in JSON format.

License Management

This section describes Parallels Desktop license management tasks.

Sign in to Parallels Account

web-portal signin <email>

Sign in to your Parallels account. The <email> parameter specifies your registered email address. When prompted, enter your Parallels account password. You can also specify a file containing the password using an optional parameter (see below).

This command must be used before you activate Parallels Desktop Pro or Home editions from the command line using the install-license command.

Optional parameters

-p,--read-passwd <path>

Specifies a text file with your Parallels account password.

Related commands

web-portal signout

Signs you out of your Parallels account.

info --web-portal

Displays the information about whether you are signed in to your Parallels account and lists details if you are.

Install a Parallels Desktop License

prlsrvctl install-license <-k, --key <key>>

Installs a Parallels Desktop license. The -k, --key <key> parameter specifies a Parallels Desktop license key to install.

Command-Line Reference

Optional parameters

-n, --name <name>

The license owner name.

-c, --company <name>

The license company name.

--deferred

Stores the license for deferred installation. The license will be activated the next time Parallels Desktop is started. If a license has already been activated, it should be deactivated first before using this option. See the prlsrvctl deactivate-license command.

--activate-online-immediately

Activates the license over the Internet immediately.

Notes

When activating Parallels Desktop Pro or Home editions, you must be signed in to your Parallels account before executing this command. See Sign in to Parallels Account (p. 6).

Install / Remove a Deferred License

prlsrvctl deferred-license <--install | --remove>

Installs or removes a license stored for deferred installation.

Parameters

--install

Installs the license stored for deferred installation.

--remove

Removes the license stored for deferred installation.

Update a License

prlsrvctl update-license

Updates the current Parallels Desktop license.

Activate a License Online

prlsrvctl activate-license-online

Command-Line Reference

Activates the installed Parallels Desktop license over the Internet.

Notes

This command is no longer used in Parallels Desktop v14 and later.

Activate a License Offline

prlsrvctl install-license-offline -f, --file <path-to-license-file>

Activates the installed Parallels Desktop license offline.

Deactivate a License

prlsrvctl deactivate-license [--skip-network-errors]

Deactivates the current Parallels Desktop license. The --skip-network-errors option skips network errors and removes the license locally.

Parallels Desktop Preferences

prlsrvctl set

The prlsrvctl set command is used to modify Parallels Desktop preferences. The available parameters and options are described below.

Parameters

--mem-limit <auto | size>

Sets the total memory allocated to Parallels Desktop and its virtual machines. The auto option optimizes the memory usage. The size option allows the user to set the memory size manually.

-s, --min-security-level <low | normal | high>

Specifies the minimum connection security level to connect to the server. Low - no transmitted data is encrypted. Normal - only the most important data is encrypted. High - all transmitted data is encrypted.

-c, --cep <on | off>

Enables or disables the participation in the Customer Experience Program.

--verbose-log <on | off>

Enables or disables verbose logging.

--log-rotation <on | off>

Command-Line Reference

Enables or disables automatic rotation of the Parallels Dispatcher Service and virtual machine log files.

--allow-attach-screenshots <on | off>

Enables or disables attaching virtual machine and host screenshots to a problem report.

--require-pwd <create-vm | add-vm | remove-vm | clone-vm>:<on | off>

Require to enter an administrator password to perform a corresponding action (create a VM, add a VM, etc.).

Require to enter a custom password to perform a corresponding action.

--custom-pwd [--custom-pwd-mode <on | off | change>] [--replace-commands]

Set, reset, or change the custom password for operations that require it. See the explanation of parameters below.

--custom-pwd-mode <on | off | change> — set, reset, or change the custom password for operations which require it.

--replace-commands — specify this option to reset commands that are protected with the admin password. This means that when you enable a custom password, commands that require the admin password will now require a custom password. Commands that previously required a custom password will be discarded. The same logic is used when you switch back to the admin password (set --custom-pwd-mode to off). When you disable a custom password, commands that require it will now require the admin password. Commands that previously required the admin password will be discarded. This option is ignored if --custom-

pwd-mode is set to change.

--lock-edit-settings <on | off [--host-admin <name>]>

Locks or unlocks Parallels Desktop preferences for editing. The --host-admin parameter specifies the host administrator name if an administrator password is required to unlock Parallels Desktop preferences for editing.

--external-dev-auto-connect <host | guest | ask>

When a new external device is attached to the Mac, connect it to the host, guest, or ask the user what to do.

--default-encryption-plugin <plugin-id>

Sets the default encryption plugin.

--reset-default-encryption-plugin

Resets the default encryption plugin.

Command-Line Reference

--hide-license-request-params <on | off>

Hides the host name and user name in requests to Parallels Licensing Server.

User List and Virtual Machine Location

prlsrvctl user list [-o, --output field [,field...]] [-j, --json]

Lists users currently existing in Parallels Desktop. The -o, --output field [,field...] option is used to display the specified field(s) only.

prlsrvctl user set <--def-vm-home <path>>

Modifies the default virtual machines location to the specified path.

Virtual Network Info

prlsrvctl net info <vnetwork_id>

Displays a detailed information about the specified virtual network.

prlsrvctl net list [-j, --json]

Lists existing virtual networks.

Virtual Network Settings

prlsrvctl net set <vnetwork_id> [options]

The prlsrvctl net set command is used to modify virtual network settings. The available parameters and options are described below.

Parameters

-i, --ifname <if>

Sets the name of the network interface in Parallels Desktop to which the virtual network will be bound.

-m, --mac <mac>

Sets the MAC address of the network interface in Parallels Desktop to which the virtual network will be bound. The network interface with the specified MAC address must exist in Parallels Desktop.

-t, --type <bridged | host-only | shared>

Sets the virtual network type.

Command-Line Reference

-d, --description <description>

Sets the virtual network description.

-n, --name <new_name>

Sets a new name for the virtual network.

--ip <ip[/mask]>

Sets an IPv4 address and subnet mask for the Parallels virtual network adapter.

--dhcp-server <on | off>

Enables or disables the Parallels virtual DHCPv4 server.

--dhcp-ip <ip>

Sets an IPv4 address for the Parallels virtual DHCPv4 server.

--ip-scope-start <ip>

Sets the start IPv4 address for the pool of IPv4 addresses.

--ip-scope-end <ip>

Sets the end IPv4 address for the pool of IPv4 addresses.

--ip6 <ip[/mask]>

Sets an IPv6 address and subnet mask for the Parallels virtual network adapter.

--dhcp6-server <on | off>

Enables or disables the Parallels virtual DHCPv6 server.

--dhcp-ip6 <ip>

Sets an IPv6 address for the Parallels virtual DHCPv6 server.

--ip6-scope-start <ip>

Sets the start IPv6 address for the pool of IPv6 addresses.

--ip6-scope-end <ip>

Sets the end IPv6 address for the pool of IPv6 addresses.

--host-assign-ip6 <on | off>

Sets whether the host interface for this network will have IPv6 address.

--connect-host-to-net <on | off>

Connects the host to the current Parallels virtual network adapter.

Command-Line Reference

--nat-<tcp | udp>-add <rule_name, src_port,<dest_ip | dest_vm>, dest_port>

Adds a new port forwarding rule. The options are:

rule_name: a rule name.

src_port: port number for incoming connections.

dest_ip: an IP address to which incoming connections will be forwarded.

dest_vm: the name or UUID of the virtual machine to which incoming connections will be

forwarded.

dest_port: port number to which incoming connections will be forwarded.

--nat-<tcp | udp>-del <rule_name>

Deletes the specified port forwarding rule.

USB Devices

prlsrvctl usb list [-j, --json] [-c, --compat] [-a, --all]

Lists USB devices installed on the server together with the information on their assignments for the current user. In the compat mode all known USB devices are listed, showing the device name, device ID and autoconnect options. In the new mode (without the [-c, --compat] option), some additional information about the device is shown, such as whether the device is connected to a VM at the current moment. By default, only currently plugged to host devices are shown. To see all devices, call with the [-a, --all] option.

Either assigns a USB device with ID <usb_dev_id> to the specified virtual machine or configures the action for this device (suggest to connect to active VM or silently connect to host). When the device is configured to connect to a virtual machine, this USB device will be connected to the specified virtual machine when you start the virtual machine or attach the device to the host computer.

prlsrvctl usb del <usb_dev_id>

Removes a specified USB device assignment.

Send Problem Report

prlsrvctl problem-report <-d, --dump | -s, --send [--proxy <user[:password]@proxyhost[:port]> |

--no-proxy]>

Generates a problem report. If the -s, --send option is specified, sends the report to Parallels. The --proxy parameter specifies Internet proxy settings if you are using one to connect to the Internet.

Optional parameters

--stand-alone

Assembles a report without connecting to the Parallels Desktop service.

--name <user_name>

Appends the user name to the report.

--email <user_email>

Appends the user email address to the report.

--description <problem_description>

Appends a free-form description to the report.

Shut Down Parallels Desktop

Command-Line Reference

prlsrvctl shutdown [-f, --force]

Shuts down Parallels Desktop. The command correctly stops all services. The optional -f, -- force parameter forcibly shuts down Parallels Desktop and hard-stops services if necessary.

Parallels Desktop Plugin Commands

prlsrvctl plugin list [-j, --json]

Lists installed Parallels plugins.

prlsrvctl plugin refresh

Refreshes installed Parallels plugins.

Error Handling

The prlsrvctl utility returns 0 on success or an error code on failure.

Virtual Machine Management

The prlctl utility is used to perform management tasks on virtual machines. The utility supports a full range of tasks from creating and administering virtual machines to getting statistics and generating problem reports.

The general syntax is as follows:

Command-Line Reference

prlctl command <vm_ID | vm_name> [options] [-v, --verbose number]

The parameters are:

• command: one of the available commands.

• vm_ID | vm_name: ID or name of the target virtual machine.

• options: command options.

• -v, --verbose number: Show verbose output. The greater the number, the more verbose

output will be produced.

The subsequent sections describe the available prlctl commands grouped by functionality.

General Virtual Machine Management

This section describes various prlctl commands allowing you to perform such tasks as listing virtual machines, creating new virtual machines, cloning, performing power operations (start, stop, pause, etc.), encrypting, and many others.

List Virtual Machines

Syntax 1

prlctl list

Lists existing virtual machines. By default (when no parameters are included), only running VMs are displayed.

Optional parameters

-a, --all

Lists all existing virtual machines regardless of their state (running, stopped, suspended, etc.).

-f, --full

Shows the real IP address(es) for running virtual machines.

-o, --output field [, field...]

Displays only the specified field(s).

-s, --sort <field | -field>

Sorts by field (arguments are the same as those for -o). Add "-" (minus sign) before the field name to reverse the sort order.

-L

+ 30 hidden pages