Difference between revisions of "MailStore Server Management Shell"

[unchecked revision][checked revision]
(47 intermediate revisions by 4 users not shown)
Line 3: Line 3:
 
The management shell is useful when no graphical user interface is available (e.g. if using telnet or ssh) or for the integration of scripts (e.g. batch files) that are executed either manually or automatically.
 
The management shell is useful when no graphical user interface is available (e.g. if using telnet or ssh) or for the integration of scripts (e.g. batch files) that are executed either manually or automatically.
  
−
= Option 1: Starting the Management Shell in MailStore Client =
+
Beside the client-side commands, the Management Shell also offers access to server-side commands of the [[Administration API - Using the API|MailStore Server Administration API]]. Output of server-side commands is in JSON format.
−
 
 
−
The management shell can be started directly from MailStore: Log on to MailStore Client as administrator and click on ''Administrative Tools'' > ''Miscellaneous'' and then on ''Management Shell''.
 
  
 +
== Starting the Management Shell in MailStore Client ==
 +
The management shell can be started directly from MailStore: Log on to MailStore Client as administrator and click on ''Administrative Tools > Management API > Command Prompt''.
 
[[File:tech_mscmd_01.png|center|450px]]
 
[[File:tech_mscmd_01.png|center|450px]]
 +
The font size can be adjusted by holding the Ctrl key and using the mouse wheel or pressing + and -. Holding down the Ctrl key and pressing 0 resets the font size.
  
−
= Option 2: Starting the Management Shell with MailStoreCmd.exe =
+
== Using MailStoreCmd.exe in Non-Interactive Mode ==
 +
In non-interactive mode, the management shell logs on with the access data passed, executes the command passed, and automatically terminates upon execution. If the login and the execution of the command were successful, the exit code (ERRORLEVEL) of the process is set to 0 (zero), otherwise it is set to any value other than 0. ''MailStoreCmd.exe'' can be found in the installation directory of MailStore Server. ''MailStoreCmdSilent.exe'' does the same, but does not open a console window.
  
−
The command line client can be started in interactive mode by executing <code>MailStoreCmd.exe</code> without any parameters. After successful login, MailStore is ready to receive commands. Enter ''exit'' to log off and close the management shell.
+
Login credentials for your installation can be found in the scheduled task of an archiving profile of the type ''E-Mail Programs'' or ''E-Mail Files''.
  
−
[[File:tech_mscmd_02.png|center|450px]]
+
There are multiple ways to pass credentials to ''MailStoreCmd.exe''.
  
−
= Using MailStoreCmd.exe in Non-Interactive Mode =
+
To read credentials from the Windows Credentials Manager, they have to be stored there first. The MailStore Client does this automatically when creating a scheduled task in the Windows Task Planer. This methods prevents reading passwords easily by unauthorized persons.
  
−
In non-interactive mode, the management shell logs on with the access data passed, executes the command passed, and automatically terminates upon execution. If the login and the execution of the command were successful, the exit code (ERRORLEVEL) of the process is set to 0 (zero), otherwise it is set to any value other than 0.
+
MailStoreCmd.exe --h=<server> --cred=<user>@<server/ip address> --pkv3=<thumbprint> -c <command> [--param1=<value> --param2=<value> ...]
  
−
To use the non-interactive mode, pass the parameters as follows:
+
The credentials can also be passed as plain text.
  
−
  MailStoreCmd.exe --h="localhost" --pkv3="23:18:06:3f:24:7d:f3:83" --u="admin" --p="admin"
+
MailStoreCmd.exe --h=<server> --u=<user> --p=<password> --pkv3=<thumbprint> -c <command> [--param1=<value> --param2=<value> ...]
−
  -c <Actual Command and Parameter>
 
  
−
The following is a description of the parameters:
+
The below command line parameters are required followed by additional API command parameters if necessary.
  
−
  --h="localhost"
