Product Documentation

Configure server roles and locations from the command line

Jun 05, 2015
Updated: 2014-10-09

This topic assumes that you have installed the Services Manager Configuration Tool on the platform servers you want to configure and on the server where you want to configure the primary location or a remote location. When you install a platform server role, the Configuration Tool is installed automatically. To install the Configuration Tool only, see To install server roles from the command line.

Command Conventions

Several options use Boolean values (true or false).
  • If you omit an option that requires a Boolean value, the default value is used. For example, if you do not include the /UseCortexSql:True | False option in the command, the default value (false) is used; that is, the reporting database will not use the settings configured for the main system database.
  • If you specify an option that requires a Boolean value but you omit the value, the option value is true. For example, if you specify only /UseCortexSql (with no True or False value), the option is true; that is, the reporting database will use the settings configured for the main system database.

You can use environment variables to represent one or more command-line options or option values (for example, /ReportingDBServer:%currentServer%, where currentServer is defined as an environment variable).

Enclose option values that contain spaces in quotation marks (for example, /LocationName:"Southeast Hub").

Return Codes

The configuration command supports the following return codes:
Value Meaning
1 Another instance is already running.
0 Success.
-1, -2, -3 Command-line error.
-4 General failure during configuration. To debug further, review the log in %WINDIR%Temp.

Syntax

To configure the server roles and create the primary location from the command line, you execute the Services Manager Configuration Tool by typing the following at a command prompt:

CortexConfigConsole.exe /ConfigFile:config-file /Configure:tasks /task-options [/Help]

/ConfigFile:config-file
Location of XML configuration file with read-write access for the current user. If this file already exists, its content will be overwritten during the configuration.
/Configure:tasks
Configures specified installed Services Manager roles and a location. Valid values are:
  • Databases – Creates the main Services Manager system databases.
  • Provisioning – Configures the Provisioning Engine.
  • DirectoryService - Configures the Directory Web Service.
  • Web – Configures the Web Server.
  • Location – Initializes the Services Manager instance. A location is the main unit of isolation between tenants, and usually corresponds to an Active Directory domain or forest.
  • Reporting – Creates the reporting database and configures the Data Warehouse feature.
  • ReportMailer – Configures the email environment for sending usage reports to the Citrix license monitor. Configuring the Report Mailer is required.
/Help
Displays command help.

Databases options

/CortexSql:name
Required. Name of the main system database (the previously-installed Microsoft SQL Server 2008 R2 instance).
/CortexSqlAuthMode:SQL|Windows
SQL Server authentication mode: SQL or Windows. Default = Windows
/CortexSqlUsername:username
Username for the main system database user. This is optional if you specify /CortexSqlAuthMode:Windows and are using integrated security.
/CortexSqlPassword:password
Password for the user name specified with the /CortexSqlUsername option. This is optional if you specify /CortexSqlAuthMode:Windows and you are using integrated security.
/CortexSqlPort:port
SQL Server port. Default = 1433 if this is the default SQL Server instance.
/GenerateCortexSqlCredentials:True | False
If true, passwords for the CortexProp, ExchangeLogs, OLMReports, and OLMUser system database users are automatically generated.
/CortexPropPassword:password
Password for the CortexProp database user. This is optional if you specify /GenerateCortexSqlCredentials:True.
/ExchangeLogsUserPassword:password
Password for the ExchangeLogs database user. This is optional if you specify /GenerateCortexSqlCredentials:True.
/OlmReportsUserPassword:password
Password for the OLMReporting database user. This is optional if you specify /GenerateCortexSqlCredentials:True.
/OlmUserPassword:password
Password for the main system database user. This is optional if you specify /GenerateCortexSqlCredentials:True.
/GenerateConfigFile:filename
Path and file name for XML configuration file.

Provisioning options

