Exchange virtual directories: setting the URLs and resetting a broken one

Outlook on the web, the EAC, Outlook over MAPI/HTTP, EWS applications, ActiveSync phones and offline address book downloads all reach Exchange through IIS virtual directories. Wrong URLs send clients to the wrong place, and one damaged directory breaks one protocol on one server. Here's how to check and set every URL in one pass, and how to reset a broken directory without losing the settings you rely on.

How it works#

Every Exchange Server SE, 2019 or 2016 Mailbox server runs two IIS websites:

• Default Web Site is the front end that clients connect to on port 443. You manage its directories with Exchange cmdlets: owa, ecp, EWS, mapi, OAB, Microsoft-Server-ActiveSync, Autodiscover, Rpc and PowerShell.
• Exchange Back End (port 444) receives the requests the front end proxies to it. Clients never connect to it directly.

Each front-end directory has an InternalUrl and an ExternalUrl, and Autodiscover passes these to clients. Setup sets the internal URL to the server's own FQDN (for example https://ex01.contoso.com/owa) and leaves the external URL blank. In production you normally point both at a shared namespace on your certificate, such as mail.contoso.com.

Exchange keeps each directory's settings in both Active Directory and IIS, and the two can drift apart. Microsoft calls a directory deleted in IIS but still present in AD an Active Directory orphan; the supported clean-up is the matching Remove-*VirtualDirectory cmdlet.

Step 1: Take an inventory#

In the Exchange Management Shell (EMS), -ADPropertiesOnly reads only the AD side. That's quick and still works when a server's IIS isn't responding:

$s = "EX01"
Get-OwaVirtualDirectory         -Server $s -ADPropertiesOnly | Format-List Name, InternalUrl, ExternalUrl
Get-EcpVirtualDirectory         -Server $s -ADPropertiesOnly | Format-List Name, InternalUrl, ExternalUrl
Get-WebServicesVirtualDirectory -Server $s -ADPropertiesOnly | Format-List Name, InternalUrl, ExternalUrl
Get-MapiVirtualDirectory        -Server $s -ADPropertiesOnly | Format-List Name, InternalUrl, ExternalUrl
Get-OabVirtualDirectory         -Server $s -ADPropertiesOnly | Format-List Name, InternalUrl, ExternalUrl
Get-ActiveSyncVirtualDirectory  -Server $s -ADPropertiesOnly | Format-List Name, InternalUrl, ExternalUrl
Get-OutlookAnywhere             -Server $s | Format-List InternalHostname, ExternalHostname
Get-ClientAccessService         -Identity $s | Format-List AutoDiscoverServiceInternalUri

Compare the output with a healthy server. The odd one out is usually the damaged directory.

Step 2: Set the URLs consistently#

With split DNS, the simplest design uses one host name both inside and outside. Change the names and run this once per server:

$s = "EX01"; $h = "mail.contoso.com"
Get-OwaVirtualDirectory -Server $s | Set-OwaVirtualDirectory -InternalUrl "https://$h/owa" -ExternalUrl "https://$h/owa"
Get-EcpVirtualDirectory -Server $s | Set-EcpVirtualDirectory -InternalUrl "https://$h/ecp" -ExternalUrl "https://$h/ecp"
Get-WebServicesVirtualDirectory -Server $s | Set-WebServicesVirtualDirectory -InternalUrl "https://$h/EWS/Exchange.asmx" -ExternalUrl "https://$h/EWS/Exchange.asmx"
Get-MapiVirtualDirectory -Server $s | Set-MapiVirtualDirectory -InternalUrl "https://$h/mapi" -ExternalUrl "https://$h/mapi"
Get-OabVirtualDirectory -Server $s | Set-OabVirtualDirectory -InternalUrl "https://$h/OAB" -ExternalUrl "https://$h/OAB"
Get-ActiveSyncVirtualDirectory -Server $s | Set-ActiveSyncVirtualDirectory -InternalUrl "https://$h/Microsoft-Server-ActiveSync" -ExternalUrl "https://$h/Microsoft-Server-ActiveSync"
Get-OutlookAnywhere -Server $s | Set-OutlookAnywhere -InternalHostname $h -InternalClientsRequireSsl $true -ExternalHostname $h -ExternalClientsRequireSsl $true
Set-ClientAccessService -Identity $s -AutoDiscoverServiceInternalUri "https://autodiscover.contoso.com/Autodiscover/Autodiscover.xml"

