Exchange Server custom configuration preservation

Overview

After installing Exchange Server, a common admin task is to customize settings, such as client-specific message size limits. These settings are typically configured in web.config, sharedweb.config, and other configuration files on the Exchange server.

Historically, one of the challenges for Exchange server admins is that each time a Cumulative Update (CU) is installed, these files and the custom settings therein are overwritten by Setup, forcing an admin to back up/restore their settings, or reapply them after every CU install.

With Exchange Server 2019 CU13 and later, Setup now backs up and restores the most common configuration files so that admins no longer need to manually restore them or reapply them.

Setup preserves custom configurations in the following way:

1. Setup creates a backup of the existing files.
2. Setup installs Exchange Server (or upgrades existing Exchange Server), and overwrites existing files with default configurations and settings present in Exchange Setup.
3. Setup finally restores appropriate files and custom values of critical keys stored in the preupgrade configuration files in the new config files copied from Exchange Setup.

Setup preserves the most critical configuration settings (if present), which can include entire sections or certain key value pairs.

1. appSettings contains many key value pairs that configure a range of application settings, (for example, logging path, message queue size, etc.). Any key value pair created using <add key> tag is preserved if this section is present.

   For example, in the following file, ClientTunnelExpirationTime is preserved.

   <configuration> 
   <appSettings> 
       <add key="ClientTunnelExpirationTime" value="30" /> 
   </appSettings> 
   </ configuration>
   

2. The entire proxySettings section is critical and is preserved.

3. maxAllowedContentLength is used to specify the maximum length of content (in bytes) in a request.

   <system.webServer> 
       <security> 
       <requestFiltering> 
           <requestLimits maxAllowedContentLength="4194304" /> 
       </requestFiltering> 
       </security> 
   <system.webServer> 
   

4. maxRequestLength is used to specify the maximum request size.

   <system.web> 
       <httpRuntime maxRequestLength="4194304" /> 
   </system.web> 
   

5. maxReceivedMessageSize is used in systembinding and custombinding elements to set the maximum size (in bytes) for a message that can be received on a channel configured with this binding.

6. maxStringContentLength is present in both systembinding and customBinding elements and is used to limit the maximum string size that the XML reader returns.

7. extendedProtectionPolicy is used to set the extended protection policy, which is used by the server to validate incoming client connections.

8. defaultProxy is used to configure the HTTP proxy server.

List of preserved config files along with sections and keys preserved

Here's the list of all the config files along with sections and keys that are automatically preserved during CU upgrade.

Note

IIS URL rewrite rule mitigations that were applied on a per-site/per-vDir level will not be preserved by this feature and eventually be reapplied by the Exchange Emergency Mitigation service if they are still applicable for the CU that was installed. More information can be found here.

