CGI Services Architecture
Recent Pages

Environment Variables
Template Processing
RDF Responses
RDF Messaging
URL Rewriting
File Uploads
Sample Authenticated Se ...
HTTP Cookies
Client Authentication
GET and POST Variables

Links on Twitter
CSA Home
Table of Contents



User ID

Campaigns petition banner

Environment Variables

CSA sets and uses a number of environment variables for its own purposes. All of these variables are available also to the application program, but not all of them may be freely modified by the latter, or things may break. In the explanations below, each variable is optionally followed by a "(profile)" tag, indicating whether that variable is meant to be set by the application profile $CSA_ROOT/csa.rc.

The single-quote character, octal \047.
The horizontal-tab character, octal \009.
The rc list separator, octal \001.
The empty rc value ''.
The newline character, octal \010.
The carriage-return character, octal \013.
The '*' character, sometimes useful for pattern matching with rc(1).
Current CSA UNIX user name. Default: the value returned by whoami(1).
Extra actions to be performed after csaCommit has performed a successful commit. It MUST be a valid rc program fragment, properly escaped to make it eval-safe. It is up to the application program to make sure that special rc characters have been properly escaped in the fragment. The important difference between commands listed in CSA_ONCOMMIT (see further down) and those listed in CSA_AFTERCOMMIT is that the formers are executed inside the commit sub-process, while the latters are run inside the main CSA flow so they can be used to change variable values in a way that is visible to the main program. Default: unset.
The UNIX account that the CSA application MUST run as. If the application finds itself to be running under a different account then it MUST "commit suicide", i.e. stop immediately with an error message. CGI programs are often executed by setuid wrappers and this security measure is meant to avod that, if the wrapper crashes, the application program runs as root, with unpredictable and usually dangerous effects on the integrity and security of the system. Default: nobody (profile).
If CSA_DUMP is set to 1 (see below) this variable is set to the path of a file containing a copy of the command-line arguments received by the CSA CGI front-end. Such file will be called /tmp/csa.args.XXXXXX (see mktemp(1) for the meaning of XXXXXX). Default: dynamically set.
If set to 1, then any changes to files done by the csaCommit function will be subject to rcs(1) versioning. Do not set this variable if change-management is already done with something different/better, like CVS for example. Default: unset (profile).
The domain attribute of the User Session Cookie. Default: unset (profile).
The path attribute of the User Session Cookie. Default: unset (profile).
Authenticated session password. Note that this variable, although loaded in the program environment as usual, will not appear on output pages, not even on those that are meant to show the environment, for obvious security reasons. Default: unset.
The realm for CSA-managed HTTP Basic Authentication (see also CSA_AUTH_TYPE). Default: $CSA_ID (profile).
Set by the csaAuth.send() function to prevent sending authentication data to the client multiple times, which would be harmless but also useless.
The secure attribute of the User Session Cookie. Default: unset (profile).
the type of Web authentication that is in effect. Valid values are:
CSA-managed Basic HTTP authentication
Custom authentication scheme, usually based on an HTTP session cookie or other session-level variable.
Server-managed authentication, normally of the basic or digest type.
Default: basic.
The authenticated user-id. Default: unset.
directory path where local AWK function overrides can be found. Default: unset.
If set to 1, the AWK function cache is rebuilt. Default: unset.
extra rc(1) files to be loaded by CSA batch programs. Default: unset (profile).
This is a general purpose "safety-valve" that can be used to prevent loops inside the CSA code. A CSA library function that may not be called repeatedly will have to list its name in this variable and perform the relevant test any time it is called. Default: unset.
If set to a sintactically valid RFC822 e-mail address, a bug report will be sent to that address in the event of certain CSA internal errors. Default: unset (profile).
Original value of the command-line argument, if any, passed by the CGI interface to the application program for ISINDEX queries.
extra rc(1) files to be loaded by CSA CGI programs. Default: unset (profile).
Where to read the original CGI standard input stream from.
Initial part of the CSA CGI script absolute URL from the point of view of the local Web server, but without any trailing CSA personality identifiers, such as 'I', 'P', etc. Default: /cgi-bin/CSA (global profile).
Path to a file containing CDATA stuff, i.e. data to be included verbatim in a Web response template. Default: unset.
RCS ci(1) command and arguments. Default: ci -q -t/dev/null (profile).
Name and arguments of the local encryption utility. Default: sed 's/./X/g' (profile).
Name and arguments of a local HTTP client, such as curl(1), wget(1), and the like. Default: curl -0 -s (profile).
Name and arguments of the local dot-lock creation utility. By default, CSA uses Alberto Bertogli's Open Lock Daemon, old(1), to manage locks. However, Web applications living on shared hosting services may not be allowed to execute long-running processes, i.e. daemons. If this variable is non empty it will cause the relevant CSA library functions to apply a more traditional (but also more problematic) dot-locking scheme. A typical setting for CSA_CMD_DOTLOCK is
lockfile -r3 -s8. Default: unset (global profile).
Name and arguments of the local message-digest computation utility. Default: md5sum (profile).
Name and arguments of the local command that can be used to list the processes having a given EUID. Default: pgrep -u $CSA_ALLOW_USER. On systems where pgrep(1) is not available, the much slower ps(1) can be used, with suitable options, like ps h -u $CSA_ALLOW_USER (profile).
Name and arguments of the local MTA command.
Default: /usr/lib/sendmail -oi -t (profile).
Contains the list of files to be acted upon by the csaCommit library function. See csaMainlib.rc. Default: dynamically set.
List of variables that are not to be shown in output templates and similar places, for security reasons. Default: dinamically set.
If equal to 1, y, yes or true (all case-insensitive) it tells that a Web action requiring confirmation was confirmed by the client. Unless this variable is assigned the special value noskip by the client, it is automatically set to 1 in case the amount of data sent by the client is greater then 200KB (but still smaller than CSA_RPC_MAXSIZE), to skip the confirmation step and prevent large chunks of data, which may occur for instance with file uploads, from travelling back an forth between the server and the client multiple times. Default: unset.
If set to 1, then the $CSA_ROOT/var/debug.log file will be created, containing the CSA function-call trace and a lot of other useful debugging information. Writing such file is quite expensive in terms of extra system resources, so it should be avoided when not strictly necessary, by setting CSA_DEBUG=0. Default: (profile).
The length of this variable is increased by one every time the csaDebug function is called, and the value of such length is included in STDERR messages produced by said function as a debugging aid. Default: dynamically set.
It is the same as either $CSA_DOCROOT1 or $CSA_DOCROOT2 (see below), depending on the execution context. Default: dinamically set.
Non-SSL document root directory of either the Web Server or the Virtual Host. Default: $DOCUMENT_ROOT (profile).
Same as CSA_DOCROOT1, but for SSL Web connections. Default: $CSA_DOCROOT1 (profile).
If set to 1, then the CSA CGI front-end will write a lot of debugging information into a number of temporary workfilesa. See CSA_DUMP_FILE, CSA_ENV_FILE and CSA_ARGS_FILE for more information. Default: (CSA CGI front-end).
If CSA_DUMP is set to 1 (see above) this variable is set to the path of the file where the CSA CGI front-end program STDERR will be stored. Such file will be called /tmp/csa.stderr.XXXXXX (see mktemp(1) for the meaning of XXXXXX). Default: dynamically set.
Allow CSA Processing Instructions (CPI) in [X]HTML response templates. Default: false (profile).
If CSA_DUMP is set to 1 (see above) this variable is set to the path of a file containing a copy of the initial CSA CGI front-end program environment. Such file will be called /tmp/csa.env.XXXXXX (see mktemp(1) for the meaning of XXXXXX). Default: dynamically set.
Used to pass csaExit.fault and csaExit.ok (as defined by csaCgilib.rc) an application-level script file containing custom code to be run prior to exiting. Default: unset.
RDF block inclusion stub for HTML forms. Default: $CSA_INSTALL/lib/rwadiv.txt (profile).
Fully-Qualified Domain Name of the CSA host. Default: as reported by
hostname --fqdn (profile).
General purpose Globally-Unique ID in TagURI format, for CSA programs that need one. Default: dinamicaly computed.
HTTP response headers are stored in this variable when they are set with csaHttp.header --defer. Default: dynamically set.
Value of the Content-Length: HTTP header. Default: dynamically set.
HTTP status message. Default: dynamically set.
Value of the Location: HTTP header. Default: CSA_URL2 (literal, not var!).
Host-name of the Web Server running the current CSA application instance. Default: the value returned by the hostname command.
CSA application name. It MUST comprise only characters in the set [-_A-Za-z0-9], such as foo, test, example, ABC, some-name, etc. Default: unset (profile).
If CSA_DUMP is set to 1 (see above) this variable is set to the path of a file containing a copy of the CSA CGI front-end program STDIN stream. Such file will be called /tmp/csa.stdin.XXXXXX (see mktemp(1) for the meaning of XXXXXX). Default: dynamically set.
CSA installation directory. Default: /usr/local/csa (profile).
Contents of the QUERY_STRING variable of an ISINDEX HTTP request. Given the current CSA CGI calling conventions, pure ISINDEX queries may no longer occur, as the "?" URL argument is already used to identify the target CSA program (i.e. ?0=class.method&...). Default: unset.
Local language code for messages and Web pages, according to the usual classification ( en, en_US, it, en_UK, es, etc.). The selected language MUST correspond to message and template directories that actually exist on the server. Currently, CSA provides messages only in the it and en_US versions. Default: $CSA_LANG_DEFAULT.
Default language code. Default: en_US (profile).
List of CSA rc(1) library functions already loaded by csaLoadLib at any given time. By testing the content of this variable, other CSA scripts and functions will be able to assess whether what they need is already available or whether they need to call csaLoadLib to get it. This is meant to save the subshell associated with using the `{whatis ...} construct of rc(1). Default: dynamically set.
Must be set to a string which needs to be shared by all hosts that need to access the same data over some kind of network share, like NFS etc. Default: csa@localhost (profile).
If set to 1 all locking operations are reported verbosely to STDERR. This can be especially useful to detect lock timeouts due to deadlock conditions. Default: unset (profile).
List of lock-files (semaphores) created so far by the CSA program through the csaLock function. Default: unset.
Where to store CSA log files. Default $CSA_ROOT/var/ (profile).
The logfile verbosity. Can be INFO, WARN or ERR, and each value can be abbreviated to its first letter (i.e. I, W, E, case-insensitive). Default WARN (profile).
Max. no. of active processes allowed on the system. If this limit is exceeded then no new requests will be denied with an error message. This check is normally not active. Default: unlimited (profile).
Current message group name. Default: CSA_SYSTEM.
Current message number. Default: 0000.
Default positive completion message, with arguments. Default: 0028.
Current message text. Default: unset.
Contains the list of files that are not to be versioned even if CSA_AUDIT is set. See csaMainlib.rc. Default: dynamically set.
rc(1) list of session-management related values. Default: dynamically set.
Extra actions to be performed by csaCommit. It MUST be a valid rc program fragment, properly escaped to make it eval-safe. It is up to the application program to make sure that special rc characters have been properly escaped in the fragment. Default: unset.
List of program names that have been assigned throughout a CSA run. When the CSA CGI front-end is called as CSAI the underlying libraries will know that CSA is running in interactive mode, that is presumably by a human client. This can be used by well-written application programs to decide whether action confirmations need to be used or not. Otherwise, if confirmations are always requested, they are likely to get "in the way" of automatic interactions by a programmatic client. Default: dynamically set.
NFS-safe unique identificator of the current CSA program. Default: $CSA_HOST.$pid.
The URL, either absolute or relative, to redirect the client to when performing POST-Redirect-GET schemas. Default: /prg;$CSA_GUID (profile).
A pseudo-random integer value. It is currently only available when CSA is running as a CGI program, otherwise this value is unset. Default: dynamically set.
Remote Procedure Call arguments, in RDF format. Default: $TMPDIR/arg$pid.tmp.
Used internally by CSA. Default: $CSA_RDF_ARG.
Remote Procedure Call response body, in RDF format. Default: dinamically set.
If this is set to 1, then the call arguments and the method-specific IDL documentation (if any) are included in the HTTP response body. Default: unset (profile).
Machine-readable Web ( Semantic Web) response body, in RDF format. Default: dinamically set.
Opaque Response Block, used to produce XML responses which do not fall within the definition of the Semantic Web, such as XML-RPC, SOAP, RSS 2.0, etc. It is the responsibility of CSA applications to write the desired data to this file. Default: /dev/null.
If set to (zero), then CSA will ignore RDF datatype directives received in the CGI request message and it will consider everything to be a string, consistently with the basic behaviour of the CGI API. The defaultt is to use data-types, as they provide for more power in the communicattion between the client and the server, and are especially useful when one piece of data can take several formats, for example when it can be either a string or aa base64-encoded binary object. Without data-typing the CSA has no easy way to understand how to consider that particular value. Default: 1 (profile).
Concatenation of $PATH_INFO?$QUERY_STRING in HTTP requests, useful for debugging purposes. If either values are unavailable then the corresponding token is set to the word UNKNOWN. So, for instance, if neither values are known, CSA_REQUEST_URI will be set to /UNKNOWN?UNKNOWN. Default: dinamically set.
The character-set possibly specified in the XML prologue by an XML-RPC or SOAP client. Default: $CSA_CHARSET.
Used by many CSA library functions to return the function result to the caller, mainly useful to save a `{} subprocess. Default: unset.
Current request-ID. Default: $CSA_HOST^_$pid.
CSA application installation directory. Default: / (profile).
Path to a temporary file containing the RPC dynamic AWK filter. Default: $TMPDIR/awk$pid.tmp.
Path to a temporary file containing the RPC request. Default: $TMPDIR/rpc$pid.tmp.
This is set to either I, S, R, 2, P or null, depending on whether CSA is invoked by the client as either CSAI, CSAS, CSAR, CSA2, CSAP or CSA respectively. Default: internally set.
Preferred response format requested by the client. Currently only RDF and RSS (both case insensitive) are supported. Default: unset.
if this variable is present in an RPC request, and if it is set to a syntactically acceptable value, then it is passed to the CSA CGI program unchanged. Default: unset.
if this is set to main by the client then the session data will be updated with new values at the end of the current run, otherwise it will be left alone. Default: main.
Data returned to a CSA client by a remote web service, in AWK format. Default: dynamically set.
Useful for pointing at fragment identifiers inside response page templates. For instance <a href='$[CSA_RPCHREF]#1'>Some Link</a>. Default: $CSA_RPC_URL$PATH_INFO.
Path to the IDL (Interface Definition Language) file associated with the requested method, if any, in RDF format. Default: $CSA_ROOT/doc/ methodname.rdf.
Path to the RPC I/O library associated with the requested method, if any. Default: $CSA_INSTALL/lib/csa-rpciolib.awk.
Max. size in bytes of POST/PUT data. Default: 100 Kbytes (global profile).
Max. size of actual argument names+values in a POST request. Default: 10 Kbytes (global profile).
Path to a temporary file containing the entity body of a PUT request. Default: $TMPDIR/put$pid.tmp.
Value to be returned to the client, in RDF format, as the result of an RPC request (used internally by CSA). Default: unset.
List of temporary workfiles used by CSA to store files uploaded by the client. The list is used mostly to pass the _UPLOAD AWK array between csaCgi.awk and the application-layer AWK scripts (see CSA_RPC_IOLIB). Default: dynamically set.
This is the same as either $CSA_RPC_URI1 or $CSA_RPC_URI2 (see below), depending on the execution context. Default: dinamically set.
Non-SSL absolute URL of the current CSA front-end. Default: $CSA_URL1$CSA_CGI_STEM$CSA_ID (profile).
Same as CSA_RPC_URI1, but for SSL Web connections. Default: $CSA_URL2$CSA_CGI_STEM$CSA_ID. (profile).
This is the same as either $CSA_RPC_URL1 or $CSA_RPC_URL2 (see below), depending on the execution context. This variable is now deprecated in favour of $CSA_RPC_URI. Default: dinamically set.
Non-SSL absolute URL of the current CSA front-end. This variable is now deprecated in favour of $CSA_RPC_URI1.Default: $CSA_URL1$CSA_CGI_STEM (profile).
Same as CSA_RPC_URL1, but for SSL Web connections. This variable is now deprecated in favour of $CSA_RPC_URI2. Default: $CSA_URL2$CSA_CGI_STEM (profile).
Path to a temporary file containing the CSA program call (GET/POST) variables, in rc syntax. Default: dynamically set.
Fault code for XML-RPC responses. Default: -32400 for XML-RPC and Server for SOAP.
Positive completion code for XML-RPC and SOAP responses. Default: <boolean>true</boolean> for both XML-RPC and SOAP.
This RPC variable, if present, is expected to contain the XML request body of CSA RwA (RDF with Attachments) payload. Default: unset.
Generic HTTP session variable that a CSA application can use to store pieces of data that are need to logically link different client requests together. Like with any mechanisms that require cooperation on the part of the client, CSA_SESSION is not guaranteed to work so the application should not rely on its existence/validity and the application itself should always apply a sensible default behaviour if CSA_SESSION is unusable. The content of CSA_SESSION is made available to the application program regardless of whether the latter calls the csaGetArgs function or not. Individual information tokens are stored in CSA_SESSION in the usual rc(1) list format and they may not contain the ``pipe'' symbol, i.e. a vertical bar ' |'. Default: unset.
Used internally by CSA to handle CSA_SESSION. See the latter for more info. Default: unset.
Tells whether the application requires SSL. In the normal case a CSA web service can be invoked by clients either over HTTP or HTTPS, with only selected security-sensitive functions optionally requiring SSL (i.e. sending login credentials, etc.). By setting CSA_SSL_MODE=strict the application can refuse to serve any data if it detects that a non-SSL communication channel is being used between the server and the client. Default: relaxed (profile).
Generic CSA error flag, used by some of the library functions. Default: .
Where to send the standard error stream. Default: /dev/stderr (profile).
Where to send the standard output stream. Default: /dev/stdout (profile).
Where the csaSystem function stores the called program STDOUT. Default: dinamically set.
Where the csaSystem function stores the called program STDERR. Default: dinamically set.
syslog facility name where to log to, instead of using a local file. Default: unset (profile).
Generic flag used to tell programs that we are running in test mode. Whether to test this flag is up to the application programs. Default: (profile).
AWK pattern specifying allowed tag names in templates. The filter does not apply to file tags. If any template tags match that pattern, their values will be forced to the literal string <!-- removed --> on output. Default: ^CSA_ (profile).
AWK pattern specyfing environment variables which values MUST NOT appare on output templates. If any environment variables match that pattern, their values will be forced to the literal string <!-- removed --> on output. Default: (^(fn_|HTTP_COOKIE|CSA_AUTH_PW|csa0)|(CRYPTKEY|SALT)$) (profile).
List of names to be eval'ed by the csaTemplate() library function. Default: unset.
File-name extension of template files. Default: html (profile).
Max. recursion depth for includes. Default: 10 (profile).
Templates may either contain an embedded RDF block or they can include it from an external file. The RDF file is expected to have the same full-path name as the associated template file, with .rdf appended to it.
Directory where csaTemplate will look for templates. Default: CSA_ROOT/lib (profile).
list of filesystem paths that can be considered safe with respect to template tags of the form $[/path/to/file]. If such inclusion tags reference paths not listed in CSA_TPL_SAFEPATH the inclusion is not performed. For backward compatibility, by default CSA_TPL_SAFEPATH is empty and any path can be used. Default: unset (profile)
Path to a temporary workfile to be used by application-level procedures invoked with $[program|] template tags. Default: dynamically set.
Write-back buffer for template post-procesing (used internally by CSA). Default: unset.
Context-dependent base URL of the current CSA server. It is the same as either $CSA_URL1 or $CSA_URL2 (see below), depending on the execution context. Default: dinamically set.
Non-SSL base URL of the current CSA server. Default: http://localhost (profile).
Same as CSA_URL1, but for SSL Web connections. Default: $CSA_URL1 (profile).
Web User ID, for authenticated sessions. Default: unset.
Current CSA version. Default: fixed.
Write-back message. This is a variable through which a sub-program, i.e. a called process, can request the parent rc program to print a CSA message through csaPrintMsg. This capability requires that the caller capture the called program output into a temporary file, which is then sourced with the " ." shell operator. After sourcing the generated script file, the caller will then test the content of said variable and take the proper actions. Building a source-safe script is the responsibility of the called program. Default: unset.
List of the work-files created by the CSA application during the current run. Such files will be removed on exit by the csaExit function. Default: unset.
Creative Commons (CC) Namespace URI. Default:
CSA Namespace URI. Default:
Dublin Core (DC) Namespace URI. Default:
RDF Namespace URI. Default:
RDF Schema Description URI. Default:
XML Schema Description. Default:
if set to true it will trigger a degree of compatibility with XHTML in the output produced by certain CSA functions an programs, for instance by closing void tags with > and things like that. Default: false (profile).
Starting with version 1.1.0 some core parts of CSA, including the locking-primitives, were moved to a separate package named Shell-Ware Utilities (SWU, hence the name of this variable). SWU, in turn, relies on the Open Lock Daemon (OLD) for locking. As with any other cooperative locking mechanism, OLD allows anyone to release enyone else's locks, if they know what strings where used to acquire them. Since OLD sits on a TCP/IP network socket, this may be a security exposure. To make things more secure, SWU allows an application program to set a password-like string, that will be used to acquire the locks. For instance, if the CSA library function is requested to lock /path/to/some/file, and supposing the SWU_LOCK_SALT is set to the string xyz123 in the CSA application profile, the actual resource that will be locked is xyz123:/path/to/some/file. If we keep the content of SWU_LOCK_SALT secret, the name of the lock will be hard to guess, and therefore more difficult to break on the part of unauthorized third parties. Default: SWU (profile).

Date and time values.

The CSA variables CSA_TIME_LOCAL and CSA_TIME_UTC are used to hold local and UTC time values respectively. Here is how their values are set:

  CSA_TIME_LOCAL =`{date '+%Y %m %d %H %M %S %Z %a %b %s %z %:z .%3N'}
  CSA_TIME_UTC =`{date -u '+%Y %m %d %H %M %S %Z %a %b %s %z %:z .%3N'}

Application programs, as well as other parts of CSA, can use selected elements from CSA_TIME_LOCAL and CSA_TIME_UTC to build their own custom date and time values.

Using elements from the above two lists, CSA sets also the following time-related scalar values (shown with example values):

   CSA_TIME_HTTP = Tue, 18 Jan 2005 10:50:31 GMT
   CSA_TIME_ISO = 2005-01-18 10:50:31
   CSA_TIME_ISO8601 = 2005-01-18T10:50:31+01:00

Such variables are used internally by CSA itself, but they are also available for use by application programs.

Trackbacks (0) | New trackback | Print

This Web Site is Copyright © 2007,2008,2009,2010 Carlo Strozzi, Some Rights Reserved
site map | recent changes | disclaimer