+
{| class="wikitable"
−
The machine name of the MailStore server to which <code>MailStoreCmd.exe</code> is to connect.
+
! width=100px | Parameter
 +
! width=100% | Description
 +
|-
 +
| <code>--h</code>
 +
|The machine name of the MailStore server to which <code>MailStoreCmd.exe</code> is to connect.
 +
|-
 +
| <code>--pkv3</code>
 +
| The (optional) Public Key Fingerprint, which guarantees the identity of MailStore Server.
 +
|-
 +
| <code>--u</code>
 +
| User name
 +
|-
 +
| <code>--p</code>
 +
| Password
 +
|-
 +
| <code>--cred</code>
 +
| Alternative to <code>--u</code> and <code>--p</code>, the password is read from the Windows Credential Manager. The parameter must be entered in the from <user>@<server/ip address>.
 +
|-
 +
| <code>--nologo</code>
 +
| Optional. Prevents the logo from being displayed.
 +
|-
 +
| <code>--o</code>
 +
| Optional. Redirects the output to a given file. When this parameter is given, no output is sent to the console.
 +
|-
 +
| <code>-c</code>
 +
| The actual command follows (non-interactive mode).
 +
|}
  
−
  --pkv3="..."
+
== Command Overview ==
−
The (optional) Public Key Fingerprint, which guarantees the identity of MailStore Server.
 
  
−
  --u="admin"
+
=== Client side commands ===
−
User name.
+
Find a list of all client side commands below.
  
−
   --p="admin"
+
   clear
−
Password.
 
  
−
  -c
+
Clears the texts currently displayed improving visibility.
−
The actual command follows (non-interactive mode).
 
  
−
= Command Overview =
+
  debug-conn
  
−
  backup --target=<targetdirectory> [--nosync] [--skipreadonly] [--filegroups=1,2,...,4]
+
Activates debug protocol for IMAP and HTTP connections during archiving for the running MailStore Client process.
  
−
Create a backup of the archive.
+
  debuglog-browse
  
−
{| width=80% |
+
Opens the file explorer and shows MailStore's ''Debug Log'' directory.
−
|-
 
−
| <code>--target</code>
 
−
| directory where to create the backup
 
−
|-
 
−
| <code>--nosync</code>
 
−
| copy all files; not only new or modified ones
 
−
|-
 
−
| <code>--skipreadonly</code>
 
−
| skip file groups marked as read only
 
−
|-
 
−
| <code>--filegroups=1,2,...,4</code>
 
−
| make backup of given file groups only
 
−
|}
 
  
−
   clear
+
   debuglog-enable,  debuglog-disable
  
−
Clears the texts currently displayed improving visibility.
+
Activates or deactivates the global debug protocol (within computer scope).
  
−
   debug-console,  debuglog-browse,  debuglog-disable,  debuglog-enable
+
   export-execute [--name=<profilename>] [--id=<profileid>] [--verbose] [--[property]="value"]
  
−
Activates, displays or deactivates the global debug protocol (within computer scope).
+
Executes an export profile. Following parameters are supported:
  
−
  export-execute [--name=<profilename>] [--id=<profileid>] [--verbose]
+
{| width=80% |
−
 
+
|-
−
Executes the export profile with the name or the ID specified (only one of these parameters is required). The parameter --verbose activates a detailed status display on the console.
+
| width="20%" | <code>--name</code> <nowiki>|</nowiki> <code>--id</code>
 +
| name or ID of the export profile to execute
 +
|-
 +
| <code>--verbose</code>
 +
| activates a detailed status display on the console
 +
|-
 +
| <code>--[property]</code>
 +
| Overwrites the given property of a profile. The internal properties can be displayed, by selecting an export profile and press <code>CTRL + SHIFT + P</code>. The name of the property has to be in brackets. Multiple properties can be modified by repeating the parameter.
 +
|}
  
 
   export-list
 
   export-list
Line 82: Line 101:
 
Displays a list of all available commands and their parameters.
 
Displays a list of all available commands and their parameters.
  
