Parallels Desktop Pro Edition - 12.0 Command-Line Reference

Parallels Desktop for Mac Pro Edition

Command-Line Reference

Version 12

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 ...............................................................................................................5

Overview........................................................................................................................... 5

Parallels Desktop Management................................................................................6

General Syntax.................................................................................................................. 6

prlsrvctl info....................................................................................................................... 7

prlsrvctl install-license........................................................................................................ 7

prlsrvctl deactivate-license ................................................................................................8

prlsrvctl net ....................................................................................................................... 8

net add.................................................................................................................................... 8

net set ..................................................................................................................................... 9

net del ................................................................................................................................... 11

net list.................................................................................................................................... 11

prlsrvctl problem-report................................................................................................... 11

prlsrvctl set .....................................................................................................................12

prlsrvctl shutdown...........................................................................................................13

prlsrvctl statistics............................................................................................................. 14

prlsrvctl usb ....................................................................................................................14

usb list................................................................................................................................... 15

usb set .................................................................................................................................. 15

usb del .................................................................................................................................. 16

prlsrvctl user list .............................................................................................................. 16

Virtual Machine Management

General Syntax................................................................................................................ 17

prlctl capture................................................................................................................... 18

prlctl change-passwd...................................................................................................... 18

prlctl convert ...................................................................................................................19

.................................................................................17

prlctl clone ...................................................................................................................... 20

prlctl create..................................................................................................................... 20

prlctl debug-dump ..........................................................................................................23

prlcore2dmp.......................................................................................................................... 24

Contents

prlctl delete ..................................................................................................................... 25

prlctl encrypt, decrypt ..................................................................................................... 25

prlctl enter.......................................................................................................................26

prlctl exec ....................................................................................................................... 26

prlctl installtools............................................................................................................... 26

prlctl list ..........................................................................................................................27

prlctl pause, suspend, resume ........................................................................................28

prlctl problem-report ....................................................................................................... 28

prlctl register, unregister.................................................................................................. 29

prlctl server ..................................................................................................................... 30

prlctl set.......................................................................................................................... 30

Modifying Virtual Machine Configuration................................................................................ 30

Managing Virtual Devices....................................................................................................... 32

Managing Shared Folders...................................................................................................... 42

prlctl snapshot ................................................................................................................ 43

prlctl snapshot-delete...................................................................................................... 44

prlctl snapshot-list...........................................................................................................44

prlctl snapshot-switch ..................................................................................................... 45

prlctl start, stop, restart, reset, status .............................................................................. 45

prlctl statistics .................................................................................................................46

Index ........................................................................................................................ 47

C HAPTER 1

Introduction

Welcome to Parallels Desktop for Mac Pro Edition. Built on the world’s best-selling, top-rated, most-trusted virtualization solution, Parallels Desktop Pro Edition adds the capabilities that make it an ideal platform for developing and testing software products.

Note: This guide refers to version 12 of Parallels Desktop. If you are using a newer version of Parallels Desktop (including updates), please download the latest guide from the Parallels website.

In This Chapter

Overview................................................................................................................... 5

Overview

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 command-line utilities:

• prlsrvctl

The prlsrvctl 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 prlctl 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 Business Edition installation. You can run the utilities in Terminal.

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.

Syntax

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

Parameters

Name Description

command

The name of the command to execute.

options

-v, --verbose number

Command options. See individual commands for available options.

Show verbose output. The greater the number, the more verbose output will be produced.

Remarks

To display help, enter prlsrvctl on the command line without any parameters.

General Syntax

Syntax

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

Parameters

Name Description

command

The name of the command to execute.

options

-v, --verbose number

Command options. See individual commands for available options.

Show verbose output. The greater the number, the more verbose

Parallels Desktop Management

output will be produced.

Remarks

To display help, enter prlsrvctl on the command line without any parameters.

prlsrvctl info

Displays the host computer and Parallels Desktop configuration information.

Syntax

prlsrvctl info

Remarks

The information returned by the info command includes the following:

• Host machine name.

• Parallels Desktop version number.

• Host operating system type and version.

• The default virtual machine directory name and path.

• Parallels Desktop memory limits.

• Parallels Desktop minimum allowable security level.

• Parallels Desktop license information.

• Host machine hardware configuration information.

• Other miscellaneous info.

prlsrvctl install-license

Installs Parallels Desktop license on the host computer.

Syntax

prlsrvctl install-license -k,--key key [-n,--name name] [-c,--company name] [--deferred]

Parameters

Name Description

-k, --key key

-n, --name name

License key.

License user name.

Parallels Desktop Management

-c,--company name

--deferred

License company name.

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 prlsrvctl deactivate-license (p. 8)

prlsrvctl deactivate-license

Deactivates Parallels Desktop license.

Syntax

prlsrvctl deactivate-license

prlsrvctl net

The prlsrvctl net command is used to create and configure virtual networks.

Subcommands

Name Description

net add

net set

net del

net list

Creates a new virtual network

Configures the parameters of an existing virtual network.

Removes an existing virtual network.