/SmtpServer:address
Required. Address of SMTP server from which email messages are sent, including system updates for administrators and account notifications for end users.
/SmtpServerPort:port
Port on SMTP server to be used for sending email messages about system updates for administrators and account notifications for end users. Default = 25
/SmtpOutFolder:folder
Folder that serves as an outbox for the control panel when sending emails. Default = %WINDIR%TempCortexEmail
/GenerateQueueMonitorCredentials (or GenQMonCreds):True | False
If true, user credentials are automatically generated for the Queue Monitor service, which processes administrative requests from the Web Server and automates other services. Default = False
/QueueMonitorUserName:username
User name for a domain account to be used by the Queue Monitor service (default = cortex_qmon_svc). The user must have full domain administrator permissions. This is optional if you specify GenerateQueueMonitorCredentials:True.
/QueueMonitorPassword:password
Password for the user name specified with the /QueueMonitorUserName option. This is optional if you specify /GenerateQueueMonitorCredentials:True.
/AutoCreateQueueMonitorCredentials:True | False (or /AutoCreateQMon:True | False)
If true, the domain user account to be used by the Queue Monitor service is created if it does not already exist. Default = True
/GenerateDirectoryMonitoringCredentials:True | False (or GenDirMonCreds:True | False)
If true, user credentials for the Directory Monitoring service are generated automatically. This service monitors Active Directory, keeping account information current and sending email notifications for key events such as password expiry. Default = False
/DirectoryMonitoringUserName:username
User name for the account to be used by the Directory Monitoring service (default = cortex_dirmon_svc). This is optional if you specify /GenerateDirectoryMonitorCredentials:True.
/DirectoryMonitoringPassword:password
Password for the user name specified with the /DirectoryMonitoringUserName option. This is optional if you specify /GenerateDirectoryMonitorCredentials:True.
/AutoCreateDirectoryMonitoringCredentials:True | False (or /AutoCreateDirMon:True | False)
If True, the user account to be used by the Directory Monitor service is created if it does not already exist. Default = True

Directory Web Service options

/DirectoryServicePort:port
Port used by the Directory Web Service. Default = 8095
/GenerateDirectoryServiceUserCredentials:True | False (or GenDirWSCreds:True | False)
If true, user credentials for the Directory Web Service are generated automatically. Default = False
/DirectoryServiceUserName:username
User name for an account to be used by the Directory Web Service. This is optional if you specify /GenerateDirectoryServiceUserCredentials.
/DirectoryServicePassword:password
Password for the user name specified with the /DirectoryServiceUserName option. This is optional if you specify /GenerateDirectoryServiceCredentials.
/AutoCreateDirectoryServiceUser:True | False (or /AutoCreateDirWS:True | False)
If true, the user account to be used by the Directory Web Service is created if it does not already exist. Default = True

Web options

/ExternalAddress:address
Externally-resolvable address by which the Web Server can be reached. Default = cortexweb
/UseSsl:True | False
If true, an SSL binding is created for the management portal. Default = True (recommended)
/SslCertificate:name
Friendly name of the SSL certificate to use. This is required if you specify /UseSSsl:True.
/BindingIpip-address
IP address to use for the new site binding. Default = "*" (all unassigned)

Location options

When configuring locations, consider the following items:
  • Run all configuration steps as a domain administrator.
  • Ensure user account settings conform to any domain policies, such as minimum password complexity, and are valid.
  • Ensure the required firewall ports are configured for each server in the deployment.
/PrimaryLocation:True | False
Required. If True, the /Locationx configuration option values are for the first Services Manager administrator. This is the top-level administrative account in the control panel; it can add customers, assign services, and manage delegated administration.
/LocationName:name
Required. Name of the location. Default = Top Location
/LocationDescription:description
Description of the location. Default = Top-level Service Provider Location
/LocationOU:location
OU of the location.
/LocationOULabel:label
OU label of the location.
/CspAdminFirstName:first-name
First name of administrator (Default = CSP). This is optional if you are configuring a secondary location (/PrimaryLocation:False).
/CspAdminLastName:last-name
Last name of administrator (Default = Admin). This is optional if you are configuring a secondary location (/PrimaryLocation:False).
/CspAdminUserName:username
User name for the administrator (Default = cspadmin). This is optional if you are configuring a secondary location (/PrimaryLocation:False).
/CspAdminPassword:password
Password for the user name specified with the /CspAdminUserName option. This is optional if you are configuring a secondary location (/PrimaryLocation:False).
/CspContact:name
Contact name of the service provider. This is optional if you are configuring a secondary location (/PrimaryLocation:False).
/CspContactEmail:address
Email address of the service provider. This is optional if you are configuring a secondary location (/PrimaryLocation:False).
/CspName:name
Name of service provider that will appear in displays. This is optional if you are configuring a secondary location (/PrimaryLocation:False).
/CspUPN:suffixes
UPN suffixes (Default = tsp.local). This is optional if you are configuring a secondary location (/PrimaryLocation:False).

Reporting options for deploying the Reporting service

