Page 1
Parallels Desktop for Mac
Business Edition
IT Administrator's Guide
v13 Update 3
Page 2
Parallels International GmbH
Vordergasse 59
8200 Schaffhausen
Switzerland
Tel: + 41 52 672 20 30
www.parallels.com
Copyright © 1999-2018 Parallels International GmbH. All rights reserved.
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.
Page 3
Contents
Introduction ............................................................................................................... 5
Parallels Desktop Business Edition Features Overview ..................................................... 5
Parallels Desktop for Mac Business Edition Features ............................................. 8
Restricting User Actions in Parallels Desktop with a Custom Password ............................ 8
Restricting a Virtual Machine Configuration with a Custom Password ............................... 9
Locking a Virtual Machine on Suspend .......................................................................... 11
Setting an Asset Tag in the Virtual Machine BIOS ........................................................... 12
Using Custom Graphics and Links in the Control Center ................................................ 13
Hiding Developer Tools in the Parallels Desktop GUI ...................................................... 14
Encrypting a Virtual Machine from the Command Line .................................................... 15
Single Application Mode ................................................................................................ 16
Setting an Expiration Date for a Virtual Machine ............................................................. 17
Enforcing USB Device Policies ....................................................................................... 18
Resetting the Guest OS Password ................................................................................. 19
Setting Up a Local Update Server .................................................................................. 20
Installing a Web Server .......................................................................................................... 20
Creating the Parallels Update XML File .................................................................................. 21
Configuring Individual Macs ................................................................................................... 23
Configuring Parallels Desktop Update Branch ................................................................ 25
Customizing the Support Center Option......................................................................... 26
Participating in the Customer Experience Program ......................................................... 27
Mass Deployment of Parallels Desktop and Virtual Machines .............................. 28
Prerequisites ................................................................................................................. 28
Kernel Extensions in macOS High Sierra ........................................................................ 29
Using MDM Configuration ..................................................................................................... 29
Using spctl Command ........................................................................................................... 30
Manually Approving Kernel Extensions .................................................................................. 30
Supported Deployment Tools ........................................................................................ 32
Preparing the Deployment Package ............................................................................... 33
Download the Deployment Package ...................................................................................... 33
Page 4
Contents
Add the Parallels Desktop Installation Image ......................................................................... 34
Specify a License Key ........................................................................................................... 34
Add a Virtual Machine ............................................................................................................ 35
Adding Windows Application Stubs ....................................................................................... 37
Configure Deployment Configuration Options ........................................................................ 39
Single Application Mode ........................................................................................................ 46
Testing the Deployment Package .......................................................................................... 48
Deploying Parallels Desktop and Virtual Machines to Macs ............................................. 49
Deploying with Jamf Pro ........................................................................................................ 49
Deploying with Parallels Mac Management for Microsoft SCCM ............................................ 55
Deploying with Apple Remote Desktop ................................................................................. 57
Deploying macOS Image Using NetBoot ............................................................................... 61
Parallels Desktop Command Line Interface ........................................................... 62
Parallels Desktop Management ..................................................................................... 62
Display Parallels Desktop Info ................................................................................................ 63
License Management ............................................................................................................ 63
Parallels Desktop Preferences ............................................................................................... 65
User List and Virtual Machine Location .................................................................................. 66
Virtual Network Info ............................................................................................................... 66
Virtual Network Settings ........................................................................................................ 66
USB Devices ......................................................................................................................... 68
Send Problem Report ............................................................................................................ 69
Shut Down Parallels Desktop ................................................................................................ 69
Parallels Desktop Plugin Commands ..................................................................................... 69
Error Handling ....................................................................................................................... 70
Virtual Machine Management ......................................................................................... 70
General Virtual Machine Management ................................................................................... 70
Virtual Machine Configuration Tasks ...................................................................................... 78
Snapshot Management ......................................................................................................... 92
Miscellaneous Commands .................................................................................................... 93
Error Handling ....................................................................................................................... 95
Index ........................................................................................................................ 96
Page 5
C HAPTER 1
Introduction
Welcome to Parallels Desktop for Mac Business Edition. Built on the world’s best-selling, top-rated,
most-trusted solution for running Windows applications on the Mac, Parallels Desktop Business
Edition adds the capabilities that help IT administrators and purchasing agents save time and
money.
Note: This guide refers to Parallels Desktop v13 Update 2. If you are using a newer version of Parallels
Desktop (including updates), please download the latest guide from the Parallels website.
In This Chapter
Parallels Desktop Business Edition Features Overview ............................................. 5
Parallels Desktop Business Edition Features Overview
With Parallels Desktop for Mac, your Mac users can seamlessly run both Windows and Mac
applications side-by-side with speed, control and confidence. Business users can experience as
much or as little Windows as they want. Multiple view modes and options make it possible for users
to customize the level of integration between Mac and Windows without compromising
performance. Best of all, IT can lock down, secure, and control the settings that matter most.
Parallels Desktop Business Edition Feature Highlights
• License management portal (Parallels My Account)
• Split license keys into sublicenses
• Maintain corporate compliance with restricted virtual machines
• Set an expiration date for a virtual machine
• Mass deployment of Parallels Desktop and virtual machines
• Business-level support including 24/7 phone and email support options
Parallels Desktop Business Edition Feature Matrix
See how Parallels Desktop Business Edition compares to Parallels Desktop Pro and Home
editions.
Page 6
Introduction
Feature
World’s most powerful, best-performing solution for running Windows
applications on a Mac
Home
•
Merge the coolness of Mac with the utility of Windows. Seamlessly utilize
Mac features inside Windows and leverage Windows' strengths on your
•
Mac.
Advanced networking tools. Create virtual networks for complex network
scenarios and testing, including simulating various network scenarios.
Mass deploy and mass manage Parallels Desktop and Windows VMs for
your employees.
Single Application Mode. A special Parallels Desktop deployment option
allowing Mac users to run a Windows application without being aware of
Parallels Desktop and Windows running in a virtual machine.
Licensing and Support
Premium 24/7 phone and email support First 30 days
Centralized license management via Licensing Portal
Simple deployment with unified volume license key
Extended grace period
Pro
•
•
•
Business
•
•
•
•
•
•
•
•
•
•
Customizable in-product Support Center option
Removed in-product notifications
Configurable software update policy and local update server options
Security
Restrict end-users from changing virtual machine settings
Restrict end-users from creating new virtual machines
Create expiring virtual machines
Enforce USB device policies
Configurable policies via SCCM and Parallels Mac Management
Advanced
Run virtual machines in “head-less” mode
Assign up to 32 vCPU and 128 GB vRAM per virtual machine and control
resources on the fly
•
•
•
•
•
•
•
•
•
•
•
•
•
•
6
Page 7
Command line interface to control Parallels Desktop and virtual machines.
Command line interface allows you to work with Parallels plugins for
popular development tools including Vagrant and Jenkins
Introduction
•
•
Customize the Parallels Control Center to include custom graphics, text,
and links.
•
7
Page 8
C H APTER 2
Parallels Desktop for Mac Business Edition Features
This chapter describes features that are specific to Parallels Desktop for Mac Business Edition.
In This Chapter
Restricting User Actions in Parallels Desktop with a Custom Password .................... 8
Restricting a Virtual Machine Configuration with a Custom Password....................... 9
Locking a Virtual Machine on Suspend .................................................................... 11
Setting an Asset Tag in the Virtual Machine BIOS .................................................... 12
Using Custom Graphics and Links in the Control Center ......................................... 13
Hiding Developer Tools in the Parallels Desktop GUI ............................................... 14
Encrypting a Virtual Machine from the Command Line ............................................. 15
Single Application Mode ......................................................................................... 16
Setting an Expiration Date for a Virtual Machine ....................................................... 17
Enforcing USB Device Policies ................................................................................ 18
Resetting the Guest OS Password .......................................................................... 19
Setting Up a Local Update Server ........................................................................... 20
Configuring Parallels Desktop Update Branch ......................................................... 25
Customizing the Support Center Option .................................................................. 26
Participating in the Customer Experience Program .................................................. 27
Restricting User Actions in Parallels Desktop with a Custom Password
As an administrator of Parallels Desktop Business Edition, you have the ability to restrict the
following user actions in Parallels Desktop:
• Creating a new virtual machine.
• Adding an existing virtual machine.
• Removing a virtual machine.
• Cloning a virtual machine or converting it to a template.
• Opening the Parallels Desktop Preferences dialog.
Page 9
Parallels Desktop for Mac Business Edition Features
You can set a custom password (i.e. it can be different from the local Mac administrator password)
and specify which user actions from the list above should require it. Once you apply these settings,
even the local Mac administrator will not be able to perform these actions without specifying the
password that you set.
To set the password and specify the actions:
1 In the Parallels Desktop menu bar, click Parallels Desktop > Preferences.
2 Click the Security tab.
3 Click the Custom password: Turn On... button.
4 In the dialog that opens, type a password. This becomes the custom password that will be
required to perform actions that you will select in the next step. Click OK.
Note: If later you need to change this password, click the Change Password button and follow the
instructions on the screen.
5 Back in the Security dialog, select the user action(s) you want to restrict.
6 Close the dialog to apply the settings.
If a Mac user now tries to perform any of the actions that were password-protected (e.g. creating a
virtual machine, etc.), they will be required to enter this custom password. To select or deselect an
action in the Parallels Desktop Preferences dialog will also require the password.
The steps described above allow you to set the password and restrict user actions in Parallels
Desktop on a particular Mac. If you want to apply these settings on multiple Mac computers in your
organization, you can do it using the mass deployment process. For more information, please see
Mass Deployment of Parallels Desktop and Virtual Machines (p. 28). Specifically, these options
are set in the Security section of the deploy.cfg file, as described in Configure Deployment
Configuration Options (p. 39).
Restricting a Virtual Machine Configuration with a Custom Password
Parallels Desktop Business Edition provides you with the ability to protect the configuration of a
virtual machine with a custom password. When a password is set, even a local Mac administrator
will be required to enter it in order to modify virtual machine settings.
Using the Parallels Desktop graphical user interface to set the password
To set a password in the Parallels Desktop graphical user interface:
1 Open Parallels Desktop and select a virtual machine.
2 On the Parallels Desktop menu bar, select Actions > Configure to open the virtual machine
configuration dialog.
9
Page 10
Parallels Desktop for Mac Business Edition Features
3 Select Security.
4 Click the Custom password: Turn On... button.
5 Enter a password, then enter it again to verify and click OK.
To change or remove the password:
• To change the password, click the Change Password button and follow the instructions on
the screen.
• To remove the password, click Custom password: Turn Off and follow the instructions on the
screen.
If the password is set and the user tries to view or modify the virtual machine configuration, they will
be required to enter this custom password.
Using the command line utility to set the password
In addition to the graphical user interface, you can use the prlctl command-line utility to set,
reset, and view the password protection of a virtual machine.
To set the password, type the following command in Terminal:
prlctl set "vm_name" --password-to-edit
where vm_name is the virtual machine name in quotes.
You'll be asked to enter a password and then confirm it.
Please enter a new password:
Please confirm password:
To change or remove the password, type the following command:
prlctl set "vm_name" --password-to-edit
where vm_name is the virtual machine name in quotes.
You'll be asked to enter the current password.
lease enter current password:
You will then be asked to enter and confirm a new password. To remove the password, leave the
line blank and press Enter twice (when asked to enter and confirm the password).
Please enter a new password:
Please confirm password:
To view the current protection status, type the following command:
prlctl list "vm_name" -i
The output will look similar to the following:
Encrypted: no
Edit restricted: yes
10
Page 11
Parallels Desktop for Mac Business Edition Features
Using the mass deployment process to set the password
If you are mass deploying Parallels Desktop and one or more virtual machines, you can set the
password in the deploy.cfg file. The password will be applied to all virtual machines included in
the deployment package.
For more information, please see Mass Deployment of Parallels Desktop and Virtual Machines
(p. 28). Specifically, the password is set in the Virtual Machines section of the deploy.cfg file
using the vm_password_to_edit parameter, as described in Configure Deployment
Configuration Options (p. 39).
Compatibility with Other Parallels Desktop Versions
The described functionality works only in Parallels Desktop 7 or later. If you set a password in a
virtual machine and then open the virtual machine in an earlier version of Parallels Desktop, the
protection will NOT work (i.e. the user will be able to view and modify the virtual machine
configuration).
You can only set or remove the password in Parallels Desktop Business Edition. However, if the
password is set and the virtual machine is opened in the Parallels Desktop Home Edition, the
password will continue to work (i.e the virtual machine configuration will remain locked).
Locking a Virtual Machine on Suspend
To avoid possible security and privacy issues, a suspended Windows virtual machine can be
completely locked from user interaction and viewing. When this option is enabled and a virtual
machine is suspended, the Windows desktop in the virtual machine window (and in the Parallels
Desktop Control Center) is replaced with a black background and the Windows session is
interrupted. When the virtual machine is resumed, the Windows session is remained locked and the
user will have to enter their user ID and password to unlock it and to see the Windows desktop.
To enable or disable this option:
1 Open Parallels Desktop and select the desired virtual machine (e.g. the source virtual machine
when preparing it for mass deployment).
2 On the Parallels Desktop menu bar, select Actions > Configure to open the virtual machine
configuration dialog.
3 Click the Security tab.
4 Depending on your needs select or clear the Always lock Windows on suspend option.
5 Close the dialog.
Note: The Always lock Windows on suspend option is available only for virtual machine running
Windows with Parallels Tools installed. For all other virtual machines, the option will be hidden.
11
Page 12
Parallels Desktop for Mac Business Edition Features
Setting an Asset Tag in the Virtual Machine BIOS
Asset tags help identify, control, and track computer assets in an organization. Parallels Desktop
for Mac Business Edition provides the ability to set an asset tag in the virtual machine BIOS, which
can then be read using the standard tools of the guest operating system. You can set an asset tag
using the Parallels Desktop graphical user interface or the prlctl command line utility that comes
with Parallels Desktop.
To set an asset tag using the Parallels Desktop GUI:
1 On the Parallels Desktop menu bar, select Actions > Configure to open the virtual machine
configuration dialog.
2 Select Business.
3 Use the Asset tag field to specify the desired tag.
To set an asset tag using the prlctl command line utility, use the following syntax:
prlctl set ID|name --asset-id tag
where ID|name is the virtual machine ID or name, and tag is the asset tag to set.
To obtain the asset tag in Windows, use the WMIC.exe command:
WMIC SystemEnclosure get SMBIOSAssetTag
For the complete syntax of the WMIC utility please see the Microsoft documentation.
Once set, the asset tag never changes. Even if you perform such virtual machine operations as
cloning, template manipulation, registering, or any other, the asset tag always stays the same. If
you do want to change an existing asset tag for any reason, you can do it manually using of the
methods described above.
12
Page 13
Parallels Desktop for Mac Business Edition Features
Using Custom Graphics and Links in the Control Center
Parallels Desktop Control Center is a part of the Parallels Desktop graphical user interface. It's a
window from which a Mac user launches virtual machines. By default, the Control Center displays
the list of the available virtual machines, as in the following example:
You can customize the Control Center by specifying a URL to your own HTML document, which
will be embedded at the top of the Control Center window. The HTML page can contain text,
graphics, and links such as your company logo, custom text, a link to a support page, etc. The
HTML document format doesn't have any specific requirements.
The URL must be specified during the preparation stage of the Mass Deployment process (p. 28).
Specifically, you need to specify the URL and the HTML page size using the following variables in
the mass deployment configuration file (deploy.cfg):
• control_center_banner_url
• control_center_banner_height
• control_center_banner_min_width
For the description of how to specify the values, please see Configure Deployment Configuration
Options (p. 39). The variables are described in the Virtual Machines section.
13
Page 14
Parallels Desktop for Mac Business Edition Features
The following is an example of Parallels Desktop Control Center displaying a custom banner at the
top.
You can download a sample HTML document defining the banner using the following URL:
http://download.parallels.com/desktop/tools/header13.zip
Hiding Developer Tools in the Parallels Desktop GUI
Parallels Desktop Business and Pro editions include developer tools which are aimed at software
developers using Parallels Desktop as their development platform. The tools are accessed by
clicking the Develop menu on the virtual machine menu bar and then choosing one of the available
options (e.g. Start SSH Session, Start Debugging Session, and others). If users in your
organization are not using these tools, you can hide the Develop menu altogether. The reason you
would want to do this, some of these features (if used accidentally) may start a debugging session
or engage some other development-specific task that may temporarily disrupt a normal Parallels
Desktop operation.
This option is a part of a virtual machine configuration and can be set using the Parallels graphical
user interface as follows:
1 Open the virtual machine configuration dialog (click the gear icon or choose Actions >
Configure).
2 In the dialog, click Options (at the top) and then click More Options in the left pane.
14
Page 15
Parallels Desktop for Mac Business Edition Features
3 In the right pane, select or clear the Show developer tools option. This will show or hide the
Develop menu on the virtual machine menu bar (you don't have to restart a virtual machine if
it's running).
To modify this setting from the command line, execute the following command in Terminal:
prlctl set ID|Name --show-dev-tools on|off
where ID/Name is the GUID or name of a target virtual machine.
When mass deploying Parallels Desktop on Mac computers in your organization, you can configure
the deployment package to apply this settings to all included virtual machines automatically. For
details, see Configure Deployment Configuration Options (p. 39).
Note: In Parallels Desktop prior to version 13, hiding or showing developer tools was a global option (not
a virtual machine level option). If you are still using Parallels Desktop version 12 or older, the option to
hide or show developer tools is located in Parallels Desktop Preferences. In these older versions of
Parallels Desktop, you can also turn this option on or off from the command line by modifying the
com.parallels.Parallels Desktop.plist file located in the ~/Library/Preferences folder. For example, to show
developer tools, execute the following command: defaults write "com.parallels.Parallels Desktop"
"Application preferences.Show Develop Menu" -bool yes (use "-bool no" to hide the tools).
Encrypting a Virtual Machine from the Command Line
A Parallels virtual machine can be encrypted from the Parallels Desktop graphical user interface.
This is done from the Security tab of the virtual machine configuration dialog.
You can also use the prlctl command line utility (included with Parallels Desktop) to perform a
full set of encryption operations on a virtual machine.
The following command line options are available:
• Encrypt a virtual machine
prlctl encrypt <ID | NAME>
• Decrypt a virtual machine
prlctl decrypt <ID | NAME>
• Change the encryption password
prlctl change-passwd <ID | NAME>
The <ID | NAME> parameter can be either the virtual machine ID or the virtual machine name.
When encrypting a virtual machine, you'll be asked to enter a password phrase, which will be used
to encrypt the machine. When decrypting a virtual machine, you will be asked to enter the current
password. When changing the password, you'll be asked to enter the old password and then the
new password.
15
Page 16
Parallels Desktop for Mac Business Edition Features
The encryption password will also be required to perform any other command line operation on an
encrypted virtual machine, including starting, stopping, restarting, pausing, suspending, cloning,
deleting a virtual machine, etc. For example, to start an encrypted virtual machine, you'll use the
following command:
$ prlctl start my_virtual_machine
After executing the command above, you'll be asked to enter the password:
Virtual machine "my_virtual_machine" is encrypted - password required to continue
operation
Please enter password:
After typing in the correct password, you'll see the following output:
Starting the VM...
The VM has been successfully started.
If you need to execute a command remotely without having to enter the password on every Mac,
you can send the password via standard input (stdin) as shown in the following example:
$ echo mypass | prlctl start my_virtual_machine
Virtual machine 'my_virtual_machine' is encrypted - password required to continue
operation
Please enter password:
Starting the VM...
The VM has been successfully started.
If you need to provide two passwords (as with the change-passwd command that changes the
password), you can save the passwords to a text file and then use the following syntax:
$ cat /tmp/pass | prlctl change-passwd my_virtual_machine
Virtual machine 'my_virtual_machine' is encrypted - password required to continue
operation
Please enter password:
Please enter new password:
The password has been successfully changed.
The /tmp/pass file in the example above should contain the old password on the first line and the
new password on the second line:
$ cat /tmp/pass
mypass
newpass
Single Application Mode
Single Application Mode is a special Parallels Desktop deployment option that allows you to
completely hide Parallels Desktop and Windows on a Mac and make a Windows application
appear like it's a native macOS app. This mode is designed for system administrators who want
Mac users in their organization to run one or more Windows applications without being aware of
Parallels Desktop or Windows running in a virtual machine.
To make Parallels Desktop run in Single Application Mode, you need to deploy it on Mac
computers via the mass deployment package. This includes preparing the deployment package in
a special way and then either deploying it on Mac computers using Mac management tools or
running it manually on a Mac.
16
Page 17
Parallels Desktop for Mac Business Edition Features
For more information about how to use the mass deployment package and how to deploy Parallels
Desktop in Single Application Mode, please see the following sections of this guide:
• Mass Deployment of Parallels Desktop and Virtual Machines (p. 28)
• Single Application Mode (p. 46)
Setting an Expiration Date for a Virtual Machine
You can set an expiration date for a virtual machine. This can be a useful option if you are preparing
a virtual machine for a contractor (or a third party user) and want to make sure that it works only for
the duration of the contract.
To set an expiration date for a virtual machine:
1 Open Parallels Desktop and select the desired virtual machine.
2 On the Parallels Desktop menu bar, select Actions > Configure to open the virtual machine
configuration dialog.
3 Select the Security tab.
4 An expiration date can only be set on an encrypted virtual machine. If your machine is not yet
encrypted, click Encryption: Turn On, specify an encryption password, and click OK. Make
sure to record the password or you will not be able to start the virtual machine. Wait until the
encryption process finishes.
5 To set an expiration date for the virtual machine, click Expiration Date: Set Date, specify a
password and click OK. Make sure to record the password to be able to change the expiration
settings later. You should keep this password secret to prevent the prospective user of the
virtual machine from changing the expiration date.
6 On the next screen, specify the following options:
• Do not allow this VM start after: specifies the virtual machine expiration date.
• Contact info: specifies the system administrator email, phone number, or other contact
information. This information will be included in the message that will be displayed to the
user when the virtual machine is about to expire. You can include each piece of information
on a separate line.
• Time Server: specifies the time server URL. The virtual machine expiration time will be
checked against this server. The default time server is https://parallels.com.
• Date Check Frequency: specifies how often the date and time should be verified against
the time server. You can specify it in minutes, hours, or days.
• If unable to check date, use VM for: specifies for how long the virtual machine should be
kept working if the time server cannot be reached. For the duration of this period, the virtual
machine will continue to check the date. If it succeeds before this period is over, the counter
is reset and the virtual machine will continue to work normally.
7 Click OK when done entering the expiration info.
17
Page 18
Parallels Desktop for Mac Business Edition Features
8 To modify the current expiration date or password, click Expiration Date: Change Date or
Expiration Date: Change Password and enter the new values.
Note: When giving the virtual machine to a contractor, make sure to provide them the encryption
password, which is needed to start the virtual machine. Please note that this is NOT the expiration date
password you've set in step 5 above. This is the password you set when you encrypted the virtual
machine.
When the expiration date approaches, the virtual machine user will be notified as follows: a
message will begin to be displayed seven days before the expiration date. The message will be
shown to the user every 24 hours and additionally on every virtual machine startup. Once the date
is reached, the virtual machine will be locked, so the user will not be able to start or resume it
anymore.
Enforcing USB Device Policies
When configuring USB device settings for a virtual machine, you can enforce what types of USB
devices are allowed to be connected. For example, if storage devices (in general) are not allowed,
the Mac user will not be able to connect an external hard disk or thumb drive to the virtual machine.
This functionality is available in Parallels Desktop Business edition only and is absent in other
editions.
18
Page 19
Parallels Desktop for Mac Business Edition Features
To enforce USB device policies, open the virtual machine configuration window and select
Hardware > USB & Bluetooth.
In the Allow external devices list:
• Clear the types of devices that you don't want Mac users to connect to the virtual machine.
• Select the types of devices that should be allowed.
Resetting the Guest OS Password
If a virtual machine user forgets the password of their guest OS account (e.g. a Windows user
password), it can be reset outside the virtual machine using the command line interface.
To use this functionality the following conditions must be met:
• Parallels Tools must be installed in the guest OS.
19
Page 20
Parallels Desktop for Mac Business Edition Features
• The virtual machine must be running. If it's stopped, start it and wait until you see the guest OS
login prompt.
• Depending on your requirements, the following option can be selected or cleared in the virtual
machine configuration dialog: Security > Require Password to: [ ] Change guest OS
password via CLI. If this option is selected, you will be asked to provide the macOS
administrator password to change the guest OS password from the command line. If the option
is cleared, the administrator password will not be required. By default, the option is cleared.
To reset the password, open Terminal and enter the following command:
prlctl set vm_name --userpasswd username:new_password
where:
• vm_name is the virtual machine name. To obtain the list of virtual machines installed on this
Mac, type prlctl list.
• username is the guest OS user name.
• new_password is the new password.
Example:
prlctl set My_Win8_VM --userpasswd JohnDoe:A12345
If the Require Password to: Change guest OS password via CLI option is selected in the virtual
machine configuration dialog (see above), the command will display the following text and prompt:
Only host administrator can change user password in the guest OS.
Confirm your administrator credentials.
Username:
Enter the name of the macOS user with administrative privileges and press the Enter key. Type the
user password and press Enter again.
Once the new password is set, you can use it to log in to the guest OS.
Setting Up a Local Update Server
With Parallels Desktop Business Edition you can set up a local update server on your network from
which Mac users can get Parallels Desktop updates. Updates are released periodically to improve
the performance and reliability of Parallels Desktop. To reduce Internet traffic when downloading
updates, you can set up a local update server, download the available updates to it, and then set
up individual Macs on your network to take the updates from it instead of the Internet. Read on to
learn about setting a local update server.
Installing a Web Server
To set up a Parallels Desktop update server, you'll need a local Web server. Install a Web server on
a computer connected to your network (or use an existing one).
20
Page 21
Parallels Desktop for Mac Business Edition Features
Creating the Parallels Update XML File
Create a file named parallels_updates.xml on the Web server where it can be accessed via
HTTP. The file is an XML document that should contain specifications for a particular Parallels
Desktop update available on your local updated server.
To create your own document, use the following sample XML document and the XML document
specification that follows it as a reference.
Sample parallels_updates.xml file
<?xml version="1.0" encoding="UTF-8"?>
<ParallelsUpdates schemaVersion="1.0">
<Product>
<ProductName>Parallels Desktop</ProductName>
<UpdateEnabled>1</UpdateEnabled>
<Version>
<Major>12</Major>
<Minor>0</Minor>
<SubMinor>12494</SubMinor>
<SubSubMinor>262214</SubSubMinor>
<StringRepresentation>Sumer</StringRepresentation>
<Update uuid="desktop.13.0.13291.237436.en_US.parallels.mac">
<UpdateType>0</UpdateType>
<UpdateName>Build 13291 is available!</UpdateName>
<UpdateDescription>Update description goes here</UpdateDescription>
<FilePath>URL to the update file goes here</FilePath>
<FileSize>219515</FileSize>
<Status>0</Status>
<DateTime>2017-06-17 01:23:00</DateTime>
<Chargeable>0</Chargeable>
<LocaleName>en_US</LocaleName>
<DistributorName>parallels</DistributorName>
<OsType>mac</OsType>
<Ancestry>
<Ancestor>desktop.13.0.12927.482436.en_US.parallels.mac</Ancestor>
<Ancestor>desktop.13.0.12473.274921.en_US.parallels.mac</Ancestor>
<Ancestor>desktop.13.0.12262.823647.en_US.parallels.mac</Ancestor>
</Ancestry>
</Update>
</Version>
</Product>
</ParallelsUpdates>
XML Document Specification
Name Type Description
ParallelsUpdates
Product
ProductName
UpdateEnabled
Root element.
string Use "Parallels Desktop".
int
Container for Parallels Desktop information.
Specifies whether the automatic updates are enabled. To
enable updates, specify 1.
21
Page 22
Parallels Desktop for Mac Business Edition Features
Major
platform
UpdateDescription
LocaleName
Version
Minor
SubMinor
SubSubMinor
StringRepresentation
Update
int Major version number (e.g. 13)
int Minor version number. Specify 0.
Container for Parallels Desktop version information.
Build number. This element may be empty.
Revision number. This element may be empty.
Product codename. This element may be empty.
Container for the information about the Parallels Desktop
update.
Attributes:
uuid — String. A globally unique ID identifying the
product.
The uuid attribute is very important and must contain the
correct information for the update to work. The attribute
value consists of the following parameters (substrings)
separated by periods (see the provided XML example):
desktop — specify "desktop"
major — major version number (e.g. 13)
minor — minor version number (0)
build — build number
UpdateType
UpdateName
FilePath
FileSize
Status
DateTime
Chargeable
DistributorName
OsType
revision — revision number
locale — locale ("en_US", "de_DE", etc)
vendor — vendor ("parallels")
— platform ("mac")
int Update type. Specify 0.
string The user-defined update name.
string The update description.
string
int The update file size, in megabytes.
int Specify 0.
string
int Specify 0.
string Locale name ("en_US", "it_IT", etc).
Operating system type. Specify "mac".
A URL to the update file on your local update server. The
actual update files can be obtained from Parallels.
Date and time when the updated was published. Use the
following format:
yyyy-mm-dd hh:mm:ss
The update distributor name. Specify "parallels".
Ancestry
22
Container for the list of updates that directly preceded this
update.
Page 23
Parallels Desktop for Mac Business Edition Features
An individual Parallels Desktop update information.
This element may appear more than once in the same
document, one for each update.
The value is combined using the following parameters
(substrings) separated by periods (see the provided XML
example):
desktop — specify "desktop".
Ancestor
string
major — Parallels Desktop major version number.
minor — minor version number.
build — build number.
revision — revision number.
locale — locale (e.g. "en_US")
vendor — vendor ("parallels").
platform -— platform ("mac").
Configuring Individual Macs
The next step is to configure individual Macs to take their updates from the local update server.
This can be done automatically during the mass deployment of Parallels Desktop by modifying the
appropriate deployment configuration option. Please see Configure Deployment Configuration
Options (p. 39) for the complete info (see the description of the Software Updates section of the
configuration file).
If you have an existing Parallels Desktop installation that was not configured for automatic updates
during deployment, then read on to learn how to do it manually.
Note: The information provided here applies only to Parallels Desktop installations that were NOT
configured to use automatic updates during the mass deployment process.
To configure Parallels Desktop automatic updates, you need to modify the Parallels Desktop
property list file on a Mac as follows:
1 Find the com.parallels.Parallels Desktop.plist file located in the
Library/Preferences subfolder in the user's home folder. This is the Parallels Desktop
property list file that contains the user-specific information.
2 Open the file using the Property List Editor application (included with Xcode).
3 Set the update policy by modifying the Application
preferences.VolumeLicenseUpdatePolicy property. If the property doesn't exist, add
it to the file specifying its data type as String. Set the property value using one of the following
options (see also the Notes subsection below):
23
Page 24
Parallels Desktop for Mac Business Edition Features
• "Parallels" — when this value is set, the updates will be downloaded from the Parallels
update server via the Internet. The value is case-sensitive.
• Complete URL of the parallels_updates.xml file residing on your local update server.
For example, "http://10.0.0.1/pdfm/v8/en_us/parallels/parallels_updates.xml". When the
URL is specified, the updates will be obtained from the local update server.
• "None" — automatic updates are disabled. The value is case-sensitive.
4 Specify how often Parallels Desktop should check for updates. This is done by modifying the
Application preferences.Check for updates property. If the property doesn't exist,
add it to the file specifying its data type as Number. Specify the property value using one of the
following options:
• 0 — Never
• 1 — Once a day
• 2 — Once a week
• 3 — Once a month
5 Set the automatic download option. Find the Application preferences.Download
updates automatically property. If it doesn't exist, add it to the file specifying its data
type as Boolean. Set the property value using one of the following options:
• True — Download updates automatically. Specify this value when using a local update
server.
• False — Notify the user about the updates but don't download them automatically. This
option is useful only when updates are downloaded from the Parallels update server and the
user has full control over the update functionality.
6 Save the file and close the Property List Editor application.
Note: If Parallels Desktop is running while you are modifying the plist file, it will have to be restarted for
the changes to take effect.
Notes
On initial Parallels Desktop activation using a Business Edition key, the Parallels Desktop update
properties will be absent from the com.parallels.Parallels Desktop.plist file. In such a
case, a Mac user will be able to configure Parallels Desktop automatic updates using the Parallels
Desktop graphical user interface.
When the update-related properties are added to the com.parallels.Parallels
Desktop.plist file, the automatic updates will be performed according to the specified values.
In addition, the value of the Application preferences.VolumeLicenseUpdatePolicy
property will affect the Parallels Desktop update-related elements in the Parallels Desktop graphical
user interface as follows:
24
Page 25
Parallels Desktop for Mac Business Edition Features
• If the property contains a URL of the local update server or "None", the Parallels Desktop
update-related controls will be disabled (grayed out) in the Parallels Desktop graphical user
interface. The displayed settings will have no effect on how the Parallels Desktop updates are
carried out. Therefore, the user will not be able to configure automatic updates or check for
updates manually.
• If the property doesn't exist, has no value, or contains "Parallels" as a value, the Parallels
Desktop update controls will be enabled in the user interface giving the user the ability to
configure automatic updates and check for updates manually.
Note: The Application preferences.VolumeLicenseUpdatePolicy property value has no
effect when Parallels Desktop is activated using the Parallels Desktop Home Edition license key.
Configuring Parallels Desktop Update Branch
By default, Parallels Desktop Business Edition downloads updates from a special location on the
Parallels website dedicated to hosting Parallels Desktop Business Edition updates specifically.
Other editions of Parallels Desktop (Home, Pro) download their updates from a different location.
As an administrator, you have an option to choose the location from which Parallels Desktop
Business Edition downloads updates. The reason why you would want to do this is explained
below.
When Parallels Desktop updates are released by Parallels, they become immediately available for
Parallels Desktop Home and Pro Editions. Updates for Parallels Desktop Business Edition are
released at a slightly later date (from a few days to 1-2 weeks from the initial release). The delay is
necessary for additional testing of business features of Parallels Desktop to ensure they meet the
highest quality standards. During this period, we even give an updated version of Parallels Desktop
to some of our business clients, who test and evaluate it in their real-world business environments.
We recommend that you use the default configuration and download Parallels Desktop Business
Edition updates when they are finalized and available for download. However, if for any reason you
don't want to wait, you can configure Parallels Desktop Business Edition to download updates from
the Parallels Desktop Pro location. The updates are the same regardless of where you download
them from. The only difference is, the updates downloaded from the Parallels Desktop Pro location
will not be fully tested in a business environment.
When you mass-deploy Parallels Desktop, you can set the desired Software Update options in the
deployment configuration file. Mass Deployment of Parallels Desktop is described later in this guide.
For more information, please read the entire Mass Deployment chapter (p. 28) and specifically the
Configure Deployment Configuration Options section (p. 39). Look for the Software Updates
section in the parameter table.
If you need to modify Parallels Desktop software update options on a specific Mac without using
the Mass Deployment procedure, you can do this as follows:
• To configure Parallels Desktop to download updates from the Parallels Desktop Pro location,
execute the following command on a Mac:
25
Page 26
Parallels Desktop for Mac Business Edition Features
defaults write com.parallels.Parallels\ Desktop.plist Application\
preferences.VolumeLicenseUpdatePolicy
http://update.parallels.com/desktop/v12/parallels/parallels_sbscr_up
dates.xml
The command above writes the specified URL (the parameter in the second part of the
command) into the Parallels Desktop plist file. Please note that the "v12" part of the URL
indicates the current Parallels Desktop version number. If you are using a later version,
substitute this part with the correct number.
• To switch back to the default Parallels Desktop Business download location, execute the
following command:
defaults write com.parallels.Parallels\ Desktop.plist Application\
preferences.VolumeLicenseUpdatePolicy Parallels
Notes
Options described above only work in Parallels Desktop Business Edition. Other editions can only
download software updates from their default locations.
When you configure Parallels Desktop to download updates from a custom URL (i.e. the Parallels
Desktop Pro download location), the Check for Updates option in the Parallels Desktop GUI
becomes disabled. This means that a Parallels Desktop Business Edition user will not be able to
check for and install updates manually.
Customizing the Support Center Option
The Parallels Desktop graphical user interface has a menu option named Help > Support Center.
By default, in Parallels Desktop Business Edition this option opens a dialog that asks the user to
contact the system administrator for assistance. You can change this default behavior and make
the menu open a custom URL, such as a corporate Help Desk or a wiki page.
The customization can be done during mass deployment of Parallels Desktop by modifying the
appropriate deployment configuration parameter. Please see Configure Deployment
Configuration Options (p. 39) for the complete info (see the description of the Help and Support
section of the configuration file).
You can also make these changes manually on an individual Mac as follows:
1 Log in to the Mac.
2 In the Finder, navigate to the /Users/<User_Name>/Library/Preferences directory
and locate the com.parallels.Parallels Desktop.plist file.
3 Open the file using the Property List Editor application, which is included with Xcode.
4 Find the SupportRequestUrl property in the file. If the property doesn't exist, add it to the
file specifying its data type as String.
26
Page 27
Parallels Desktop for Mac Business Edition Features
5 To specify the action that should be performed by the Help > Support Center menu, set the
value of the SupportRequestUrl property:
• To display the default text message, clear the property value.
• To open a URL, specify the full URL to the desired Web page or a resource.
Note: The SupportRequestUrl property value has no effect when Parallels Desktop is activated using
the Parallels Desktop Home Edition license key.
Participating in the Customer Experience Program
The Parallels Customer Experience Program is a feedback solution that allows Parallels Desktop to
automatically collect usage statistics and system information that will help Parallels to develop new
features and updates for future releases.
When you install Parallels Desktop on a Mac computer, it will ask you if you want to participate in
the Customer Experience Program. If later you decide to change the participation parameter, you
can do this by executing the following command on a Mac:
prlsrvctl set --cep on|off
The same action can also be done through the Parallels graphical user interface by navigating to
Parallels Desktop > Preferences > Advanced and then selecting (or clearing) the Feedback
option.
If you are using the Parallels mass deployment package to deploy Parallels Desktop, you can set
the participation parameter in the deployment configuration file (p. 39).
27
Page 28
C HAPTER 3
Mass Deployment of Parallels Desktop and Virtual Machines
This chapter describes how to mass deploy Parallels Desktop Business Edition to Mac computers
in your organization. It provides step-by-step instructions on how to prepare the deployment
package and how to deploy it using one of the available deployment tools.
In This Chapter
Prerequisites .......................................................................................................... 28
Kernel Extensions in macOS High Sierra ................................................................. 29
Supported Deployment Tools ................................................................................. 32
Preparing the Deployment Package ........................................................................ 33
Deploying Parallels Desktop and Virtual Machines to Macs ...................................... 49
Prerequisites
To mass deploy Parallels Desktop Business Edition you'll need:
• A Mac computer on which you'll configure the Parallels Desktop deployment package. The Mac
must have Parallels Desktop installed in order to create and configure one or more virtual
machines to be deployed together with Parallels Desktop.
• The Parallels Desktop for Mac installation image file (ParallelsDesktop-xxxx.dmg, where "xxx" is
the current version number). This is the same image file that you use to install Parallels Desktop
on a single Mac. The file can be downloaded from
http://www.parallels.com/products/business/download/
• A valid Parallels Desktop for Mac Business Edition license key.
• The Parallels Desktop deployment package, which can be downloaded using the following
URL: http://download.parallels.com/desktop/tools/pd-autodeploy.zip
Download the deployment package to the Mac computer on which you'll be preparing it for the
deployment of Parallels Desktop.
Note: If you already have a configured deployment package from an earlier version (or build) of Parallels
Desktop, don't use it because it may not be compatible with your build of Parallels Desktop. Always
download the latest version of the deployment package from the Parallels website using the link above.
• If your Mac computers run macOS High Sierra, please read the Kernel Extensions in macOS
High Sierra section (p. 29) that follows this one.
Page 29
Mass Deployment of Parallels Desktop and Virtual Machines
• For the complete list of hardware and operating system requirements for running Parallels
Desktop, please refer to Parallels Desktop User's Guide.
Kernel Extensions in macOS High Sierra
If you deploy Parallels Desktop on macOS High Sierra, Mac users will need to approve kernel
extensions before they can launch Parallels Desktop. See Manually Approving Kernel Extensions
(p. 30) for instructions on how it is done. As a system administrator, you can make the deployment
more transparent for your Mac users by allowing Parallels Desktop kernel extensions to load before
you deploy it on Mac computers. This can be done using one of the following options:
• Allowing kernel extensions to load via MDM configuration. For instructions, please see Using
MDM Configuration (p. 29).
• If your Mac computers are not enrolled in MDM, you can use the spctl command while
booted to macOS Recovery. See Using spctl Command (p. 30).
Please note that kernel extensions don't require user consent if they:
• Were on the Mac before the upgrade to macOS High Sierra. This means that if Parallels
Desktop was installed on a Mac before upgrading to High Sierra, you don't have to approve its
kernel extensions.
• Are replacing previously approved extensions.
Using MDM Configuration
Starting with macOS High Sierra 10.13.2, you can use MDM to specify a list of kernel extensions
which will load without user consent. This option requires a Mac running macOS High Sierra
10.13.2 which is either enrolled in MDM via the Device Enrollment Program (DEP) or whose MDM
enrollment is User Approved. For more information about User Approved Kernel Extension Loading
and User Approved MDM enrollment, please see the following Apple Support article:
https://support.apple.com/en-gb/HT208019
At the time of this writing, simply enrolling a Mac computer in MDM automatically disables User
Approved Kernel Extension Loading. This means that Parallels Desktop will start normally on such a
Mac computer. However, this will change in spring 2018 when an update to macOS is released,
according to Apple. When that happens, you will need to approve Parallels Desktop kernel
extensions using the Kernel Extension Policy payload described below.
To approve Parallels Desktop kernel extensions, you need to create a macOS configuration profile
with the Kernel Extension Policy payload and then install it via MDM on Mac computers. The
following table describes the payload keys and how to specify them to approve Parallels Desktop
kernel extensions.
Key Type Value
AllowUserOverrides
Boolean
If set to true, users can approve additional kernel extensions
not explicitly allowed by the configuration profile.
29
Page 30
Mass Deployment of Parallels Desktop and Virtual Machines
Specifies team identifiers that define which validly signed
kernel extensions will be allowed to load.
AllowedTeamIdentifiers
Array of Strings
Parallels team identifier is 4C6364ACXT. When set, all
possible Parallels kernel extensions will be authorized.
Alternatively, you can specify kernel extensions individually
(see below).
A set of kernel extensions that will be allowed to load on a
Mac computer. The dictionary maps the team ID to an array
of bundle IDs.
The Parallels team ID is 4C6364ACXT. The bundle IDs are as
follows:
• com.parallels.kext.usbconnect
AllowedKernelExtensions
Dictionary
• com.parallels.kext.vnic
• com.parallels.kext.netbridge
• com.parallels.kext.hypervisor
Note that the AllowedTeamIdentifiers key (described
above) does the same thing, but approves all possible
Parallels extensions, while here you can specify them
individually. You can use either key depending on your
requirements.
If your Mac computers are not enrolled in MDM, you can use the spctl command described in
the section that follows this one.
Using spctl Command
You can disable the user approval requirement for Parallels Desktop kernel extensions using the
spctl command on a Mac. This can be done either via booting into macOS Recovery or while
preparing NetBoot/NetInstall/NetRestore images. The command is as follows:
spctl kext-consent add 4C6364ACXT
The 4C6364ACXT value in the example above is the Parallels Team ID. The command disables
User Approved Kernel Extension Loading for Parallels Desktop, so user consent to load the
extensions will not be required.
Please note that if you reset NVRAM after executing the spctl command, the Mac reverts to its
default state with User Approved Kernel Extension Loading enabled. To prevent unauthorized
changes to NVRAM, you can set a firmware password on the Mac.
Manually Approving Kernel Extensions
If you don't disable User Approved Kernel Extension Loading for Parallels Desktop in advance, Mac
users will need to approve them manually.
To manually authorize Parallels Desktop kernel extensions on a Mac:
30
Page 31
Mass Deployment of Parallels Desktop and Virtual Machines
1 If user consent is required to load the extensions, Parallels Desktop version 13.2.0 or later will
guide the user by displaying the dialog shown below.
Note that earlier versions of Parallels Desktop will not display this dialog, so a user will need to
open the Security & Privacy window (see the second screenshot below) directly.
31
Page 32
Mass Deployment of Parallels Desktop and Virtual Machines
2 The user clicks the Open Security Preferences button, which will open the Security &
Privacy dialog (the user can also open the dialog by going to System Preferences > Security
& Privacy > General):
3 The user then clicks the Allow button located next to the message about the software from
Parallels International GmbH. This will approve Parallels Desktop kernel extensions.
Parallels Desktop will now start normally. This has to be done only once when a user starts Parallels
Desktop for the first time.
Supported Deployment Tools
Parallels Desktop Business Edition can be deployed to Mac computers using one of the following
Mac package deployment tools:
• Jamf Pro
• Parallels Mac Management for Microsoft SCCM
• DeployStudio
32
Page 33
Mass Deployment of Parallels Desktop and Virtual Machines
• Apple Remote Desktop (ARD)
• Munki
This chapter includes detailed instructions on how to deploy Parallels Desktop using Jamf Pro,
Parallels Mac Management for Microsoft SCCM, and Apple Remote Desktop. For instructions on
how to use other tools, please see their respective documentation.
Preparing the Deployment Package
To prepare the deployment package, you need to add the following required and optional
components to it:
• Parallels Desktop installation image (required).
• Parallels Desktop Business Edition license key (required).
• One or more virtual machines (optional).
• One or more Windows application stubs (optional). Stubs are special links to Windows
applications installed in a virtual machine that can be added to the Dock in macOS during
deployment.
• You can also configure deployment options according to your needs by modifying the
configuration file included in the deployment package.
The subsequent sections describe how to add the necessary components and how to configure
deployment package options.
Download the Deployment Package
If you haven't already, download the Parallels Desktop deployment package to a Mac computer
from the following location:
http://download.parallels.com/desktop/tools/pd-autodeploy.zip
By default, Safari automatically extracts files from a ZIP archive after downloading it to a Mac. If
your web browser is configured otherwise, unzip the archive.
The archive contains a folder named "Parallels Desktop Business Edition mass deployment
package vxxx", where "vxxx" is the deployment package version number.
The folder contains the following files:
• Changelog.txt — contains a record of changes that were made to the deployment package
over time.
• Parallels-Desktop-Business-Edition-Administrators-Guide.pdf — the version of the guide
that matches the deployment package version (otherwise, it's the same guide you are reading
now).
33
Page 34
Mass Deployment of Parallels Desktop and Virtual Machines
• Readme.txt — a readme file containing general information about the package.
• Parallels Desktop Autodeploy.pkg — this is the actual deployment package that you need to
prepare for mass deployment of Parallels Desktop. To view the package contents, right-click it
and choose Show Package Contents.
Read on to learn how to add the necessary components to the deployment package.
Add the Parallels Desktop Installation Image
To add the Parallels Desktop installation image file to the deployment package:
1 Right-click the Parallels Desktop Autodeploy.pkg file and choose Show Package Contents.
2 Open the Parallels Desktop DMG folder and copy the Parallels Desktop installation image file
to it (the .dmg file). If you don't have the file, you can download it from
http://www.parallels.com/products/business/download/
The package should now look like the following:
Please note that the Parallels Desktop installation image file name on the screenshot above is just
an example. In your case, the file name will also include the current build number information.
Specify a License Key
Parallels Desktop Business Edition license key is required to activate Parallels Desktop on target
Macs. The key must be specified in the deployment package.
To specify the license key:
34
Page 35
Mass Deployment of Parallels Desktop and Virtual Machines
1 In the deployment package, expand the License Key and Configuration folder.
2 Open the deploy.cfg file in a text editor.
3 Find the License section (second from the top) and enter your Parallels Desktop Business
Edition license key as a value of the license_key variable. The key must be supplied in the
following format: "XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX" (including quotes and dashes).
4 Save the deploy.cfg file.
To learn about other configuration parameters in the deploy.cfg file, please see Configure
Deployment Configuration Options (p. 39).
Note: Parallels Desktop activation requires Internet access. You need to make sure that port 443 is
opened on target Mac computers, so they can communicate with Parallels License Server. You can also
verify that the Mac computers can reach the Parallels License Server at
https://desktop.parallels.com
Add a Virtual Machine
To add a virtual machine to the deployment package, simply copy the virtual machine file (.pvm) to
the Virtual Machine(s) folder. You can add more than one virtual machine if needed.
Before adding a virtual machine to the deployment package, you can configure it according to your
needs. The subsections that follow this one describe the modifications that you can make to the
virtual machine configuration.
Please note that the virtual machine must be fully stopped before adding it to the deployment
package (it cannot be paused or suspended). This is necessary because deployment configuration
options are applied to a virtual machine on a target Mac and this can only be done if the virtual
machine is stopped.
35
Page 36
Mass Deployment of Parallels Desktop and Virtual Machines
After you add a virtual machine to the deployment package, the package folders should look like
the following:
Read on to learn about modifications that you can make to the virtual machine configuration before
adding it to the deployment package. If you are not planning on configuring a virtual machine at this
time, you can skip to the Adding Windows Application Stubs section (p. 37).
Installing Parallels Tools
Parallels Tools is a collection of utilities and drivers that vastly improve the virtual machine
performance and enable some features that are not available otherwise. Parallels Tools are included
with every copy of Parallels Desktop and are highly recommended to be installed in every virtual
machine right after an operating system is installed in it. Your source virtual machine should have
Parallels Tools installed. For instructions on how to install Parallels Tools, please see
http://kb.parallels.com/en/115835.
General Configuration Options
When preparing a source virtual machine for mass deployment, you may change any of its
configuration settings according to your needs. The following list describes a few common options:
• Shared Folders and Profiles. Parallels Desktop offers great flexibility in bridging the
capabilities of macOS and your guest operating system by configuring shared folders and
profiles. Think over which files and folders you wish to share between the two operating
systems and set up them in advance.
• Enforce USB Device Policies. Specify what types of USB devices can be connected to the
virtual machine. See Enforcing USB Device Policies (p. 18) for complete details.
• Installing Applications. You can install all the necessary applications in the virtual machine
before deploying it.
36
Page 37
Mass Deployment of Parallels Desktop and Virtual Machines
• Parallels Desktop Business Edition Options. Parallels Desktop Business Edition includes the
following additional configuration options:
• Set up a local update server and specify the Parallels Desktop automatic update options.
• Customize the Support Center option.
• Configure participation in the Customer Experience program.
For the information on how to configure these options, see Configure Deployment
Configuration Options (p. 39) and Parallels Desktop Business Edition Features (p. 8).
For the complete information about Parallels virtual machine configuration, please refer to the
Parallels Desktop User's Guide.
Adding Windows Application Stubs
Windows application stubs are special links to Windows applications installed in a virtual machine
that can be added to the Dock in macOS during deployment.
About Application Stubs
Application stubs are created in macOS when you create a virtual machine and install Parallels
Tools in it. To see applications stubs for a virtual machine:
1 In macOS, navigate to /Users/<user-name>/Applications (Parallels)
37
Page 38
Mass Deployment of Parallels Desktop and Virtual Machines
2 Expand a desired virtual machine folder. For example, Windows 10 Applications, as shown in
the screenshot below:
The icons that you see in the folder are Windows application stubs. If you double-click an icon, the
corresponding Windows application will be started in the virtual machine.
You can add one or more application stubs to the deployment package to be added to the Dock
on a target Mac computer. For example, if your Mac users will use a particular application most of
the time, it would make sense to add it to the Dock, so they can quickly launch it without dealing
with the Windows user interface.
Windows application stubs are specifically used when you deploy Parallels Desktop using Single
Application Mode. For more information, please see the Single Application Mode section (p. 46).
38
Page 39
Mass Deployment of Parallels Desktop and Virtual Machines
Adding an Application Stub to the Deployment Package
To add one or more application stubs to the deployment package, simply copy it to the Windows
Application(s) stubs to add to Dock folder, as shown on the screenshot below:
Configure Deployment Configuration Options
The deployment package contains a special script, which is automatically executed on a target
Mac after the package is transferred to it. When executed, the script reads the configuration
parameter values from the deploy.cfg file, which you can modify according to your needs.
To modify the parameters, expand the License Key and Configuration folder in the deployment
package and open the deploy.cfg file in a text editor. The configuration parameters are organized
in sections, which are described below.
License
The License section is used to specify the Parallels Desktop Business Edition license key.
Variable Description
license_key
Virtual Machines
Specifies the Parallels Desktop license key. See Specify a License
Key (p. 34)for more info.
The Virtual Machines section is used to specify virtual machine deployment options.
39
Page 40
Mass Deployment of Parallels Desktop and Virtual Machines
The default destination folder for virtual machines can be modified using
vm_destination_folder
Variable Description
Specifies the registration mode for the deployed virtual machines.
Accepted values:
"Private" — The virtual machines will be registered for the active
user only. The virtual machines will be copied to the
vm_register_mode
/Users/<user>/Documents/Parallels folder.
"Shared" — The virtual machines will be registered for all users of a
Mac. The virtual machines will be copied to the
/Users/Shared/Parallels folder.
vm_reset_hwid
vm_deploy_mode
the
Specifies whether the virtual machine SMBOIS ID (hardware ID) will be
regenerated. Each Parallels virtual machine is assigned a universally
unique SMBIOS ID when it is created. When you deploy a virtual
machine to many Macs, each resulting copy of the machine will have
the same SMBIOS ID. This is the default behavior and should not be
normally changed. If your enterprise management system relies on
unique SMBOIS IDs, you can change the value of the
vm_reset_hwid variable as follows:
"no" — Keep the original SMBIOS ID.
"yes" — Regenerate the ID.
Specifies whether the virtual machine(s) will be copied or moved from
the deployment package to their destination folder on a Mac (see the
explanation below).
Accepted values:
"Copy" — Copy the virtual machine(s).
"Move" — Move the virtual machine(s).
If your deployment package contains one or more virtual machines,
they need to be copied or moved to their destination folder on a Mac
during deployment (see vm_register_mode and
vm_destination_folder variables). Moving a virtual machine file is
almost instantaneous, while copying it will take a considerable time due
to the large size of a typical virtual machine. The option you specify
here depends on the following:
variable (see below).
• If the deployment tool that you are using copies the entire
deployment package to a Mac computer before running it,
you can use the fast "Move" option. Jamf Pro, Parallels Mac
Management, and Apple Remote Desktop all copy
packages to a Mac before running them, so you can use the
"Move" option when using these tools. Note that the
package and the destination folder must be located on the
same mount point on a Mac for the "Move" operation to be
fast; otherwise, it'll be essentially a copy-and-delete
operation, hence slow.
• If you are running the deployment package from a network
share mounted on a Mac (e.g. manually), then you should
use "Copy" because moving a virtual machine from a
40
Page 41
remote location will be as slow as copying it, plus the virtual
vm_destination_folder
Mass Deployment of Parallels Desktop and Virtual Machines
machine will be removed from the package if you move it,
so the package will become incomplete (you want it to stay
intact if you want to install it on other Macs).
Please note that when testing the deployment package on a local Mac,
you should be careful when using the "Move" option as it will remove
the virtual machine(s) from the package. If that happens, you will need
to add them again to the package before mass deploying it to Mac
computers in your organization.
Allows you to change the default destination folder for virtual machines.
The default folder is determined by the value of the
vm_register_mode variable (see above). The
vm_destination_folder variable allows you to change the default
folder while keeping the selected virtual machine registration mode.
vm_password_to_edit
<VM_file_name>
Specifies a password that will be required to modify the configuration of
a virtual machine. For more information, please see Restricting Virtual
Machine Configuration with a Custom Password (p. 9).
This variable takes a name of a virtual machine file and allows you to
change the destination location and/or name of the target virtual
machine.
The virtual machines contained in the Parallels folder of the deployment
package will be copied to a default location on a Mac, which is
determined by the vm_register_mode variable (or the
vm_destination_folder variable if is present). If you have
more than one virtual machine in this folder, you can specify a different
destination location and/or name for a specific virtual machine if
needed.
To specify a different location, you need to define a variable/value pair
as shown in the examples below. The variable name should be the
same as the virtual machine file name (including the ".pvm" extension).
The variable value should contain an absolute path where you want the
virtual machine to be copied on a Mac. You can specify a different
destination location, a different virtual machine name, or both. Note that
only the specified virtual machine will be copied to the specified
location. All other virtual machines will be copied to the default location.
Examples:
"Shared_VM.pvm"="/Users/Shared/Shared VM.pvm"
"Private_VM.pvm"="~/Documents/Parallels/Private
VM.pvm"
The following three variables are grouped together and allow you to customize Parallels Desktop Control Center by
displaying a custom HTML banner at the top of its window. For additional information, see Using Custom
Graphics and Links in the Control Center (p. 13).
The URL of a custom HTML page to be displayed as a banner in the
control_center_banner_url
Parallels Desktop Control Center window.
To disable the banner, comment out the variable or specify an empty
string as a value.
41
Page 42
Mass Deployment of Parallels Desktop and Virtual Machines
The banner height, in pixels. The recommended value is 350.
control_center_banner_height
control_center_banner_min_widt
h
To use the current value (if you are updating Parallels Desktop on a
Mac), comment out the variable.
The banner minimum width, in pixels. When resizing the Control Center
window, its minimum width will be limited accordingly. The
recommended value is 350.
To use the current value (if you are updating Parallels Desktop on a
Mac), comment out the variable. To disable the minimum width
limitation, comment out the variable or specify 0 (zero) as a value.
Launch Options
The Launch Options section is used to specify whether Parallels Desktop should run as a service
on or an application.
Note: The start_pd_as_service option is no longer supported in Parallels Desktop 12 and later
versions. Instead, Parallels Desktop makes a decision whether to start as a service based on how the
virtual machines are configured. If virtual machines are configured to run in background, Parallels Desktop
will start as a service. Versions of Parallels Desktop prior to 12 will continue to use the
start_pd_as_service option.
Variable Description
Specifies whether Parallels Desktop should run as an application or as
a service.
The value of "yes" specifies that Parallels Desktop will run as a service.
The service will start automatically on host startup and will stop on host
shutdown. The service can be managed by launchctl (the standard
macOS command line utility that allows you to manage daemons,
applications, processes, etc.).
The value of "no" specifies that Parallels Desktop will run as a macOS
application. The user will have to start and exit Parallels Desktop
manually.
start_pd_as_service
Depending on whether Parallels Desktop is already installed on a target
Mac or not, the following will happen:
- If Parallels Desktop is already installed on a Mac as a service and the
value of "no" is specified, the new installation will set up Parallels
Desktop to run as an application.
- If this option is commented out and Parallels Desktop is already
installed on a Mac, no changes will be made to the way Parallels
Desktop runs.
- If this option is commented out and Parallels Desktop is not installed
on a Mac, it will run as an application.
Software Updates
The Software Updates section is used to configure Parallels Desktop automatic updates.
Variable Description
42
Page 43
Parallels Desktop Business Edition updates, which become available on
"3"
updates_url
Mass Deployment of Parallels Desktop and Virtual Machines
Specifies the update URL. Possible values are:
"Parallels" — Download updates from the Parallels website over
the Internet. Updates are downloaded from a special server hosting
the server at a slightly later date compared to Parallels Desktop Pro
edition. This is the default and recommended option. For more info,
please see Configuring Parallels Desktop Update Options (p. 25).
"None" — Turn off automatic updates.
<URL> — Specifies a custom update URL. You can use this option in
one of the following two cases:
1) If you have a local update server, specify a complete URL (in quotes)
of the parallels_updates.xml file on your local Web server. For
more information, please see Setting Up a Local Update Server (p.
20).
2) If you don't want to wait until Parallels Desktop Business Edition
updates become available, you can specify the URL to download
updates intended for Parallels Desktop Home and Pro editions, which
are released a bit earlier. For more info, please see Configuring
Parallels Desktop Update Options. The URL is as follows (when
assigning it to the variable, put it in quotes):
http://update.parallels.com/desktop/v13/parallels/parallels_sbscr_upda
tes.xml
Note: The "v13" part in the URL above indicates the current Parallels
Desktop version number. If you are using a later version, substitute it
with the correct number.
Specifies how often Parallels Desktop should check for updates.
Possible values:
updates_auto_check
updates_auto_download
"0" — never
"1" — once a day
"2" — once a week
— once a month
Specifies the automatic update download options:
"on" — Download updates automatically. This value should be
specified when using a local update server.
"off" — Notify the user about updates but don't download them
automatically. This option is useful only when updates are downloaded
from the Parallels website and the user has full control over the update
functionality.
Help and Support
The Help and Support section is used to specify the action for the Help > Support Center menu
item in the Parallels Desktop graphical user interface.
Variable Description
support_url
Specifies a URL of a page that will be displayed when user selects the
Help > Support Center menu option in the Parallels Desktop graphical
43
Page 44
Mass Deployment of Parallels Desktop and Virtual Machines
user interface. To display the default message, specify an empty string
Specifies a URL that will be included in error message dialogs related to
"no"
(this is the default behavior). To display your own Web page (help desk,
wiki, etc.), specify its URL.
See also Customizing Support Center Option (p. 26).
licensing operations. The URL should point to a web page or a
resource that the user can visit to get help with the problem.
lic_admin_url
The error message appears when there's a problem with activating,
renewing, or deactivating a Parallels Desktop license. If you specify a
URL using this variable, it will be included in the message dialog in the
form "For details click <URL>". If you don't specify a URL (comment
out the variable or specify an empty string), the default "Contact your
system administrator" message will be displayed.
Problem Reporting
The Problem Reporting section is used to specify whether Parallels Desktop problem reports
should contain screenshots of the macOS and virtual machine desktops. You can exclude the
screenshots for security reasons.
Variable Description
"yes" — Include screenshots of the macOS and virtual machine
report_allow_screenshots
desktops in Parallels Desktop problem reports.
— Do not include the screenshots.
Customer Experience
The Customer Experience section allows you to specify whether the Macs should participate in
the Parallels Customer Experience Program. The Parallels Customer Experience Program is a
feedback solution that allows Parallels Desktop to automatically collect usage statistics and system
information that will help Parallels to develop new features and updates for future releases.
Variable Description
"off" — participation in the program is turned off.
cep_participation
"on" — participation in the program is turned on.
See also Participating in Customer Experience Program (p. 27).
Security
The Security section allows you to enable or disable the password requirement for a number of
Parallels Desktop operations.
Variable Description
The following set of parameters allows you set a custom password and then specify whether this password is
required to perform a corresponding action in Parallels Desktop. For more information about this feature, please
see Restricting User Actions in Parallels Desktop with a Custom Password (p. 8).
current_password
The current password (if one is already set in target Parallels Desktop
44
Page 45
Mass Deployment of Parallels Desktop and Virtual Machines
installations).
"off"
"off"
"off"
"off"
"off"
"off"
Use this key if you want to disable or change the current password, or
if you want to enable/disable any of the actions when the password is
already set.
When disabling the password completely, simply specify the current
password and leave the new_password key (below) commented out.
When changing the password, specify the current password here and
the new password using the new_password key. You can also
enable or disable any of the actions if needed.
When enabling or disabling any of the actions without changing the
password, both the current_password and the new_password
keys must contain the current password.
new_password
password_to_edit_prefs
password_to_create_vm
password_to_add_vm
password_to_remove_vm
password_to_clone_vm
The following set of parameters allows you to specify whether a local Mac administrator password is required to
perform a corresponding action in Parallels Desktop. Please note that the parameters described above provide a
higher level of security since they allow you to use a custom password.
admin_password_to_create_vm
Custom password. If no password is currently set, use this key to
specify the password. If a password is currently set, see the
description above.
"on" — require the password to open the Parallels Desktop
Preferences dialog.
— the password is not required.
"on" — require the password to create a new virtual machine.
"off" — the password is not required.
"on" — require the password to add an existing virtual machine.
— the password is not required.
"on" — require the password to remove a virtual machine.
"off" — the password is not required.
"on" — require the password to clone a virtual machine or converting
it to a template.
— the password is not required.
"on" — require a local Mac administrator password to create a virtual
machine.
"off" — a password is not required.
admin_password_to_add_vm
admin_password_to_remove_vm
admin_password_to_clone_vm
"on" — require a local Mac administrator password to add an
existing virtual machine.
— a password is not required.
"on" — require a local Mac administrator password to remove a
virtual machine from Parallels Desktop.
— a password is not required.
"on" — require a local Mac administrator password to clone a virtual
machine.
— a password is not required.
45
Page 46
Mass Deployment of Parallels Desktop and Virtual Machines
User Experience
The User Experience section allows you specify options related to user experience.
Variable Description
Specifies whether to enable Single Application Mode. For more
information, please see Single Application Mode (p. 46).
Possible values:
"yes" — enable Single Application Mode.
enable_single_application_mode
show_developers_menu
Single Application Mode
If the parameter is commented out, Parallels Desktop will be deployed
using the "standard" mode.
NOTE: Please note that you cannot redeploy Parallels Desktop with
this option set to "no" or commented out to disable Single
Application Mode. For that, you will need to completely remove
Parallels Desktop from your Mac computers and then redeploy
Parallels Desktop with this option commented out.
Specifies whether to show or hide developer tools in the Parallels
Desktop GUI. For more information, please see Hiding Developer
Tools in Parallels Desktop GUI (p. 14)
Possible values:
"no" — hide developer tools.
"yes" — show developer tools.
Please note that this setting will be applied to every virtual machine
included in the deployment package. You can also configure each
virtual machine to hide (or show) developer tools prior to deployment,
but with this option you can apply the setting automatically during
deployment.
Overview
Single Application Mode is a special Parallels Desktop deployment option that allows you to
completely hide Parallels Desktop and Windows on a Mac and make a Windows application
appear like it's a native macOS app. This mode is designed for system administrators who want
Mac users in their organization to run one or more Windows applications without being aware of
Parallels Desktop or Windows running in a virtual machine.
When Parallels Desktop is deployed using Single Application Mode:
• A Mac user will not see the Parallels Desktop icon, user interface, or the virtual machine window
at any time.
• A Windows application icon is added to the Dock. When the user clicks on the icon, the
application will run on a Mac desktop like a native macOS application.
46
Page 47
Mass Deployment of Parallels Desktop and Virtual Machines
• A Mac user will never know that Parallels Desktop and Windows are running on their Mac
computer.
Configuring Deployment Options
To deploy Parallels Desktop using Single Application Mode, do the following:
1 Add a virtual machine to the deployment package. For instructions, see Add a Virtual Machine
(p. 35). Please take note of the following:
• You can add only ONE virtual machine when using Single Application Mode.
• The virtual machine must be properly shut down before adding it to the deployment
package (i.e. you need to properly shut down Windows). DO NOT simply close it, as this will
be detected as a crash by Windows and a Mac user will have to deal with it at startup.
2 Add a Windows application stub to the deployment package that will be used to run a desired
Windows application on a Mac. If you want to deploy more than one Windows application, add
a corresponding stub for each one. For details, please see Adding Windows Application
Stubs (p. 37).
3 To enable Single Application Mode, set the enable_single_application_mode="yes"
parameter in the deploy.cfg file, as described in Configure Deployment Configuration
Options (p. 39). The parameter is included in the User Experience section of the
deploy.cfg file.
4 Deploy Parallels Desktop to Mac computers as described in Deploying Parallels Desktop and
Virtual Machines to Mac Computers (p. 49). If you want to deploy it on a single Mac, you can
simply execute the deployment package (Parallels Desktop Autodeploy.pkg) on that Mac.
Configuring Windows
Please note that for Windows to be completely hidden on a Mac, you need to make some changes
manually because they cannot be automated. The following list describes these changes:
• Enable auto logon in Windows. Make sure that Windows in the virtual machine doesn't ask
the user to log on. If this is not done, a Mac user will see the Windows logon screen when
Windows starts or reboots.
• Disable Windows updates. If this is not done, Windows may ask the user to install updates
when they become available. You can install updates manually if needed.
• Configure file associations in Windows. This is necessary so that Windows doesn't open
another Windows application when the user tries to open a file from the primary application. For
example, let's say you deployed Outlook for Windows. A Mac user may try to open a text file
attachment in Outlook. Normally, the file will open in Notepad in Windows, which may confuse
the user. To prevent this, you can associate text files with TextEdit (a macOS application) in a
virtual machine. The ability to associate file extensions with macOS applications is a standard
Parallels Desktop feature available in Windows in a virtual machine. In addition, we recommend
that you have as little applications installed in Windows as possible in order not to create
additional file associations.
47
Page 48
Mass Deployment of Parallels Desktop and Virtual Machines
• Use the Productivity profile. When creating a virtual machine for Single Application Mode,
choose the Productivity profile in the virtual machine Installation Assistant. If you are using an
existing virtual machine, change its profile by going to Configuration > General > Configure
for, clicking Change and then selecting Productivity.
• Turn Windows sounds off. You may consider turning all Windows sounds off, so no standard
Windows sounds are played on a Mac computer at any time. A quick way to do this is to
disable sound support in the virtual machine configuration by going to Hardware and clicking
the minus-sign icon to remove the Sound item from it.
Configuring macOS
If you are deploying Parallels Desktop on macOS Hight Sierra, you have to make sure in advance
that Parallels Desktop kernel extensions are either approved or don't require user consent on each
Mac. This is particularly important when using the Single Application Mode because if the
extensions are not approved, Mac users will see warning messages about them when they try to
run a Windows application for the first time. For more information, please see Kernel Extensions in
macOS High Sierra (p. 29).
Testing the Deployment Package
Once you have the Parallels Desktop deployment package configured, you can test it on a single
Mac before you mass deploy it to other Mac computers in your organization.
To test the package:
1 Copy it to a Mac on which you want to test it. The Mac should have a configuration similar to
other Mac computers on which you'll be deploying Parallels Desktop. Specifically, if your target
Mac computers don't have Parallels Desktop and virtual machines installed, the test Mac
shouldn't have them installed either. If target Macs have an older version of Parallels Desktop,
the test Mac should have it installed too, so you can see what will be the results.
2 To speed up the execution of the package during testing, consider running it from the
command line using /System/Library/CoreServices/Installer.app. When executed this way, the
package will not be tested by macOS whether it is signed and the usual verification of the
package will be skipped. Please note that if you run the package by double-clicking on it,
macOS will complain that the package is not signed and will not install it. If you run the package
by right-clicking and choosing Open, the check whether the package is signed will be skipped
but the verification of the package will take a long time if you have one or more virtual machines
in it (because of the large size of a typical virtual machine). When you use the Installer.app to run
the package, the installation will begin immediately without any checks or verifications. All of the
above only applies when you run the package manually. When you mass deploy it on Mac
computers, verification is not performed and the installation is completely silent.
3 When the installation is complete, verify that Parallels Desktop is installed, activated, and is
functioning properly. If your package is configured to deploy Parallels Desktop in Single
Application Mode, try running the application and see that it starts and runs as it should.
Read on to learn how to mass deploy the package using one of the Mac management tools.
48
Page 49
Mass Deployment of Parallels Desktop and Virtual Machines
Deploying Parallels Desktop and Virtual Machines to Macs
This section contains instruction on how to deploy the Parallels Desktop deployment package
using the following solutions:
• Jamf Pro (p. 49)
• Parallels Mac Management for Microsoft SCCM (p. 55)
• Apple Remote Desktop (p. 57)
• Deploying macOS Image Using NetBoot (p. 61)
Deploying with Jamf Pro
Jamf Pro includes the Software Distribution functionality that you can use to deploy the Parallels
Desktop package to Mac computers in your organization. To deploy the package you need:
• Jamf Pro server installed and configured.
• Target Mac computers enrolled in Jamf Pro.
• A distribution point (cloud or file share) configured and be accessible from the target Mac
computers.
Add a distribution point
A distribution point is a server that hosts files for distribution to computers. If your Jamf Pro
installation doesn't have a distribution point, you need to add one to host the Parallels Desktop
deployment package.
To add a distribution point:
1 Open the Jamf Pro console and log in to your Jamf server.
49
Page 50
Mass Deployment of Parallels Desktop and Virtual Machines
2 Click the gear icon in the upper right and then click Server Infrastructure in the left pane.
3 Jamf Pro supports cloud-based (content delivery networks) and file share distribution points.
Depending on what is available to you, click the Cloud Distribution Point or the File Share
Distribution Points icon. The instructions below are for setting up a file share distribution point.
If you would like to set up a cloud distribution point, please consult Jamf Pro documentation for
details.
4 After you click the File Share Distribution Point icon, click New.
5 On the General tab page:
• Type a name for the distribution point.
• Specify the IP address or the host name of the distribution point server.
• Select the Use as master distribution point option.
6 Click the File Sharing tab and specify the following:
• Protocol: Select AFP or SMB depending on which protocol is used on your server for file
sharing.
• Share name: Specify the share name. For example, if your server name is MYSERVER and
your full share name is \\MYSERVER\JAMF-SHARE, specify JAMF-SHARE in this field.
• Port: In most cases the default value is what a given protocol normally uses. If you know
that your server uses a different port number, specify it here.
• Read/Write Account: Specify credentials of an account that has read/write access to the
share.
• Read-Only Account: Specify credentials of an account that has read-only access to the
share.
7 If your server supports HTTP downloads, select the HTTP/HTTPS tab and then select the Use
HTTP downloads option. Based on our own and other users' experience, HTTP/HTTPS-
enabled distribution points are more reliable than AFP/SMB shares, but you can try both
options and see which one works better for you.
8 Click Save to save the settings and add the distribution point to your Jamf Pro installation.
50
Page 51
Mass Deployment of Parallels Desktop and Virtual Machines
Add the deployment package to the distribution point
To add the deployment package to the distribution point:
1 Open the Jamf Admin app on a Mac and login to your Jamf Pro server.
2 Drag the Parallels Desktop deployment package to the main repository area (the middle area in
the right pane).
3 The package will be uploaded to the master distribution point and will appear in Jamf Admin as
a zip archive, as shown on the screenshot below.
Don't be alarmed about the .zip extension. Jamf Admin compresses non-flat PKGs in order to
make their size smaller. When deployed, the archive is automatically unzipped on a target Mac
and the package is executed normally.
4 You can set other options if needed, such as add a package to a category or change the
package priority. Indexing the package is not necessary for the purpose of deploying it on
Macs.
5 Close the Jamf Admin when done.
51
Page 52
Mass Deployment of Parallels Desktop and Virtual Machines
To verify that the package has been added to the distribution point:
1 Open the Jamf Pro console and login to Jamf Pro server.
2 Click the gear icon in the upper right and select Computer Management in the left pane.
3 Click Packages in the right pane. You should see the Parallels Desktop Autodeploy.pkg.zip
package in the list.
4 If needed, you can modify the package display name and other settings. To do so, click the
package and then click the Edit button in the lower right. Modify any of the settings as you
require (except the file name). All settings are optional. If not sure, simply leave them
unchanged.
Install the package
You can install the package on Mac computers using a policy or you can use the Jamf Remote app
that works similar to Apple Remote Desktop. This section contains instructions on how to install a
package using a policy. For Jamf Remote instructions, please refer to the Jamf Pro documentation.
Create a policy
To create a policy:
52
Page 53
Mass Deployment of Parallels Desktop and Virtual Machines
1 In the Jamf Pro console, click the Computers tab in the left pane and then click Policies.
2 In the right pane, click New. The New Policy pane loads where you can define the policy.
3 In the General payload, specify the following:
• Type a name for the policy.
• Select the Enabled option.
• Specify a category (optional).
• In the Trigger section, select one or more events that should trigger the policy retrieval on
target Mac computers.
• In the Execution Frequency drop-down list, select a frequency at which to run the policy.
Since Parallels Desktop has to be installed just once, you may select Once per computer
or Once per user (to install Parallels Desktop for each user if a Mac has more than one).
• The Target Drive option allows you to specify the drive on which to run the policy. You
would normally use the default option, which will run the policy on the boot drive.
• Other options in the General payload allow you to configure limitations on when the policy
can and cannot run. This includes server-side and client-side limitations. You can specify
them according to your needs or you can leave them blank.
4 To specify a package for the policy, click the Packages payload and then click the Configure
button in the right pane.The pane will be populated with the list of available packages.
53
Page 54
Mass Deployment of Parallels Desktop and Virtual Machines
5 Locate the Parallels Desktop Autodeploy.pkg.zip package and click Add.
6 Select a distribution point that contains the Parallels Desktop package. If you select the
Specific file share distribution point option, choose the distribution point. If the distribution
point is both an AFP/SMB and HTTP share, Jamf will try to use the HTTP option to download
the package to target Macs. If needed, you can force it to use the AFP/SMB share by selecting
the Force file sharing over AFP/SMB option. Based on our observations, HTTP shares work
more reliably in Jamf, but you can try different options if you are experiencing issues with
mounting shares on Mac computers during the policy execution.
7 In the Action drop-down list, select how the package should be downloaded and installed on
Mac computers:
• Install — when the policy runs, the package is downloaded and installed on a Mac
computer as a single operation. Note that if you have a large number of Macs and the policy
runs on all of them simultaneously, all of them will try to download the policy at the same
time. For this reason, you may consider the options below to avoid overloading your
network.
• Cache — when the policy runs, the package is downloaded to a Mac computer but is not
installed at that time.
• Install Cached — a policy with this action installs the package that has been downloaded
previously using the Cache option. You can use this and the "Cache" options if you are
deploying Parallels Desktop on a large number of Macs. First, you "cache" the deployment
package on each Mac at a convenient time. Once that's done, you run the "Install Cached"
policy to install the package, which will be a completely local operation for each Mac. This
way, you can ensure that Parallels Desktop is deployed on each Mac at roughly the same
time (e.g. on the weekend) without delays.
8 The rest of the payloads are not required for Parallels Desktop package deployment.
9 To specify target Mac computers, click the Scope tab at the top of the pane. You can specify
targets by computer name or user name (or both).You can also set limitations and exclusions to
further narrow down the target list.
54
Page 55
Mass Deployment of Parallels Desktop and Virtual Machines
10 If you would like the package to appear in the Self Service app on a Mac, click the Self
Service tab, select the Make the policy available in Self Service option, and specify
additional options if needed. The Self Service app allows the user to initiate the policy retrieval
manually without waiting for it to trigger.
11 The User Interaction tab page allows you to specify messages that will be displayed to a Mac
user when the policy runs on their Macs. If you want the installation to be completely silent, you
can skip this page.
12 When done, click Save to save the policy.
Deploy the package
Once the policy is retrieved by a Mac computer, it will install and activate Parallels Desktop on it.
Once completed, the Mac user can begin using Parallels Desktop immediately.
If you are testing your policy, you can wait for it to trigger or you can run it manually using the Self
Service app on a Mac. The app is installed when a Mac is enrolled in Jamf Pro and can be opened
from the Applications folder in macOS. If there errors executing the policy, you can review them in
the app. Please also note that when testing a policy, don't try to run it on the same Mac that you
use as a distribution point because an attempt to mount a share on the same Mac that hosts it will
fail.
Deploying with Parallels Mac Management for Microsoft SCCM
Parallels Mac Management for Microsoft SCCM enables you to deploy Parallels Desktop to Mac
computers via the SCCM Software Distribution functionality. For the complete information about
Parallels Mac Management for Microsoft SCCM, please read the Administrator's Guide that can be
downloaded from https://www.parallels.com/products/mac-management/resources/.
The basic steps of deploying Parallels Desktop using Parallels Mac Management are:
1 Prepare the Parallels Desktop deployment package (described earlier in this guide).
2 Create a software distribution package using the Microsoft Configuration Manager console.
3 Send the package to a distribution point.
4 Deploy the package.
The following describes steps 2-4 in detail.
Create a software distribution package
The Parallels Desktop deployment package is distributed to Macs using the standard Configuration
Manager functionality:
1 In the Configuration Manager console, navigate to Administration / Overview / Application
Management / Packages.
2 On the toolbar, click Create Package.
55
Page 56
Mass Deployment of Parallels Desktop and Virtual Machines
3 Use the Create Package and Program Wizard to create a software distribution package and
a program.
4 On the Package page, specify the package name and an optional description, manufacturer,
language, and version information. Select the This package contains source files option and
click Browse. Select the folder that contains the Parallels Desktop Autodeploy.pkg
folder. Please note that you must select the parent folder of the Parallels Desktop
Autodeploy.pkg folder, NOT the .pkg folder itself.
5 Click Next.
6 On the Program Type page, select the Standard program item and click Next.
7 On the Standard Program page, specify the information about the program. Type the following
in the Command line field:
chmod 700 "Parallels Desktop
Autodeploy.pkg/Contents/Resources/postflight" && installer -pkg
"Parallels Desktop Autodeploy.pkg" -target /
8 When done specifying the program information, click Next.
9 Click Next on the Requirements page.
10 Review the summary and click Next to create the package.
Upload the package to the distribution point
To upload a copy of the package to the distribution point, right-click the package and choose
Distribute Content in the pop-up menu. Use the Distribute Content Wizard to specify a
distribution point to which you want to send the package.
Please make sure that the distribution point is properly configured. For more information, see the
Parallels Mac Management Administrator's Guide.
Deploy the package
To deploy the package:
1 In the Configuration Manager console, right-click the package and then click Deploy in the
pop-up menu. The Deploy Software Wizard opens.
2 On the General page, click the Browse button next to the Collection field and select the
collection containing your Macs (e.g. All Mac OS X Systems). Click OK and then click Next.
3 On the Content page, verify the distribution point info and click Next.
4 Click Next on the Deployment Settings page.
5 On the Scheduling page, specify the schedule for this deployment. Click New to specify the
assignment schedule. When done, click Next.
6 Use the default values on the rest of the wizard pages and complete the wizard.
56
Page 57
Mass Deployment of Parallels Desktop and Virtual Machines
The package will be advertised to Macs in the specified collection and will be distributed to them
according to the specified schedule.
Deploying with Apple Remote Desktop
To use Apple Remote Desktop, you need Apple Remote Desktop Admin, which should run on your
administrator Mac, and Apple Remote Desktop client, which should run on client Macs.
Apple Remote Desktop Admin doesn't come standard with macOS. You will have to obtain the
software from Apple and install it on a Mac from which you are deploying Parallels Desktop. Apple
Remote Desktop client is installed during the standard macOS installation.
Note: Before continuing, please verify that the versions of Apple Remote Desktop Admin and each
instance of Apple Remote Desktop client match. If they don't, update the necessary software.
Configure Remote Management Services on target Macs
For a remote management tool (ARD in our case) to be able to distribute the software, the Remote
Management Services have to be configured in macOS on each individual Mac. In order to do so,
you need to log in to each Mac and perform the following steps:
1 In macOS, open System Preferences.
2 Click Sharing.
3 In the Service list, select Remote Management.
4 Click Options.
5 Select the following options: Observe, Control, Open and quit applications, Change
settings, Delete and replace items, Copy items (see the picture below).
6 Click OK.
7 Close System Preferences.
57
Page 58
Mass Deployment of Parallels Desktop and Virtual Machines
Deploy the package
To deploy the package to Macs:
1 On the administrator Mac, open the Finder and click Applications > Remote Desktop to
display the main window of Apple Remote Desktop.
Note: If you have set up a Task Server, you can deploy the package from that server.
2 Click All Computers in the left section of the ARD main window. The Mac computers
connected to your network are displayed in the right pane of the window.
3 Select the desired destination Macs and click Install in the ARD toolbar (or select Manage >
Install Packages menu). The Install Packages window opens.
58
Page 59
Mass Deployment of Parallels Desktop and Virtual Machines
4 Add the Parallels Desktop Autodeploy.pkg file to the Packages list either by
dragging it there with the mouse or by locating the package using the '+' button
5 Click Install to distribute the deployment package to selected Macs. The installation progress is
displayed in the main window. The result of the package distribution to each individual Mac is
displayed in the Status column.
When the package is distributed to a Mac, it runs on it and installs Parallels Desktop and the virtual
machine(s). It then activates Parallels Desktop using the supplied license key.
Using Apple Remote Desktop templates
Apple Remote Desktop allows you to save package installation settings as templates. This feature
may be useful if you need to deploy Parallels Desktop more than once using different settings. For
example, you may have a virtual machine specifically configured for your developers and another
one configured for your graphics designers or quality assurance engineers. Instead of modifying the
deployment package every time you need to deploy Parallels Desktop to a specific group of Mac
users, you can create separate packages and save them as templates.
To create an ARD template:
59
Page 60
Mass Deployment of Parallels Desktop and Virtual Machines
1 On the administrator Mac, open Apple Remote Desktop.
2 Click All Computers in the left pane of the ARD main window.
3 Select the computers where the deployment package is to be installed and click Install in the
ARD toolbar.
4 In the Install Packages window, add the desired Parallels Desktop deployment package either
by dragging it to the top area of the displayed window or locating it by using the '+' button.
5 Save current installation setup as a template by selecting Save as Template from the
Template pop-up menu located in the upper right-hand corner of the Install Packages
window.
6 In the displayed window, specify the name that you would like to use for the template and click
OK.
The next time when you are ready to deploy Parallels Desktop to a specific group of Mac users,
simply select the desired template from the same Template pop-up menu in the Install Packages
window and then click Install.
60
Page 61
Mass Deployment of Parallels Desktop and Virtual Machines
Deploying macOS Image Using NetBoot
If you are using NetBoot to deploy a macOS image with Parallels Desktop Business Edition
preinstalled, some additional steps need to be taken to properly activate a copy of Parallels
Desktop on individual Macs.
The following steps describe the process of installing Parallels Desktop and creating an image from
it suitable for NetBoot deployment:
1 Install macOS on a Mac.
2 Install Parallels Desktop Business Edition.
3 Make sure your Mac can connect to the Internet.
4 Activate Parallels Desktop using your Business Edition license key.
5 Tune Parallels Desktop settings and add or create virtual machines according to your needs.
6 Open Terminal and deactivate the Parallels Desktop license by typing the following command:
prlsrvctl deactivate-license
On successful license deactivation, you should see the following output:
The License has been successfully deactivated
7 Quit Parallels Desktop.
8 In Terminal, type the following command to prepare Parallels Desktop to activate a license in
deferred mode:
prlsrvctl install-license --key <key> --deferred
where <key> is the Parallels Desktop Business Edition license key.
On success, you should see the following output:
The License has been successfully prepared for deferred
installation.
This means that the next time Parallels Desktop starts, it will try to activate the license
automatically. The Internet connection is required for activation. If a Mac can't connect to the
Internet, the Parallels Desktop license activation will be postponed until the Internet connection
is available.
You can now create a macOS image from this system and deploy it to other Macs in your
enterprise using NetBoot.
61
Page 62
C HAPTER 4
Parallels Desktop Command Line Interface
This chapter 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.
In This Chapter
Parallels Desktop Management ............................................................................... 62
Virtual Machine Management .................................................................................. 70
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.
Page 63
Parallels Desktop Command Line Interface
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
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.
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.
Optional parameters
-n, --name <name>
The license owner name.
-c, --company <name>
The license company name.
--deferred
63
Page 64
Parallels Desktop Command Line Interface
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.
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
Activates the installed Parallels Desktop license over the Internet.
Activate a License Offline
prlsrvctl activate-license-offline <-i, --id <confirmation-id>>
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.
64
Page 65
Parallels Desktop Command Line Interface
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>
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 a password to perform a corresponding action (create a VM, add a VM, etc.).
--require-custom-pwd <create-vm | add-vm | remove-vm | clone-vm | edit-preferences>:<on
| off>
Require to enter a custom password to perform a corresponding action.
--custom-pwd [--custom-pwd-mode <on | off | change>]
Sets, resets, or changes the custom password for restricting common operations.
--lock-edit-settings <on | off [--host-admin <name>]>
65
Page 66
Parallels Desktop Command Line Interface
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.
--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.
66
Page 67
Parallels Desktop Command Line Interface
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.
-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.
67
Page 68
Parallels Desktop Command Line Interface
--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.
--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]
Lists installed USB devices together with the information on their assignments for the current
user.
prlsrvctl usb set <usb_dev_id> <vm_uuid | vm_name>
Assigns a specified USB device to the specified virtual machine. The USB device will be
connected to the specified virtual machine when the virtual machine is started or a device is
attached to the host computer.
prlsrvctl usb del <usb_dev_id>
68
Page 69
Parallels Desktop Command Line Interface
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
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.
69
Page 70
Parallels Desktop Command Line Interface
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:
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
70
Page 71
Parallels Desktop Command Line Interface
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
Lists fields which can be used for both the output (-o, --output) and sort order (-s, --sort)
options.
-t, --template
Include templates in the output.
-j, --json
Produces output in JSON format.
Syntax 2
list -i, --info
Displays the VM configuration information. By default, the information for all existing VMs is
shown.
Optional parameters
-f, --full
Shows the real IP address(es) for running virtual machines.
-j, --json
Produces output in JSON format.
vm_id | vm_name
Returns the information about a VM specified by ID or name.
71
Page 72
Parallels Desktop Command Line Interface
Create a Virtual Machine
Syntax 1
prlctl create <vm_name> --ostemplate <name>
Creates a virtual machine from the specified virtual machine template. The --ostemplate
<name> parameter specifies the source template name. To obtain the list of available
templates, use the prlctl list -t command.
Optional parameters
--dst
A path to the directory where the virtual machine files will be stored. If omitted, the default
location will be used.
--changesid
Change the Windows security identifier (SID) of a Windows-based virtual machine template. It
requires Parallels Tools to be installed in the template. If omitted, the original SID will be used.
Syntax 2
prlctl create <vm_name> -o,--ostype <name | list>
Creates a virtual machine and optimizes it for the OS type specified in the --ostype option. Use
the list option to get the list of available OS types: prlctl create vm_name -o list, then select a
desired OS type name and use it as a value of the -o parameter.
Syntax 3
prlctl create <vm_name> -d,--distribution <name | list>
Creates a virtual machine and optimizes it for the OS distribution specified in the --distribution
option. Use the list option to get the list of available distributions: prlctl create vm_name -d
list, then select a desired distribution name and use it as a value of the -o parameter.
Common optional parameters
--no-hdd
Create a virtual machine without hard disk drives.
--lion-recovery
Create a virtual machine from the Lion OS host recovery partition.
72
Page 73
Parallels Desktop Command Line Interface
Delete a Virtual Machine
prlctl delete <vm_id | vm_name>
Deletes a virtual machine. The command removes a virtual machine from Parallels Desktop and
permanently deletes all its files from the host computer. Once completed, this operation cannot
be reversed.
Register / Unregister a Virtual Machine
Register a virtual machine
prlctl register <path>
Registers a virtual machine with Parallels Desktop. The <path> parameter specifies a path to
the virtual machine file.
Optional parameters
--preserve-uuid
If included, the existing virtual machine ID will be kept unchanged.
--uuid <UUID>
If included, the specified UUID will be assigned to the virtual machine. Note that you can include
either the -uuid or the --preserve-uuid parameter, but not both. If none of the two parameters
are included, an automatically generated ID will be used for the virtual machine.
--force
If included, all validation checks will be skipped.
--regenerate-src-uuid
If included, the virtual machine source ID will be automatically generated (the SMBIOS product
ID will be changed as well).
Unregister a virtual machine
prlctl unregister <vm_id | vm_name>
Unregisters the specified virtual machine.
73
Page 74
Parallels Desktop Command Line Interface
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 Parallels Desktop. This can be a machine that was
previously removed from Parallels Desktop or a machine that was manually copied from another
location.
The unregister command removes a virtual machine from Parallels Desktop but does not delete it
from the host. You can re-register such a machine with Parallels Desktop later using the register
command.
Clone a Virtual Machine
prlctl clone <vm_id | vm_name> --name <new_name>
Clones (makes an exact copy of) a specified virtual machine. The -name <new_name>
parameter specifies a name to give to the new virtual machine.
Optional parameters
--template
Make the new virtual machine a template.
--dst
Set the path to the directory where the virtual machine files will be stored. If omitted, the default
location will be used.
--changesid
Change the current Windows security identifier (SID) of a Windows-based virtual machine
template. It requires Parallels Tools to be installed in the virtual machine template.
--regenerate-src-uuid
Regenerate the virtual machine source ID (the SMBIOS product ID will also be changed).
--linked
Create a linked clone.
-i, --id <snapid>
Create a linked clone based on a snapshot with given snapid.
--detach-external-hdd <yes | no>
74
Page 75
Parallels Desktop Command Line Interface
Specifies what to do with hard disks located outside the source virtual machine file. If you
specify yes, outside hard disks will be removed from the destination VM. If you specify no,
outside hard disks will remain in the new VM. Please note that in either case, the outside hard
disks will NOT be copied to the destination.
Convert a Virtual Machine
prlctl convert <path>
This command is used to convert a third-party virtual machine to a Parallels virtual machine.
The <path> parameter specifies a path to the original virtual machine.
Optional parameters
--dst <path>
A path where the converted virtual machine files will be stored. If omitted, the default virtual
machine location will be used.
--force
If included, the virtual machine conversion will continue even if the guest OS cannot be
identified.
Notes
The following third-party virtual machines and disks are supported:
• Microsoft Hyper-V
• Microsoft Virtual PC
• Virtual Box
• VMware
Move Virtual Machine Files
prlctl move <vm_id | vm_name> --dst <path>
Moves the files of a specified virtual machine to a location specified in the -dst parameter on
the same computer. The command supports moving only stopped and suspended virtual
machines.
Install Parallels Tools
prlctl installtools <vm_id | vm_name>
Installs Parallels Tools in the specified virtual machine. To use this command, the target virtual
machine must be running.
75
Page 76
Parallels Desktop Command Line Interface
Log In to a Virtual Machine
prlctl enter <vm_id | vm_name>
Logs in to the virtual machine. The command creates a command prompt channel to a virtual
machine and allows you to execute commands in it. Parallels Tools must be installed in the
virtual machine.
Optional parameters
--current-user or --user <user_name>
Include the --current user option to log in as the current macOS user or use the --user
parameter and specify a user name.
--password <password>
The user password.
Execute a Command In a Virtual Machine
prlctl exec <vm_id | vm_name> <command>
Executes a command inside a virtual machine. Parallels Tools must be installed in the virtual
machine. Commands in Linux guests are invoked with bash -c.
Optional parameters
--current-user or --user <user_name>
Include the --current user option to log in as the current macOS user or use the --user
parameter and specify a user name.
--password <password>
The user password
-r, --resolve-paths
Enable converting host paths to guest.
Get Virtual Machine Status
prlctl status <vm_id | vm_name>
Displays the status of the specified virtual machine.
Power Operations
prlctl start <vm_id | vm_name>
76
Page 77
Parallels Desktop Command Line Interface
Starts the specified virtual machine. The start command can be used to start a stopped virtual
machine or to resume a paused virtual machine.
prlctl resume <vm_id | vm_name>
Resumes the specified virtual machine.
prlctl pause <vm_id | vm_name>
Pauses the specified virtual machine.
prlctl suspend <vm_id | vm_name>
Suspends the specified virtual machine.
prlctl restart <vm_id | vm_name>
Restarts the specified virtual machine. The restart command first gracefully shuts down a virtual
machine and then starts it again.
prlctl reset <vm_id | vm_name>
Resets the specified virtual machine. The reset command first performs a 'hard' virtual machine
shutdown and then starts it again.
prlctl reset-uptime <vm_id | vm_name>
Resets the specified virtual machine uptime counter (the counter start date/time will also will be
reset with this action).
prlctl stop <vm_id | vm_name> [--kill]
Stops the specified virtual machine. You can use the --kill option to forcibly stop the VM. 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.
Change Windows SID
prlctl change-sid <vm_id | vm_name>
Changes the Windows security identifier (SID) in the specified virtual machine.
Capture a Screen Area
prlctl capture <vm_id | vm_name> --file <name>
77
Page 78
Parallels Desktop Command Line Interface
Captures a screen area of a virtual machine to a file in PNG format. The --file <name>
parameter specifies the target file name and path.
Encrypt / Decrypt a Virtual Machine
prlctl encrypt <vm_id | vm_name> [--dry-run]
Encrypts the specified virtual machine. You can use the the --dry-run option to check
preconditions for successful encryption. 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. The password will be required to decrypt the virtual machine later. The
encryption password can be modified for an encrypted virtual machine using the change-
passwd command (see below).
prlctl decrypt <vm_id | vm_name> [--dry-run]
Decrypts the specified encrypted virtual machine. You can use the the --dry-run option to
check preconditions for successful decryption. The decrypt command will decrypt the
specified virtual machine. A user will have to enter a password that was specified when the
virtual machine was encrypted.
prlctl change-passwd <vm_id | vm_name>
Changes the encryption password for the specified virtual machine. A user will be asked to
enter the current and the new password.
Archive / Unarchive a Virtual Machine
prlctl archive <vm_id | vm_name>
Archives the specified virtual machine bundle.
prlctl unarchive <vm_id | vm_name>
Unarchives the specified virtual machine bundle.
Set Password Protection
prlctl protection-set <vm_id | vm_name>
Protects the specified encrypted virtual machine expiration date settings with a password.
prlctl protection-remove <vm_id | vm_name>
Disables password protection of the specified encrypted virtual machine expiration date
settings.
Virtual Machine Configuration Tasks
This section describes prlctl set command options that you can use to configure a virtual machine.
78
Page 79
Parallels Desktop Command Line Interface
The general syntax is as follows:
prlctl set <vm_id | vm_name> [options]
The prlctl set command is used to modify the configuration of a virtual machine and manage virtual
machine devices and shared folders. The subsequent subsections describe parameters and
options that can be used with this command to perform a variety of virtual machine configuration
management tasks.
CPU and Memory Parameters
--cpus <num>
Sets the number of CPUs to be available to the virtual machine.
--memsize <num>
Sets the amount of memory for the virtual machine (in megabytes).
Boot Order Parameters
--device-bootorder <"name1 name2 ...">
Specifies the order of boot devices for the virtual machine. Supported devices are HDD,
CD/DVD, FDD, Network. A device name can be obtained using the prlctl list -i command.
--efi-boot <on | off>
Sets EFI boot options. Specify on to boot using the EFI firmware. Specify off to boot using the
BIOS firmware (default).
--select-boot-device <on | off>
Enables or disables selecting a boot device at the virtual machine startup.
--external-boot-device <name>
Sets an external device from which to boot the virtual machine.
Video Parameters
--videosize <num>
Sets the amount of memory for the virtual machine graphic card (in megabytes).
--3d-accelerate <off | highest | dx9>
Sets 3d acceleration video mode.
--vertical-sync <on | off>
Enables or disables vertical synchronization.
79
Page 80
Parallels Desktop Command Line Interface
--high-resolution <on | off>
Enables or disables high resolution video mode for retina display.
Mouse and Keyboard Parameters
--smart-mouse-optimize <auto | on | off>
Sets smart mouse optimization mode.
--sticky-mouse <on | off>
Enables or disables sticky mouse option.
--keyboard-optimize <on | off>
Enables or disables keyboard optimization mode.
Virtual Printer Parameters
--sync-host-printers <on | off>
Enables or disables using host printers in Windows guests (starting from Windows 2000).
--sync-default-printer <on | off>
Synchronizes host's default printer with Windows default printer.
USB and Bluetooth Parameters
--auto-share-camera <on | off>
Enables or disables automatic Web camera sharing.
--auto-share-bluetooth <on | off>
Enables or disables automatic sharing of bluetooth devices.
--support-usb30 <on | off>
Enables or disables USB 3.0 support.
Startup and Shutdown Parameters
--autostart <off | open-window | start-app | start-host | user-login>
Sets the virtual machine autostart options:
off: The virtual machine is started manually.
open-window: The virtual machine starts when its window opens.
start-app: The virtual machine starts when Parallels Desktop starts.
80
Page 81
Parallels Desktop Command Line Interface
start-host: The virtual machine is started automatically on the host boot.
user-login: The virtual machine is started automatically on user logon.
--autostart-delay <n>
Sets the delay of the virtual machine autostart on host boot to n seconds.
--autostop <stop | suspend | shutdown>
Specifies what should happen to the virtual machine on host shutdown.
--startup-view <same | window | coherence | fullscreen | modality | headless>
Sets the virtual machine startup view options:
same: Same as the last time
window: Normal window
coherence: Coherence
fullscreen: Full screen
modality: Modality
headless: Headless
--on-shutdown <window | close | quit>
Sets the virtual machine shutdown options:
window: The virtual machine window stays open after the virtual machine is shut down.
close: The virtual machine window closes after the virtual machine is shut down.
quit: Parallels Desktop quits after the virtual machine is shut down.
--on-window-close <suspend | shutdown | stop | ask | keep-running>
Sets the virtual machine window close options:
suspend: The virtual machine is suspended after its window is closed.
shutdown: The virtual machine is shut down after its window is closed.
stop: The virtual machine is forcibly stopped after its window is closed.
ask: Ask the user what to do: suspend, shut down, or stop the virtual machine.
keep-running: The virtual machine is kept running after its window is closed.
--pause-idle <on | off>
Enables or disables pausing of an idle virtual machine.
--undo-disks <off | discard | ask>
Sets the virtual machine undo disks options:
81
Page 82
Parallels Desktop Command Line Interface
off: Undo disks mech is off.
discard: Discard all changes made in the virtual machine after it is stopped.
ask: Ask the user what to do: apply changes or discard them after the virtual machine is
stopped.
Optimization Parameters
--faster-vm <on | off>
Sets the performance mode: faster virtual machine or faster host.
--adaptive-hypervisor <on | off>
Enables or disables adaptive hypervisor.
--disable-winlogo <on | off>
Enables or disables Windows logo.
--auto-compress <on | off>
Enables or disables automatic compression of virtual disks.
--nested-virt <on | off>
Enables or disables nested virtualization.
--pmu-virt <on | off>
Enables or disables PMU virtualization.
--longer-battery-life <on | off>
Sets a power option: longer battery life or better performance.
--battery-status <on | off>
Shows or hide battery status.
--resource-quota <low | medium | unlimited>
Sets the virtual machine resource quota:
low: The host uses maximum possible resources.
medium: The host and the virtual machine evenly share resources.
unlimited: The virtual machine uses maximum possible resources.
Sharing Parameters
--smart-mount <on | off>
82
Page 83
Parallels Desktop Command Line Interface
Enables or disables shared volumes.
--shared-profile <on | off>
Enables or disables shared profile.
--shared-cloud <on | off>
Enables or disables shared cloud.
--sh-app-guest-to-host <on | off>
Enables or disables sharing guest applications with host.
--show-guest-app-folder-in-dock <on | off>
Enables or disables showing the folder with guest OS applications in the Dock.
--sh-app-host-to-guest <on | off>
Enables or disables sharing host applications with guest.
Coherence Parameters
--winsystray-in-macmenu <on | off>
Shows Windows notification area in the Mac menu bar.
--auto-switch-fullscreen <on | off>
Allows applications to auto-switch to full screen.
--disable-aero <on | off>
Enables or disables Windows Aero.
--hide-min-windows <on | off>
Allows to hide minimized windows.
Security Parameters
--require-pwd <exit-fullscreen | change-vm-state | manage-snapshots | change-guest-
pwd>:<on | off>
Sets whether a password is required to perform a corresponding action.
--lock-on-suspend <on | off>
Always locks the guest OS on suspend.
--isolate-vm <on | off>
Isolates the the virtual machine from the host.
83
Page 84
Parallels Desktop Command Line Interface
--smart-guard <on | off>
Enables or disables smart guard mech.
--sg-notify-before-create <on | off>
Notifies the user before creating a snapshot.
--sg-interval <seconds>
Sets a time interval between taking snapshots.
--sg-max-snapshots <num>
Sets the maximum allowed number of snapshots.
--lock-edit-settings <on | off [--host-admin <name>]>
Locks or unlocks editing of the virtual machine configuration.
--host-admin <name>
Specifies the host administrator name if an administrator password is required to unlock editing
of the virtual machine configuration.
--userpasswd <user : passwd> [--host-admin <name>]
Sets a password for the specified user in the virtual machine. If the user account does not exist,
it is created. The --host-admin <name> parameter specifies the host administrator name if an
administrator password is required to change the user password in the virtual machine.
Parallels Tools must be installed in the virtual machine for the command to succeed.
--password-to-edit
Asks a password to edit the virtual machine configuration.
Expiration Date Parameters
--expiration <<on|off>|date:<yyyy-MM-ddThh:mm:ss>|time-check:<seconds>|offline-
time:<seconds>|time-server:<url>|note:<text>>
Expiration date parameters:
on|off: Enables or disables expiration date checking.
date: Sets a date and time when the virtual machine usage period expires (e.g. 2014-12-
30T20:30:00).
time-check: Sets how often (in seconds) Parallels Desktop contacts the time server to check
the expiration date and time.
offline-time: Sets the time period (in seconds) during which a user can work with the virtual
machine if Parallels Desktop is unable to check the expiration date and time.
84
Page 85
Parallels Desktop Command Line Interface
time-server: Specifies the URL of a trusted time server to check the expiration date and time.
note: Adds a note (e.g. system administrator contact info).
Device Management
The following options can be used to manage devices: --device-add, --device-set, --device-del,
--device-connect, --device-disconnect. Only one option can be specified at a time.
Device Connect / Disconnect / Set / Delete
--device-connect <device_name>
Connects the specified device to a running virtual machine. The device can be of type fdd,
cdrom, sound, or net. To obtain a device name, use the prlctl list -i command.
--device-disconnect <device_name>
Disconnects the specified device from a running virtual machine.
--device-set <device_name> <<--enable | --disable> | <--connect | --disconnect>>
Enables/disables or connects/disconnects the specified device in the virtual machine
configuration.
--device-del <device_name> [--detach-only | --destroy-image | --destroy-image-force]
Removes the specified device from the virtual machine.
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 detach the HDD image as if --detach-only
was specified.
Adding a Device
The general syntax is as follows:
--device-add <hdd | cdrom | net | fdd | serial | parallel | sound | usb> [device_options]
The subsequent sections describe specific device type options.
Adding a Virtual Hard Disk
--device-add hdd [--image <image_name>] [--type <expand | plain>] [--size <n>] [--split]
85
Page 86
Parallels Desktop Command Line Interface
[--iface <ide | scsi | sata>] [--position <n>] [--subtype <buslogic | lsi-spi | lsi-
sas>]
[--online-compact <on | off>]
Parameters
image_name: the name of the file to be used for emulating the VM virtual disk drive. If this option is
omitted, a new file is created inside the directory storing all VM-related configuration files and
assigned the name of harddiskN.hdd.
--type: specifies the type of the virtual disk from one of the following:
• expand (default): virtual disks of this type are small initially and grow in size as you add data to
it.
• plain: virtual disks of this type have a fixed size from the moment of their creation.
--size: hard disk size, in megabytes.
--split: splits the hard disk into 2 Gb pieces.
--iface: virtual hard disk interface type: ide, scsi, or sata.
--position: the SCSI / IDE / SATA device identifier to be used for the disk drive. Allowed ranges:
• 0-3 for IDE disk drives
• 0-6 for SCSI disk drives
• 0-5 for SATA disk drives
--subtype: virtual hard disk subtype: buslogic, lsi-spi, lsi-sas.
--online-compact: enables or disables virtual hard disk online compact mode.
Connecting a Physical Hard Disk
--device-add hdd --device <real_name> [--iface <ide | scsi | sata>] [--passthr <yes | no>]
[--position <n>] [--subtype <buslogic | lsi-spi | lsi-sas>]
Parameters
--device: the name of the host computer hard disk that will be connected to the virtual machine.
To obtain the names of all hard disks installed on the host, use the prlsrvctl info command.
--iface: virtual hard disk interface type: ide, scsi, sata.
--passthr: enables the passthrough mode for the specified device.
86
Page 87
Parallels Desktop Command Line Interface
--position: the SCSI / IDE / SATA device identifier to be used for the disk drive. Allowed ranges:
• 0-3 for IDE disk drives
• 0-6 for SCSI disk drives
• 0-5 for SATA disk drives
--subtype: virtual hard disk subtype: buslogic, lsi-spi, lsi-sas.
Adding a Virtual CD/DVD Drive
--device-add cdrom [--image <name>] [--iface <ide | scsi | sata>] [--position <n>]
[--subtype <buslogic | lsi-spi | lsi-sas>]
Parameters
--image: connect the specified image file to the virtual machine. The following image file formats
are supported: iso, cue, ccd, dmg.
--iface: virtual CD/DVD interface type: ide, scsi, sata.
--position: the SCSI / IDE / SATA device identifier to be used for the DVD/CD drive. Allowed
ranges:
• 0-3 for IDE disk drives
• 0-6 for SCSI disk drives
• 0-5 for SATA disk drives
--subtype: virtual CD/DVD-ROM subtype: buslogic, lsi-spi, lsi-sas.
Connecting a Physical CD/DVD Drive
--device-add cdrom --device <name> [--iface <ide | scsi | sata>] [--passthr <yes | no>]
[--position <n>] [--subtype <buslogic | lsi-spi | lsi-sas>]
Parameters
--device: the name of the host computer CD/DVD drive that will be connected to the virtual
machine. To obtain the names of all CD/DVD drives installed on the host, use the prlsrvctl info
command.
--iface: virtual CD/DVD drive interface type.
--passthr: enables the passthrough mode for the specified device.
87
Page 88
Parallels Desktop Command Line Interface
--position: the SCSI / IDE / SATA device identifier to be used for the CD/DVD drive. Allowed
ranges:
• 0-3 for IDE disk drives
• 0-6 for SCSI disk drives
• 0-5 for SATA disk drives
--subtype: virtual CD/DVD drive subtype.
Adding a Virtual Floppy Disk Drive
--device-add fdd --image <image> [--recreate]
Adds a virtual floppy disk drive based on a file image. The --recreate option recreates the
image file if it exists.
Connecting a Physical Floppy Disk Drive
-device-add fdd [--device <real_name>]
Adds a physical floppy disk drive. The --device option specifies a physical floppy disk drive
name.
Adding a Virtual Network Adapter
--device-add net --type <shared | bridged | host-only> [--iface <name>] [--mac <addr | auto>]
[--ipadd <addr [/mask]> | --ipdel <addr[/mask]> | --dhcp <yes | no> | --dhcp6 <yes |
no>]
[--gw <gw>] [--gw6 <gw>] [--nameserver <addr>] [--searchdomain <addr>]
[--configure <yes | no>] [--apply-iponly <yes | no>]
[--adapter-type <virtio | e1000 | e1000e | rtl>]
Parameters
--type: the type of the network adapter to create in the virtual machine.
--iface: the host network interface to be assigned to the bridged or host-only virtual network
adapter.
--mac: the MAC address to be assigned to the virtual network adapter. If omitted, the MAC
address will be automatically generated.
--ipadd: the IP address to be assigned to the network adapter in the virtual machine.
88
Page 89
Parallels Desktop Command Line Interface
--ipdel: the IP address to be removed from the network adapter in the virtual machine.
--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.
--gw: the default gateway to be used by the virtual machine.
--gw6: the default IPv6 gateway to be used by the virtual machine.
--nameserver: the default DNS server to be used by the virtual machine.
--searchdomain: the default search domain to be used by the virtual machine.
--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.
--apply-iponly: if set to yes, the hostname, nameserver, and search domain settings from the
virtual machine configuration file are ignored.
--adapter-type: specifies the network adapter emulation type.
Adding a Virtual Serial Port
--device-add serial {--device <name>|--output <file>|--socket <name> [--socket-mode
<server|client>]}
Parameters
--device: the number of the host computer serial port that will be used by the virtual machine.
--output: the path to the file where the output of the virtual serial port will be sent.
--socket: the name of the host computer socket to which the serial port will be connected.
--socket-mode: the socket operation mode.
Adding a Virtual Parallel Port
--device-add parallel {--device <name> | --output <file>}
Parameters
--device: the parallels port number on the host computer that will be used by the virtual machine.
89
Page 90
Parallels Desktop Command Line Interface
--output: the path to the file where the output of the virtual parallel port will be sent.
Adding a Virtual Sound Card
--device-add sound --output <name> --input <name>
Enabling USB Support
--device-add usb
Shared Folders
A shared folder is a host OS folder that can be accessed from a virtual machine.
--shf-host <on | off>
Enables or disables sharing the user-defined host OS folders with guest OS.
--shf-host-add <name> --path <path> [--mode <ro | rw>] [--shf-description <desc>] [--enable |
--disable]
Shares the host OS folder name with a virtual machine.
--shf-host-del <name>
Removes the specified folder from the list of shared folders.
--shf-host-set <name> --path <path> [--mode <ro | rw>] [--shf-description <desc>] [--enable |
--disable]
Modifies the settings of the host OS shared folder name.
--shf-host-defined <off | alldisks | home>
off: Disable sharing of folders defined by the host OS.
alldisks: Share all host OS disks with a virtual machine.
home: Share a host OS user's home directory with a virtual machine.
--shf-guest <on | off>
Enables or disables sharing of user-defined guest OS folders with the host OS.
--shf-guest-automount <on | off>
Enables or disables automatic mounting of shared guest OS folders on the desktop.
Advanced
--time-sync <on | off>
90
Page 91
Parallels Desktop Command Line Interface
Enables or disables the virtual machine time synchronization.
--disable-timezone-sync <on | off>
Enables or disables timezone synchronization. Enable this option to sync only UTC time without
timezone synchronization.
--sync-vm-hostname <on | off>
Enables or disables synchronization of the virtual machine name and hostname in guest OS.
Supported only for Linux guests.
--sync-ssh-ids <on | off>
Enables or disables synchronization of macOS SSH public keys with those from the guest OS
"authorized_keys" file.
This feature is similar to the ssh-copy-id(1) utility. When enabled, all macOS SSH public keys
are added to the guest OS "authorized_keys" file. This allows users to log in to the guest OS via
SSH without having to enter the password.
The following SSH keys are synced:
- When a user creates a new SSH key pair in macOS, the public key is also added to the guest
OS.
- When a user removes a public key from macOS, this key is also removed from the guest OS.
The details of current implementation:
- Public key synchronization is currently available for Linux guests only.
- Public key synchronization works if the guest OS user has the same name in macOS or the
user is the only regular user of the guest system.
The public key is synced in the following cases:
- After Parallels Tools are installed.
- After booting or rebooting the guest OS.
- After the virtual machine resumes.
- After the public key synchronization feature is enabled/disabled.
Additional information:
- If the feature is disabled, all macOS SSH public keys are removed from the guest OS.
- The "authorized_keys" file and public keys are searched only in the "~/.ssh" directory.
- SSH authorization certificates are not supported.
--show-dev-tools <on | off>
Enables or disables show developer tools in menu.
--swipe-from-edges <on | off>
91
Page 92
Parallels Desktop Command Line Interface
Enables or disables edge swipe gestures.
--rename-ext-disks
Renames external virtual hard disks bundles using the virtual machine name.
Miscellaneous
--name <name>
Changes the virtual machine name.
--description <desc>
Sets the virtual machine description.
--distribution <name | list>
Sets the virtual machine OS version(s) family.
--asset-id <id>
Changes the virtual machine asset ID.
--template <on | off>
Converts the virtual machine to template and back.
--tools-autoupdate <yes | no>
Enables or disables the auto-update mode for Parallels Tools Agent.
--usedefanswers <on | off>
Enables or disables default mech answers to the questions from the virtual machine.
Snapshot Management
This section describes command used to manage virtual machine snapshots.
Take a Virtual Machine Snapshot
prlctl snapshot <vm_id | vm_name>
Creates a virtual machine snapshot.
Optional parameters
-n, --name <name>
A snapshot name. If omitted, a default name will be used.
92
Page 93
Parallels Desktop Command Line Interface
-d, --description <desc>
A snapshot description.
Delete a Snapshot
prlctl snapshot-delete <vm_id | vm_name> -i, --id <snapid>
Deletes a virtual machine snapshot. The -i, --id <snapid> parameter specifies the ID of the
snapshot to delete.
Optional parameters
-c, --children
If included, all child snapshots of the specified snapshot will be deleted.
List Snapshots
prlctl snapshot-list <vm_id | vm_name> [{-t,--tree] | [-i,--id <snapid>}] [-j, json]
Lists the virtual machine snapshot tree. There are three modes of snapshot listing:
• If the -t, --tree option is specified, the tree is displayed using ASCII graphics.
• If the -i, --id <snapid> option is specified, the specified snapshot information is displayed.
• If no option is specified, the snapshot tree is displayed as a table with two columns:
PARENT_SNAPSHOT_ID, SNAPSHOT_ID.
The optional -j, --json parameter produces an output in JSON format.
Revert to a Snapshot
prlctl snapshot-switch <vm_id | vm_name> -i, --id <snapid> [--skip-resume]
Reverts the specified virtual machine to the specified snapshot. The -i, --id <snapid>
parameter specifies the ID of a snapshot to revert to.
If the optional --skip-resume parameter is included, the virtual machine will not be started if it
was running when the snapshot was taken.
Miscellaneous Commands
This section describes miscellaneous prlctl commands.
Generate a Problem Report
prlctl problem-report <vm_id | vm_name>
93
Page 94
Parallels Desktop Command Line Interface
<-d, --dump | -s, --send [--proxy [user [:password] @proxyhost [:port]]] [--no-proxy]>
Generates a problem report. If the -s, --send option is specified, the report is sent to Parallels.
Otherwise, it is dumped to stdout.
Parameters
-d, --dump
If included, the report is displayed on the screen. You can pipe the output to a file and then
send it to the Parallels technical support.
-s, --send
If this option is included (instead of -d, --dump), the report is sent to Parallels. You can specify
additional optional parameters, which are described below.
--proxy user:password@proxyhost:port
If you use a proxy server to connect to the Internet, include the --proxy parameter and specify
the proxy server information. The problem report will be sent to Parallels through this proxy
server.
--no-proxy
Do not use a proxy server to send the problem report. This is the default behavior, so you can
include or omit this parameter.
Optional Parameters
--name <user_name>
Inserts the specified user name into the report.
--email <user_e-mail>
Inserts the specified e-mail address into the report.
--description <problem_description>
Inserts the specified free-form description into the report.
Use Guest Debugger
prlctl guest-debugger <vm_id | vm_name> [--port <port>]
Allows you to connect the debugger to a running virtual machine via the specified port. The
debugger must be installed on the same computer where the virtual machine is running.
94
Page 95
Parallels Desktop Command Line Interface
Create a VM Dump
prlctl debug-dump <vm_id | vm_name>
[--name <dump_file_name>] [--path <output_directory_path>]
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.
Optional parameters
--name <dump_file_name>
Allows you to specify a dump file name. By default, the file is named memory.elf.dmp. When
you create a new dump file, it replaces the previous file (if it exists). Giving it a custom name to a
file solves this issue.
--path <output_directory_path>]
By default, dump files are saved to the virtual machine directory. If you want to save them to
another directory, specify the directory path using the --path parameter.
Notes
To create a dump, the virtual machine must be running or paused. Suspended virtual machines are
not supported by this command. The command returns 0 (zero) on success and a non-zero value
on failure.
Error Handling
The prlctl utility returns 0 on success or an error code on failure.
95
Page 96
Index
Index
A
Activate a License Offline - 64
Activate a License Online - 64
Add a Virtual Machine - 35
Add the Parallels Desktop Installation Image -
34
Adding a Device - 85
Adding a Virtual CD/DVD Drive - 87
Adding a Virtual Floppy Disk Drive - 88
Adding a Virtual Hard Disk - 85
Adding a Virtual Network Adapter - 88
Adding a Virtual Parallel Port - 89
Adding a Virtual Serial Port - 89
Adding a Virtual Sound Card - 90
Adding Windows Application Stubs - 37
Advanced - 91
Archive / Unarchive a Virtual Machine - 78
B
Boot Order Parameters - 79
C
Capture a Screen Area - 77
Change Windows SID - 77
Clone a Virtual Machine - 74
Coherence Parameters - 83
Configure Deployment Configuration Options
- 39
Configuring Individual Macs - 23
Configuring Parallels Desktop Update Branch
- 25
Connecting a Physical CD/DVD Drive - 87
Connecting a Physical Floppy Disk Drive - 88
Connecting a Physical Hard Disk - 86
Convert a Virtual Machine - 75
CPU and Memory Parameters - 79
Create a Virtual Machine - 72
Create a VM Dump - 95
Creating the Parallels Update XML File - 21
Customizing the Support Center Option - 26
D
Deactivate a License - 64
Delete a Virtual Machine - 73
Delete a Snapshot - 93
Deploying macOS Image Using NetBoot - 61
Deploying Parallels Desktop and Virtual
Machines to Macs - 49
Deploying with Apple Remote Desktop - 57
Deploying with Jamf Pro - 49
Deploying with Parallels Mac Management for
Microsoft SCCM - 55
Device Connect / Disconnect / Set / Delete -
85
Device Management - 85
Display Parallels Desktop Info - 63
Download the Deployment Package - 33
E
Enabling USB Support - 90
Encrypt / Decrypt a Virtual Machine - 78
Encrypting a Virtual Machine from the
Command Line - 15
Enforcing USB Device Policies - 18
Error Handling - 70, 95
Execute a Command In a Virtual Machine -
76
Expiration Date Parameters - 84
G
General Configuration Options - 36
General Virtual Machine Management - 70
Generate a Problem Report - 94
Get Virtual Machine Status - 76
H
Hiding Developer Tools in the Parallels
Desktop GUI - 14
I
Install / Remove a Deferred License - 64
Page 97
Index
Install a Parallels Desktop License - 63
Install Parallels Tools - 75
Installing a Web Server - 20
Installing Parallels Tools - 36
Introduction - 5
K
Kernel Extensions in macOS High Sierra - 29
L
License Management - 63
List Snapshots - 93
List Virtual Machines - 70
Locking a Virtual Machine on Suspend - 11
Log In to a Virtual Machine - 76
M
Manually Approving Kernel Extensions - 30
Mass Deployment of Parallels Desktop and
Virtual Machines - 28
Miscellaneous - 92
Miscellaneous Commands - 94
Mouse and Keyboard Parameters - 80
Move Virtual Machine Files - 75
O
Optimization Parameters - 82
Restricting a Virtual Machine Configuration
with a Custom Password - 9
Restricting User Actions in Parallels Desktop
with a Custom Password - 8
Revert to a Snapshot - 93
S
Security Parameters - 83
Send Problem Report - 69
Set Password Protection - 78
Setting an Asset Tag in the Virtual Machine
BIOS - 12
Setting an Expiration Date for a Virtual
Machine - 17
Setting Up a Local Update Server - 20
Shared Folders - 90
Sharing Parameters - 82
Shut Down Parallels Desktop - 69
Single Application Mode - 16, 46
Snapshot Management - 92
Specify a License Key - 34
Startup and Shutdown Parameters - 80
Supported Deployment Tools - 32
T
Take a Virtual Machine Snapshot - 92
Testing the Deployment Package - 48
P
Parallels Desktop Business Edition Features
Overview - 5
Parallels Desktop Command Line Interface -
62
Parallels Desktop for Mac Business Edition
Features - 8
Parallels Desktop Management - 62
Parallels Desktop Plugin Commands - 69
Parallels Desktop Preferences - 65
Participating in the Customer Experience
Program - 27
Power Operations - 76
Preparing the Deployment Package - 33
Prerequisites - 28
R
Register / Unregister a Virtual Machine - 73
Resetting the Guest OS Password - 19
U
Update a License - 64
USB and Bluetooth Parameters - 80
USB Devices - 68
Use Guest Debugger - 95
User List and Virtual Machine Location - 66
Using Custom Graphics and Links in the
Control Center - 13
Using MDM Configuration - 29
Using spctl Command - 30
V
Video Parameters - 79
Virtual Machine Configuration Tasks - 78
Virtual Machine Management - 70
Virtual Network Info - 66
Virtual Network Settings - 66
Virtual Printer Parameters - 80
Loading...