No.	Config File Name	Sections Preserved	Additional Keys Preserved
1	<ExchangeInstallPath>\V15\Bin\ComplianceAuditService.exe.config	appSettings	-
2	<ExchangeInstallPath>\V15\Bin\EdgeTransport.exe.config	appSettings	-
3	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.Diagnostics.Service.exe.config	appSettings	-
4	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.Directory.TopologyService.exe.config	appSettings	maxReceivedMessageSize, maxStringContentLength
5	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.EdgeSyncSvc.exe.config	appSettings	-
6	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.Mitigation.Service.exe.config	appSettings	-
9	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.RpcClientAccess.Service.exe.config	appSettings, defaultProxy	maxReceivedMessageSize, maxStringContentLength
10	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.Search.Service.exe.config	appSettings	-
12	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.Servicehost.exe.config	appSettings, defaultProxy	maxReceivedMessageSize, maxStringContentLength
14	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.Store.Service.exe.config	appSettings	-
17	<ExchangeInstallPath>\V15\Bin\MSExchangeCompliance.exe.config	appSettings	-
18	<ExchangeInstallPath>\V15\Bin\MSExchangeDelivery.exe.config	appSettings	-
19	<ExchangeInstallPath>\V15\Bin\MSExchangeFrontEndTransport.exe.config	appSettings	-
20	<ExchangeInstallPath>\V15\Bin\MSExchangeHMHost.exe.config	appSettings	-
21	<ExchangeInstallPath>\V15\Bin\MSExchangeHMRecovery.exe.config	appSettings	-
22	<ExchangeInstallPath>\V15\Bin\MSExchangeHMWorker.exe.config	appSettings	-
23	<ExchangeInstallPath>\V15\Bin\MSExchangeMailboxAssistants.exe.config	appSettings	-
24	<ExchangeInstallPath>\V15\Bin\MsExchangeMailboxReplication.exe.config	appSettings, defaultProxy	maxReceivedMessageSize, maxStringContentLength
26	<ExchangeInstallPath>\V15\Bin\MSExchangeSubmission.exe.config	appSettings	-
27	<ExchangeInstallPath>\V15\Bin\MSExchangeThrottling.exe.config	appSettings	-
28	<ExchangeInstallPath>\V15\Bin\MSExchangeTransport.exe.config	appSettings	-
29	<ExchangeInstallPath>\V15\ClientAccess\PopImap\Microsoft.Exchange.Imap4.exe.config	appSettings, defaultProxy	-
30	<ExchangeInstallPath>\V15\ClientAccess\PopImap\Microsoft.Exchange.Imap4Service.exe.config	appSettings	-
31	<ExchangeInstallPath>\V15\ClientAccess\PopImap\Microsoft.Exchange.Pop3.exe.config	appSettings, defaultProxy	-
32	<ExchangeInstallPath>\V15\ClientAccess\PopImap\Microsoft.Exchange.Pop3Service.exe.config	appSettings	-
33	<ExchangeInstallPath>\V15\FrontEnd\PopImap\Microsoft.Exchange.Imap4.exe.config	appSettings, defaultProxy	-
34	<ExchangeInstallPath>\V15\FrontEnd\PopImap\Microsoft.Exchange.Imap4Service.exe.config	appSettings	-
35	<ExchangeInstallPath>\V15\FrontEnd\PopImap\Microsoft.Exchange.Pop3.exe.config	appSettings, defaultProxy	-
36	<ExchangeInstallPath>\V15\FrontEnd\PopImap\Microsoft.Exchange.Pop3Service.exe.config	appSettings	-
37	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.AddressBook.Service.dll.config	appSettings	-
38	<ExchangeInstallPath>\V15\Bin\Microsoft.Exchange.Management.Transport.dll.config	appSettings	-
39	<ExchangeInstallPath>\V15\TransportRoles\agents\Antimalware\Microsoft.Exchange.Transport.Agent.Malware.dll.config	appSettings	-
40	<ExchangeInstallPath>\V15\Bin\MSExchangeUM.config	appSettings	-
41	<ExchangeInstallPath>\V15\ClientAccess\Autodiscover\web.config	appSettings	maxReceivedMessageSize
42	<ExchangeInstallPath>\V15\ClientAccess\ecp\web.config	appSettings	maxReceivedMessageSize, maxStringContentLength
43	<ExchangeInstallPath>\V15\ClientAccess\ecp\DLPPolicy\Web.config	-	maxRequestLength
44	<ExchangeInstallPath>\V15\ClientAccess\ecp\Handlers\Web.config	-	maxRequestLength
45	<ExchangeInstallPath>\V15\ClientAccess\ecp\PersonalSettings\Web.config	-	maxRequestLength
46	<ExchangeInstallPath>\V15\ClientAccess\ecp\UsersGroups\Web.config	-	maxRequestLength
47	<ExchangeInstallPath>\V15\ClientAccess\exchweb\ews\web.config	appSettings, defaultProxy, extendedProtectionPolicy	maxAllowedContentLength, maxReceivedMessageSize, maxRequestLength, maxStringContentLength
48	<ExchangeInstallPath>\V15\ClientAccess\mapi\emsmdb\web.config	appSettings, defaultProxy	maxAllowedContentLength, maxReceivedMessageSize, maxRequestLength, maxStringContentLength
49	<ExchangeInstallPath>\V15\ClientAccess\mapi\nspi\web.config	appSettings, defaultProxy	maxAllowedContentLength, maxRequestLength
50	<ExchangeInstallPath>\V15\ClientAccess\OAB\web.config	appSettings	-
52	<ExchangeInstallPath>\V15\ClientAccess\PowerShell\web.config	appSettings	-
53	<ExchangeInstallPath>\V15\ClientAccess\PowerShell-Proxy\web.config	appSettings	-
54	<ExchangeInstallPath>\V15\ClientAccess\PushNotifications\web.config	appSettings	maxReceivedMessageSize
55	<ExchangeInstallPath>\V15\ClientAccess\rest\web.config	appSettings	maxAllowedContentLength, maxRequestLength
56	<ExchangeInstallPath>\V15\ClientAccess\RpcProxy\web.config	appSettings	-
57	<ExchangeInstallPath>\V15\ClientAccess\Sync\web.config	appSettings, defaultProxy	MaxDocumentDataSize, maxRequestLength, maxAllowedContentLength
58	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\autodiscover\web.config	appSettings	-
59	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\ecp\web.config	appSettings	maxAllowedContentLength, maxRequestLength
60	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\ews\web.config	appSettings	maxAllowedContentLength, maxRequestLength
61	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\mapi\web.config	appSettings	maxAllowedContentLength, maxRequestLength
62	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\oab\web.config	appSettings	-
63	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\owa\web.config	appSettings	maxAllowedContentLength, maxRequestLength
64	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\powershell\web.config	appSettings	-
65	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\pushnotifications\web.config	appSettings	maxAllowedContentLength, maxRequestLength
66	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\ReportingWebService\web.config	appSettings	-
67	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\rest\web.config	appSettings	maxAllowedContentLength, maxRequestLength
68	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\rpc\web.config	appSettings	maxAllowedContentLength, maxRequestLength
69	<ExchangeInstallPath>\V15\FrontEnd\HttpProxy\sync\web.config	appSettings	maxRequestLength, maxAllowedContentLength
70	<ExchangeInstallPath>\V15\FIP-FS\Data\Configuration.xml	ProxySettings	-
71	<ExchangeInstallPath>\V15\Bin\Search\Ceres\Runtime\1.0\Noderunner.exe.config	-	memoryLimitMegabytes