−
   filegroup-attach --directory=<directory>
+
   import-execute [--name=<profilename>] [--id=<profileid>] [--verbose] [--user=<username>] [--[property]="value"]
  
−
With this command a file group, which has been removed from MailStore using filegroup-detach, can be reattached to MailStore.
+
Executes the archiving profile. Following parameters are supported:
  
−
  filegroup-create --directory=<directory>
+
{| width=80% |
−
 
+
|-
−
Create a new file group at the location given as <directory>
+
| width="20%" |<code>--name</code> <nowiki>|</nowiki> <code>--id</code>
−
 
+
| name or ID of the import profile to execute
−
  filegroup-detach --gid=<filegroupid>
+
|-
−
 
+
| <code>--verbose</code>
−
In Administrative Tools under Storage Locations, the status of a file group can be set to inactivate. The file group (along with the emails it contains) is no longer available until it is reactivated but remains in the list of existing file groups. By using the command filegroup-detach, a file group is completely removed from MailStore but physically remains on the hard drive.
+
| activates a detailed status display on the console
−
 
+
|-
−
  filegroup-upgrade --gid=<filegroupid>
+
| <code>--user</code>
−
 
+
| user archive to store archived emails
−
Upgrade file group with ID <filegroupid> to latest database version.
+
|-
−
 
+
| <code>--[property]</code>
−
  filegroup-verify --gid=<filegroupid>
+
| Overwrites the given property of a profile. The internal properties can be displayed, by selecting an archiving profile and press <code>CTRL + SHIFT + P</code>. The name of the property has to be in brackets. Multiple properties can be modified by repeating the parameter.
−
 
+
|}
−
Start a verification of the file group with ID <filegroupid>.
 
−
 
 
−
  index-rebuild [--folder=<userfolder>] --gid=<filegroupid>
 
−
 
 
−
Rebuild full text index for file group with ID <filegroupid>. Rebuild can be limited to one folder only by supplying the --folder parameter.
 
−
 
 
−
  import-execute [--name=<profilename>] [--id=<profileid>] [--verbose] [--user=<username>]
 
−
 
 
−
Executes the archiving profile with the name or the ID specified (only one of these parameters is required). The parameter --verbose activates a detailed status display on the console.
 
  
 
   import-list [--user=<username>]
 
   import-list [--user=<username>]
Line 114: Line 124:
 
Displays a list of all existing archiving profiles (ID and profile name).
 
Displays a list of all existing archiving profiles (ID and profile name).
  
−
   maintain-db [--gid=<filegroupid>] --command=[backup-restore|sweep]
+
   livelog-client-disable,  livelog-client-enable,  livelog-server-disable,  livelog-server-enable
  
−
Information about this commands can be found in the chapter [[Maintenance_and_Repair|Maintenance and Repair]].
+
Activates or deactivates the live debug protocol of MailStore Server or MailStore Client. The live protocol can be viewed with Sysinternal's DebugView. DebugView must be started with elevated privileges and it must be configured to capture ''Global Win 32'' events.
  
−
   process-info
+
   store-setprop --name=<name> [--value=true/false]
  
−
Provides information about the MailStore-Windows process.
+
Changes the value of a global property
  
−
  rpc-info
+
{| width=100% |
 +
|-
 +
| scope="col" width="20%" | <code>--name</code>
 +
| Name of the global property
 +
|-
 +
| <code>--value</code>
 +
| Value of the global property
 +
|}
  
−
Provides information about the connection with the MailStore Server process.
+
Following global properties are supported:
  
−
  session-logout
