Thalassa CMS logo

Thalassa CMS

Thalassa CGI configuration basics


Configuration file

There's one thing you should keep in mind configuring the CGI program. The web server runs CGIs in directories where they are, so whenever the CGI receives control, its current working directory is the directory where the binary resides. This fact is actively used from the very start: the program expects to find its configuration file (thalcgi.ini) in its current working directory, which effectively means it must be placed in the same directory with the thalcgi.cgi binary itself.

As usual, the file is in the ini format.

In the present version, the configuration file name is hardcoded. If you really need it to either have another name or be located elsewhere, then either edit the file thalcgi.cpp (see the THALASSA_CGI_CONFIG_PATH macro near the start of the file) and rebuild, or simply build with -DTHALASSA_CGI_CONFIG_PATH="your/path/file.ini".

WARNING: the configuration file must be kept private as it contains a secret for checking the captcha. Okay, the most serious harm you can get by leaking your thalcgi.ini is that someone circumvents your captcha, well, unless you place something more sensitive in your configuration file on your own, but you don't, do you? Anyway, please don't underestimate the possible consequences. Unfortunately enough, the file has to be placed inside your web space, so certain care must be taken in order not to expose it to arbitrary people through your web server. It is strongly recommended to use suexec so that your CGIs are executed under UID/GID other than your web server's, and keep the configuration file readable to its owner only (e.g., mode 0600).

The CGI program even performs a check at every start. In case the current UID differs from the UID of the configuration file's owner, it assumes there's no suexec (perhaps we're running under the UID of the HTTP server) and aborts the check letting the things go. It doesn't mean everything's fine, but hardly the simple program can do anything about it. If, however, the UIDs are equal, the program checks if there are any permissions for the configuration file for others, and refuses to continue if so. A built-in error page is sent to the client. In case you see it, do something like chmod o-rwx thalcgi.ini to fix the problem. If you place your thalcgi.ini into your web space with the help of the thalassa program (e.g., as a binary object), which is recommended, be sure to place “chmod = 600” into the binary configuration section.

CGI-specific macros

Just like the thalassa program, the CGI program actively uses macros in its configuration file. Besides the common macros, there are some CGI-specific macros, only available in the thalcgi.ini file, and, certainly, in some contexts there are context-specific macros as well.

Some of these are directly related to particular features such as pages, sessions, comments and so on; such macros will be documented along with the respective features. However, some of the CGI-specific macros don't fall into any of the feature-specific categories. To keep the picture consistent, we'll document them right here.

The %[req: ] macro provides access to certain properties of the HTTP request being handled. As usual, its first parameter must be the name of a function; the following functions are supported:

The %[getenv: ] macro gives access to the environment variables; actually it is just a wrapper for a well-known getenv function from the standart C library. It accepts exactly one argument, the name of the variable, and returns the respective value, or an empty string in case the variable is empty or unset; there's no way to tell these apart. As the CGI protocol makes heavy use of the environment, this macro becomes an important tool, specially in case some information you need for some reason is not available through the %[req:] macro.

Configuring global parameters

The global parameters are set within the [general] section. As of the present, three parameters are expected: userdata_dir, post_content_limit and post_param_limit.

The userdata_dir sets the path to the database directory, where sessions, user accounts and other dynamic information is stored. The path must be either absolute (not recommended), or relative to the CGI's working directory (which is, let's repeat it, the directory where the CGI binary is placed).

It's better to place the database directory outside of your web tree, so the path will start with one or more “../”. Make sure the directory is available for “write” and “execute” for the CGI program (that is, for the UID/GID under which the CGI runs). The directory itself must exist, which means you must make it, the program won't do this for you; however, it will create all necessary subdirectories and all work files inside.

The other two parameters, post_content_limit and post_param_limit, are intended to limit the size of what the client can send within a POST request; both parameters set the default value which can be overriden on a per-page basis (with parameters with the same name within the [page ] configuration section), and both are given as integers, in kilobytes (damn, a kilobyte is 1024 bytes, don't trust anyone who tries to convince you otherwise). The post_content_limit is the maximum size of the POST request body, which means that in case the value of the CONTENT_LENGTH environment variable is greater than this value times 1024, the CGI refuses to work and displays the respective error page.

The funny thing about the post_param_limit is that it is completely ignored by the current Thalassa CGI version, because the present version doesn't handle the multipart/form-data POST body format (which is used for forms that upload files).

HTML snippets and templates

Just like the thalassa program configuration, the thalcgi.ini can (and perhaps should) contain the [html] section, in which HTML snippets and simple templates are defined. The snippets and templates can be accessed by %[html:snippet_name] macro calls.

Both the ini file section and the macro work exactly the same way as in the thalassa program; please refer to the [html] section description for details and examples.

The error page

In case something goes wrong, the CGI program has to display an error page. For the case there are problems with the configuration file, e.g., it doesn't exist, unreadable or is in wrong format, the program uses a built-in template for the error page. The same is true for the case you didn't specify your custom template for the error page, but it is strongly not recommended to rely on that.

The custom error page template is set by creating a [errorpage] section, which is presently supposed to contain only one parameter, named template. The parameter's value is passed through the macroprocessor to make the actual HTML code. Two context-specific macros are available within the template: %errcode% expands to the 3-digit error code (like 404 for “page not found”), and %errmessage% expands to the error message, as composed by the program.

In the present version all messages are hardcoded, which is likely to change in the future.

Special pages

Error page is one of the three special pages supported by Thalassa. In contrast to ordinary pages, special pages are not bound to particular paths; by they nature, they can be displayed in place of any other page in case Thalasa CGI can't (or is not allowed to) display what the user requests. The two other special pages are [nocookiepage], which is displayed instead of the requested page in case the page requires a work session to be active but the user doesn't have one, and [retrycaptchapage], displayed when the user tried to solve the CAPTCHA test but failed. Both pages are supposed to contain the CAPTCHA test challenge and the input form to submit the answer. The two pages will be documented along with session handling.

© Andrey V. Stolyarov, 2023, 2024