Share via


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.