Sysquake Remote Installation

To install Sysquake Remote, follow these steps:

Install Apache with mod_so enabled

Follow the documentation of Apache. You can check that mod_so (the support for modules included dynamically at run-time) is enabled by typing

httpd -l

Among others, the module "mod_so.c" should be displayed.

If Apache 1.3 is not installed yet, you can try the following if you do not want to read its documentation:

• Download the latest Apache 1.3.x source code tar.gz to a suitable place, such as your home directory. You can find Apache at www.apache.org. Note that currently, Sysquake Remote is not compatible with Apache 2. You also need developer tools, such as a C compiler and a "make" utility, which you can find with your Unix distribution or at www.gnu.org.
• gzip -d apache*.tar.gz
• tar xf apache*.tar
• cd apache*
• su
• ./configure --enable-module=so --enable-shared=max --prefix=/usr/local/apache
• make
• make install
• /usr/local/apache/bin/apachectl start

If an error message says that some symbols cannot be resolved, try adding --enable-rule=SHARED_CHAIN --enable-rule=SHARED_CORE to configure.

On Mac OS X, Apache should already be installed; you can start it by activating Personal Web Sharing in the System Preferences. When you make changes to Apache's configuration file (normally /private/etc/httpd/httpd.conf), you can restart Apache by stopping and starting again Personal Web Sharing in System Preferences, or by typing sudo apachectl restart in a Terminal window.

Install mod_sqr

Copy mod_sqr.so to the directory of Apache modules, typically /usr/local/apache/libexec.

If you do not know where Apache is installed, type which httpdctl, which should display the location of Apache binaries (executable files), such as /usr/local/apache/bin/apachectl. The path to the directory of Apache module is given by replacing bin/apachectl with libexec.

Install Sysquake Remote libraries

Copy the lib directory and its contents to a suitable location, such as /usr/local/LME/lib, which must be matched by the SQRLibraryPath directive (see below).

Configure Sysquake Remote

With appropriate permissions (you should probably be root: type su root), edit httpd.conf (typically in a conf directory at the same level as libexec) and add the following lines:

• To load the module:

LoadModule sqr_module libexec/mod_sqr.so

• To enable the module:

AddModule mod_sqr.c

• To map files whose suffix is .sqr to make them processed by the Sysquake Remote module:

<IfModule mod_sqr.c>
AddType application/x-sysquake-remote .sqr
</IfModule>

• To add the registration key which enables Sysquake Remote (copy the whole line of the registration key exactly as you received it):

SQRRegistration webserver-hostname registration-key

or

SQRRegistration webserver-hostname registration-key name

If you have not received the registration key, you can skip this step now. Each .sqr page is displayed with a message which says that Sysquake Remote is not registered and the host name of the server. Please specify this host name, exactly as it is displayed, when you order your registration key.

• Add other configuration directives (see below). Options are secure by default, so this step is not absolutely required. Note however that to have access to LME libraries, you must add a SQRLibraryPath directive, such as

SQRLibraryPath /usr/local/LME/lib

Restart Apache

Type

apachectl restart

(if apachectl is not in your path, type its complete path, such as /usr/local/apache/bin/apachectl restart)

Configuration

This section describes the configuration directives which can be added to the files httpd.conf (main configuration file, usually in /usr/local/apache/conf for Solaris and Linux, and /private/etc/httpd for Mac OS X) and .htaccess (in directories).

Here is a possibility for such options. Note that only the SQRRegistration line is required, and that default options are secure by default; you should read carefully the documentation below before changing the options on a server on the Internet or in an insecure environment.

SQRRegistration www.company.com 6e8a.281f.a924.200306.a
SQRStartup useifexists stdlib, sqr;
SQRLibraryPath /usr/local/LME/lib
SQRLocalLibraries on
SQROutputLimit 10000
SQRTimeout 1000
SQREnableStderr on
SQREnableAns on

SQRCleanImagesCmd

Syntax: SQRCleanImagesCmd command

Context: server config

Override: n/a

This directive changes the command run periodically to clear the image files. The default value is a command which keeps at least the last 30 images:

cd /tmp/mod_sqr_im/; rm -f `ls -t|tail +30` >&/dev/null

SQRDefaultFigureSize

Syntax: SQRDefaultFigureSize width height

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive changes the default figure size. The default default is 300 pixels wide by 200 pixels high.

SQRDisableFunction

Syntax: SQRDisableFunction list of commands to be disabled

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive disables all the functions which are listed. Several such directives can be used. This may be useful for security reasons, for instance to disable direct access to the shell with the unix command.

SQREnable

Syntax: SQREnable none|fileio|shell|fileio shell

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive enables potentially unsecure functions. The default value is none. Functions which can be enabled are:

File access restrictions are specified with one of the following characters:

