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.

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).

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.

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.

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.