+
{| width="100%" border="0" cellpadding="0" cellspacing="0"
−
 
+
|-
−
 
+
! scope="col" width="20%" bgcolor="#cccccc" | Name
−
  statistics-refresh
+
! scope="col" bgcolor="#cccccc" | Version
−
 
+
! scope="col" bgcolor="#cccccc" | Values
−
Recalculates all statistics.
+
! scope="col" bgcolor="#cccccc" | Default
−
 
+
|-
−
  store-getprop --name=<propertyname>
+
| scope="col" width="20%" align="left" valign="top" | public.arcclient.skipMimeContentConversionFailed
−
 
+
| align="center" valign="top" | 8
−
  store-setprop --name=<propertyname> [--value=<value>]
+
| ''true'' = Exchange ''MimeContentConversionFailed'' errors are ignored and not handled as an archiving error.<br/><br/>  
−
 
+
''false'' = Exchange ''MimeContentConversionFailed'' errors are handled as archiving errors.
−
 
+
| align="center" valign="top" | false
−
  user-add --name=<username> --pwd=<password>
+
|-
−
 
+
| scope="col" width="20%" align="left" valign="top" | public.arcclient.skipVirusDetected
−
Add a new user MailStore integrated user and set password
+
| align="center" valign="top" | 8.1
−
 
+
| ''true'' = Exchange ''ErrorVirusDetected'' errors are ignored and not handled as an archiving error.<br/><br/>  
−
  user-info [--name=<username>]
+
''false'' = Exchange ''ErrorVirusDetected'' errors are handled as archiving errors.
−
 
+
| align="center" valign="top" | false
−
Get information about currently logged in user or <username> if supplied.
+
|-
 +
| scope="col" width="20%" align="left" valign="top" | public.arcclient.skipEwsErrorItemNotFound
 +
| align="center" valign="top" | 10
 +
| ''true'' = Exchange ''ErrorItemNotFound'' errors are ignored and not handled as an archiving error.<br/><br/>  
 +
''false'' = Exchange ''ErrorItemNotFound'' errors are handled as archiving errors.
 +
| align="center" valign="top" | false
 +
|-
 +
| scope="col" width="20%" align="left" valign="top" | public.backup.hideNotDetectedWarningMessage
 +
| align="center" valign="top" | 11
 +
| ''true'' = Backup warning messages are not shown on dashboard.<br/><br/>  
 +
''false'' = Backup warning messages are shown on dashboard.
 +
| align="center" valign="top" | false
 +
|}
  
 
   user-list
 
   user-list
Line 150: Line 179:
 
Display list of users.
 
Display list of users.
  
−
  user-set-folder-access [--name=<username>] --folder=<folder> [--access=rwd]
+
=== Server side commands ===
  
−
Set folder access permissions <username> to <folder>. Value of --access parameter can be one ore more of these: read (r), write(w) and delete (d).
+
An overview of all available server side commands can be found under [[Administration API - Function Reference|Function Reference]].
  
−
  user-set-password [--name=<username>] --pwd=<password>
+
The parameters of server side commands are case sensitive and must be entered with two dashes (--). Boolean values must be entered as ''true'' or ''false''. Strings that contain white space characters must be set in quotes.
  
−
Set password of <username> to <password>.
+
'''Examples:'''
  
−
  user-set-rights [--name=<username>] [--rights=alcimend]
+
GetProfiles --raw=true
 +
Lists all archiving and export profiles.
  
−
Set rights of <username>. Value of --rights parameter can be set to one of these:
+
  GetUserInfo --userName="alexis.page"
−
: <code>a</code> - administrator (unlimited access rights)
+
Lists the properties of the user ''alexis.page''.
−
: <code>l</code> - login
 
−
: <code>c</code> - change password
 
−
: <code>i</code> - execute import profiles (archive emails)
 
−
: <code>m</code> - modify existing import profiles
 
−
: <code>e</code> - execute export profiles
 
−
: <code>n</code> - modify export profiles
 
−
: <code>d</code> - delete emails
 
−
   
 
−
maintain-db [--gid=<filegroupid>] --command=[backup-restore|sweep]
 
  
−
  maintain-ix --gid=<filegroupid> --command=[list|optimize|reload|verify|] [--ixid=<indexid>]
