Parallels Command Line Reference Manual

Parallels Command Line
Reference Guide
Copyright © 1999-2010 Parallels Holdings, Ltd. and its affiliates. All rights reserved.
Parallels Holdings, Ltd. c/o Parallels International GMbH. Parallels International GmbH Vordergasse 49 CH8200 Schaffhausen Switzerland Tel: + 49 (6151) 42996 - 0 Fax: + 49 (6151) 42996 - 255 www.parallels.com
Copyright © 1999-2010 Parallels Holdings, Ltd. and its affiliates. 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/trademarks.
Microsoft, Windows, Windows Server, Windows NT, Windows Vista, and MS-DOS are registered trademarks of Microsoft Corporation. Linux is a registered trademark of Linus Torvalds. Mac is a registered trademark of Apple, Inc. All other marks and names mentioned herein may be trademarks of their respective owners.
3
Contents
Introduction 5
About Parallels Command Line Tools......................................................................................................... 5
Organization of This Guide.......................................................................................................................... 6
Feedback......................................................................................................................................................6
Parallels Service Management 7
Formatting Legend....................................................................................................................................... 7
General Syntax............................................................................................................................................. 8
prlsrvctl Commands..................................................................................................................................... 9
prlsrvctl info...................................................................................................................................... 9
prlsrvctl install-license.................................................................................................................... 10
prlsrvctl net..................................................................................................................................... 10
prlsrvctl problem-report.................................................................................................................. 14
prlsrvctl set...................................................................................................................................... 15
prlsrvctl shutdown........................................................................................................................... 16
prlsrvctl statistics ............................................................................................................................ 17
prlsrvctl user list.............................................................................................................................. 18
Virtual Machine Management 19
Formatting Legend..................................................................................................................................... 19
General Syntax........................................................................................................................................... 20
prlctl........................................................................................................................................................... 20
prlctl set .......................................................................................................................................... 20
prlctl backup ................................................................................................................................... 38
prlctl backup-delete......................................................................................................................... 39
prlctl backup-list............................................................................................................................. 40
prlctl capture................................................................................................................................... 41
prlctl change-passwd....................................................................................................................... 41
prlctl clone ...................................................................................................................................... 42
prlctl create ..................................................................................................................................... 43
prlctl delete ..................................................................................................................................... 45
prlctl encrypt, decrypt..................................................................................................................... 46
prlctl enter....................................................................................................................................... 47
prlctl exec........................................................................................................................................ 47
prlctl installtools ............................................................................................................................. 48
prlctl list.......................................................................................................................................... 49
prlctl migrate................................................................................................................................... 50
prlctl pause, suspend, resume..........................................................................................................51
prlctl problem-report....................................................................................................................... 52
prlctl register, unregister................................................................................................................. 53
prlctl restore.................................................................................................................................... 54
prlctl server..................................................................................................................................... 55
prlctl snapshot................................................................................................................................. 55
prlctl snapshot-delete...................................................................................................................... 56
prlctl snapshot-list........................................................................................................................... 56
prlctl snapshot-switch..................................................................................................................... 57
prlctl start, stop, reset...................................................................................................................... 58
Contents 4
Index 59
5
C HAPTER 1

Introduction

In This Chapter
About Parallels Command Line Tools.................................................................................. 5
Organization of This Guide................................................................................................... 6
Feedback ...............................................................................................................................6

About Parallels Command Line Tools

Parallels Server, Parallels Workstation, and Parallels Desktop come with two command-line utilities: prlsrvctl and prlctl.
prlsrvctl
The prlsrvctl utility is used to administer Parallels Service (the core component of any Parallels hypervisor-based virtualization product). The tasks that can be performed include getting general information about the Parallels Service and its configuration settings, modifying Parallels Service preferences, getting a list of users, obtaining statistics, installing a license, and others.
To launch the utility from the command line, type:
prlsrvctl
prlctl
The prlctl utility is used to perform administration tasks on virtual machines. The utility supports a full range of tasks from creating and administering virtual machines to installing Parallels Tools, getting statistics, and generating problem reports.
To launch the utility from the command line, type:
prlctl
The rest of this guide provides detailed technical information about commands and options available with each utility.
Introduction 6

Organization of This Guide

This guide is organized into the following chapters:
Introduction (you are reading it now). Parallels Service Management. Provides technical information about the prlsrvctl utility, its
commands and options. Virtual Machine Management. Provides technical information about the prlctl utility, its
commands and options.

Feedback