After Setup completes, it will display the following messages to indicate that all preserved configuration settings were successfully restored.

GUI mode

Unattended mode

The backup of the preserved configuration files is stored in %ProgramFiles%\Microsoft\Exchange Server\V15\Config in subfolders that using a naming format of v_<ExchangeVersion>_<Timestamp>.

Note

If these files are not needed after Setup has completed, they can be safely deleted.

Setup preserves custom settings by default. If you don't want to use this feature, you can disable it by creating a REG_SZ entry DisablePreservation under HKLM\SOFTWARE\Microsoft\ExchangeServer\v15\Setup and setting the value to 1.

The key/value pair can be created by running the following PowerShell command:

New-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\ExchangeServer\v15\Setup -Name "DisablePreservation" -Value 1 -Type String

If the Exchange Setup is run after setting the regkey to 1, setup won't back up nor restore any key/value pair in any of the configs.

Registry Key	Registry Value	Exchange setup behavior
DisablePreservation (Type: REG_SZ)	1	All the key value pairs in config files are reset and no backup of preupgrade config is stored (this behavior is equivalent to previous CU upgrades).
DisablePreservation (Type: REG_SZ)	NULL	Setup creates a backup of preupgrade configs and preserves certain key/value pair in preupgrade configs to the new configs.
DisablePreservation (Type: REG_SZ)	Any other value	Setup creates a backup of preupgrade configs and preserves certain key/value pair in preupgrade configs to the new configs.

If Setup can't restore all settings to their previous state, it displays a warning.

Unattended Mode

Attended Mode

As a next step, admins can analyze the Setup log file to see which settings couldn't be preserved. One or more entries may be present in the log file to indicate which settings couldn't be preserved:

1. Exception encountered during reading config file: <configFileName>. Skipping preservation.
2. Exception encountered during saving <Preservation cmdlet name> changes to: <configFileName>.
3. Exception encountered during schema validation of config file: <configFileName>. Skipping preservation.
4. <Preservation cmdlet name> failed for: <configFileName>

Admins can manually copy any configurations files from the backup location to the required location by overwriting the files created by Setup. This also restores these files to their pre-Setup state.