+
  GetJobResults --fromIncluding="2018-01-01T00:00:00" --toExcluding="2019-01-01T00:00:00" --timeZoneId="$Local" --jobId=1
 +
Lists the results of the job with id 1 of the year 2018.
  
−
  folder-reindex [--folder=<userfolder>] --gid=<filegroupid>
+
  GetWorkerResults --fromIncluding="2018-01-01T00:00:00" --toExcluding="2019-01-01T00:00:00" --timeZoneID="$Local" --profileID=1
 +
Lists the results of the archiving profile with  id 1 of the year 2018.
 +
The command ''GetWorkerResults'' is the only command where the parameter ''timeZoneID'' is written with a capital ''D''.
  
−
  filegroup-verify --gid=<filegroupid>
+
  RunProfile --id=1
 +
Starts the archiving or export profile with id 1.
  
−
Information about these commands can be found in the chapter [[Maintenance_and_Repair|Maintenance and Repair]].
 
 
[[de:MailStore_Server_Management_Shell]]
 
[[de:MailStore_Server_Management_Shell]]
 +
[[en:MailStore_Server_Management_Shell]]

Revision as of 15:16, 4 December 2019

Many instructions available in the graphical user interface of MailStore Client can also be executed using MailStore's management shell, a command line client which is automatically included when installing MailStore Server and MailStore Client.

The management shell is useful when no graphical user interface is available (e.g. if using telnet or ssh) or for the integration of scripts (e.g. batch files) that are executed either manually or automatically.

Beside the client-side commands, the Management Shell also offers access to server-side commands of the MailStore Server Administration API. Output of server-side commands is in JSON format.

Starting the Management Shell in MailStore Client

The management shell can be started directly from MailStore: Log on to MailStore Client as administrator and click on Administrative Tools > Management API > Command Prompt.

Tech mscmd 01.png

The font size can be adjusted by holding the Ctrl key and using the mouse wheel or pressing + and -. Holding down the Ctrl key and pressing 0 resets the font size.

Using MailStoreCmd.exe in Non-Interactive Mode

In non-interactive mode, the management shell logs on with the access data passed, executes the command passed, and automatically terminates upon execution. If the login and the execution of the command were successful, the exit code (ERRORLEVEL) of the process is set to 0 (zero), otherwise it is set to any value other than 0. MailStoreCmd.exe can be found in the installation directory of MailStore Server. MailStoreCmdSilent.exe does the same, but does not open a console window.

Login credentials for your installation can be found in the scheduled task of an archiving profile of the type E-Mail Programs or E-Mail Files.

There are multiple ways to pass credentials to MailStoreCmd.exe.

To read credentials from the Windows Credentials Manager, they have to be stored there first. The MailStore Client does this automatically when creating a scheduled task in the Windows Task Planer. This methods prevents reading passwords easily by unauthorized persons. 

MailStoreCmd.exe --h=<server> --cred=<user>@<server/ip address> --pkv3=<thumbprint> -c <command> [--param1=<value> --param2=<value> ...]

The credentials can also be passed as plain text. 

MailStoreCmd.exe --h=<server> --u=<user> --p=<password> --pkv3=<thumbprint> -c  <command> [--param1=<value> --param2=<value> ...]

The below command line parameters are required followed by additional API command parameters if necessary.

Parameter Description
--h The machine name of the MailStore server to which MailStoreCmd.exe is to connect.
--pkv3 The (optional) Public Key Fingerprint, which guarantees the identity of MailStore Server.
--u User name
--p Password
--cred Alternative to --u and --p, the password is read from the Windows Credential Manager. The parameter must be entered in the from <user>@<server/ip address>.
--nologo Optional. Prevents the logo from being displayed.
--o Optional. Redirects the output to a given file. When this parameter is given, no output is sent to the console.
-c The actual command follows (non-interactive mode).

Command Overview

Client side commands

Find a list of all client side commands below. 

 clear

Clears the texts currently displayed improving visibility. 

 debug-conn

