Everything in ExSite happens through a small number of programs:
| Program | Description |
|---|---|
| ex.cgi | Master control program—all normal page views and system functions go through this program. |
| publish.pl, publish.cgi | The publisher—writes content out to fast static files for better security and performance. publish.cgi is a setuid wrapper that gives the necessary permissions for publish.pl to write files to the web server. |
| cron.pl | The scheduler—manages off-line and scheduled tasks. |
There is also a small collection of utilities, that can only be executed from the command line.
ex is the Master Control Program. All regular interactions with the system will normally happen via this program.
Every request happens through a URL like
https://your-domain.com/cgi/ex.cgi/COMMAND/PATH?QUERY
The set of all commands is:
| Command | Path | Description |
|---|---|---|
| admin | blank, or module | invokes the administrator interface |
| api | API command | calls the API interface for direct data manipulation |
| app | module | runs a plug-in module |
| captcha | n/a | generates an anti-robot captcha |
| chart | n/a | generates an SVG graph or chart |
| debug | displays debug information about the URL | |
| dialog | n/a | generates a modal dialog, typically for content editing purposes |
| dispatch | n/a | process a batch of AJAX requests |
| doform | n/a | generic form/POST processing |
| file | file path | access a file in the file repository |
| help | module | display system help |
| home | n/a | go to the most appropriate location for the current user |
| login | n/a | request credentials to access the system |
| logout | n/a | discard your login credentials and return to being anonymous |
| page | content | display a web page |
| post | content | post direct to a content object |
| publish | n/a | write out content to fast, secure static files (calls publish.cgi, below) |
| test | n/a | run some basic system tests |
| view | content | display a content object directly |
publish writes out content to fast, secure static files. It is generally not invoked directly, but will be linked/called by appropriate ex.cgi commands, when needed.
publish.pl is the actual program that does the work; publish.cgi is a binary setuid wrapper program that confers the necessarily privileges to write to the web server. Calling publish.pl directly from the address bar will normally fail because Apache will lack the write permissions to alter your file system. However, when debugging from the command line, you can run publish.pl directly, because you are normally not the www user.
cron is the task manager and scheduler. It manages your off-line tasks that run without user interaction.
This program is meant to be run via a crontab. For example, you can set it to run every hour on the hour, using a crontab setting like this:
0 * * * * /home/your-website/cgi/cron.pl
However, in all likelihood you will need to set some environment variables to spoof the Apache environment, as most pieces of code are expecting to run in a webserver environment. There are a few ways you can do this.
Firstly, you could just hard-code the environment variables into cron.pl. (There is a section near the top for you to do so.)
If you want to avoid forking your cron.pl, you could just code the environment variables into the crontab, like so:
0 * * * * DOCUMENT_ROOT=/home/your-website/html; SCRIPT_NAME=/cgi/ex.cgi; SCRIPT_FILENAME=/home/your-website/cgi/ex.cgi; HTTP_HOST=www.your-website.com; HTTPS=on; cd /home/your-website/cgi; /usr/bin/nice /home/your-website/cgi/cron.pl
Lastly, you could set up the environment variables in a shell script that in turn runs cron.pl, like so:
0 * * * * /home/your-website/cron.sh
The bin directory of your ExSite distribution includes a number of useful utility programs. These can be run from the terminal command line, usually from the cgi-bin directory to ensure your include paths are correct.
| Program | Description |
|---|---|
| cgi | debugger; allows you to "run" a URL. Spoofs the Apache environment and places you in the perl debugger. Can also be used for performance profiling. |
| cdump.pl | content exporter; converts a site (or part of a site) to perl code that can be run on another site to import it |
| crypt.pl | encrypt/decrypt texts that have been run through the system encryption tools |
| dbcheck.pl | validates that your database matches your dbmap; displays discrepancies as MySQL scripts to alter your database. |
| importdir.pl | loads directories of files into the CMS |
| makepod.csh | autogenerates system documentation |
| makesql.pl, makesqldrop.pl | generates the SQL commands to create or drop your system tables |
| printconf.pl | displays all your configuration settings |
| purge-fileroot.pl | remove files no longer referenced by the CMS |
| store.pl | manually interact with the persistent data store |
| test-content.pl | tests your content for setup errors and other problems |
Most end-user interactions will go through the page command of ex.cgi, for example:
https://www.your-domain.com/cgi/ex.cgi/page/contact
The /cgi/ex.cgi/page elements of this URL are the same for all dynamic page views, which means they are uninteresting URL clutter, and can be removed if you want to present cleaner URLs to your visitors. For example, the string /cgi/ex.cgi/page could be shortened to just /page:
https://www.your-domain.com/page/contact
To do this, you need to
To change how you generate your page links, you need to switch your system from automatic self-configuration to manual configuration. These settings are usually near the top of your system configuration file /cgi/conf/exsite.conf. If you have auto-configuration turned on
server.auto = 1
then turn it off by removing that line or commenting it out. Then add manual configuration, by defining some of the key server locations of your installation:
# your domain name
server.domain = your-domain.com
# note: server host is typically either www or blank
server.host =
# your protocol is either http or https (probably the latter)
server.protocol = https
# CGIroot is the location of your cgi-bin directory
server.CGIroot = /home/your-domain/cgi
# CGIpath is how that appears in the URL - note that we are blanking it out
server.CGIpath =
# HTMLroot is the location of your HTDOCS
server.HTMLroot = /home/your-domain/html
# HTMLpath is how that appears in the URL - usually left blank on most production sites
server.HTMLpath =
# port is usually left as the default
server.port =
Lastly, you need to add one more setting to tell it that the "command" for generating a page is changing from ex.cgi/page to simply page:
prog.page = page
Now your installation will generate URLs in the correct format. Your webserver, however, will not recognize them. To fix that you need to add a rewrite rule that transforms these new URLs into the default URLs that Apache is expecting. Something like this should do the trick:
RewriteRule /page/(.*) /cgi/ex.cgi/page/$1 [PT]
This rewrite rule goes into your website's Apache configuration file, following a RewriteEngine On declaration.
Note that /cgi/ in the above example should reflect the format of your cgi-bin urls, which might be /cgi-bin/ or /CGI-Executables/ or something else.
A couple of warnings about using URL re-writes for your dynamic URLs:
page in the above example) cannot be used as a content name at the top level of your site map, since any links to that content will be re-written according to your rewrite rule.