Virtual Domains
Overview
Summary can produce separate sets of reports for each domain you host, or for various portions of a single domain. Each set of reports, for a single domain or portion of a domain, is called a sub-report. Summary supports up to three sub-reports, Summary Plus supports up to 50 sub-reports, Summary SP Lite supports up to 100 sub-reports, and Summary SP supports up to 1,000 sub-reports.
Each sub-report contains an entire set of the reports available on the Report Menu. These reports show information on a subset of all the available log entries. You configure each sub-report to select which log entries get included in the sub-report.
Summary can process a log file generated by a single web server or multiple logs generated by a single web server or even multiple logs generated by each of multiple web servers. Each individual log file may contain entries from a single domain or from multiple domains running on the same server. Summary refers to a single domain, out of the collection of all the domains for which you have log files, as a virtual domain.
In some cases configuring virtual domains may seem complicated. This is because it can sometimes be very complicated. Each brand of server software seems to have their own way of doing things and Summary has to be flexible enough to deal with all of them. Summary can even handle cases where you use a single copy of Summary to report on several different domains running on different brands of server software, where each server stores domain information differently.
A Quick Example
Lets say you are running a web server with sites for three of your friends: Bob, Jane and Bill. Even though you are running a single web server that generates a single log file, Summary can process that log file into three separate sub-reports - one for each of your friends, assuming the server is properly configured. Now Bob has a set of reports that contain information only about his site and Jane has a set of reports for her site, and so on. Obviously, if you are running a commercial web server, you can see why separate sub-reports for each virtual domain is useful to your clients and profitable for you as a value added option.
Since all of the log entries appear in a single log file, we need to be sure that there is information in each log entry telling Summary which site it belongs to. This could be a portion of the URI, for example Bob's content might always start with "/~bob/". Or, the site information might appear as a field in the log entry containing a domain name, for example "www.jane.com". Or, the site information might appear as a field in the log entry containing a virtual server name, for example Bill's site might be called "www03".
Configuring Summary for Virtual Domains
Summary provides multiple ways to detect each virtual domain and split them up into sub-reports. There are four common approaches to detecting which virtual domain a log entry is associated with.
- Method One: information in the requested URI (i.e. the path starts with /~bob or /~jane) (a common configuration for WebStar)
- Method Two: the host name as the client typed it into the browser, from the HTTP "Host" header
- Method Three: the host name as configured on the server (a common configuration for Microsoft IIS)
- Method Four: separate log files for each virtual domain (a common configuration for Apache)
Method One
The first method is to determine the virtual domain from the requested URI path. For example, requests starting with http://www.mydomain.com/~bob/ and http://www.mydomain.com/~jane/ can be split out into separate sub-reports. This approach can be used when you don't actually have separate domain names, you just want to report on different parts of your site separately. This is also commonly used with WebSTAR 4 because WebSTAR 4 will add the internal folder name to a request before logging it. For example WebSTAR 4 might log a request to http://www.bob.com/index.html as /bob/index.html. The exact folder names WebSTAR 4 adds depend on your WebSTAR 4 configuration.
To configure Summary in this situation you enter the leading portion of the request, followed by a "*" into "Requests to include in this Sub-report" field and enter a "*" into "Domains to include in this Sub-report". For example, to get all request that start with "/~bob/" you would enter "/~bob/*" into "Requests to include in this Sub-report". If you are not sure what names WebSTAR is adding to the request you can take a look at the Directory Report in a sub-report that includes all log entries or at your WebSTAR configuration settings.
Method Two
The second method is to determine the virtual domain from the host name the client entered into their browser. For this approach to work, your server must be logging the HTTP Host header. WebSTAR will log this information if you include the CS(HOST) log token in the log format. Apache will log this information if you include %{HOST}i in the log format string.
First, you need to determine all of the different host names that will lead to your web site. There are frequently several different names which will access a single site. For example, summary.net, www.summary.net, and 209.163.232.96 will all take you to the Summary web site. Enter all of the domain names that lead to your site into "Domains to include in this Sub-report". Enter a "*" into "Requests to include in this Sub-report" field. You also need to be sure that either "Always use folder name as domain name" is not checked or the log file is contained directly in Summary's Logs folder and not in a sub-folder.
If you are not sure which domain names to use, take a look at the Details:Domains report in a sub-report that includes all log entries. It will show you what domain names occur in your log file. If the report is blank your server is probably not configured to log this information.
Method Three
The third method is to use the virtual server name as configured on the server to determine the virtual domain. Summary reads the virtual server name from the log entry into it's "domain" field and you can then use that to configure your sub-reports. Enter the virtual server/domain name into "Domains to include in this Sub-report" field. Enter a "*" into "Requests to include in this Sub-report" field.
For this approach to work, your server must be logging the virtual server/domain name. You also need to be sure that either "Always use folder name as domain name" is not checked or the log file is contained directly in Summary's Logs folder and not in a sub-folder.
Microsoft IIS typically includes the virtual server name in the log file. Apache can be configured to log this information by including %v or %V in the log format string. If you are not sure which virtual server name to use, take a look at the Details:Domains report in a sub-report that includes all log entries. It will show you what server names occur in your log file. If the report is blank your server is probably not configured to log this information.
Method Four
The fourth method is to log each virtual domain into a separate log file. In order to tell Summary which log files go with which virtual domain you need to create sub-folders (sub-directories) inside the Logs folder (logs directory on Unix systems).
- Create one sub-folder for each virtual domain that you want a separate report for.
- Put the log files into the corresponding folders.
- Put the folder name into "Domains to include in this Sub-report" field.
- Enter a "*" into "Requests to include in this Sub-report" field.
- Check "Always use folder name as domain name" on the Options configuration page.
Apache and WebSTAR 5 typically use this approach, creating a separate log file for each domain. You can also use this approach any time you have separate log files for each virtual domain you want reports for.
When setting up log downloading for use with Method Four you need to put the correct folder name in "store download in sub-folder name". Set the field to the name of the sub-folder that corresponds to the server you are downloading logs from.
Solving Configuration Problems?
When debugging virtual domain configurations it is often handy to make a sub-report that reports on all entries in all log files. Set both "Domains to include in this Sub-report" and "Requests to include in this Sub-report" to "*". You can then look at the Details:Domains report to see what values occur for the virtual domain name or the Content:by Directory report to see which path name prefixes are actually in use.
Configuring Virtual Domains for use with WebSTAR
WebSTAR V and newer should be configured to create separate log files for each domain and then you can set up Summary using Method Four. Since WebSTAR V includes an extra path prefix to the request in the logs, you will also want to check "Remove first directory name" and or "Remove two directory names" and or "Remove four directory names", on the Sub-report Details configuration page, so that requests will appear correctly in the reports.
WebSTAR 4 and older always logs all requests to a single log file. There are two ways to configure Summary for WebSTAR 4. You can configure WebSTAR to log the virtual domain name by adding the CS(HOST) token to the log format. Then you can configure Summary using Method Two. Summary reports this name, typically the DNS name of the domain, as the "domain name". With this log token included, Summary can select log entries for inclusion in a sub-reports based on this name. Typically a single virtual domain can appear with several different names. This means that you will have to include all of the possible names for the domain in the "Domains to include in this sub-report". For example summary.net can appear as summary.net or www.summary.net.
Alternatively, you can configure Summary using Method One. WebSTAR 4 always adds the name of the root folder to the front of all requests to virtual domains. For example if I have a virtual domain called virtual.summary.net and have configured WebSTAR 4 to fill all requests to that domain from the "virtual" folder, it will log a request to <http://virtual.summary.net/home.html> as a request to "/virtual/home.html". You can then use the folder name to select which log entries are to be included in a sub-report. In this case you would set "Requests to include in this Sub-report" to "/virtual/*". You will also want to check "Remove first directory name" on the Sub-report Details configuration page so that requests will appear correctly in the reports.
Configuring Virtual Domains for use with Apache
Apache is usually configured is to write log entries for each virtual domain into a separate log file. You can then configure Summary using Method Four. We strongly recommend using this approach. It is also possible to configure Apache to record all log entrees for all virtual domains into a single log file, and set up Summary using Method Two but if you decide to do this there will be complications. There is no standard log file format that includes the virtual server name or domain name in the log file that is supported by Apache and automatically read by Summary. Further, if you neglect to include the virtual server name or domain name in the log format file, your log files are worthless because no one will have any way to distinguish which log entries belong with which virtual domain.
If you want to have a single log file with entries from all of your domains, you are going to need to add the domain name to each log entry and make a custom log format string for Summary. The best place to put the domain name is in place of the second field of NCSA Common or NCSA Combined format log files. The "ident" field (the second field) is never used anymore, it used to be the users e-mail address but privacy concerns caused it to be disabled on all browsers. The Apache configuration for NCSA Combined format with the host name in the second field is:
LogFormat "%h %v %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" withdomain
The custom user log format string to configure Summary to read this format is:
HOST DOMAIN USER DATE-CLF FULL-REQUEST STATUS BYTES IF-EOL REFERER AGENT
Configuring Virtual Domains for Microsoft IIS
Microsoft IIS logs each virtual domain to a separate log file. It's normally simplest to set up Summary using Method Four. Logs in Microsoft Native format and logs in W3C ExLF format, when the "Server Name" field is included, contain the virtual server name and so Summary can be set up using Method Three.
Other Servers
All servers will work with one of the four methods presented above. Method Four, separate log files for each domain, is by far the most common approach.
Some web servers use NCSA Common or NCSA Combined log format but they replace the second token of each line with the HTTP Host name. Summary does not directly support this log format, but can be told how to read that format. On the Miscellaneous configuration page, set "User log format definition" to:
HOST DOMAIN USER DATE-CLF FULL-REQUEST STATUS BYTES IF-EOL REFERER AGENT
Auto Configure
Summary also features an auto configure option. Auto Configure is located on the Tools configuration page. A link to the Tools page is located near the bottom of the main configuration page. When Auto Configure is selected Summary will attempt to suggest meaningful sub-report settings based on results from the most recent log processing run.
To use auto configure, you will need to process the logs with at least one sub-report that includes all of the log entries (this is the default configuration). Auto Config will then search for virtual domain names and directory names and propose various sub-reports. You simply check off the ones you want. You still need to re-process the logs to get the new sub-reports to contain information.
Why not use auto configure all the time? The problem with auto configure is that it may suggest things you don't want. Auto configure can make intelligent suggestions - up to a point. For example, it does not know which server software you are using. Therefore, it has a habit of suggesting that normal directories are virtual domains. It will only suggest 50 at a time, and it won't suggest ones you already have.
Using Sub-Reports
If Summary is running on the same machine as your main server, you should be able to access Summary by any of the domain names you are hosting with the :9000 port number (or whatever port you have configured Summary to use) added. To go directly to a specific report you would type <http://their.domain:9000/~name> where "name" is the string entered in "Identifier for use in report URLs" for their sub-report.
If you give each sub-report a different name and password you can skip the ~name part and Summary will find the correct sub-report from the name and password.
Password Protection of Sub-Reports
Sub-reports can be name and password protected. If there is a configuration name/password and the first sub-report is name/password protected, the name and password entered will be used to automatically select the correct sub-report. A sub-report can also be given an "Identifier for use in report URLs". This identifier can be used to go directly to a specific sub-report by appending "~" (or "." or "$") and the identifier to the URL Summary gives when it starts up. For example if Summary is at "http://my.computer.com:9000/" and you have a sub-report with the id "james", you would use the URL "http://my.computer.com:9000/~james" to directly access that sub-report.