Autodiscover is the exception. Domain-joined Outlook finds it through the service connection point (SCP) that Set-ClientAccessService writes, and other clients find it through DNS.

For the external URLs, the EAC has a shortcut: in Servers › Virtual directories, click Configure, select the Internet-facing servers and enter the external host name. Microsoft recommends leaving the external URL blank on servers with no Internet presence.

Step 3: Reset or recreate a broken directory#

Reset a directory when one protocol fails on one server but works on the others. Typical signs are a blank page or error from OWA or ECP on that server only, a directory missing from IIS Manager, a Get-*VirtualDirectory warning about a directory that exists in AD but not in IIS, or unexplained edits in IIS. A reset recreates the directory with default settings. Drain the server from the load balancer first and work on one server at a time.

Option A: the EAC (OWA)#

1. Go to Servers › Virtual directories, filter on the server and select its OWA directory.
2. Click Reset. The EAC asks for a UNC path where it saves the current settings as a text file, such as \\EX01\c$\owavdir.txt.
3. Click Reset, then restart IIS as shown below.

The EAC runs on ECP, so if ECP is broken on every server, use the shell.

Option B: the shell (any directory)#

# 1. Save the current settings
New-Item -ItemType Directory -Path C:\VdirBackup -Force | Out-Null
Get-OwaVirtualDirectory -Server EX01 | Format-List * | Out-File C:\VdirBackup\EX01-owa.txt

# 2. Remove and recreate the front-end directory
Remove-OwaVirtualDirectory -Identity "EX01\owa (Default Web Site)" -Confirm:$false
New-OwaVirtualDirectory -Server EX01 -WebSiteName "Default Web Site" -InternalUrl "https://mail.contoso.com/owa" -ExternalUrl "https://mail.contoso.com/owa"

The other directories work the same way with their own cmdlets, such as Remove-EcpVirtualDirectory and New-EcpVirtualDirectory. Compare the new directory with your backup and use the matching Set- cmdlet to restore anything that wasn't a default. Then restart IIS from an elevated command prompt:

net stop w3svc /y
net start w3svc

Set-WebServicesVirtualDirectory -Identity "EX01\EWS (Default Web Site)" -MRSProxyEnabled $true

Leave the PowerShell directory and the Exchange Back End site alone unless Microsoft's guidance says otherwise. EMS connects through the PowerShell directory, so rebuilding it means working from a local Windows PowerShell session with the Exchange snap-in loaded.

Verify#

• Re-run the Step 1 inventory. Every server should show the same URLs, and the rebuilt directory should match its counterpart on another server.
• Open https://ex01.contoso.com/owa/healthcheck.htm and the same page under ecp, EWS, mapi, OAB, Microsoft-Server-ActiveSync and Autodiscover. A healthy directory returns 200 OK.
• Sign in to OWA and the EAC through that server.
• In Outlook, hold Ctrl and right-click the Outlook icon in the notification area. Choose Test E-mail AutoConfiguration, clear the Guessmart boxes and run the test. The Results tab should list the URLs you set.
• Re-run the Exchange Health Checker. If it flags Extended Protection on the rebuilt directory, follow enabling Extended Protection safely.

Tips & gotchas#

• Make changes through the cmdlets or the EAC, not IIS Manager. The cmdlets can't see edits made directly in IIS or web.config, and a cumulative update can overwrite edited configuration files.
• Use shared namespaces in URLs, never server names. Server names end up in client configuration and break when you retire the server.
• Outlook picks up new URLs at its next Autodiscover lookup, and restarting Outlook triggers one.

References#

• View or configure Outlook on the web virtual directories in Exchange Server (Microsoft Learn)
• Remove-OwaVirtualDirectory (Microsoft Learn)
• New-OwaVirtualDirectory (Microsoft Learn)