Configuring the Cache in Multi-Server Scenarios
This article applies to EPiServer CMS 4.61 and 4.62.
This article describes how to configure multiple EPiServer installations to contact each other when changes to the cache occur. The concept of forwarding cache invalidations is called cache listeners.
Important! The cache listener support requires Web Services to communicate. Make sure Web Services are accessible before you follow this guide. For forms-authenticated sites, refer to the Web Services section in EPiServer SDK.
Contents
Introduction
EPiServer installations can send cache invalidations to other EPiServer installations that either share the same database or use different databases, but share information through Web Services. To understand this concept you must understand how EPiServer separates one page from another.
All pages in EPiServer are identified with a structure that consists of the identification number of the page, the identification number of the working version, and the site name. The site name is just a short name to identify the logical site, the same way you identify a domain in Windows that uses a common user account store. For example, the site www.episerver.com could have the site name “episervercom”. If www.episerver.com had three load-balanced Web sites, all should have the name “episervercom”, because all deliver pages from the same database. Page with ID 30 on site “episervercom” is always the same, irrespective of the load-balanced server delivering it, and should be treated so by EPiServer.
If “episervercom” were to read pages using Web Services from www.ep.se that have another database, they must be separated by the site name. The local site name for www.ep.se is set to “epse”. EPiServer now knows that a page with ID 30 on “episervercom” is not the same as 30 on “epse”.
When you request a page with ID 30 on the site “epse” from the site “episervercom”, the EPiServer data factory must know where to get this page on your network. In Admin mode in EPiServer, you have a user interface to configure remote sites. Here you can specify that “epse” can be contacted at this URL with this user name and password.
“Remote Web sites” in Admin mode is only a way to configure which site names match up with which configurations.
Cache Listeners
You can configure an EPiServer installation that some of these sites want to listen to on local cache invalidations. For example, if you wish to specify that "epse” should contact “episervercom” every time changes in the cache occur, set the EPsCacheListeners key in web.config to “episervercom”. The actual data will not be transmitted to the remote site. It will only call to tell that this page is no longer valid and should be read from the Web Service or database again.
Configuration for Installations Sharing a Database
Sites that share the same database are most often referenced as load-balanced servers. This example shows a common scenario with two servers: Server1 and Server2.
We have a site with URL http://www.domain.com that is installed on both servers. The steps below assume that a user with name “WebServerUser” has been created in the “ntdomain” domain with access to the "WebServices" folder of your EPiServer installation.
Note The names of the sites are case-sensitive. We recommend that you always use lowercase names as used in this sample.
- Edit web.config in the root directory of the Web on both Server1 and Server2 to make sure that they have the same logical site name. This is necessary, because they will be using the same database and delivering the same pages. This example uses the logical site “domaincom”.
<add key="EPsLocalSite" value="domaincom" /> - EPiServer now knows its name is “domaincom”, but as we communicate internally inside the logical site, we must add a remote site configuration for this site. Click Remote websites in Admin mode and select Create to add the site. Enter the settings as shown below and make sure you click Create on the right side of the Shared secret for signature field before you save your new site.
Note It is easier to understand why we do this if you consider how we would forward cache invalidation to another site. Then the remote site must add “domaincom” to its remote sites list to be able to pick up the correct shared secret for the signature on incoming calls. As the sites we are communicating with use the same database, we need this setting locally.
We don’t specify credentials, because we will never contact ourselves as a logical site, and by not setting all values, we enforce that an erroneous configuration never goes by without notice. - We have configured the servers with logical site and ensured that we can communicate internally using this name. As we want to contact the individual servers and not the cluster, we must add aliases for the servers. We do this by adding two remote sites “domaincom1” and “domaincom2” in Admin mode and making sure that the URL points to either the DNS name or the IP address of the individual site as shown below.
- All sites are now configured, but if you click Ping for “domaincom1”, you will probably receive a “Communication was signed but checksum was not valid” message. This is because the configured sites have different signatures. Click domaincom, copy the value in the Shared secret for signature field and paste it into both “domanicom1” and “domaincom2”. Save your changes. Go to the Troubleshooting chapter if you still receive the error message.
- All sites and communications are now set up correctly and we have to configure the cache listeners. Edit web.config on Server1 and set the following key:
<add key="EPsCacheListeners" value="domaincom2" />
Also edit web.config on Server2 and set the following key.<add key="EPsCacheListeners" value="domaincom1" />
You have now configured both load-balanced servers to contact each other when parts of the cache must be invalidated. Try creating new pages on one of the servers and the changes should show up on the other server without any noticeable delay.
Troubleshooting
Error: "Communication was only signed locally and not by the remote site"
Some of the sites do not have any signatures set. Verify that all sites have the same identical signature set under Remote Web sites in Admin mode.
Error: "Communication was signed but checksum was not valid"
All sites do not have the same identical signature. Verify that all sites have the same identical signature set under Remote Web sites in Admin mode.
Error: "Object moved"
The site is probably using forms authentication and the credentials are not valid. Check that the credentials you entered are not only valid in Windows, but also valid for the WebServices folder of the site. See the Web Services section in the EPiServer SDK for more information about configuring Windows-authenticated Web Services on a forms-authenticated site.
The Underlying Connection was Closed. Unable to Connect to the Remote Server
The URL on the site does not point to a valid site. Open the URL in a Web browser and make sure you can contact it from the actual server. The actual communication is done using a Web Service call from one server to another, either over HTTP port 80 or HTTPS/SSL port 443.
Note Remember to test this locally on the site, not from your local workstation, as other DNS or firewall rules may apply.
Important! Prior to configuring cache listeners, read the Web Services section in EPiServer SDK for background information about configuring Web Services.
Communication Seems to Work in Admin Mode, but the Cache Doesn’t Get Updated
The most common error is typing errors. Verify that all site names are identical. Remember that site names are case-sensitive when it comes to pushing cache changes. For example, if Site 1 is named “mysite” and Site 2 is named “MySite” the communication may be valid, but the cache will not get updated as expected.
Make sure that you have also checked the following:
- Check that there are no blank spaces in any of the fields in Remote Web Sites in Admin mode.
- Check that there are no blank spaces in EPsLocalSite and EPsCacheListeners in web.config.
- Add the following code to a template being run:
Local Site Name: <%=EPiServer.Global.EPConfig["EPsLocalSite"] %>
My Cache Listeners: <%=EPiServer.Global.EPConfig["EPsCacheListeners"] %>
<%=EPiServer.Global.EPDataFactory.LookupRemoteSite("YourCacheSiteNameFromEPsCacheListeners") == null ? "Site is null" : "Site exists"%> - Use Log4Net with DEBUG level. Check the log after a page has been changed and check that the CacheManager has been run (1.7.* messages).
- Check the access rights in the /WebServices folder and web.config in the file system on the server.