List the available virtual networks.

net add

The prlsrvctl net add command is used to create a new virtual network.

Syntax

prlsrvctl net add vnetwork_id [-i,--ifname if] [-m,--mac mac_address] [-t,--type bridged|host-only|shared] [-d,--description description] [--ip addr[/mask]][--dhcp-server on|off][--dhcp-ip ip] [--ip-scope-start ip][--ip-scope-end ip] [--ip6 addr[/mask]][--dhcp6-server on|off][--dhcp-ip6 ip] [--ip6-scope-start ip][--ip6-scope-end ip]

Parameters

Name Description

vnetwork_id

A user-defined name that will identify the new virtual network.

Parallels Desktop Management

-i,--ifname if

-m,--mac mac_address

-t,--type value

-d,--description description

--ip addr[/mask]

--dhcp-server on|off

--dhcp-ip ip

--ip-scope-start ip

--ip-scope-end ip

--ip6 addr[/mask]

--dhcp6-server on|off

The name of a physical network adapter on the host to which this virtual network should be bound.

The MAC address of a virtual network adapter on the host to which this virtual network should be bound.

The type of the virtual network to create. Possible values are:

• bridged. A virtual machine connected to this type of virtual network appears as an independent computer on the network.

• host_only (default). A virtual machine connected to this type of virtual network can access only the host and the virtual machine connected to the same virtual network.

• shared. A virtual machine shares the network adapter with the host computer.

A user-defined description of the virtual network.

IPv4 address and mask for the Parallels virtual adapter.

Enable or disable the Parallels virtual DHCPv4 server.

Set an IPv4 address for the Parallels virtual DHCPv4 server.

Sets the start and end IP addresses for the DHCP pool. The virtual machines connected to the network you are creating will automatically receive their IP addresses from this DHCP pool.

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

Enable or disable the Parallels virtual DHCPv6 server.

--dhcp-ip6 ip

--ip6-scope-start ip

--ip6-scope-end ip

Set an IPv6 address for the Parallels virtual DHCPv6 server.

Set a start IPv6 address for the pool of IPv6 addresses.

Set an end IPv6 address for the pool of IPv6 addresses.

net set

The prlsrvctl net set command is used to modify an existing virtual network.

Parallels Desktop Management

Syntax

prlsrvctl net set vnetwork_id [-i,--ifname if] [-m,--mac mac_address] [-t,--type bridged|host-only|shared] [-d,--description description] [-n, --name new_name] [--ip addr[/mask]][--dhcp-server on|off][--dhcp-ip ip] [--ip-scope-start ip][--ip-scope-end ip] [--ip6 addr[/mask]][--dhcp6-server on|off][--dhcp-ip6 ip] [--ip6-scope-start ip][--ip6-scope-end ip]

Parameters

Name Description

vnetwork_id

The name of the virtual network to modify.

-i,--ifname if

-m,--mac mac_address

-t,--type value

-d,--description description

-n, --name new_name

--ip addr[/mask]

--dhcp-server on|off

The name of a physical network adapter on the host to which this virtual network should be bound.

The MAC address of a virtual network adapter on the host to which this virtual network should be bound.

The type of the virtual network to create. Possible values are:

• bridged. A virtual machine connected to this type of virtual network appears as an independent computer on the network.

• host_only (default). A virtual machine connected to this type of virtual network can access only the host and the virtual machine connected to the same virtual network.

• shared. A virtual machine shares the network adapter with the host computer.

A user-defined description of the virtual network.

A new name for the virtual network. Use this parameter if you would like to rename the virtual network.

IPv4 address and mask for the Parallels virtual adapter.

Enable or disable the Parallels virtual DHCPv4 server.

--dhcp-ip ip

--ip-scope-start ip

--ip-scope-end ip

--ip6 addr[/mask]

--dhcp6-server on|off

--dhcp-ip6 ip

Set an IPv4 address for the Parallels virtual DHCPv4 server.

Sets the start and end IP addresses for the DHCP pool. The virtual machines connected to the network you are creating will automatically receive their IP addresses from this DHCP pool.

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

Enable or disable the Parallels virtual DHCPv6 server.

Set an IPv6 address for the Parallels virtual DHCPv6 server.

Parallels Desktop Management

--ip6-scope-start ip

--ip6-scope-end ip

Set a start IPv6 address for the pool of IPv6 addresses.

Set an end IPv6 address for the pool of IPv6 addresses.

net del

The prlsrvctl net del command is used to delete an existing virtual network.

Syntax

prlsrvctl net del vnetwork_id

Parameters

Name Description

vnetwork_id

The name of the virtual network to delete.

net list

The prlsrvctl net list command lists the existing virtual networks.

Syntax

prlsrvctl net list

prlsrvctl problem-report

Obtains the Parallels Desktop problem report and displays it on the screen.

Syntax

prlsrvctl problem-report [-s, --send] [-d, --dump]

Parameters

Send the problem report to Parallels (-s, --send) or dump it to stdout (-d, --dump).

Parallels Desktop Management

Remarks

