Connected® Backup for PC 8.2

Installation Command-Line Options and Parameters

Version(s): Connected Backup/PC 8.0 - 8.2
Component(s): Agent
Last updated: May 16, 2008
Document number: 1422

This document lists the options and parameters you can use with the Installation Command-Line interface. Refer to Agent Command-Line Interface for information about how to install Agents using the Command-Line interface.

Command-Line Options

You can use the standard msiexec command-line options when running a Hands-Free Install. The following table contains the most common options for an Agent installation:

Switch:	Description:
/i	Installs the product.
/qn	Hides the installation interface screens. This option is required for installation. You can also use this option with the /x option.
/x	Uninstalls a product.
/L* logfile	Logs all installation activity in the specified file.
HELP	Displays online help for the installation command-line interface.

Installation Command-Line Parameters

In addition to the standard msiexec command-line options, you can use the following product-specific parameters (parameters are case sensitive):

LDAPID

Syntax: LDAPID= enterprise_directory_username

This parameter specifies the user name stored in the enterprise directory. This parameter is required if the community where the Agent will register is mapped to an enterprise directory. If you specify the PASSWORD parameter, the Agent Setup ignores this value.

You can use system variables when specifying this parameter. For example, you can specify LDAPID=%username%. You cannot use registry variables.

For reserved account installations, use this parameter to specify the account reservation code (which must be equal to the user's enterprise directory user ID). The RESERVATIONCODE parameter is not used when installing an Agent for an account in a community mapped to an enterprise directory.

RESERVATIONCODE

Syntax: RESERVATIONCODE= account_reservation_code

Required parameters: Use the EMAILADDRESS and PASSWORD parameters with this parameter.

This parameter specifies an account reservation code associated with the community where the Agent will register when you use the RESERVATIONCODE parameter. The RESERVATIONCODE parameter is not used when installing an Agent for an account in a community mapped to an enterprise directory. Instead, the LDAPID parameter is used.

TECHID

Syntax: TECHID= technician_ID

Required parameters: Use the ACCOUNTNUMBER and PASSWORD parameters for account recovery.

This parameter specifies a technician identifier (ID) . This parameter is required when performing an account recovery. Verify that the ID is valid for the community where you expect the account to register. The ID must have the Access Users’ Data permission enabled. Technician ID.

IMPORTANT: EMAILADDRESS and PASSWORD are no longer required for installation. If the EMAILADDRESS and PASSWORD arguments are not defined, the install process generates a temporary password, and leaves the email address undefined. However, when EMAILADDRESS and PASSWORD are not defined, end users cannot log in to the Account Management Website or use MyRoam.

EMAILADDRESS

Syntax: EMAILADDRESS= user_email_address

Required parameters: If you use this parameter, use the PASSWORD parameter with this parameter as well.

This parameter specifies an email address for the account. The email address must include a domain, for example, user@myemail.com. Users use this value to log on to the Account Management Website. This parameter is required if the Agent will register in a community that is not mapped to an enterprise directory. If the community where the account registers is mapped to an enterprise directory, the Agent Setup uses the values stored in the enterprise directory and ignores any values that you specify on the command line.

If the email address is not supplied, the only way to identify an account will be through the computer name. Therefore, the following additional changes make it easier to identify account owners.

You can populate the computer name in the database earlier, preferably after registration. Currently, the computer name is populated after the first backup. This change is necessary for troubleshooting accounts that do not back up after install.

You can also add the Computer Name field to the Account Summary page. Previously, the Computer Name appears on the account’s Software Profile page, which makes it hard to find. The Computer Name now also appears on the Account Summary page.

PASSWORD

Syntax: PASSWORD= {user_password | technician_password}

If you choose not to use the PASSWORD parameter, the Agent uses a cryptographically-secure algorithm to generate the password. The Agent transmits the password using encrypted SSL to the Data Center, where it is stored non-reversibly in an encrypted form. If a user has not set a password and needs to perform one of the following actions, technicians can either set the password and email address in Support Center, or perform the password-dependent actions themselves:

Account recovery (also called “reinstall”) – This also requires an email address to log on to the Account Management Website to download and reinstall the MSI.
Password-protected retrieve and Heal.
To log on to the Account Management Website and MyRoam, which also requires an email address.

Required parameters: Use the EMAILADDRESS parameter or the ACCOUNTNUMBER and TECHID parameters with this parameter.

NOTE: If you upgrade a 7.x account that does not have a password, these 7.x accounts do not need a password after upgrade.

This parameter specifies one of the following:

An account’s password — For a Hands-Free Install, the account password must be at least six characters long, and cannot exceed 100 characters. Users enter this password to open the Agent user interface for the first time, log on to the Account Management Website, and to perform Retrieves or a Heal if those are password-protected. If the community where the account registers is mapped to an enterprise directory, the Agent Setup uses the values stored in the enterprise directory and ignores any values that you specify on the command line.
A technician’s password — For a Hands-Free Account Recovery, the technician password is at least eight characters long and must contain at least one non-alphabetical character. This password allows a technician to perform an account recovery.

FIRSTBACKUP

Syntax: FIRSTBACKUP=value

This parameter specifies whether to run a backup after installation and registration complete. Valid values are:

1 — Runs a backup after installation and registration complete.
0 — Does not run a backup after installation and registration complete. The default value is 0.

TARGETDIR

Syntax: TARGETDIR=target_dir

This parameter specifies the path in the Program Files folder where you want to install the Agent software. Use this parameter for new installations only. This parameter must include a complete path, including the drive letter. Use this parameter for new installations only. The Agent Setup ignores this parameter if you also specify the ACCOUNTNUMBER parameter.

ACCOUNTNUMBER

Syntax: ACCOUNTNUMBER=nnnnn-nnnnn

Required parameters: Use the TECHID and PASSWORD parameters with this parameter.

This parameter specifies an account number for account recovery. You can find the account number by searching for accounts in Support Center or by viewing the account information in the Account Management Website. You must enter the account number using the format, nnnnn-nnnn. It is important to include the hyphen.

IMPORTANT: Only use the command-line arguments COMMUNITYID and CONFIGURATIONID with new installs. If used for to move an account, the back-end tables do not upgrade properly. Instead, move accounts in Support Center. Similarly, pushing out an MSI for a different community to upgrade a deployed Agent will also not upgrade back-end tables correctly.

Iron Mountain provides a new command called GetSettings.exe. This command obtains the Configuration ID and Community ID. The syntax for this command is:

GetSettings.exe –c[onfig][-b[rief]][-x[ml]]

The –config parameter is required to allow us to enhance the command in the future for returning other information.

Example 1: No options GetSettings.exe –c

Output:

Community = 3

Configuration = 9

Example 2: -b or –brief option
GetSettings.exe –c –b

Output: 3, 9

Example 3: -x or –xml option

GetSettings.exe –c –x

Output:<RegistrationInfo>
<Community>3</Community>
<Configuration>9</Configuration>
</RegistrationInfo>

REGISTRATIONFILE

Syntax: REGISTRATIONFILE= <drive>:<directory>\<filename>.xml

This parameter provides the 8.x command-line installer a way for administrators to set registration fields during the hands-free install process.

REGISTRATIONFILE uses an XML file. To set one or more registration fields in the installation process, the customer must generate an XML file and specify the file name and path using REGISTRATIONFILE.

The installation will fail if the XML file that is supplied along with the parameter does not exist, is not valid (either because it can not be loaded or is corrupt), or the path is incorrect. There will a message in the installation log. The final outcome will be “installation failed.”

Using this parameter with the command-line installer instructs the Agent to read the file and transmit any registration fields it contains to the Data Center immediately after installation.

Note: The XML file is optional. When used, it must contain all registration fields. An empty field is valid, but it will set the existing registration field value in Support Center to blank. Iron Mountain recommends that you enter values for all relevant fields in the XML file.

The XML file can only pass registration field values, not the states such as hidden, read-only, or required. States must be set in Website Settings.

The Agent only reads the XML immediately after it is installed as part of a new install or account recovery. If the XML file content changes after installation, the Agent will not send updated registration fields to the Data Center. All data transmitted to the Data Center is encrypted. The following lists the required fields and the maximum character length for each field:

Field Name: Maximum Character Length
FIRST NAME: 32
MIDDLE NAME: 16
LAST NAME: 64
COUNTRY: 32
ADDRESS1: 40
ADDRESS2 40
ADDRESS3 40
CITY 40
STATE 40
POSTAL CODE 11
EMAIL 100
COMPANY 64
DEPARTMENT 64
LOCATION 32
MAIL STOP 16
COST CENTER 16
EMPLOYEE ID 16
PHONE 32
EXTENSION 16
CUSTOM 16

Note: All of these field names must be in UPPERCASE. If the RegistrationInfo.xml file exceeds its set character limit, it generates an error in DCMaint, but the error does not appear anywhere else. So, the command line user is not notified if an .xml file is passed that contains data that exceeds the field limits.

The registration fields set through the XML file include email address. This ensures that this installer works with tools for pushing deployments, such as GPO, that do not allow command-line arguments. If the email address is set in both the command line and in the XML file, the one in the XML file takes precedence. Shown below is a sample command line for using this XML file, assuming EMAILADDRESS and PASSWORD are optional:

msiexec /qn /i AgentSetup.msi REGISTRATIONFILE=”C:\testdir\filename.xml” FIRSTBACKUP=1

Note: When using the REGISTRATIONFILE and EMAILADDRESS on the same command line, the email address in the XML file always overrides the EMAILADDRESS set by the command line

Sample XML File Content:

Enclose each registration field value in a CDATA section to ensure that the parser interprets these values as character data, not XML markup. If you leave out the CDATA section, the xml file incorrectly parses any special characters, such as “<” and “&”, in the registration field values.

Note: For further information about XML, refer to http://www.xml.org/

Updating the Registration Data Profile with an XML File

A new command, UpdateProfile.exe, causes the Agent to update the registration fields as specified by an XML file passed on the command line. The XML file uses the same format as Sample XML file content, above.

All registration fields are required. Setting a field to nothing, for example:

“<EmployeeID></EmployeeID>” clears the field.

A sample command line would appear as follows:
UpdateProfile.exe –file ”C:\filename.xml”

In a PC refresh scenario, the customer can use the UpdateProfile.exe command after recovering the account:

msiexec /qn /i <filename.msi> ACCOUNTNUMBER=account_number TECHID=technician_id PASSWORD=technician_password

UpdateProfile.exe REGISTRATIONFILE=”C:\testdir\filename.xml ”

Note: This command overwrites any changes made to these fields on Support Center.

COMMUNITYID

Syntax: COMMUNITYID=&community_number

This parameter specifies the community identifier. Use this parameter to override the default community ID that the Agent Setup file. If you use this parameter, verify that the configuration you are installing is active in the community that you specify.

Iron Mountain provides a new command called GetSettings.exe. This command obtains the Configuration ID and Community ID. The syntax for this command is:

GetSettings.exe –c[onfig][-b[rief]][-x[ml]]

The –config parameter is required to allow us to enhance the command in the future for returning other information.

You can also find the communityID by doing the following:

Log on to Support Center and turn on the status bar for the Web browser.
Place your mouse cursor on the community name in the tree and look at the text string displayed in the status bar.

The numeric value following the &community= string is the community ID.

CAUTION: Use this option carefully. The Agent Setup does not verify the specified value. Unexpected behavior can occur if you specify the wrong community for an Agent configuration.

CONFIGURATIONID

Syntax: CONFIGURATIONID=&value_number

This parameter specifies the configuration identifier for the Agent configuration that you want to install. Use this parameter to override the ID that the Agent Setup contains. The ID that you specify must be the ID for an Agent configuration that is currently in the community where the Agent registers.

Iron Mountain provides a new command called GetSettings.exe. This command obtains the Configuration ID and Community ID. The syntax for this command is:

GetSettings.exe –c[onfig][-b[rief]][-x[ml]]

The –config parameter is required to allow us to enhance the command in the future for returning other information.

You can also find the configuration ID by doing the following:

Log on to Support Center and turn on the status bar for the Web browser.
Place your mouse cursor on the Agent configuration name in the tree and look at the text string displayed in the status bar.

The numeric value following the &value= string is the configuration ID. Use the number displayed after the underscore only. For example if you see this string: &value=16_45, use 45 for the CONFIGURATIONID value.

CAUTION: Use this option carefully. The Agent Setup does not verify the specified value. Unexpected behavior can occur if you specify an Agent configuration that is not active in the specified community.

Command-line examples

The following examples show how you can use the different command parameters for different types of installation results. All of the examples use the /i /qn options for Hands-Free Install.

Installation example for enterprise directory users

The following example shows the command line syntax when installing Agents that registered in a community that is mapped to an enterprise directory:

msiexec /qn /i AgentSetup.msi LDAPID=jbloggs FIRSTBACKUP=1

This installation command line does the following:

Uses the LDAPID parameter to specify an enterprise directory user name.
Uses the FIRSTBACKUP parameter to specify that a first backup should start after installation completes.

Installation example for general users

The following example shows the command line syntax when installing Agents that registered in a community that is not mapped to an enterprise directory.

msiexec /qn /i AgentSetup.msi EMAILADDRESS=joe.bloggs@mycompany.com
PASSWORD=password1 FIRSTBACKUP=1

This installation command line does the following

Uses the EMAILADDRESS parameter to specify the email address associated with the account. The user must enter this value with a password to access the Account Management Website.
Uses the PASSWORD parameter to specify the password associated with the account.The user must enter this value with the email address to access the Account Management Website. The user also enters this value to open the Agent user interface for the first time, and to perform Retrieves or a Heal if either of those is password-protected.
Uses the FIRSTBACKUP parameter to specify that a first backup should start after installation completes.

Installation example for reserved accounts

The following example shows the command line syntax when installing Agents for reserved accounts:

msiexec /qn /i AgentSetup.msi RESERVATIONCODE=ticket1
EMAILADDRESS=joe.bloggs@mycompany.com PASSWORD=password1 FIRSTBACKUP=1

This installation command line does the following:

Uses the RESERVATIONCODE parameter to specify the account reservation code.
Uses the EMAILADDRESS parameter to specify the email address associated with the account. The user must enter this value with a password to access the Account Management Website.
Uses the PASSWORD parameter to specify the password associated with the account.The user must enter this value with the email address to access the Account Management Website. The user also enters this value to open the Agent user interface for the first time, and to perform Retrieves or a Heal if either of those is password-protected.
Uses the FIRSTBACKUP parameter to specify that a first backup should start after installation completes.

Installation example for a specified directory

The following example shows the command line syntax when installing Agents in a folder other than the default installation folder.

msiexec /qn /i AgentSetup.msi EMAILADDRESS=joe.bloggs@mycompany.com
PASSWORD=password1 TARGETDIR= C:\Program Files\Backup\MyAgent

This installation command line does the following:

Uses the EMAILADDRESS parameter to specify email address associated with the account. The user must enter this value with a password to access the Account Management Website.
Uses the PASSWORD parameter to specify the password associated with the account. The user must enter this value with the email address to access the Account Management Website. The user also enters this value to open the Agent user interface for the first time, and to perform Retrieves or a Heal if either of those is password-protected.
Uses the TARGETDIR parameter to specify the that the Agent Setup should install the software in the \Backup\MyAgent folder in the Program Files folder.

Example of account recovery

The following example shows the command line syntax for recovering an account:

msiexec /qn /i <filename.msi> ACCOUNTNUMBER=account_number TECHID=technician_id PASSWORD=technician_password

The value for the ACCOUNTNUMBER parameter is the number of the account that you want to recover. You must use the following syntax, including the hyphen: nnnnn-nnnnn.
The values for the TECHID and PASSWORD parameters must be a technician ID and password that has access to the community where the account was registered.