KB10941: What is the MSTRCtl utility and how is it used in MicroStrategy Intelligence Server

Summary:
This knowledge base article provides details on the Strategy MSTRCTL utility, including some of its functionalities and example usage scenarios.
 
What is MSTRCTL?
MSTRCTL is a Strategy Intelligence Server control utility that can be used to retrieve Intelligence Server related information and manipulate Intelligence Server instances from command line. The Microsoft Windows installation of the Intelligence Server will locate the file MSTRCTL.exe under Program Files/Common Files/Strategy. For Strategy Intelligence Server Universal installations on Unix/Linux the mstrctl script may be found in the "Strategy Home/bin" folder.
 
MSTRCTL functionalities:
For a complete list of possible functionalities of the utility, navigate to the of the utility and execute it with the '-h' option: 

mstrctl -h

 
The output from the command is shown below: 
 

Usage:
mstrctl [-h|-V]
-h, --help                                      print this screen and exit.
-V, --version                                   print version information and exit.

Usage (NETWORK):
mstrctl <request>
<request>:
(list-machines|lm) [server_name]                discover machines that this utility may control.

Usage (MACHINE):
mstrctl [-m <machine_name> [-l <login>]] <request>
-m <machine_name>, --machine=<machine_name>     execute the request on the specified machine.
-l <login>,        --login=<login>              remote machine account (password will be prompted).
<request>:
(list-servers|ls)                               list servers installed on a machine.
(list-odbc-dsns|lod)                            list ODBC DSNs.

Usage (SERVER):
mstrctl [-m <machine_name> [-l <login>]] -s <server_name> <request> [parameters]
-m <machine_name>, --machine=<machine_name>     execute the request on the specified machine.
-l <login>,        --login=<login>              remote machine account (password will be prompted).
-s <server_name>,  --server=<server_name>       server that request refers to.
<request> [parameters]:
(list-instances|li)                             list existing server instances.
(get-default-instance|gdi)                      get default instance name.
(set-default-instance|sdi) <instance_name>      change default instance name.
(get-server-configuration|gsc)                  get server configuration.
(set-server-configuration|ssc)                  change server configuration.
(create-instance|ci) [instance_name]            create a new server instance.
(copy-instance|cpi) [instance_name] <new_instance_name>
                                                duplicate an instance with a new name.
(delete-instance|di) [instance_name]            delete a server instance.
(register-service|rs) [instance_name]           register a server instance as service.
(unregister-service|us) [instance_name]         unregister a server instance as service.
(get-license|gl)                                get server license information.

Usage (SERVER INSTANCE):
mstrctl [-m <machine_name> [-l <login>]] -s <server_name> <request> [instance_name]
-m <machine_name>, --machine=<machine_name>     execute the request on the specified machine.
-l <login>,        --login=<login>              remote machine account (password will be prompted).
-s <server_name>,  --server=<server_name>       server that request refers to.
<request>:
(get-service-configuration|gsvc)                get service configuration.
(set-service-configuration|ssvc)                change service configuration.
(get-server-instance-configuration|gsic)        get server instance configuration.
(set-server-instance-configuration|ssic)        change server instance configuration.
(get-status|gs)                                 get server instance status.
start [--interactive|--service]                 start a server instance.
stop                                            stop a server instance.
pause                                           pause a server instance.
resume                                          resume a server instance.
(terminate|term)                                terminate a server instance (use with caution).

 
As shown above, MSTRCTL command can be used to retrieve server related information for a network, machine, server, or server instance. The command can also be used to manipulate specific server instances.
 
Example for MSTRCTL command usage: 
The following is an example demonstrating how to use the MSTRCTL command to retrieve Strategy Intelligence Server related information. The following steps show how to retrieve the complete configuration information for an Intelligence Server instance:
 
1) Execute the command below to obtain a list of servers running on a machine: 
 

mstrctl -m test-computer ls

 
Here, test-computer is the machine name in which a user is interested. The sample output shows there are three servers running on the machine:
 

EMService
IntelligenceServer
Listener

 
2) To obtain all instances of Strategy Intelligence Server on a machine, execute the following command: 
 

mstrctl -m test-computer -s IntelligenceServer li

 
The sample output shows there is only one instance of Intelligence Server running on the test-computer machine and is called CastorServer shown below (which is the name for the default Intelligence Server instance). The "-m " option can be dropped in which case the utility reports the instances on the local machine.
 

CastorServer

 
3) To retrieve the complete configuration information for the CastorServer instance, execute the following command: 
 

mstrctl -m test-computer -s IntelligenceServer gsic CastorServer

 
Part of a sample output for the command is shown below:
 

<?xml version="1.0"?>
<configuration n="CastorServer">
   <metadata>
     <login>AccessUser</login>
     <odbc dsn="Strategy_Tutorial_Metadata"/>
   </metadata>
   <svrd n="Strategy Tutorial Server"/>
   <tcp_port_number>65534</tcp_port_number> 
   <processor_affinity_mask is_supported="1" >0</processor_affinity_mask>
   <performance_monitor_enabled>1</performance_monitor_enabled>
   <performance_counters log_destination="DSSPerformanceMonitor" pru="1" frequency="1" persist_perf_counter="1">
     <cat n="Strategy Intelligence Server Profiler">
          <performance_counter n="DSSAnalyticalEngineServerTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSAnalyticalEngineServerTask Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSAnalyticalEngineServerTask Total Counts" persist="0"/>
          <performance_counter n="DSSApplyViewContextTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSApplyViewContextTask Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSApplyViewContextTask Total Counts" persist="0"/>
          <performance_counter n="DSSCloseJob CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSCloseJob Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSCloseJob Total Counts" persist="0"/>
          <performance_counter n="DSSDatamartExecuteTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSDatamartExecuteTask Elapse Time(sec)" persist="0"/>
          <performance_counter n="DSSDatamartExecuteTask Total Counts" persist="0"/>
          <performance_counter n="DSSDocumentDataPreparationTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSDocumentDataPreparationTask E lapse Time(sec)" persist="0"/>
          <performance_counter n="DSSDocumentDataPreparationTask Total Counts" persist="0"/>
          <performance_counter n="DSSDocumentExecuteTask CPU Time(sec)" persist="0"/>
          <performance_counter n="DSSDocumentExecuteTask Elapse Time(sec)" persist="0"/>
....

 
From the output of the command, all the information about the CastorServer Instance can be observed. For example, the Intelligence Server instance uses 65534 as the TCP port number (see the line in bold).