Activates debug protocol for IMAP and HTTP connections during archiving for the running MailStore Client process. 

 debuglog-browse

Opens the file explorer and shows MailStore's Debug Log directory. 

 debuglog-enable,  debuglog-disable

Activates or deactivates the global debug protocol (within computer scope). 

 export-execute [--name=<profilename>] [--id=<profileid>] [--verbose] [--[property]="value"]

Executes an export profile. Following parameters are supported:

--name | --id name or ID of the export profile to execute
--verbose activates a detailed status display on the console
--[property] Overwrites the given property of a profile. The internal properties can be displayed, by selecting an export profile and press CTRL + SHIFT + P. The name of the property has to be in brackets. Multiple properties can be modified by repeating the parameter. 
 export-list

Displays a list of all existing export profiles (ID and profile name). 

 help

Displays a list of all available commands and their parameters. 

 import-execute [--name=<profilename>] [--id=<profileid>] [--verbose] [--user=<username>] [--[property]="value"]

Executes the archiving profile. Following parameters are supported:

--name | --id name or ID of the import profile to execute
--verbose activates a detailed status display on the console
--user user archive to store archived emails
--[property] Overwrites the given property of a profile. The internal properties can be displayed, by selecting an archiving profile and press CTRL + SHIFT + P. The name of the property has to be in brackets. Multiple properties can be modified by repeating the parameter. 
 import-list [--user=<username>]

Displays a list of all existing archiving profiles (ID and profile name). 

 livelog-client-disable,  livelog-client-enable,  livelog-server-disable,  livelog-server-enable

Activates or deactivates the live debug protocol of MailStore Server or MailStore Client. The live protocol can be viewed with Sysinternal's DebugView. DebugView must be started with elevated privileges and it must be configured to capture Global Win 32 events. 

 store-setprop --name=<name> [--value=true/false]

Changes the value of a global property

--name Name of the global property
--value Value of the global property

Following global properties are supported:

Name Version Values Default
public.arcclient.skipMimeContentConversionFailed 8 true = Exchange MimeContentConversionFailed errors are ignored and not handled as an archiving error.

false = Exchange MimeContentConversionFailed errors are handled as archiving errors.

false
public.arcclient.skipVirusDetected 8.1 true = Exchange ErrorVirusDetected errors are ignored and not handled as an archiving error.

false = Exchange ErrorVirusDetected errors are handled as archiving errors.

false
public.arcclient.skipEwsErrorItemNotFound 10 true = Exchange ErrorItemNotFound errors are ignored and not handled as an archiving error.

false = Exchange ErrorItemNotFound errors are handled as archiving errors.

false
public.backup.hideNotDetectedWarningMessage 11 true = Backup warning messages are not shown on dashboard.

false = Backup warning messages are shown on dashboard.

false 
 user-list

Display list of users.

Server side commands

An overview of all available server side commands can be found under Function Reference.

The parameters of server side commands are case sensitive and must be entered with two dashes (--). Boolean values must be entered as true or false. Strings that contain white space characters must be set in quotes.

Examples: 

GetProfiles --raw=true

Lists all archiving and export profiles. 

GetUserInfo --userName="alexis.page"

Lists the properties of the user alexis.page. 

GetJobResults --fromIncluding="2018-01-01T00:00:00" --toExcluding="2019-01-01T00:00:00" --timeZoneId="$Local" --jobId=1

Lists the results of the job with id 1 of the year 2018. 

GetWorkerResults --fromIncluding="2018-01-01T00:00:00" --toExcluding="2019-01-01T00:00:00" --timeZoneID="$Local" --profileID=1

Lists the results of the archiving profile with id 1 of the year 2018. The command GetWorkerResults is the only command where the parameter timeZoneID is written with a capital D. 

RunProfile --id=1

Starts the archiving or export profile with id 1.

Retrieved from "https://help.mailstore.com/en/server/index.php?title=MailStore_Server_Management_Shell&oldid=6440"