Mathematica 9 is now available
9.3 Site Configuration

Documentation9. Appendix

 

9.3 Site Configuration

This section summarizes how to configure a webMathematica site. Most configuration information is held in the file MSP.conf. The contents of this file are used to initialize the system and individual Mathematica kernels; this is described in the Mathematica Initialization section.

webMathematica can support multiple kernel pools. A kernel pool is a group of Mathematica kernels that can be specially configured and is documented in the Advanced Topics: Multiple Kernel Pools section. If you do not configure any extra pools, then only one pool—known as the General Pool—is used.

9.3.1 MSP.conf

MSP.conf is the main configuration file. In addition, any extra kernel pool can have its own configuration file. Configuration for a pool Tests is in the file Tests.conf. The pool configuration file can override settings in MSP.conf. If you do not set a parameter in a pool configuration file, its value is inherited from MSP.conf. A few parameters modify the operation of the entire site and only have any meaning in MSP.conf, and any setting in a pool configuration file will be ignored.

Let us consider each of the parameters in greater detail.

CheckToExpression

This parameter controls whether the Mathematica command ToExpression should carry out a security check if the first argument is a string that was sent with the webMathematica request. By default the test is carried out, but a setting of false disables the check.

CheckToExpression=false

Typical sites should not modify this feature. This topic is discussed in greater detail in the Security section.

This parameter modifies the site and can only be set in MSP.conf.

CollectStreams

This parameter controls whether input and output streams that were opened in the Mathematica kernel are automatically closed. By default, they are closed. Setting CollectStreams to false prevents streams from being closed.

CollectStreams=false

Typical sites will not want to modify this feature. This topic is discussed in greater detail in the Security section.

This parameter can appear in MSP.conf and in a pool-specific configuration file.

FrontEndGraphics

This parameter controls whether graphics should be rendered by the front end or by the kernel only. When set to true, the front end is used; when set to false, the kernel only will be used. By default it is set to true. The setting is used to initialize the Mathematica variable MSP`Utility`FrontEndGraphics. Note that the front end is always used for mathematical typesetting regardless of the setting of FrontEndGraphics.

FrontEndGraphics=true

The front end generates higher-quality images and it is strongly recommended not to modify this parameter. It is only provided in case of problems in running the front end.

This parameter can appear in MSP.conf and in a pool-specific configuration file.

FrontEndLaunchCommand

To make images or to use notebook API functions, webMathematica uses the Mathematica front end. To launch the front end, you may need to set special configuration parameters with FrontEndLaunchCommand. Alternatively, you may choose to use a different command for launching the front end.

For example, to tell the front end to connect to a different X server for display, you could do the following.

FrontEndLaunchCommand=mathematica -mathlink -display :1 -nogui -geometry 1000x500+10+10

This instructs the front end to use DISPLAY 1 with fixed geometry and in a server mode.

This parameter can appear in MSP.conf and in a pool-specific configuration file.

ImageAltText

This parameter sets the value of the alt attribute of generated img tags. By default, the value is "Created by webMathematica".

ImageAltText="This image was created by my server."

This parameter can appear in MSP.conf and in a pool-specific configuration file.

JLinkNativeLibraryDirectory

Certain servlet containers will not load the J/Link native library from inside the web application layout. For these it is possible to place the native library in a central location and specify this location in MSP.conf. An example is shown below.

JLinkNativeLibraryDirectory=/usr/local/jlink

Note that the directory specified by this parameter should be the directory that contains the SystemFiles directory that is typically found in webMathematica/WEB-INF/lib. For Linux the layout should look something like the following.

jlink
SystemFiles
      Libraries
         Linux
            libJLinkNativeLibrary.so

This parameter modifies the site and can only be set in MSP.conf.

KernelAcquireLimit

This parameter specifies the number of times that each kernel can be taken from the kernel pool before being shut down. Generally it is a good idea to shut down each kernel at a regular, but not necessarily frequent, interval. In this example each kernel is restarted after 500 hits.

KernelAcquireLimit=500

This parameter can appear in MSP.conf and in a pool-specific configuration file.

KernelConnectLimit

This parameter specifies the time that webMathematica waits while trying to launch a kernel. If a kernel cannot be launched in this time, an error is reported. In this example, each kernel is restarted after 100 seconds.

KernelConnectLimit=100000

This parameter can appear in MSP.conf and in a pool-specific configuration file.

KernelInitialization

This optional parameter gives extra evaluations for the Mathematica kernel that are processed at the end of kernel initialization. These could be used to load special packages or to set details of the MSP functions. In this example, the command Needs["MyApplication`"] evaluates every time a kernel is launched.

KernelInitialization=Needs[ "MyApplication`"]

