Customizing Our Web Interface

Fast & Security Conscious
High-Availability Unix Hosting

Language:
[English] [Français] [Norsk]

Our web interface (or "control panel"), which we call csoftadm.fcgi, allows users to configure everything that would otherwise require administrative access to do. This document describes how users can install their own customized version of csoftadm.fcgi under their accounts. This is a popular feature among resellers (as well as people who aren't that impressed by our web design skills).

One important feature of csoftadm.fcgi is its ability to execute without any particular privileges. It authenticates and communicates with a csoftadm server over TCP/IP. It is possible to use it on a different machine than the server hosting your account (but you will need to set up an SSH tunnel to the csoftadm server since there is no built-in SSL support at this time).

csoftadm.fcgi is written in C and depends on the OpenMGI client library, the csoft-cgi library and the FastCGI development kit. Optional dependencies include libidn for internationalized domain names support, cracklib if you want to check for weak passwords and libiconv (standard on most systems) for character set conversion in the webmail module.

If you are going to use csoftadm.fcgi on one of our servers, you don't need to worry about these dependencies since they are already installed.

Downloading the source

First download the csoftadm.fcgi sources into some temporary directory under your $HOME, such as ~/src/csoftadm. At this time, we are not making numbered csoftadm.fcgi releases, so the source is only available via Subversion:

  $ mkdir ~/src
  $ cd ~/src
  $ svn co http://dev.hypertriton.com/openmgi/trunk/cgi csoftadm.fcgi

Execute ./configure to prepare for compilation, and specify the directory in which you want csoftadm.fcgi installed, using --prefix.

  $ cd csoftadm.fcgi
  $ ./configure --prefix=$HOME/www/mycsoftadm --with-html-source

Tip: If you omit --with-html-source, the HTML sources/templates and all other files which are needed to re-generate your HTML files will not be installed. This reduces the number of files, but you will need to edit your HTML templates and sources from csoftadm.fcgi's source directory instead.

When the configure script finishes, you are ready to build and install:

  $ make all depend install

At this point you can delete ~/src/csoftadm.fcgi. If you inspect $HOME/www/mycsoftadm, you should see the csoftadm.fcgi binary.

Creating user-map

csoftadm.fcgi has only a single configuration file, ./etc/user-map. This file defines which users are allowed to connect, and what server is actually hosting their account (this applies to all account types including mailbox accounts).

Each line should contain one username and one hostname, separated by a colon. Unless you have multiple csoft.net accounts on multiple servers, you will probably only need to use localhost as server:

  alice:localhost
  bob:foo.domain.ext

In the future, user-map will be used to define specific privileges, such as the ability for a mailbox user to configure e-mail addresses (currently this can only be done from the main account).

Editing the templates

Purely cosmetic changes are easy to accomplish. This usually boils down to editing the master template file, html/m4/csoft.m4, which is standard HTML (it is preprocessed with m4, but you don't need to know it). When you are done with your edits, run make in the html directory. This will regenerate your HTML.

If more specific changes are required (e.g., moving forms around or adding translations to new languages), the HTML source files (those files with the *.htm extension in the html directory) can be edited. *.htm files will be preprocessed, at compile time, using the m4 macro processor and xsltproc XSLT stylesheet processor. HTML source files can contain variable names (such as "$foo"), which will be substituted at run-time.

Translating to a new language

If you would like to translate csoftadm.fcgi to a new language, you can edit the *.htm files and use the syntax: <ml lang="xx"></ml>, where "xx" is your ISO language code. The *.htm files can be encoded in UTF-8.

In addition to the <ml> tag, csoftadm.fcgi also uses gettext to translate dynamic strings. Go to the ./po directory and run make. Copy csoftadm_fcgi.pot to xx.po and simply edit the "msgstr" lines xx.po using your favorite text editor.

Even if it is not completely done, you are more than welcome to submit us your translation so that other users can benefit from it.

Code changes

People who are comfortable with C can modify every aspect of the web interface by editing, what we hope, is relatively easy-to-understand code. The csoft-cgi library (which is preinstalled on our servers) includes manual pages for its functions.

Client functions are organized in a set of modules. For example, group.c is an interface to the unix group management functions of the csoftadm server. It implements functions named group_list, group_add, group_del, etc. Those functions use the MGI_Query() and MGI_QueryData() calls to communicate with the csoftadm server. Here is a short introduction to the csoft-cgi API. The MGI_* calls should be documented here.

You are of course encouraged to submit any change you believe would be appreciated by other users. You must agree to make your patches available under the BSD license. You can contact us directly or use Bugzilla to submit bug reports, feature requests and patches.