If you spot a typo in this guide, or if you have an opinion about how to make this guide more helpful, you can share your comments and suggestions with us by completing the Documentation Feedback form on our website (http://www.parallels.com/en/support/usersdoc/).
7
C HAPTER 2

Parallels Service Management

Parallels Virtualization Service is a core component of any Parallels hypervisor-based virtualization product. Parallels Service is managed using the prlsrvctl command-line utility, which is supplied with all Parallels virtualization products and is installed on the host machine during the product installation.
In This Chapter
Formatting Legend................................................................................................................ 7
General Syntax...................................................................................................................... 8
prlsrvctl Commands.............................................................................................................. 9

Formatting Legend

Format Meaning
Bold
Italic
Between square brackets. Example: [--name name]
Between curly brackets and/or separated by pipe (|).
Examples:
ID|name
{-o name|-d name}
Parameter followed by the same parameter in brackets with ellipses.
Parameters that the user must type exactly as shown.
Parameter values that the user must supply.
Optional parameters.
Set of choices from which the user must choose only one.
Parameters that can be repeated more than once in the same command line.
Example: name[,name...]
Parallels Service Management 8

General Syntax

The prlsrvctl command-line utility is used to perform management tasks on Parallels Service. The tasks include getting the Parallels Service information, modifying Parallels Service preferences, installing a license, obtaining statistics and problem reports, and some others.
Syntax
prlsrvctl command [options] [-l,--login user[:passwd]@server] [-v, --verbose number]
Parameters
Name Description
command
The name of the command to execute.
options
-l, --login
user Name of the user on the remote server. passwd The user password. If the password is omitted, you will be
server The remote server IP address or hostname.
-v, --verbose
number
Command options. See individual commands for available options. Connect to the remote Parallels Service and execute a command on
it. If this parameter is omitted, the command will be executed on the local machine.
prompted to enter it.
Show verbose output. The greater the number, the more verbose output will be produced.
Remarks
To display help, enter prlsrvctl on the command line without any parameters.
Links
Legend (p. 7)
Parallels Service Management 9

prlsrvctl Commands

prlsrvctl info

Displays the host computer and the Parallels Service configuration information.
Syntax
prlsrvctl info
Remarks
The information returned by the info command includes the following:
Host machine name. Parallels virtualization product version number. Host operating system type and version. The default virtual machine directory name and path. Parallels Service memory limits. Parallels Service minimum allowable security level. The default backup directory name and path for virtual machines. Parallels license information. Host machine hardware configuration information. Other miscellaneous info.
Links
General Syntax (p. 8), Legend (p. 7)
Parallels Service Management 10

prlsrvctl install-license

Installs Parallels Server, Parallels Desktop, or Parallels Workstation license on the host computer.
Syntax
prlsrvctl install-license -k,--key key [-n,--name name] [-c,--company name]
Parameters
Name Description
-k, --key key
License key.
-n, --name name
-c,--company name
License user name.
License company name.
Links
General Syntax (p. 8), Legend (p. 7)

prlsrvctl net

The prlsrvctl net command allows you to create and configure Parallels virtual networks. The following subsections describe how to perform individual virtual network configuration tasks.
Parallels Service Management 11
Creating a New Virtual Network
The prlsrvctl net add command can be used to create a new virtual network.
Syntax
prlsrvctl net add vnetwork_id -i --ifname if -m --mac mac_address] [ , ] [ , [-t,--type bridged|host-only|shared] [-d,--description description]
Parameters
Name Description
vnetwork_id
A user-defined name that will identify the new virtual network.
-i,--ifname if
-m,--mac mac_address
-t,--type value
-d,--description
description
Links
General Syntax, Legend (p. 7)
The name of a physical network adapter on the host computer to which this virtual network should be bound.
The MAC address of a virtual network adapter on the host computer to which this virtual network should be bound.
The type of the virtual network to create. Possible values are:
bridged -- a virtual machine connected to this
type of virtual network appears as an independent computer on the network.
host_only -- a virtual machine connected to this
type of virtual network can access only the host computer and the virtual machines connected to the same virtual network.
shared -- a virtual machine connected to this type
of virtual network uses the host computer network connections.
A user-defined description of the virtual net wo rk .
Parallels Service Management 12
Modifying a Virtual Network
The prlsrvctl net set command allows you to modify an existing virtual network.
Syntax
prlsrvctl net set vnetwork_id -i --ifname if -m --mac mac_address] [ , ] [ , [-t,--type bridged|host-only|shared] [-d,--description description] [-n, --name new_name]
Parameters
Name Description
vnetwork_id
The name of the virtual network to modify.
-i,--ifname if
-m,--mac mac_address
-t,--type
-d,--description
description
-n, --name new_name
Links
The name of a physical network adapter on the host computer to which this virtual network should be bound.
The MAC address of a virtual network adapter on the host computer to which this virtual network should be bound.
The type of the virtual network to create. Possible values are:
bridged -- a virtual machine connected to this
type of virtual network appears as an independent computer on the network.
host_only -- a virtual machine connected to this
type of virtual network can access only the host computer and the virtual machines connected to the same virtual network.
shared -- a virtual machine connected to this type
of virtual network uses the host computer network connections.
A user-defined description of the virtual net wo rk .
A new name for the virtual network. Use this parameter if you would like to rename the virtual network.
General Syntax, Legend (p. 7)
Parallels Service Management 13
Deleting a Virtual Network
The prlsrvctl net del command allows to delete an existing virtual network.
Syntax
prlsrvctl net del vnetwork_id
Parameters
Name Description
vnetwork_id
The name of the virtual network to delete.
Links
General Syntax, Legend (p. 7)
Listing Existing Virtual Networks
The prlsrvctl net list command lists the existing virtual networks.
Syntax prlsrvctl net list
Links
General Syntax, Legend (p. 7)
Parallels Service Management 14

prlsrvctl problem-report

Obtains the Parallels Service problem report and displays it on the screen.
Syntax
prlsrvctl problem-report
Parameters
The command accepts no parameters.
Remarks
The command collects technical data about the Parallels Service and displays the report on the screen (the output can also be piped to a file). The report can then be directed to Parallels technical support for analysis.
Links
General Syntax (p. 8), Legend (p. 7)
Parallels Service Management 15

prlsrvctl set

Allows to modify Parallels Service preferences.
Syntax
prlsrvctl set [--mem-limit auto|size] [-s,--min-security-level low|normal|high] [-c --cep on off, | ] [--mng-settings allow|deny] [{--device device --assignment host|vm}] [--backup-storage user[[:passwd]@server[:port]]] [--backup-path path] [--default-encryption-plugin plugin-id ] | [--reset-default-encryption-plugin]
Parameters
Name Description
--mem-limit
Sets the upper limit of the memory size that can be reserved for Parallels Service operation. The following options are available:
-s,--min-security-level
-c,--cep
--mng-settings
auto -- if this option is used, the memory size will
be calculated automatically.
size -- user-defined memory size, in megabytes.
The lowest allowable security level that can be used to connect to the Parallels Service. The following options are available:
low -- plain TCP/IP (no encryption). normal -- most important data is sent and received
using SSL over TCP/IP (user credentials during login, guest OS clipboard, etc.) Other data is sent and received using plain TCP/IP with no encryption.
high -- all of the data is sent and received using
SSL.
Enables/disables the participation in the Customer Experience Program. The following options are available:
on -- enables CEP. off -- disables CEP.
Allows to grant or deny permission to new users to modify Parallels Service preferences. By default, only administrators of the host OS can modify Parallels Service preferences. When a new Parallels Service user profile is created (this happens when a user logs in to Parallels Service for the first time), he/she will be granted or denied this privilege based on the default setting. This parameter allows to set that default setting. Please note that this parameter only affects new users (the users that will be created in the future). The profiles of the existing users will not be modified.
Parallels Service Management 16
--device device -­assignment
Allows to set the assignment mode for the specified VTd device. The following options are available:
host -- assign the device to host. vm -- assign the device to virtual machines.
--backup-storage
user Name of the user on the backup server.
passwd The user password.
server The backup server IP address or hostname.
port Port number. If omitted, the default port number will be used.
--backup-path path
--default-encryption­plugin plugin-id
--reset-default­encryption-plugin
The default backup server where virtual machine backups will be stored.
Name and path of the default directory on the backup server where virtual machines backups will be stored.
Allows to specify which encryption plug-in should be used by default. An encryption plug-in implements an encryption algorithm, which is used to encrypt a virtual machine. Use this option to specify the ID of the plug-in, which should be used by default.
Resets the default encryption plug-in assignment and sets the built-in plug-in to be used by default.
Links
General Syntax (p. 8), Legend (p. 7)

prlsrvctl shutdown

Shuts down the Parallels Service.
Syntax
prlsrvctl shutdown [-f,--force]
Parameters
Name Description
-f, --force
Links
General Syntax (p. 8), Legend (p. 7)
Specifies whether the shutdown operation should be for c ed. If one or more virtual machines are running, clients are connected, or some tasks are currently in progress, then forcing the shutdown will stop all processes automatically and will shut down the Parallels Service.
Parallels Service Management 17

prlsrvctl statistics

Obtains Parallels Service statistics.
Syntax
prlsrvctl statistics [-a, --all] [--loop] [--filter name]
Parameters
Name Description
-a, --all
This parameter is not currently used.
--loop
--filter name
Subscribes to receive statistics on the periodic basis. Once you execute the command with this option, the statistics will be displayed in your console window every time a new set of values is collected. To unsubscribe, press the Enter key or Ctrl-C in your console window.
This parameter is not currently used.
Links
General Syntax (p. 8), Legend (p. 7)
Parallels Service Management 18

prlsrvctl user list

Displays the list of Parallels Service users.
Syntax
prlsrvctl user list [-o,--output name[,name...]]
Parameters
Name Description
-o,--output name
Names of the fields to include in the output. The following fields are available:
name -- User name. mng_settings -- Indicates whether the user is allowed
to modify Parallels Service preferences.
def_vm_home -- The user default virtual machine
folder.
The fields must be specified using the lower case letters.
See Also
prlsrvctl user set
Links
General Syntax (p. 8), Legend (p. 7)
Loading...
+ 42 hidden pages