Troubleshooting - Web-Server

It is the web-server which connects with all of the external NCC components, including the NCC database. It is also the server-side software which performs all of the access security checks, and which manages all of the N2C5 site configuration parameters. This means that in practice it will be the web-server which is the cause of any configuration or NCC connection problems.

Web-Server Error Logs

The Apache Web Server handles all requests from the client's web browser. The location of the Apache Web Server Error Log file varies from installation to installation. A typical location is:

/var/log/apache2/n2c5-<instance>-error.log

e.g.

/var/log/apache2/n2c5-model-error.log
/var/log/apache2/n2c5-prod-error.log

All server-side processing log output on the N2C5 platform should be written to these files. If an unusual processing scenario is occurring on N2C5, then it will very likely be generating an associated message to this file.

Static Pages

There are three separate types of resources which the web-browser client can request from the web-server.

  1. Static Files (JS, CSS, Images)
  2. HTML Pages (the GeneratePage Plugin)
  3. Dynamic Data (other Datasets & Plugins)

Static files used by the web-application include JavaScript (.js), CSS (.css) and Image Files (.jpg, .png). These files are served unchanged by the web-server from the appropriate directory, e.g. from:

/usr/share/n2c5-model/htdocs

Note: Your site may have the apache "pagespeed" module installed. If so, note that the pagespeed module will add a suffix to resource files to ensure that caching is always performed correctly. E.g. the file "utils.js" may be renamed on-the-fly by the pagespeed module and presented to the web-browser as "utils.js.pagespeed.jm.vo6PAl1IOv.js". For more information, see the PageSpeed Module Development Page.

Note: Any error associated to missing static content should show as a "404 Not Found" or similar error in the web-browser client. This generally indicates a misconfiguration in file paths or permissions on the server.

HTML Pages

The base HTML pages (e.g. "/n2c5-prod/subscriber") are handled by the "GeneratePage" module, and are constructed using the popular "Template Toolkit" library.

The following section describes how the HTML request from the browser is processed by Template Toolkit. This mechanism is given in some detail. For debugging system faults, all you probably need to know is that the Perl module "GeneratePage.pm" will process the template "subscriber.tt2". If you are short of time, you may wish to skip down to the next topic.

In Detail: Firstly, the web-browser requests a path as follows:

/n2c5-prod/subscriber

The "/n2c5-prod/" path is handled by "Alias" and "<Directory>" directives in the standard apache httpd configuration files. See httpd.apache.org for the full apache documentation. The apache Alias maps /n2c5-prod/ to the following on-disk path:

/usr/share/n2c5-prod/htdocs/

This directory contains an apache ".htaccess" file which contains something similar to the following.

#
# All pages are generated by Jarvis plugins using Template Toolkit.
#
# The Apache URL rewriting allows the system to allow users to access:
#  /n2c5-prod/pagename
#
# and it gets rewritten as:
#  /jarvis-agent/n2c5-prod/generate-page/pagename
#
RewriteEngine on
RewriteBase /jarvis-agent/n2c5-prod/

# Don't rewrite any static content (specified directories, and/or anything else *.html).
RewriteRule ^css/ - [L]
RewriteRule ^js/ - [L]
RewriteRule ^jquery/ - [L]
RewriteRule ^img/ - [L]
RewriteRule ^bootstrap/ - [L]
RewriteRule ^bootstrap\-datetimepicker/ - [L]
RewriteRule ^glyphicons/ - [L]
RewriteRule \.html$ - [L]

# All other pages get passed to the "GeneratePage" plugin.
RewriteRule ^(.*)$ generate-page/$1

The final RewriteRule captures all HTML pages and applies the RewriteBase. So the path:

/n2c5-prod/subscriber

Is translated by the .htaccess file to become:

/jarvis-agent/n2c5-prod/generate-page/subscriber

This path is given to the Jarvis Library. You should find Jarvis installed at:

/usr/share/jarvis/...

All Jarvis paths are of the form:

/jarvis-agent/<application>/<dataset>/<additional-args>

So Jarvis will access the "n2c5-prod" application. It will request the "generate-page" dataset, and will give the argument "subscriber".

The configuration for the "n2c5-prod" Jarvis application is contained in:

/etc/jarvis/n2c5-prod.xml

The relevant line for the "generate-page" dataset is:

<!-- Access is ** on the Page module, since it also serves our login page. -->
<plugin dataset="generate-page" access="**" module="GeneratePage" add_headers="no">
    <parameter name="template_dir" value="/usr/share/n2c5-prod/template"/>
    <parameter name="dictionary" value="/usr/share/n2c5-prod/etc/dictionary/vodafone/dictionary.txt"/>
    <parameter name="definitions.edr_filter_functions" value="all,call,activity,credit_card"/>
</plugin>

Here we see that the "generate-page" dataset is actually a Jarvis plugin which is performed by the "GeneratePage" module. The module code can be found in:

/usr/share/n2c5-prod/jarvis/plugin/GeneratePage.pm

The "GeneratePage.pm" module will look for templates in the "template_dir", which according to the definition above is configured to be:

/usr/share/n2c5-prod/template

The specific template file to use in this request will be:

/usr/share/n2c5-prod/template/subscriber.tt2

The important point to note is that any error generated by the N2C5 GeneratePage plugin will be written to the apache error log file.

Dynamic Data

Any other Dynamic Data required by the N2C5 web pages is requested by Ajax requests (note that the over-the-wire data encoding is JSON rather than XML). These requests are all passed to Jarvis, which applies a single security interface to all requests.

These requests are all of the form:

/jarvis-agent/n2c5-prod/<dataset-name>/<optional-REST-args>

In some cases, the "<dataset-name>" actually refers to a conventional Jarvis dataset defined in terms of SQL UPDATE/INSERT/UPDATE/DELETE statements. For example, the dataset-name "subscriber.credit_cards" is a conventional SQL dataset defined in the file:

/usr/share/n2c5-prod/jarvis/datasets/subscriber/credit_cards.xml

However, the majority of datasets used by N2C5 are actually "plugin" Jarvis datasets which are implemented as programmed modules. E.g. the dataset "rate-table-info" is defined by the following configuration in n2c5-prod.xml:

<plugin dataset="rate-table-info" access="*" module="RateTableInfo"
    add_headers="yes" mime_type="application/json"/>

This configuration specifies that the "rate-table-info" plugin is implemented by the "RateTableInfo" module, which can be found here:

/usr/share/n2c5-prod/jarvis/plugin/RateTableInfo.pm

Any error generated by N2C5 Dynamic Data datasets and plugins will be written to the apache error log file.