Difference between revisions of "Moving Roles"

[unchecked revision]

[checked revision]

Latest revision as of 07:03, 23 September 2024

Single Server Mode

In order to retain a single server mode setup by keeping the Management Server, Instance Host and Client Access Server on a single server, follow the instructions below. If only one of the roles in a single server mode setup should to be moved to another server, refer to corresponding section under Multi Server Mode in this article.

The following only applies if MFA has been enabled for some or all system administrators:
- Log in at the Management Console and disable MFA for all administrators that have it enabled.
  The MFA secret, that is used to generate MFA codes, is stored DPAPI-protected in the management database. When the management database is transferred to a different machine, the secret cannot be decrypted on that machine and manual editing of the database would be required, which should be avoided.
Start the MailStore Service Provider Edition Configuration tool on the server that has the Management Server role by double-clicking its desktop icon. On Windows Server Core use the command line prompt to start the executable (default: %PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe.
Stop the Client Access Server, Instance Host, and Management Server services.
Transfer your MailStore SPE license to the new server through our license portal.
Install MailStore Service Provider Edition on the new server and set it up Single Server Mode.
Stop the Client Access Server, Instance Host, and Management Server services on the new server.
Remove all MailStore SPE related certificates from the server's personal (MY) certificate store of the new server.
Export the SSL certificates and private keys from the old server's certificate store and import them into the same location on the new server.
- On Windows Server 2016 and newer you can use the following PowerShell command to export all certificats stored in the computers MY store as PFX containers to the current user's desktop. That PowerShell session requires elevated privileges:
```
(Get-ChildItem Cert:\LocalMachine\My).Thumbprint | ForEach-Object { Export-PfxCertificate -Cert ("Cert:\LocalMachine\My\{0}" -f $_) -FilePath ("$env:USERPROFILE\Desktop\{0}.pfx" -f $_) -Password  (ConvertTo-SecureString -AsPlainText -Force "not_secure_234") }
```
- Windows Server 2016 and newer Powershell command to import the previously exported certificates from the current user's desktop into the new server's certificate store. That PowerShell sessions requires elevated privileges:
```
Get-ChildItem -Path $env:USERPROFILE\Desktop\ -Filter *.pfx | Import-PfxCertificate -Exportable -Password  (ConvertTo-SecureString -AsPlainText -Force "not_secure_234") -CertStoreLocation Cert:\LocalMachine\My
```
Remove the %program files%\MailStore Infrastructure\config directory on the new server and replace it with the config directory from the old one.
Transfer your instance data directories to the new server. If the instance data on the new server is stored in a different location than on the old one, the Base Directory of the instances must be adjusted accordingly. Refer to Instance Management for further details.
When the host name of the server has changed, also follow the instructions in Renaming the Server
Start the Management Server service followed by the Instance Host and Client Access Server service.
Log on to the Management Console and check the dashboard for the connection status of servers and roles.
Re-enable Multi-Factor Authentication for system administrators that had it enabled.
Re-enter the SMTP password if it had been set.

Multi Server Mode

Moving the Management Server

The following only applies if MFA has been enabled for some or all system administrators:
- Log in at the Management Console and disable MFA for all administrators that have it enabled.
  The MFA secret, that is used to generate MFA codes, is stored DPAPI-protected in the management database. When the management database is transferred to a different machine, the secret cannot be decrypted on that machine and manual editing of the database would be required, which should be avoided.
Start the MailStore Service Provider Edition Configuration tool on the server that has the Management Server role by double-clicking its desktop icon. On Windows Server Core use the command line prompt to start the executable (default: %PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe.
Stop the Management Server service.
Transfer your MailStore SPE license through our license portal.
Install the MailStore Service Provider Edition on the new server and set it up in Multi Server Mode
Add the Management Server role on the new server, but do not start it yet.
Transfer the file MailStoreManagementDatabase.json from the old server's configuration directory to the same location on the new server. By default, this file resides in %programfiles\MailStore Infrastructure\config%.
Start the Management Server service on the new server.
Adjust the Management Server setting in the configuration of each Instance Host and Client Access Server by clicking on the corresponding Configure... button in the MailStore Service Provider Edition Configuration tool.
Log on to the Management Console and check the dashboard for the connection status of servers and roles.
Re-enable Multi-Factor Authentication for system administrators that had it enabled.
Re-enter the SMTP password if it had been set.

Moving an Instance Host

Start the MailStore Service Provider Edition Configuration tool on a server that is a Instance Host by double-clicking it's desktop icon. On Windows Server Core use the command line prompt to start the executable (default: %PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe.
Stop the Instance Host service.
Install MailStore Service Provider Edition on the new server and set it up in Multi Server Mode.
Add the Instance Host role.
Pair with the Management Server.
Start the Instance Host service.
Log on to the Management Console and check the dashboard for the connection status of servers and roles.
Follow the Moving Instances guide to move the instances to the new instance host.
Remove the Instance Host role from the old server.
Finally remove the instance host that still exist with the old host name.

Moving a Client Access Server

Export the certificates, including their private keys, that are visible to the end users on the old client access server. By default these are MailStoreClientAccessServerHttp and MailStoreClientAccessServerImap, but not MailStoreClientAccessServerTcp.
Import these certificates into the new server's personal (MY) certificate store.
Start the MailStore Service Provider Edition Configuration tool on a server that is a Client Access Server by double-clicking it's desktop icon. On Windows Server Core use the command line prompt to start the executable (default: %PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe.
Stop the Client Access Server service.
Install MailStore Service Provider Edition on the new server and set it up in Multi Server Mode.
Add the Client Access Server role.
Pair with the Management Server.
Adjust the certificate settings in the Configure Client Access Server Role dialog to use the imported certificates.
Start the Client Access Server service.
Log on to the Management Console and check the dashboard for the connection status of servers and roles.
Remove the Client Access Server role from the old server.
Finally remove the client access server that still exist with the old host name.

@@ Line 1: / Line 1: @@
-= Renaming the server where the SPE runs on in Single Server Mode =
+== Single Server Mode ==
+In order to retain a single server mode setup by keeping the Management Server, Instance Host and Client Access Server on a single server, follow the instructions below. If only one of the roles in a single server mode setup should to be moved to another server, refer to corresponding section under [[Moving Roles#Multi_Server_Mode|Multi Server Mode]] in this article.
-When the server has been renamed, the management dashboard will show you the warning
+* The following only applies if MFA has been enabled for some or all system administrators:
-<p class=msnote>The Name of this Server differs from the licensed Machine Name. Therefore your license has been disabled.</p>
+*:* Log in at the Management Console and [[Management_Console_-_System_Administrators|disable MFA]] for all administrators that have it enabled.<br />The MFA secret, that is used to generate MFA codes, is stored DPAPI-protected in the management database. When the management database is transferred to a different machine, the secret cannot be decrypted on that machine and manual editing of the database would be required, which should be avoided.
-The <tt>Instance Host</tt> and <tt>Client Access Server</tt> roles are not connected to the <tt>Management Server</tt> role and the instances are not started. Perform the following steps to get your SPE running again:
+* Start the MailStore Service Provider Edition Configuration tool on the server that has the Management Server role by double-clicking its desktop icon. On Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.
+* Stop the ''Client Access Server'', ''Instance Host'',  and ''Management Server'' services.
-* Start the ''MailStore Service Provider Edition Configuration'' and stop the MailStore SPE instance host, client access server and management roles.
-* Transfer your MailStore SPE license through our [https://my.mailstore.com/TransferLicense license portal].
-* Open the configuration of the management role and adjust the <tt>Server Name</tt> to match the new name.
-*: [[File:ms_spe_config_mgmt_02.png|center]]
-* Start the management server role.
-* Log in into the dashboard and verify that he license warning is gone.
-* Open the configuration of the instance host role and adjust the <tt>Server Name</tt> to match the new name. Additionally enter the new server name in the <tt>Management Server</tt> field and [[Multi_Server_Mode_Setup#Pairing_with_Management_Server|pair]] this role with the management server role.
-*: [[File:ms_spe_config_ih_01.png|center]]
-* Start the instance host role.
-* Change the <tt>Instance Host</tt> setting in the [[Instance_Management_-_General_Administration#Configuring Instances|instance configuration]] of each instance.
-*: [[File:Ms_spe_move_instance_01.png|center]]
-* [[Management_Console_-_Infrastructure#Instance_Hosts|Remove]] the old instance host servername from the dashboard.
-* Open the configuration of the client access server role and adjust the <tt>Server Name</tt> to match the new name. Additionally enter the new server name in the <tt>Management Server</tt> field and [[Multi_Server_Mode_Setup#Pairing_with_Management_Server|pair]] this role with the management server role.
-*: [[File:ms_spe_config_cas_01.png|center]]
-* Start the client access server role.
-* [[Management_Console_-_Infrastructure#Client_Access_Servers|Remove]] the old client acces server servername from the dashboard.
-= Renaming the management server when the SPE runs on in Multi Server Mode =
-* Start the ''MailStore Service Provider Edition Configuration'' and stop the management role.
-* Transfer your MailStore SPE license through our [https://my.mailstore.com/TransferLicense license portal].
-* Rename and restart the server.
-* Open the the configuration of each role connected to this management server and adjust the ''Management Server'' setting.
-* Start each role.
-* Check the dashboard that every role is connected again.
-= Moving the SPE running in Single Server Mode to another server =
-* Close all MailStore SPE related programs, except for the ''MailStore Service Provider Edition Configuration'' on the old server.
-* Stop the MailStore SPE instance host, client access server and management roles.
 * Transfer your MailStore SPE license to the new server through our [https://my.mailstore.com/TransferLicense license portal].
-* Install MailStore SPE on the new server.
+* Install MailStore Service Provider Edition on the new server and set it up [[Single_Server_Mode_Setup|Single Server Mode]].
-* Stop all roles on the new server.
+* Stop the ''Client Access Server'', ''Instance Host'',  and ''Management Server'' services on the new server.
-* Remove all MailStore SPE related certificates from the new server's personal (MY) certificate store.
+* Remove all MailStore SPE related certificates from the server's personal (MY) certificate store of the new server.
 *: [[File:Spe-certificate-store.png|center]]
-* Export the SSL certificates and private keys from the old server's certificate store and import it to the same location on the new server.
+* Export the SSL certificates and private keys from the old server's certificate store and import them into the same location on the new server.
-''' On Windows Server 2012 R2 you can use the following PowerShell command to export all certificats stored in the computers ''MY'' store as PFX containers to the current user's desktop '''
+** On Windows Server 2016 and newer you can use the following PowerShell command to export all certificats stored in the computers ''MY'' store as PFX containers to the current user's desktop. That PowerShell session requires elevated privileges:<br/><pre>(Get-ChildItem Cert:\LocalMachine\My).Thumbprint | ForEach-Object { Export-PfxCertificate -Cert ("Cert:\LocalMachine\My\{0}" -f $_) -FilePath ("$env:USERPROFILE\Desktop\{0}.pfx" -f $_) -Password  (ConvertTo-SecureString -AsPlainText -Force "not_secure_234") }</pre>
- (Get-ChildItem Cert:\LocalMachine\My).Thumbprint | ForEach-Object { Export-PfxCertificate -Cert ("Cert:\LocalMachine\My\{0}" -f $_) -FilePath ("$env:USERPROFILE\Desktop\{0}.pfx" -f $_) -Password  (ConvertTo-SecureString -AsPlainText -Force "not_secure_234") }
+** Windows Server 2016 and newer Powershell command to import the previously exported certificates from the current user's desktop into the new server's certificate store. That PowerShell sessions requires elevated privileges:<br/><pre>Get-ChildItem -Path $env:USERPROFILE\Desktop\ -Filter *.pfx | Import-PfxCertificate -Exportable -Password  (ConvertTo-SecureString -AsPlainText -Force "not_secure_234") -CertStoreLocation Cert:\LocalMachine\My</pre>
-''' Windows Server 2012 R2 Powershell command to import the previously exported certificates from the current user's desktop into the new server's certificate store'''
+* Remove the <tt>%program files%\MailStore Infrastructure\config</tt> directory on the new server and replace it with the <tt>config</tt> directory from the old one.
- Get-ChildItem -Path $env:USERPROFILE\Desktop\ -Filter *.pfx | Import-PfxCertificate -Exportable -Password  (ConvertTo-SecureString -AsPlainText -Force "not_secure_234") -CertStoreLocation Cert:\LocalMachine\My
+* Transfer your instance data directories to the new server. If the instance data on the new server is stored in a different location than on the old one, the ''Base Directory'' of the instances must be adjusted accordingly. Refer to [[Instance_Management#Archive_Stores|Instance Management]] for further details.
-* Remove the ''%program files%\MailStore Infrastructure\config'' directory on the new server, replace it with the ''config'' directory from the old one.
+* When the host name of the server has changed, also follow the instructions in [[Renaming_Servers#Renaming_the_Server|Renaming the Server]]
-* Transfer you instance data directories to the new server.
+* Start the ''Management Server'' service followed by the ''Instance Host'' and ''Client Access Server'' service.
-* When the name of the server has changed, open the management role configuration and adjust the ''Server Name''.
+* [[Management Console - Logging On|Log on]] to the Management Console and check the dashboard for the connection status of servers and roles.
-* Start the management role.
+* [[Management_Console_-_System_Administrators|Re-enable Multi-Factor Authentication]] for system administrators that had it enabled.
-* Log in into the management dashboard. When the server name has changed, the connection to the instance host and client access server should be failed.
+* [[Management_Console_-_General#SMTP_Settings|Re-enter the SMTP password]] if it had been set.
-* Open the client access server configuration and adjust the ''Server Name'' and the ''Management Server'' if it has changed. The ''Server Name'' must be in lower case. Perform the pairing.
-*: [[File:ms_spe_config_cas_01.png|center]]
-* Start the client access server role.
-* Verify that the connection to the client access server can be established in the dashboard.
-* [[Management_Console_-_Infrastructure#Client_Access_Servers|Remove]] the leftovers of the other client access server in the dashboard.
-* Open the instance host configuration and adjust the ''Server Name'' and the ''Management Server'' if it has changed. The ''Server Name'' must be in lower case. Perform the pairing.
-*: [[File:ms_spe_config_ih_01.png|center]]
-* Start the instance host role.
-* Verify that the connection to the instance host can be established in the dashboard.
-* [[Management_Console_-_Infrastructure#Instance_Hosts|Change]] the location of the instance host's base directory, if it has changed.
-[[File:Ms_spe_move_instance_01.png|center]]
-* [[Moving_Instances|Change]] the configuration of each instance to reflect the new ''Server Name'' and path.
-* [[Management_Console_-_Infrastructure#Instance_Hosts|Remove]] the leftovers of the other instance host in the dashboard.
-= Moving the Management Server role to another server =
+== Multi Server Mode ==
+=== Moving the Management Server ===
-* Start the ''MailStore Service Provider Edition Configuration'' and stop the management role on the old server.
+* The following only applies if MFA has been enabled for some or all system administrators:
-* Transfer your MailStore SPE license to the new server through our [https://my.mailstore.com/TransferLicense license portal].
+*:* Log in at the Management Console and [[Management_Console_-_System_Administrators|disable MFA]] for all administrators that have it enabled.<br />The MFA secret, that is used to generate MFA codes, is stored DPAPI-protected in the management database. When the management database is transferred to a different machine, the secret cannot be decrypted on that machine and manual editing of the database would be required, which should be avoided.
-* Install the SPE on the new server and select ''Multi Server Mode''.
+* Start the MailStore Service Provider Edition Configuration tool on the server that has the Management Server role by double-clicking its desktop icon. On Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.
-* Add the management role on the new server.
+* Stop the ''Management Server'' service.
-* Stop the management role.
+* Transfer your MailStore SPE license through our [https://my.mailstore.com/TransferLicense license portal].
-* Transfer the file ''MailStoreManagementDatabase.json'' from the old server's config directory to the new server to the same location. By default this file resides in ''%programfiles\MailStore Infrastructure\config%''.
+* Install the MailStore Service Provider Edition on the new server and set it up in [[Multi_Server_Mode_Setup|Multi Server Mode]]
-* Open the the configuration of each role connected to the old management server, adjust the ''Management Server'' setting and pair the roles with the new management server.
+* Add the ''Management Server'' role on the new server, but do not start it yet.
-* Verify in the dashboard that every role is connected again.
+* Transfer the file <tt>MailStoreManagementDatabase.json</tt> from the old server's configuration directory to the same location on the new server. By default, this file resides in <tt>%programfiles\MailStore Infrastructure\config%</tt>.
+* Start the ''Management Server'' service on the new server.
+* Adjust the ''Management Server'' setting in the configuration of each  ''Instance Host'' and ''Client Access Server'' by clicking on the corresponding ''Configure...'' button in the MailStore Service Provider Edition Configuration tool.
+* [[Management Console - Logging On|Log on]] to the Management Console and check the dashboard for the connection status of servers and roles.
+* [[Management_Console_-_System_Administrators|Re-enable Multi-Factor Authentication]] for system administrators that had it enabled.
+* [[Management_Console_-_General#SMTP_Settings|Re-enter the SMTP password]] if it had been set.
-= Moving the Client Access Server role to another server =
+=== Moving an Instance Host ===
+* Start the MailStore Service Provider Edition Configuration tool on a server that is a Instance Host by double-clicking it's desktop icon. On Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.
+* Stop the ''Instance Host'' service.
+* Install MailStore Service Provider Edition on the new server and set it up in [[Multi_Server_Mode_Setup|Multi Server Mode]].
+* Add the ''Instance Host'' role.
+* [[Multi_Server_Mode_Setup#Pairing_with_Management_Server|Pair with the Management Server]].
+* Start the ''Instance Host'' service.
+* [[Management Console - Logging On|Log on]] to the Management Console and check the dashboard for the connection status of servers and roles.
+* Follow the [[Moving_Instances|Moving Instances]] guide to move the instances to the new instance host.
+* Remove the ''Instance Host'' role from the old server.
+* Finally [[Management_Console_-_Infrastructure#Removing_Instance_Hosts|remove the instance host]] that still exist with the old host name.
-* Export the certificates, including their private keys, that are visible to the end users on the old client access server. By default these are MailStoreClientAccessServerHttp and MailStoreClientAccessServerImap, but not MailStoreClientAccessServerTcp.
+=== Moving a Client Access Server ===
+* Export the certificates, including their private keys, that are visible to the end users on the old client access server. By default these are ''MailStoreClientAccessServerHttp'' and ''MailStoreClientAccessServerImap'', but '''not''' ''MailStoreClientAccessServerTcp''.
 * Import these certificates into the new server's personal (MY) certificate store.
-* Install the SPE on the new server and select Multi Server Mode.
+* Start the MailStore Service Provider Edition Configuration tool on a server that is a Client Access Server by double-clicking it's desktop icon. On Windows Server Core use the command line prompt to start the executable (default: <tt>%PROGRAMFILES%\MailStore Infrastructure\MailStoreInfrastructureConfig.exe</tt>.
-* Add the client access server role.
+* Stop the ''Client Access Server'' service.
-* Pair the role with the existing management server.
+* Install MailStore Service Provider Edition on the new server and set it up in [[Multi_Server_Mode_Setup|Multi Server Mode]].
-* Check the certificate settings in the role configuration.
+* Add the ''Client Access Server'' role.
-* Start the role.
+* [[Multi_Server_Mode_Setup#Pairing_with_Management_Server|Pair with the Management Server]].
-* Verify in the dashboard that the client access server is reachable.
+* Adjust the certificate settings in the ''Configure Client Access Server Role'' dialog to use the imported certificates.
-* Remove the role from the old server.
+* Start the ''Client Access Server'' service.
-* [[Management_Console_-_Infrastructure#Client_Access_Servers|Remove]] the leftover of the old client access server in the dashboard.
+* [[Management Console - Logging On|Log on]] to the Management Console and check the dashboard for the connection status of servers and roles.
+* Remove the ''Client Access Server'' role from the old server.
-= Moving the Instance Host role to another server =
+* Finally [[Management_Console_-_Infrastructure#Removing_Client_Access_Servers|remove the client access server]] that still exist with the old host name.
-* Install the SPE on the new server and select Multi Server Mode.
-* Add the instance host role.
-* Pair the role with the existing management server.
-* Start the role.
-* Check the dashboard that the instance host is reachable.
-* Stop all instances running on the old server.
-* Move the base directories of the instances to the new instance host with your preferred file explorer.
-* Change the ''Instance Host'' setting in the [[Instance_Management_-_General_Administration#Configuring Instances|instance configuration]] of each instance.
-[[File:Ms_spe_move_instance_01.png|center]]
-* Adjust the path to the ''Base Directory'' if it has changed.
-* Start the the instances.
-* Remove the role from the old server.
-* [[Management_Console_-_Infrastructure#Instance_Hosts|Remove]] the leftover of the old instance host in the dashboard.