/UseCortexSql:True | False
If true, the reporting database will use the settings configured for the main system database. Default = False
/ReportingDBCollation:True | False
Determines how string data is sorted when comparing, selecting, or manipulating values from the database.
/ReportingDBServer:address
Address of the reporting database server. This is optional if you specify /UseCortexSql:True.
/ReportingDBServerPort:port
Port to use on the database server (Default = 1433). This is optional if you specify /UserCortexSql:True.
/ReportingDBName:name
Name of reporting database. Default = OLMReporting
/ReportingDBServerAuthMode:SQL | Windows
Authentication mode of the reporting database. This is optional if you specify /UseCortexSql:True.
/ReportingDBGenerateCredentials:True | False
If true, reporting database administrator account credentials are generated automatically. Default = False
/ReportingDBServerUserName:username
User name for an administrator account to be used to create the reporting database, plus create and configure the service account specified with the /OlmReporting* options. This is optional if you specify /UseCortexSql:True and /ReportingDBServerAuthMode:Windows.
/ReportingDBServerPassword:password
Password for the user name specified with the /ReportingDBServerUserName option. This is optional if you specify /UseCortexSql:True and /ReportingDBServerAuthMode:Windows.
/OlmReportingUserName:username
Name of service account used by the Data Warehouse process to update the reporting database. This is optional if /ReportingDBGenerateCredentials:True.
/OlmReportingPassword:password
Password for the user name specified with the /OlmReportingUserName option. This is optional if /ReportingDBGenerateCredentials:True.
/OlmReportingUserAuthMode:SQL| Windows
Authentication mode: SQL or Windows (Default = SQL). This is optional if /ReportingDBGenerateCredentials:True.

Reporting options for deploying reports

/ReportingServer:url
Required. URL of the report server.
/ReportsUserName:username
Required. User name of the Reporting Service administrator.
/ReportsPassword:password
Required. Password for the user name specified with the /ReportsUserName option.
/PublishReports:report[,report]…
Comma-separated list of reports to deploy. Valid values are: AD Sync, Billing, Citrix, Communicator, DNS, Exchange, File Sharing, FTP, Mail Archiving, Microsoft CRM, MySQL, SharePoint, SQL Server, Windows Web Hosting.
To publish all reports, use the /PublishAllReports option.
/PublishAllReports:True | False
If true, all available reports are published (Default = False). To publish a subset of the available reports, set this option to False, and use the /PublishReports option to specify the reports.

Reporting (Data Warehouse) options

/SuccessEmailFrom:address
Required. Source email address for success notifications.
/SuccessEmailTo:address
Required. Destination email address for success notifications.
/FailureEmailFrom:address
Required. Source email address for failure notifications.
/FailureEmailTo:address
Required. Destination email address for failure notifications.
/GenerateDataTransferCredentials:True | False
If true, user credentials for the Data Transfer Service are generated automatically. Default = False
/DataTransferUserName:username
User name for the account to use for the Data Transfer Service. This is optional if you specify /GenerateDataTransferCredentials:True.
/DataTransferPassword:password
Password for the user name specified with the /DataTransferUserName option. This is optional if you specify /GenerateDataTransferCredentials.
/SmtpServer:address
Address of SMTP server to be used for sending email messages.
/SmtpServerPort:port
Port on the SMTP server to be used for sending email messages.

Report mailer options

/CustomerId
Required. Customer ID.
/ReportMailerEmailServer:name
Name of SMTP mail server.
/GenerateUserCredentials:True | False
If true, credentials for the SMTP mail server user account are generated automatically. Default = False
/ReportMailerTaskUserName:username
User name for the account the Report Mailer task will use. This is optional if you specify /GenerateUserCredentails:True.
/ReportMailerTaskUserPassword:password
Password for the user name specified with the /ReportMailerTaskUserName option. This is optional if you specify /GenerateUserCredentails:True.
/ReportMailerEmailServerPort:port
Port number on SMTP server. Default = 25
/ReportMailerEmailUserName:username
User name for the user account that accesses the SMTP email server.
/ReportMailerEmailPassword:password
Password for the user name specified with the /ReportMailerEmailUserName option.

Example: Configure the Provisioning and Directory Web Service server roles

The following command configures the Provisioning and Directory Web Service server roles and uses default values for most options:
CortexConfigConsole.exe /ConfigFile:\server-nameconfig-file.xml /Configure:Provisioning,DirectoryWebService /SmtpServer:mail.takahepubs.com /DirectoryServiceUsername:cortex_dirws_svc /DirectoryServicePassword:password

Example: Configure the primary location

The following command configures the primary location and uses default values for most options:
CortexConfigConsole.exe /ConfigFile:\server-nameconfig-file.xml /Configure:Location /PrimaryLocation:True /LocationName:My First Location /LocationOU:Organization-Name /LocationOULabel:My Organization /CspAdminPassword:password /CspContact:CSP-Name /CspContactEmail:cspadmin@my-org.com /CspUPN:my-org.com

Example: Configure a remote location

The following command configures a remote location and uses default values for most options:
CortexConfigConsole.exe /ConfigFile:\server-nameconfig-file.xml /Configure:Location /PrimaryLocation:False /LocationName:My Second Location /LocationOU:Organization-Name /LocationOULabel:My Organization