Installing ctserv

The process of installing ctserv at a new site has three phases -- getting the files, compiling and configuring, and running the server to verify installation -- that are detailed below.

These instructions are for Unix systems, and assume you already have GNU emacs version 19 installed. If you have problems while following these instructions, please contact Bob Rogers <rogers@darwin.bu.edu> for assistance.

Getting the files

1. Create a directory that will become the "ctserv root" directory, say /usr/local/ctserv, and cd to it.

 
	cd /usr/local
	mkdir ctserv
	cd ctserv
 
All directory names mentioned in this document assume that you use this default location, and should be changed appropriately if this is not the case.

2. Get the tar file from the BMERC FTP server into this directory. The tar file is available via FTP on darwin.bu.edu in the ~thread/code/ctserv/ctserv-1.0.tar.gz file, and is approximately 92Kbytes long. It is less that 400Kbytes to install. (It is not available via anonymous FTP because it is not generally available. Send me email if you really want it.)

3. Unpack the tar file: cat ctserv-1.0.tar.gz | gunzip | tar xf - . This will build the initial ctserv directory tree.

Compiling and configuring

4. Edit the file ./config.el to reflect its new location. The distributed version is shown in its entirety below; you must supply values for the psa-home-directory, psa-local-domain, and psa-mail-host variable initializations.

 
    ;; Configuration file for ctserv
    ;; (cross-threading load-balancing server).

    (setq psa-home-directory
          (expand-file-name "/usr/local/ctserv/"))
    (setq load-path (cons (concat psa-home-directory "bin")
			  load-path))
    (setq psa-local-domain ".your.domain.here")
    (setq psa-mail-host "hostname.your.domain.here")
    (require 'psa-server)
    (setq psa-transaction-file
          (concat psa-log-directory "ctserv-events.log"))

    (psa-require-task 'ctserv)
 
If you chose the "default" location of "/usr/local/ctserv/" in step 1, then psa-home-directory is OK as is. Otherwise, you should replace "/usr/local/ctserv/" with a string that reflects the directory name you chose. The directory name must end with a "/", and may be abbreviated (as in "~rogers/ctserv/").

5. The definition of ctserv-home-directory in ./bin/ctserv-request.el must be changed to use the same value as psa-home-directory in ./config.el (but the files are loaded independently, so they can't share a definition). After making this change, do "M-x byte-compile-file RET ctserv-request.el RET" to compile it.

6. In the /usr/local/ctserv/bin/ directory, update all references to directories and files prefixed with /usr/local/ctserv/ in the ctserv-request, ctserv-test-request, ctserv-resume-local-host, and ctserv-suspend-local-host scripts. (These use absolute pathnames so that they (a) don't need "~" expansion and (b) don't have to depend on the users' PATH environment variable.)

7. All files have been distributed with compiled (".elc") versions that are emacs 18 compatible, so it should not be necessary to compile anything (other than ctserv-request.el, which requires site customization). But just in case, the compilation order is as follows:

 
   ./bin/discus-date.el
   ./bin/psa-tasks.el
   ./bin/psa-server.el
   ./bin/basic-task.el
   ./bin/psa-transactions.el
   ./bin/ctserv.el

   ./bin/ctserv-request.el (independent of the others)
Other than ctserv-request.el, each file needs to be byte-compiled and then loaded before compiling the next.

8. If you wish users to be able to suspend/resume jobs via emacs, put the following autoloads in your site-init.el or default.el files:

   (autoload 'ctserv-suspend-local-host
          "/usr/local/ctserv/bin/ctserv-request"
     "Suspend ctserv on the host that is running emacs" t)
   (autoload 'ctserv-resume-local-host
          "/usr/local/ctserv/bin/ctserv-request"
     "Resume ctserv on the host that is running emacs" t)
Alternatively, one can put these forms in the .emacs files of only those users who need to run them.

9. If you wish users to be able to suspend/resume jobs via the shell commands, put the ctserv-suspend-local-host and ctserv-resume-local-host scripts in peoples' PATHs. (It is not advisable to do this by putting the /usr/local/ctserv/bin/ directory on anyone's PATH; adding a symbolic link to just those scripts from some standard directory is much preferable.)

10. In order to start & stop the server, it is necessary for ./bin/ to be on $PATH, though only for the (sole) user that owns the ctserv tree. (Interactively, you could do something like "set path = (/usr/local/ctserv/bin $path)" in csh.) See the ctserv "Security issues" section for more information.

Running the server to verify installation

In the installed ctserv root directory is a "test" subdirectory, that itself contains "hosts" and "jobs" sub-subdirectories (among others).

11. Create a new test script template, based on the one found in ./bin/new-test-cross-thread.text if you so desire, that will run appropriately at your site. It should fake reasonable output onto the file designated by the output-file option, while mostly sleeping, in order to occupy "real-time" without soaking up real resources.

12. Create a new job file, say ./test/jobs/foo-1.job, based on the extant ./test/jobs/test-1.job file that uses the new test script template.

13. Assuming that your local host is called "sassafras", create a "./test/hosts/sassafras.host" file, using the existing "sewall.host" file as a guide. (Then be sure to get rid of "sewall.host", unless you are planning on using that name for your next computer.) The following minimal host file content is acceptable:

 
   job-queue: ("foo-1")
 
Even the job-queue option is, well, optional. But it is useful, as in sewall.host, to have a set of default "notify-when" options specified by the host.

14. In a new emacs (but keep the old one around), do the following:

 
    C-x C-f ./config.el RET
    M-x eval-buffer
    M-x ctserv-server-test
 
This should start up the test server running in that emacs. This test server will immediately start to initialize itself, finding the job & host files created in steps 12 and 13, and will write its progress to a new log file in the ./test/log/ directory.

15. You should now be able to interact with the server in your original emacs via M-x ctserv-test-request. Doing "M-x ctserv-test-request RET status sassafras RET" should show that foo-1 is on on the queue but idle; send a "start sassafras" to get it going. Try suspending & resuming it via the various mechanisms you installed in steps 8 and 9. Be sure to "halt foo-1" before stopping the server (via C-g), unless you want to test whether a new instantiation of the server can acquire the running process.

Starting the server

16. To start a server for real, use the start-server shell command on the host you want the server itself (as opposed to any jobs it is supposed to supervise) to run. See the "Starting and stopping ctserv" section for full details.

17. Then, create real host & job files, & start them going. Enjoy.


Bob Rogers <rogers@darwin.bu.edu>
Last modified: Tue Mar 19 16:07:32 EST 1996