Difference between revisions of "Management API - Command Line Client"
| [unchecked revision] | [checked revision] |
Ltalaschus (talk | contribs) |
Ltalaschus (talk | contribs) |
||
| (18 intermediate revisions by the same user not shown) | |||
| Line 4: | Line 4: | ||
The syntax of the ''MailStoreManagementCmd.exe'' looks as follows: | The syntax of the ''MailStoreManagementCmd.exe'' looks as follows: | ||
| − | MailStoreManagementCmd.exe -s <server> -u <user> -p <password> -t <thumbprint> -c <command> [-param1 <value> -param2 <value> ...] | + | MailStoreManagementCmd.exe -s <server> -u <user> -p <password> -t <thumbprint> -c <command> [--param1=<value> --param2=<value> ...] |
The below command line parameters are required followed by additional API command parameters if necessary. | The below command line parameters are required followed by additional API command parameters if necessary. | ||
| Line 16: | Line 16: | ||
|- | |- | ||
| <tt>-t</tt> | | <tt>-t</tt> | ||
| − | | Thumbprint of the SSL certificate used by the Management Server | + | | Thumbprint of the SSL certificate used by the Management Server. |
|- | |- | ||
| <tt>-u</tt> | | <tt>-u</tt> | ||
| Line 22: | Line 22: | ||
|- | |- | ||
| <tt>-p</tt> | | <tt>-p</tt> | ||
| − | | Password of the MailStore Service Provider Edition Administrator | + | | Password of the MailStore Service Provider Edition Administrator. In case MFA has been enabled, the API password of the user has to be given here. More about MFA can be found on the [[Management_Console_-_Your_MFA_Settings|Your MFA Settings]] documentation page. |
|- | |- | ||
| <tt>-c</tt> | | <tt>-c</tt> | ||
| Line 29: | Line 29: | ||
The output of the executed API command is returned to the standard output (STDOUT) comparable to the HTTP bodies as described in [[Management_API_-_Using_the_API|Using the API]]. Therefore a JSON parser is recommended for further processing of the output. | The output of the executed API command is returned to the standard output (STDOUT) comparable to the HTTP bodies as described in [[Management_API_-_Using_the_API|Using the API]]. Therefore a JSON parser is recommended for further processing of the output. | ||
| + | |||
| + | {{Template:API Service Provider Access}} | ||
''MailStoreManagementCmd.exe'' itself exits with error code 0 if no errors occurred, otherwise the exit code 1 is returned. | ''MailStoreManagementCmd.exe'' itself exits with error code 0 if no errors occurred, otherwise the exit code 1 is returned. | ||
| Line 34: | Line 36: | ||
== Examples == | == Examples == | ||
| − | === Backup Scripts === | + | === Backup Pre-Scripts === |
| + | |||
| + | To stop instances run | ||
| + | |||
| + | <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | ||
| + | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c StopInstances --instanceFilter="instanceFilter" | ||
| + | </source> | ||
| + | |||
| + | or to freeze instances run | ||
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | ||
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c FreezeInstances --instanceFilter="instanceFilter" | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c FreezeInstances --instanceFilter="instanceFilter" | ||
| + | </source> | ||
| + | |||
| + | === Backup Post-Scripts === | ||
| + | |||
| + | To start instances run | ||
| + | |||
| + | <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | ||
| + | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c StartInstances --instanceFilter="instanceFilter" | ||
| + | </source> | ||
| + | |||
| + | or to thaw them run | ||
| + | |||
| + | <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | ||
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c ThawInstances --instanceFilter="instanceFilter" | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c ThawInstances --instanceFilter="instanceFilter" | ||
</source> | </source> | ||
| + | |||
==== String Definition ==== | ==== String Definition ==== | ||
| Line 47: | Line 71: | ||
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | ||
| − | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c GetEnvironmentInfo | + | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c GetEnvironmentInfo |
| − | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c GetProfiles -instanceID test01 -raw true | + | MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c GetProfiles --instanceID="test01" --raw="true" |
</source> | </source> | ||
=== Powershell === | === Powershell === | ||
| − | You are able to parse the result in the Powershell by converting the | + | You are able to parse the result in the Powershell by converting the returned JSON values into Powershell objects. The ''ConvertFrom-Json'' cmdlet was introduced in Windows PowerShell 3.0. |
<source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | <source lang="powershell" smart-tabs="true" toolbar="false" gutter="false"> | ||
| − | (ConvertFrom-Json ([String](.\MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c CreateLicenseRequest))).result.instanceData | where { $_.usedLicenseCount } | + | (ConvertFrom-Json ([String](.\MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c CreateLicenseRequest))).result.instanceData | where { $_.usedLicenseCount } |
</source> | </source> | ||
Latest revision as of 13:41, 5 July 2023
Besides the option to develop your own client for the Management API in any arbitrary programming or scripting language, MailStore Service Provider Edition provides a simple to use command line client in the form of the MailStoreManagementCmd.exe executable to be used in simple batch scripts or by backup software to remote control instances.
The syntax of the MailStoreManagementCmd.exe looks as follows:
MailStoreManagementCmd.exe -s <server> -u <user> -p <password> -t <thumbprint> -c <command> [--param1=<value> --param2=<value> ...]
The below command line parameters are required followed by additional API command parameters if necessary.
| Parameter | Description |
|---|---|
| -s | IP address or host name of the Management Server to connect to. |
| -t | Thumbprint of the SSL certificate used by the Management Server. |
| -u | Username of a MailStore Service Provider Edition Administrator |
| -p | Password of the MailStore Service Provider Edition Administrator. In case MFA has been enabled, the API password of the user has to be given here. More about MFA can be found on the Your MFA Settings documentation page. |
| -c | API command to be executed. |
The output of the executed API command is returned to the standard output (STDOUT) comparable to the HTTP bodies as described in Using the API. Therefore a JSON parser is recommended for further processing of the output.
In order to run API commands that work on an instance, service provider access must be enabled for that instance. This includes all API commands that require an instanceID argument, except those that affect archive stores and search indexes. These can be run using the API without service provider access.
MailStoreManagementCmd.exe itself exits with error code 0 if no errors occurred, otherwise the exit code 1 is returned.
Examples
Backup Pre-Scripts
To stop instances run
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c StopInstances --instanceFilter="instanceFilter"
or to freeze instances run
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c FreezeInstances --instanceFilter="instanceFilter"
Backup Post-Scripts
To start instances run
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c StartInstances --instanceFilter="instanceFilter"
or to thaw them run
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c ThawInstances --instanceFilter="instanceFilter"
String Definition
instanceFilter
| Value | Affects |
|---|---|
| instance01 instance02 instance03 | instance01, instance02 and instance03 |
| * | All instances |
| *instancehost01 *instancehost02 | All instances on instancehost1 and instancehost2 |
| * .running | All running instances |
| * .safeMode | All instances running in Safe Mode |
| * .safeMode .running | All instances running in regular or Safe Mode |
| * .stopped | All stopped instances |
Other Examples
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c GetEnvironmentInfo
MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c GetProfiles --instanceID="test01" --raw="true"
Powershell
You are able to parse the result in the Powershell by converting the returned JSON values into Powershell objects. The ConvertFrom-Json cmdlet was introduced in Windows PowerShell 3.0.
(ConvertFrom-Json ([String](.\MailStoreManagementCmd.exe -s localhost -u admin -p password -t 46AD1743B61B1F7B4AD3FBB8DC24498953BA3DA7 -c CreateLicenseRequest))).result.instanceData | where { $_.usedLicenseCount }