For instance, the following directive enables read access with fopen(filename,'r') to any file in the root directory of Apache or one of its descendants, and no write access at all with fopen(filename,'w'):

SQREnable fileio=sx

SQREnableAns

Syntax: SQREnableAns off|on

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive enables the assignment of expression results to variable ans. The default is off.

SQREnableHelp

Syntax: SQREnableHelp off|on

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive enables help function. The default is off.

SQREnableStderr

Syntax: SQREnableStderr off|on

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive enables the sending of standard error output to the client. Standard error contains error messages, which may reveal the functionning of LME code. The default is on.

SQRFigureFont

Syntax: SQRFigureFont monospace|sans-serif|serif

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive selects the default font used in figures. The default is sans-serif.

SQRImageFileType

Syntax: SQRImageFileType GIF|PNG|JPEG|JPG

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive selects the default file type used for images. The default is GIF (uncompressed for patent reasons); it is supported natively by virtually all graphical browsers, back to the beginnings of the Web. It supports only 216 different colors (each component of red, green, and blue can take 6 different values). PNG supports 24-bit colors and is supported by most recent browsers; it compresses images without loss of quality. JPEG and JPG (synonymous) are lossy, i.e. compression ratio is large (typically 5-20), but the decompressed image has a lower quality than the original one. This is especially visible with images with lines and text, which makes it less suitable for all Sysquake Remote graphical commands but image. JPEG images do not support transparency. The trade-off between the quality and the compression ratio is fixed with directive SQRImageQuality.

SQRImagePath

Syntax: SQRImagePath path

Context: server config

Override: n/a

This directive sets the path where image files are stored on the server. The default is /tmp/mod_sqr_im. If the bottom-most directory does not exist, it is created (if the user Apache runs under has enough privileges; otherwise, you should create it by hand with mkdir /tmp/mod_sqr_im and change its ownership to Apache's user).

SQRImageQuality

Syntax: SQRImageQuality quality

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive sets the quality factor used for JPEG output, a number between 0 (worst quality, large compression ratio) and 100 (best quality, smallest compression ratio). Even with a quality of 100, the JPEG image has some artifacts which are visible in images with sharp contrast (lines and text).

SQRInputLimit

Syntax: SQRInputLimit n

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive sets the maximum amount of data accepted from the client with the POST method, in kibibytes (1 kibibyte is 1024 bytes). The default is 32.

SQRLibraryPath

Syntax: SQRLibraryPath paths

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive sets the path where library files are stored on the server. Several directories may be separated by colons or semicolons. The default is none.

SQRLoadExtension

Syntax: SQRLoadExtension path

Context: server config

Override: Options

This directive loads an extension which adds new functions to LME. Extensions are compatible with Sysquake's on the same platform, but must be loaded explicitly for security reasons. The default is none.

SQRLocalLibraries

Syntax: SQRLocalLibraries on|off

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive enables the search of libraries in the same directory as the file being processed. The default is off.

SQRMemory

Syntax: SQRMemory n

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive specifies how much memory must be allocated to LME, in kibibytes. The default is 8192 (8 mebibytes).

SQROutputLimit

Syntax: SQROutputLimit none|n

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive specifies the maximum amount of data sent back to the client as the contents of the request, in kibibytes (1 kibibyte is 1024 bytes). The default is 128.

SQRRandomSeed

Syntax: SQRRandomSeed on|off

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive specifies whether the seeds for the random generators rand and randn are set to a random initial value (based on the system clock). The default is on.

SQRegistration

Syntax: SQRegistration hostname key [username]

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive specifies the registration information for Sysquake Remote. It must match the host name of the server. If no such directive is found, Sysquake Remote displays a message at the top of each page which states that Sysquake Remote is not registered and it cannot be used for a long period, and which host name it has.

SQRStartup

Syntax: SQRStartup commands

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive specifies the commands which are executed before each page. The default is none. You can import default libraries such as stdlib and sqr:

SQRStartup useifexists stdlib, stat;

Note that useifexists fails silently, without an error, if libraries are not found. You may prefer use.

SQRSubdirEnforcement

Syntax: SQRSubdirEnforcement on|off

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive specifies whether limits set by SQREnable, SQROutputLimit and SQRTimeout are enforced in subdirectories. If it is on, only stricter limits can be specified by subdirectories. The default is on.

SQRTimeout

Syntax: SQRTimeout none|n

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive specifies a time limit (in milliseconds) for the execution of each page. The default is 5000 (5 s).

SQRTransparentBackground

Syntax: SQRTransparentBackground on|off

Context: server config, virtual host, directory, .htaccess

Override: Options

This directive enables a transparent background for figures. Only the part outside the frame is transparent. The default is on.