The command collects technical data about the Parallels Desktop and displays the report on the screen (the output can also be piped to a file). The report can then be directed to Parallels technical support for analysis.

prlsrvctl set

Sets the Parallels Desktop preferences.

Syntax

prlsrvctl set [--mem-limit auto|size] [-s,--min-security-level low|normal|high] [-c,--cep on|off] [{--device device --assignment host|vm}] [--default-encryption-plugin plugin-id] | [--reset-default-encryption-plugin] [--allow-attach-screenshots on|off] [--require-custom-pwd {create-vm|add-vm|remove-vm| clone-vm|edit-preferences}:on|off] [--custom-pwd [--custom-pwd-mode on|off|change]]

Parameters

Name Description

--mem-limit

-s,--min-security-level

Sets the upper limit of the memory size that can be reserved for Parallels Desktop operations. The following options are available:

• auto -- if this option is used, the memory size will be calculated automatically.

• size -- user-defined memory size, in megabytes.

The lowest allowable security level that can be used to connect to the Parallels Desktop. The following options are available:

• low -- plain TCP/IP (no encryption).

• normal -- most important data is sent and

received using SSL over TCP/IP (user credentials during login, guest OS clipboard, etc.) Other data is sent and received using plain TCP/IP with no encryption.

• high -- all of the data is sent and received using SSL.

Parallels Desktop Management

-c,--cep

--device device --assignment

--default-encryption-plugin

plugin-id

--reset-default-encryption-plugin

--allow-attach-screenshots

--require-custom-pwd

--custom-pwd

Enables/disables the participation in the Customer Experience Program. The following options are available:

• on -- enables CEP.

• off -- disables CEP.

Sets the assignment mode for the specified VTd device. The following options are available:

• host -- assign the device to host.

• vm -- assign the device to virtual machines.

Specifies which encryption plug-in should be used by default. An encryption plug-in implements an encryption algorithm, which is used to encrypt a virtual machine. Use this option to specify the ID of the plug-in, which should be used by default.

Resets the default encryption plug-in assignment and sets the built-in plug-in to be used by default.

Specifies whether to attach screenshots to problem reports:

• on -- attach screenshots.

• off -- do not attach screenshots.

Enables custom password requirement for a specified user action in Parallels Desktop. The actions are: create-vm, add-vm, remove-vm, clone-vm, edit-preferences. The on|off switch turns the requirement on or off.

To set the password, use the --custom-pwd command (see below).

Sets the custom password for restricting user actions in Parallels Desktop.

To use the command in interactive mode, execute it with no parameters.

To perform a particular task, include the --custom-pwdmode parameters and specify whether you want to turn the password on, off, or to change it.

prlsrvctl shutdown

Shuts down Parallels Desktop.

Syntax

prlsrvctl shutdown [-f,--force]

Parallels Desktop Management

Parameters

Name Description

-f, --force

Specifies whether the shutdown operation should be forced. If one or more virtual machines are running, clients are connected, or some tasks are currently in progress, then forcing the shutdown will stop all processes automatically and will shut down the Parallels Desktop.

prlsrvctl statistics

Obtains Parallels Desktop statistics.

Syntax

prlsrvctl statistics [-a, --all] [--loop] [--filter name]

Parameters

Name Description

-a, --all

--loop

--filter name

This parameter is not currently used.

Subscribes to receive statistics on the periodic basis. Once you execute the command with this option, the statistics will be displayed in your console window every time a new set of values is collected. To unsubscribe, press the Enter key or Ctrl-C in your console window.

This parameter is not currently used.

prlsrvctl usb

The prlsrvctl usb command is used to permanently assign a USB device to a specific virtual machine. A permanently assigned USB device will be connected to the virtual machine automatically on server restart.

Subcommands

Name Description

usb list

usb set

Lists USB devices connected to the host together with the information about their virtual machine assignments for the current user.

Permanently assigns a USB device to the specified virtual machine.

Parallels Desktop Management

usb del

Removes a previously created USB device assignment.

usb list

Lists the USB devices connected to the host.

Syntax

prlsrvctl usb list

Options

None.

Returns

A list of USB devices in tabular format with the following columns:

Name — the USB device name.

ID — a string that uniquely identifies the USB devices on the physical server. The ID never changes

even if the device is disconnected from the server and then reconnected again. Please note that if a device ID is listed in quotes, they are a part of the ID and must be included in other calls that use it as an input parameter.

VM UUID — a universally unique ID of the virtual machine to which this USB device is permanently assigned. If a USB device is not assigned to any virtual machine, this column will be empty.

usb set

Permanently assigns a USB device to the specified virtual machine. A permanently assigned USB device will be connected to the virtual machine automatically on server restart. The USB device assignment is performed for the current user only. Other users may create their own USB device assignments.

Syntax

prlsrvctl usb set <usb_dev_ID> <vm_ID|vm_name>

Options

Name Description

<usb_dev_ID>

The USB device ID.

<vm_ID|vm_name>

The universally unique ID or name of the virtual machine to which

+ 33 hidden pages