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.
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.
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
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.
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
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 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.
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.
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
10
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.
Send the problem report to Parallels (-s, --send) or dump it to stdout (-d, --dump).
11
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.
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]
13
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.
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
14
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
15
Parallels Desktop Management
to assign the USB device.
usb del
Deletes a USB device assignment. The USB device assignment is performed on the user level, so if
you remove an assignment, it will only be removed for the current user. Other users may have their
own USB devices assignments, which will not be affected.
Syntax
prlsrvctl usb del <usb_dev_ID>
Options
Name Description
<usb_dev_ID>
The USB device ID.
prlsrvctl user list
Displays the list of Parallels Desktop users.
Syntax
prlsrvctl user list [-o,--output name[,name...]]
Parameters
Name Description
-o,--output name
Names of the fields to include in the output. The following fields are
available:
• name -- User name.
• mng_settings -- Indicates whether the user is
allowed to modify Parallels Desktop preferences.
•def_vm_home -- The user default virtual machine
folder.
16
The fields must be specified using the lower case letters.
Virtual Machine Management
Virtual Machine Management
The prlctl utility is used to perform administration 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 ID of the virtual machine on which to perform the operation. To
obtain the list of the available virtual machines, use the prlctl list command (p. 27).
The name of the virtual machine on which to perform the operation.
To obtain the list of the available virtual machines, use the prlctl list command (p. 27).
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 prlctl without any parameters.
General Syntax
The prlctl utility is used to perform administration 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 ID of the virtual machine on which to perform the operation. To
obtain the list of the available virtual machines, use the prlctl list command (p. 27).
The name of the virtual machine on which to perform the operation.
To obtain the list of the available virtual machines, use the prlctl list command (p. 27).
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 prlctl without any parameters.
prlctl capture
Captures the screen of a virtual machine desktop and saves it to a file on the client machine. The
data is saved in the Portable Network Graphics (PNG) format.
Syntax
prlctl capture ID|name --file name
Parameters
Name Description
ID
name
--file name
The virtual machine ID.
The virtual machine name.
Name and path of the file to which the image should be saved. You should
include the file extension (.png) or the file will be saved without one.
prlctl change-passwd
Changes the encryption password for the specified virtual machine.
18
Virtual Machine Management
Syntax
prlctl change-passwd ID|name
Parameters
Name Description
ID
name
Virtual machine ID.
Virtual machine name.
Remarks
The command can be used to change the password that was used to encrypt a virtual machine. A
user will be asked to enter the current and the new password.
The virtual machine must be currently encrypted for this command to work. If you would like to
encrypt an unencrypted virtual machine, use the encrypt command (p. 25).
prlctl convert
This command is used to convert third-party virtual machines and disks to Parallels virtual
machines and disks. The following third-party virtual machines and disks are supported:
• Microsoft Hyper-V
• Microsoft Virtual PC
• Virtual Box
• VMware
Syntax
prlctl convert <path> [--dst<path>] [--force]
Options
Name Description
<path>
--dst=<path>
--force
Full path to the third-party virtual machine's configuration file on the local server.
Set the destination directory for the resulting virtual machine and its configuration
file. If omitted, the default directory (/var/parallels) is used.
Convert the third-party virtual machine even if its guest OS cannot be identified.
19
Virtual Machine Management
prlctl clone
Creates an exact copy of the specified virtual machine.
Create a virtual machine template instead of a real virtual
machine. Templates are used as a basis for creating new virtual
machines.
Name and path of the new virtual machine directory. If this
parameter is omitted, the new virtual machine will be created in
the default directory.
Generate a new Windows security identifier (SID) for a
Windows-based virtual machine. For this parameter to work,
Parallels Tools must be installed in the virtual machine.
Create a linked virtual machine.
If set to no, hard disks located outside a source virtual machine
are not removed from the configuration of the resulting clone.
Setting the parameter to yes removes outside hard disks from
the configuration.
Note: Outside hard disks are not copied to the
cloned virtual machine.
prlctl create
Creates a new virtual machine. A virtual machine can be created from scratch or from a virtual
machine template. When created from scratch, the target operating system type or version must
be specified. To create a virtual machine from a template, the template name must be passed to
the command.
20
Virtual Machine Management
Syntax
prlctl create name {--ostypename|--distribution {name|list}} [--location path]
prlctl create name --ostemplate name [--location path]
Parameters
Name Description
name
User-defined new virtual machine name. If the name consists of two
or more words separated by spaces, it must be enclosed in quotes.
-o, --ostype name
The name of the family of the operating system that will be installed in
the virtual machine. Select from one of the following:
• windows
• linux
• macos
• feebsd
• os2
• msdos
• netware
• solaris
• other (specify this option if the operating system you are
planning to install is not listed above).
21
Virtual Machine Management
-d, --distribution
name|list
The operating system version that you are planning to install in the
virtual machine.
To display the list of known operating systems, supply the list
value instead of the OS name.
Or supply one of the following values (grouped by family):
Windows
• win-311
• win-95
• win-98
• win-me
• win-nt
• win-2000
• win-xp
• win-2003
• win-vista
• win-2008
• win-7
• win (specify this option if the Windows OS version you
are using is not listed above).
Linux
• rhel
• rhel3
• suse
• debian
• fedora-core (specify this option for all Fedora Core
distributions except for Fedora Core 5).
• fc-5
• ubuntu
• mandriva
• centos
• redhat
• opensuse
Mac OS
• macos-10.4
• macos-10.5
• snowleopard
22
FreeBSD
• freebsd-4
• freebsd-5
• freebsd-6
Virtual Machine Management
--ostemplate name
--location path
The name of the virtual machine template from which to create the
new virtual machine. Use the prlctl list --template
command to obtain the list of the available templates.
Name and path of the directory where to store the new virtual
machine files. If this parameter is omitted, the files will be crated in
the default virtual machine directory.
Remarks
When creating a virtual machine from scratch, you may specify the operating system family or
version. If an operating system version is specified using the --distribution parameter, the
virtual machine will be configured for that operating system. If an operating system family is
specified using the --ostype parameter, the virtual machine will be configured for the default
version of this OS family. The default versions are determined internally by Parallels and are kept in
sync with other Parallels management tools such as Parallels Management Console. The best way
to find out the default versions used in your Parallels installation is by creating a sample virtual
machine.
prlctl debug-dump
Creates a virtual machine dump in ELF format and saves it to a file. The resulting dump file can be
opened with the Linux crash utility or (with some limitations) with the GDB debugger. To convert
the dump file to a Windows or OS X format, use the supplied prlcore2dmp utility (p. 24).
Deletes a virtual machine from the <host computer>. The command removes a virtual machine
from the Parallels Service registry and permanently deletes all its files from the host. Once
completed, this operation cannot be reversed.
Syntax
prlctl delete ID|name
Parameters
Name Description
ID
name
The ID of the virtual machine to delete.
The name of the virtual machine to delete.
prlctl encrypt, decrypt
Encrypt or decrypt a virtual machine.
Syntax
prlctl encrypt ID|name
prlctl decrypt ID|name
Parameters
Name Description
ID
name
Remarks
The encrypt command will encrypt the specified virtual machine and all its data. A user will be
prompted to enter an encryption password after the command is executed from the command line.
The ID of the virtual machine to encrypt or decrypt.
The name of the virtual machine to encrypt or decrypt.
The decrypt command will decrypt the specified virtual machine. A user will have to enter a
password that was selected when the virtual machine was encrypted.
25
Virtual Machine Management
The encryption password can be modified for an encrypted virtual machine using the change-passwd command (p. 18).
prlctl enter
Creates a command prompt channel to a virtual machine. By using this command, you can create
a command prompt channel and execute commands in a virtual machine. Parallels Tools must be
installed in a virtual machine to use this utility.
Syntax
prlctl enter exec vm_id|vm_name
Parameters
Name Description
vm_id|vm_name
The UUID or the name of the virtual machine.
prlctl exec
Executes a command inside a virtual machine. Parallels Tools must be installed in a virtual machine
to use this utility. Commands in Linux guests are invoked with bash -c.
Syntax
prlctl exec vm_id|vm_name command
Parameters
Name Description
vm_id|vm_name
command
The UUID or the name of the virtual machine.
A command to execute.
prlctl installtools
Installs Parallels Tools in the specified virtual machine.
26
Virtual Machine Management
Syntax
prlctl installtools ID|name
Parameters
Name Description
ID
name
The ID of the target virtual machine.
The name of the target virtual machine.
Notes
To use this command, the target virtual machine must be running.
prlctl list
Obtains a list of virtual machines on the host computer. The command allows you to obtain a
summary list containing only the virtual machine ID, name, and status, or to obtain a detailed
information about a specific or all virtual machines.
Syntax
prlctl list [--all] [--template] [--no-header]
[-o,--outputname[,name...]] [-s, --sortname|-name]
prlctl list--info [ID|name]
Parameters
Name Description
-a, --all
-t, --template
--no-header
-o, --output name
List all, running, stopped, suspended, and paused virtual machines. If this
and the rest of the parameters are omitted, only the running virtual machines
will be displayed.
List the available virtual machine templates. The real virtual machines will not
be included in the output.
Do not display column headers.
Display one (or any combination) of the following fields:
• uuid -- Virtual machine ID.
• name -- Virtual machine name.
• status --Virtual machine status (running, stopped, etc.).
The above fields can be combined in a single command using comma
separator (e.g. uuid, name). The excluded fields will not be displayed. The
field names must be typed in lower case.
27
Virtual Machine Management
-s, --sort name
-i, --info
ID
name
Sort the virtual machine list by the specified parameter in ascending order.
Display detailed information about a virtual machine.
The ID of the virtual machine for which to display the detailed information. If
not specified, the information will be displayed for all registered virtual
machines.
The name of the virtual machine for which to display the detailed
information. If not specified, the information will be displayed for all
registered virtual machines.
The ID of the virtual machine to pause, suspend, or resume.
The name of the virtual machine to pause, suspend, or resume.
Remarks
The pause command pauses a virtual machine. To continue the virtual machine operation, use
the prlctl start command (p. 45).
The suspen
d command suspends the virtual machine operation. When a running virtual machine
is suspended, the state of the virtual machine processes is saved to a file on the host. After that,
the machine is stopped. To resume the machine, use the resume command.
prlctl problem-report
Obtains a problem report for the specified virtual machine and displays it on the screen.
The ID of the virtual machine for which to obtain the problem
report.
The name of the virtual machine for which to obtain the report. If
the name consists of separate words, it must be enclosed in
quotes.
Collect technical data about a virtual machine and display it on
the screen. You can also pipe the output to a file and then send it
to the Parallels technical support to analyze your problem.
Send the generated problem report to the Parallels technical
support.
Use the specified information to send the generated report
through a proxy server, if you use one to connect to the Internet.
Do not use a proxy server to send the generated report. This is
the default behavior, so you can omit this parameter.
Virtual Machine Management
prlctl register, unregister
The register command is used to register a virtual machine with Parallels Service.
The unregister command removes a virtual machine from the Parallels Service registry.
Syntax
prlctl register path
prlctl unregister ID|name
Parameters
Name Description
path
ID|name
An absolute path to the virtual machine directory.
The ID or the name of the virtual machine to remove from the Parallels
Service registry.
29
Virtual Machine Management
Remarks
Use the register command when you have a virtual machine on the host that doesn't show up
in the list of the virtual machines registered with the Parallels Service. This can be a machine that
was previously removed from the registry or a machine that was manually copied from another
location.
The unregister command removes a virtual machine from the Parallels Service registry but does
not delete the virtual machine files from the host. You can re-register such a machine with the
Parallels Service later using the register command.
prlctl server
Obtains information about the host computer and Parallels the Parallels Desktop installed on it.
Also, allows you to shut down the Parallels Desktop.
Syntax
prlctl server shutdown|info
Parameters
Name Description
info
shutdown
Displays the Parallels Desktop information.
Shuts down Parallels Desktop. If one or more virtual machines are running,
clients are connected, or some tasks are currently in progress then the
shutdown operation will be aborted.
prlctl set
The prlctl set command is used to modify the configuration of a virtual machine and manage
virtual machine devices and shared folders. The following subsections provide technical information
on how to use the command to perform these tasks.
Modifying Virtual Machine Configuration
The prlctl set command can be used to modify virtual machine configuration parameters,
including virtual CPU availability, RAM and video memory size, startup and shutdown options, and
some others.
Number of virtual CPUs in the virtual machine. If
the host has more than one CPU, this option
allows you to set the number of virtual CPUs to
be available in the virtual machine.
The amount of memory (RAM) available to the
virtual machine, in megabytes.
The amount of video memory available to the
virtual machine graphics card.
Short description of the virtual machine.
Defines the virtual machine start-up options:
• off — turns autostart off (default).
• open-window — the VM starts when
its window is opened in the PD Control
Center.
• start-app — the VM starts when
Parallels Desktop is started.
• start-host — the VM starts on the host
start-up.
Sets the time delay used during the virtual
machine automatic startup.
--autostop stop|suspend
Sets the automatic shutdown mode for the
specified virtual machine:
•stop -- the virtual machine is stopped
when you shut down the Parallels
Service.
•suspend -- the virtual machine is
suspended when the Parallels Service is
shut down.
31
Virtual Machine Management
dev_
--start-as-user
administrator|owner|user:passwd
--tools-autoupdate on|off
--userpasswd os_user:new_pass
--asset-id ID
Specifies the account to use to autostart the
virtual machine:
•administrator -- start the virtual
machine as the administrator of the host
operating system.
•owner -- start the virtual machine as
the virtual machine owner.
•user:passwd -- start the virtual
machine as the specified user.
Turns on/off automatic updating of Parallels
Tools in the guest operating system. If this option
is set to ON, Parallels Tools updates will be
performed automatically every time an update is
available for your Parallels Desktop. If this option
is set to OFF, no automatic Parallels Tools
updates will be performed, so that you can do it
manually at a convenient time.
Resets the password for the specified user of the
guest OS running in a virtual machine. The
parameters are:
os_user -- guest OS user name.
new_pass -- new password.
Sets an asset ID (aka asset tag) in the virtual
machine BIOS. Asset IDs are used for computer
identification and inventory purposes.
Managing Virtual Devices
Adds virtual devices to a virtual machine, modifies and deletes existing virtual devices.
General Syntax
prlctl set ID|VM_name --device-add dev_typeoptions
prlctl set ID|VM_name --device-set nameoptions
prlctl set ID|VM_name --device-del name
Parameters
Name Description
ID
VM_name
--device-add dev_typeoptions
32
The virtual machine ID.
The virtual machine name.
Adds a virtual device to the specified virtual
machine.
The
type parameter specifies the virtual
Virtual Machine Management
device type (hdd, cdrom, fdd, net, etc.).
The options parameters specifies device-type
specific options.
--device-set name options
--device-del name
Modifies the configuration of an existing virtual
device in the specified virtual machine.
The name parameter specifies the virtual device
name.
The options parameters specifies device-type
specific options.
Deletes a virtual device from the virtual machine.
The name parameter specifies the name of the
virtual device to delete.
Remarks
All device-related parameters can be subdivided into the following categories:
• Hard disk drives (p. 33)
• Optical disk drives (p. 35)
• Network cards (p. 37)
• Floppy disk
• USB devices
drives (p. 37)
(p. 41)
• Serial ports (p. 39)
• Parallel ports (p. 40)
• Sound cards
Each group
(p. 41)
of parameters is explained in the following subsections in detail.
Notes
All operations on virtual machine devices (adding, modifying, or removing a device) must be
performed on a stopped virtual machine. An attempt to perform any of these operations on a
running virtual machine will result in error.
Hard Disk Drive Management Parameters
This group of parameters is used to add and configure virtual hard disks in a virtual machine.
prlctl set ID|VM_name --device-set hddN --device name
[--iface ide|scsi][--position number]
[--enable|--disable]
Parameters
Name Description
ID
VM_name
--device-add
--device-set
hdd
hddN
--image name
The virtual machine ID.
The virtual machine name.
Adds a virtual hard disk drive to the virtual machine.
You can connect up to four IDE devices and up to seven SCSI devices
to a virtual machine. This includes hard disks and optical disk drives.
Modifies the parameters of an existing virtual hard disk.
Specifies the type of the virtual device to add to the virtual machine (in
this instance, a virtual hard disk).
The name of the virtual hard disk to modify. Virtual hard disks are named
using the hddN format where N is the drive index number starting from 0
(e.g. hdd0, hdd1). To obtain the list of disk names, use the prlctl list command with the --info option.
This options is used to create a virtual hard disk using an
image file. You have an option of creating a new image file
or to use an existing image.
--device name
--type expand|plain
34
• To use an existing image file, specify its name and path
using the name parameter.
• To create a new image file, omit the --image
parameter. New image files are created in the virtual
machine directory and are automatically named using
the harddiskN.hdd format, where N is the disk index
number (e.g. harddisk0.hdd, harddisk1.hdd).
This option is used to create a virtual hard disk based on a boot camp
partition (Mac hosts). The name parameter must contain the boot camp
partition name.
For image file based virtual disk drives, specified the disk type:
•expand -- expanding disk. The image file is small initially and
grows in size as you add data to it. This is the default virtual
disk type.
--size number
--split
--iface ide|scsi
Virtual Machine Management
•plain -- plain disk. The image file has a fixed size from the
moment it is created (i.e the space is allocated for the drive
fully). Plain disks perform faster than expanding disks.
The size of the virtual hard disk, in megabytes. The default size is 32,000
MB.
Splits the hard disk image file into 2 GB pieces. You should split a virtual
disk if it is stored on a file system that cannot support files larger than 2
GB (e.g. FAT16).
Interface type:
• ide -- IDE drive.
• scsi - SCSI drive (default).
--position number
The SCSI or IDE device identifier to be used for the virtual disk. The
allowed ID ranges are the following:
Adds a DVD/CD drive to the virtual machine. You can connect up to four
IDE devices and up to seven SCSI devices to a virtual machine. This
includes virtual hard disks and DVD/CD drives.
Modifies the parameters of an existing virtual optical disk.
Specifies the virtual device type (in this instance, a CD or DVD drive).
The name of the DVD/CD drive to modify. The N postfix indicates the
drive index number. To obtain the list of the available drives, use the
prlctl list command with the --info option.
The name of the physical optical disk to connect to the virtual machine.
The name of an existing disk image file to mount in the virtual machine.
Currently, the following image file formats are supported: .iso, .cue, .ccd, and .dmg. The image must not be compressed and/or
encrypted.
Interface type:
--position number
--enable
--disable
--connect
--disconnect
• ide -- IDE disk.
• scsi -- SCSI disk (default).
The SCSI or IDE device identifier to be used for the DVD/CD drive. The
allowed ID ranges are the following:
You can use one of the following formats for specifying IDs: ID:bus,
ID-bus, ID. For example, if you specify 3:0 (or 3-0 or 3) as number for
a SCSI drive, the guest OS will see the drive as having ID 3 on SCSI bus
0.
Enables the specified DVD/CD drive. All newly added drives are enabled
by default (provided the --disable option is omitted).
Disables the specified optical disk drive. The disk drive itself is not
removed from the virtual machine configuration.
Automatically connect the specified optical disk drive during the virtual
machine startup process.
Do not automatically connect the specified optical disk drive during the
virtual machine startup process.
36
Virtual Machine Management
Floppy Disk Drive Management Parameters
This group of parameters is used to add floppy disk drives to a virtual machine and to modify
existing virtual floppy disk drives.
Syntax
prlctl set ID|VM_name --device-add fdd [--device name]
[--enable|--disable][--connect|--disconnect]
prlctl set ID|VM_name --device-set fdd [--device name]
[--enable|--disable][--connect|--disconnect]
Parameters
Name Description
ID
VM_name
The virtual machine ID.
The virtual machine name.
fdd
--device-add
--device-set
--device name
--enable
--disable
--connect
--disconnect
--image path
Specifies the type of the virtual device to add or modify (in this instance, a
floppy disk drive).
Adds a new floppy disk drive to the virtual machine. You can connect only
one floppy disk drive to a virtual machine.
Modifies the parameters of an existing virtual floppy disk drive.
The name of the physical floppy disk drive to connect to the virtual machine.
If this parameter is omitted, a floppy drive image emulating the floppy disk
drive will be created.
Enables the specified floppy disk drive. All newly added floppy drives are
enabled by default (provided the --disable option was omitted during the
drive creation).
Disables the specified floppy disk drive. The drive itself is not removed from
the virtual machine configuration.
Connect the specified floppy disk drive automatically during the virtual
machine startup process.
Use this option if you don't want the specified floppy disk drive automatically
connected to the virtual machine on its start.
The name and path of an existing floppy disk image file (usually
floppy.fdd) to mount in the virtual machine.
Network Adapter Management Parameters
This group of parameters is used to manage virtual network adapters in a virtual machine.
37
Virtual Machine Management
Syntax
prlctl set ID|VM_name --device-add net --type shared
[--mac addr][--enable|--disable][--connect|--disconnect]
prlctl set ID|VM_name --device-add net --type host --net_id network_id
[--mac addr][--enable|--disable][--connect|--disconnect]
prlctl set ID|VM_name --device-add net --type bridged --iface name
[--mac addr][--enable|--disable] [--connect|--disconnect]
prlctl set ID|VM_name --device-set netN --type shared
[--mac addr][--enable|--disable][--connect|--disconnect]
Adds a new virtual network adapter to the virtual machine.
Used to configure an existing virtual network adapter.
Specifies the virtual device type to add (in this instance, a virtual network
adapter).
The name of the virtual network adapter to modify. To obtain the list of the
available adapters, use the prlctl list command with the --info
option.
Sets the networking mode for the virtual network adapter:
•shared -- Shared networking. Select this option if you wish to
enable Network Address Translation (NAT) for the adapter. The
adapter will share the IP address with the host computer when
communicating with external networks.
•host -- Host-only networking. Select this option if you wish the
virtual machine to communicate only with the host computer
and other virtual machines included in the same network.
Access to external networks is not allowed.
•bridged -- Bridged networking. The adapter is bound to the
specified physical network adapter. The virtual machine will
appear as a standalone computer on the network.
--iface name
Used with the bridged networking mode (see above). Specifies the name of
the physical network adapter to which the virtual adapter should be bound.
38
Virtual Machine Management
--net_id network_id
--mac addr
--mac addr|auto
--enable
--disable
--connect
--disconnect
Used with the host-only networking mode (see above). Specifies the name
of virtual network to which the virtual adapter should be bound.
The MAC address to be assigned to the virtual network adapter. If this
option is omitted, the MAC address will be generated automatically.
Specifies the MAC address to assign to an existing network adapter.
Specify a desired MAC address using the addr parameter value or use the
auto option to re-generate the existing address automatically.
Enables the virtual network card. All newly created network adapters are
enabled by default (provided the --disable option is omitted).
Disables virtual network adapter. The adapter itself is not removed from the
virtual machine configuration. Please note that a disabled virtual network
adapter can only be enabled in a stopped virtual machine.
Automatically connect the virtual network adapter during the virtual
machine startup process.
Do not automatically connect the virtual network adapter during the virtual
machine startup process.
Serial Port Management Parameters
This group of parameters is used to manage serial ports in a virtual machine.
Syntax
prlctl set ID|VM_name --device-add serial
{--device name|--output file|--socket name}
[--enable|--disable][--connect|--disconnect]
prlctl set ID|VM_name --device-set serialN
{--device name|--output file|--socket name}
[--enable|--disable][--connect|--disconnect]
Parameters
Name Description
ID
VM_name
--device-add
--device-set
serial
--device name
--output file
--socket name
The virtual machine ID.
The virtual machine name.
Adds a new serial port to the virtual machine. You can connect up to four
serial ports to a virtual machine.
Modifies the parameters of an existing serial port.
Specifies the type of the virtual device to add (in this instance, a serial port).
The name of the physical serial port to which to connect the virtual machine.
The name and path of the output file to which to connect the virtual serial
port.
The name of the physical socket to which to connect the virtual serial port.
39
Virtual Machine Management
--enable
--disable
--connect
--disconnect
Enables the virtual serial port. All newly added serial ports are enabled by
default (provided the --disable option is omitted).
Disables the virtual serial port.
Automatically connect the virtual serial port during the virtual machine
startup process.
Do not automatically connect the virtual serial port during the virtual machine
startup process.
Parallel Port Management Parameters
This group of parameters is used to manage parallel port in a virtual machine.
Syntax
prlctl set ID|VM_name --device-add parallel
{--device name|--output file_name}
[--enable|--disable][--connect|--disconnect]
prlctl set ID|VM_name --device-set parallelN
{--device name|--output file_name}
[--enable|--disable][--connect|--disconnect]
Parameters
Name Description
ID
name
--device-add
--device-set
parallel
parallelN
--device name
--output file_name
--enable
--disable
--connect
The virtual machine ID.
The virtual machine name.
Adds a new parallel port to the virtual machine. You can connect
up to three parallel ports to a virtual machine.
Modifies the parameters of an existing virtual parallel port.
Specified the type of the virtual device to add (in this instance, a
virtual parallel port).
The name of the parallel port to modify. To obtain the list of ports,
use the prlctl list command with the --info option.
The name of the physical parallel port to which to connect the
virtual parallel port.
The name of the output file to which to connect the virtual parallel
port.
Enables the specified parallel port. All newly added parallel ports
are enabled by default (provided the --disable option was
omitted during the port creation).
Disable the specified virtual parallel port. The port itself is not
removed from the virtual machine configuration.
Automatically connect the specified virtual parallel port during the
40
Virtual Machine Management
virtual machine startup process.
--disconnect
Do not automatically connect the specified virtual parallel port
during the virtual machine startup process.
USB Controller Management Parameters
This group of parameters is used to manage the USB controller in a virtual machine.
Syntax
prlctl set ID|VM_name --device-add usb [--enable|--disable]
Parameters
Name Description
ID
VM_name
usb
--enable
The virtual machine ID.
The virtual machine name.
The type of the virtual device to add to the virtual machine (in this instance, a
USB device).
Enables the USB controller. This is the default option.
--disable
Disables the USB controller.
Sound Device Management Parameters
This group of parameters is used to manage sound devices in a virtual machine.
Syntax
prlctl set ID|VM_name --device-add sound --output name
[--enable|--disable][--connect|--disconnect]
prlctl set ID|VM_name --device-set sound --output name
[--enable|--disable][--connect|--disconnect]
Parameters
Name Description
ID
VM_name
sound
--output name
The virtual machine ID.
The virtual machine name.
The type of the virtual device to add to the virtual machine (in this instance,
a sound device).
The name of a physical output device to which to connect the virtual sound
device.
41
Virtual Machine Management
--input name
--enable
--disable
--connect
--disconnect
The name of the physical input device to which to connect the virtual
sound device.
Enables the specified sound device. All newly added sound devices are
enabled by default (provided the --disable option is omitted).
Disables the specified virtual sound device.
Automatically connect the sound device during the virtual machine startup
process.
Do not automatically connect the sound device during the virtual machine
startup process.
Removing Devices from Virtual Machine
The --device-del option is used to remove virtual devices from a virtual machine.
Syntax
prlctl set ID|name --device-del name
Parameters
Name Description
--device-del name
The name of the virtual device to delete from the virtual machine. To obtain
the list of virtual devices, use the prlctl list command with the -info option.
Managing Shared Folders
The prlctl set command can be used to add shared folders to a virtual machine and to modify
and delete existing shared folders.
Syntax
prlctl set ID|VM_name --shf-host-add name --path path
[--mode ro|rw]
[--shf-description txt]
[--enable|--disable]
The ID of the virtual machine to start, stop, restart, reset, or check the
status of.
The name of the virtual machine to start, stop, restart, reset, or check
45
Virtual Machine Management
the status of.
--kill
Perform a 'hard' virtual machine shutdown. If this option is omitted, an
attempt to perform a graceful shutdown will be made.
Remarks
The stop command can perform a 'hard' or a graceful virtual machine shutdown. If the --kill
parameter is included, the 'hard' shutdown will be performed. If the parameter is omitted, the
outcome of the graceful shutdown attempt will depend on the following:
• If the Parallels Tools package is installed in a virtual machine, the graceful shutdown will be
performed using its facilities.
• If the Parallels Tools package is not installed, the command will try to perform a graceful
shutdown using ACPI. Depending on the ACPI support availability in the guest operating
system, this may work or not.
The restart command first gracefully shuts down a virtual machine and then starts it again.
The reset command first performs a 'hard' virtual machine shutdown and then starts it again.
The start command can be used to start a stopped virtual machine or to resume a paused virtual
machine.
prlctl statistics
Obtains performance statistics for the specified virtual machine.
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.