If you set definitions for symbols that are in the default context with KernelInitialization, they are cleared and the symbols are removed by the postprocessing code for each request. This also applies to packages that are loaded by KernelInitialization that are not written in the Mathematica package format to make proper use of contexts. Any definitions that are made must use their own context for saving names. You can do this by prepending the name with a context (for example TestNameSpace`Compute) or by making appropriate use of BeginPackage[] and EndPackage[].

Another point about the use of the KernelInitialization parameter is that certain packages may require the front end in order to be initialized correctly. You can load these packages into webMathematica with UseFrontEnd; this is shown below.

KernelInitialization=UseFrontEnd[Needs[ "MyApplication`"]]

This parameter can appear in MSP.conf and in a pool-specific configuration file.

KernelNumber

The KernelNumber parameter gives the number of kernels that are launched when the system starts. You must make sure that you have sufficient licenses for this number of kernels. When there are insufficient licenses, some kernels will fail to launch. This will be noted in the log file.

KernelNumber=2

This parameter can appear in MSP.conf and in a pool-specific configuration file.

KernelPools

This parameter is used to specify the names of additional pools of Mathematica kernels, as documented in the Multiple Kernel Pools section. This example specifies two kernel pools, Examples and Test.

KernelPools=Examples, Test

This parameter modifies the site and can only be set in MSP.conf.

KernelTimeLimit

This parameter gives the maximum number of milliseconds for processing a page. When this time is exceeded, the kernel is shut down and restarted. In this example, the kernel is restarted if processing a single page takes more than 60 seconds. The log system is notified when a kernel is shut down.

KernelTimeLimit=60000

This parameter can appear in MSP.conf and in a pool-specific configuration file.

MathLinkArguments

This is used as the argument to the J/Link method createKernelLink. If it is not set, a default appropriate for the platform on which Mathematica is running will be used. Here is a typical setting.

MathLinkArguments=-linkname 'math -mathlink' -linkmode launch

MathLinkArguments gives the command for launching Mathematica. If any special command-line arguments need to be given, they can be set here. For example, if you wish to launch Mathematica with a special password file, use a -pwfile command-line option. Additionally, it may be necessary to give a full path to the executable that launches Mathematica.

This parameter can appear in MSP.conf and in a pool-specific configuration file.

MSPDirectory

This parameter is only useful for MSP scripts, an older style of working with webMathematica, described in the chapter Classic webMathematica Technology. It describes the location of MSP scripts, and if it is not set then a default will be used. This directory is put on the Mathematica $Path, so it can contain packages and other applications that MSP scripts might load.

MSPDirectory=/usr/local/mathematica/AddOns/Applications/MSP/MSPScripts

This parameter can appear in MSP.conf and in a pool-specific configuration file.

This setting is not meaningful for the JSP implementation of webMathematica since JSPs are located inside the web application.

PackagesDirectory

This optional parameter specifies a directory that is added to the Mathematica variable $Path. More information on loading and installing packages is available in the section Packages and Applications.

PackagesDirectory=/usr/local/files/Code

This parameter can appear in MSP.conf and in a pool-specific configuration file.

PoolPath

This parameter is used to map JSP scripts to kernel pools, as documented in the Multiple Kernel Pools section. This example specifies that JSPs in the ExampleDir directory will use the pool Examples and those in the TestDir directory will use the pool Test.

PoolPath.Examples=ExampleDir
PoolPath.Test=TestDir

This parameter modifies the site and can only be set in MSP.conf.

RequestLog

This optional parameter can be used to suppress the output that webMathematica makes to the log system. By default, a line of output is generated for each request. This is suppressed when RequestLog is set to false.

RequestLog=false

This parameter modifies the site and can only be set in MSP.conf.

SecurityConfigurationFile

This parameter allows you to modify the security model by making your own definitions for MSP`Utility`AllowedContexts, MSP`Utility`DisallowedContexts, MSP`Utility`AllowedSymbols, and MSP`Utility`DisallowedSymbols. These definitions should be placed into a file in the /WEB-INF/conf directory and the name of the file set by the configuration parameter SecurityConfigurationFile. For example, if the configuration information is in a file called SecurityConfiguration.m, the following should be added.

SecurityConfigurationFile=SecurityConfiguration.m

More information on security is found in a previous section.

This parameter can appear in MSP.conf and in a pool-specific configuration file.

StaticFileExtensions

This parameter gives the file extensions and content type for static files that the server may return. It is used so that MSP scripts can refer to image (and other files) with relative URLs. Further discussion is available in the Including Static Files section. A typical setting is as follows.

StaticFileExtensions=gif:image/gif, jpg:image/jpeg, jpeg:image/jpeg

This parameter modifies the site and can only be set in MSP.conf.

This setting is not meaningful for the JSP implementation of webMathematica since the static content is processed by the servlet container.

VerboseLogs

The VerboseLogs parameter controls the level of logging that is recorded by the system. A setting of false saves only serious errors and one item for each request to the site. A setting of true records more information.

VerboseLogs=true

This parameter modifies the site and can only be set in MSP.conf.

WebApplicationName

When certain servlet containers load web applications they rename directories. This can cause problems for webMathematica since it needs to know the name of the web application for generating URLs. If the name is incorrect these URLs will be incorrect and problems, such as graphics not working, will result. This can be solved by setting the name of the web application in MSP.conf, as shown below.

WebApplicationName=webMathematica

This parameter modifies the site and can only be set in MSP.conf.

9.3.2 Security Configuration

The security system for webMathematica can be customized. This is described in the Security section.

9.3.3 X Server Configuration

Special configuration is often required to allow the front end to connect an X server. This is described in the Installation section under Configuring for the X Window System (Unix Only). This is only an issue for running webMathematica under Unix.



Any questions about topics on this page? Click here to get an individual response.Buy NowMore Information
THIS IS DOCUMENTATION FOR AN OBSOLETE PRODUCT. CURRENT WEBMATHEMATICA DOCUMENTATION IS NOW AVAILABLE.