Server - CLAW 0.1 User Manual

Next: Function index, Previous: Introduction, Up: Top

2 The server

CLAW wraps the Hunchentoot (see: unchentoot), a wonderful as powerful web server written in Common Lisp, into the CLAWSERVER class.

As an Hunchentoot wrapper CLAWSERVER “provides facilities like automatic session handling (with and without cookies), logging (to Apache's log files or to a file in the file system), customizable error handling, and easy access to GET and POST parameters sent by the client.”

2.1 Understanding the clawserver

CLAWSERVER is not only a Hunchentoot wrapper, it is also the common place where you put your web applications built with CLAW into lisplet that you can see as application resource containers and request dispatchers.

2.1.1 `CLAWSERVER` instance initialization

When you want to instantiate a CLAWSERVER class, remember that it accepts the following initialization arguments:

port The port the server will be listening on, default is 80
sslport The SSL port the server will be listening on, default is 443 if the server has a certificate file defined.
address A string denoting an IP address, if provided then the server only receives connections for that address. If address is NIL, then the server will receive connections to all IP addresses on the machine (default).
name Should be a symbol which can be used to name the server. This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM
sslname Should be a symbol which can be used to name the server running in SSL mode when a certificate file is provided. This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM
mod-lisp-p If true (the default is NIL), the server will act as a back-end for mod_lisp, otherwise it will be a stand-alone web server.
use-apache-log-p If true (which is the default), log messages will be written to the Apache log file - this parameter has no effect if mod-lisp-p is NIL.
input-chunking-p If true (which is the default), the server will accept request bodies without a Content-Length header if the client uses chunked transfer encoding.
read-timeout Is the read timeout (in seconds) for the socket stream used by the server. The default value is HUNCHENTOOT:*DEFAULT-READ-TIMEOUT* (20 seconds)
write-timeout Is the write timeout (in seconds) for the socket stream used by the server. The default value is HUNCHENTOOT:*DEFAULT-WRITE-TIMEOUT* (20 seconds)
setuid On Unix systems, changes the UID of the process directly after the server has been started.
setgid On Unix systems, changes the GID of the process directly after the server has been started.
ssl-certificate-file If you want your server to use SSL, you must provide the pathname designator(s) for the certificate file (must be in PEM format).
ssl-privatekey-file the pathname designator(s) for the private key file (must be in PEM format).
ssl-privatekey-password If private key file needs a password set this parameter to the required password

2.1.2 `CLAWSERVER` class methods

clawserver-port obj
(setf clawserver-port) val obj

obj The CLAWSERVER instance
val The numeric value of listening port to assign

Returns and sets the port on which the server is listening to (default 80). If the server is started and you try to change the listening value an error will be signaled

clawserver-sslport obj
(setf clawserver-sslport) val obj

obj The CLAWSERVER instance
val The numeric value of listening port to assign for SSL connections

Returns and sets the port on which the server is listening to in SSL mode if a certificate file is provided (default 443). If the server is started and you try to change the listening value an error will be signaled

clawserver-address obj
(setf clawserver-address) val obj

obj The CLAWSERVER instance
val The string value denoting the IP address

Returns and sets the IP address where the server is bound to (default NIL => any). If the server is started and you try to change the listening value an error will be signaled

clawserver-name obj
(setf clawserver-name) val obj

obj The CLAWSERVER instance
val The symbol value denoting the server name

Should be a symbol which can be used to name the server. This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM

clawserver-sslname obj
(setf clawserver-sslname) val obj

obj The CLAWSERVER instance
val The symbol value denoting the server name running in SSL mode

Should be a symbol which can be used to name the server running in SSL mode, when a certificate file is provided. This name can utilized when defining easy handlers. The default name is an uninterned symbol as returned by GENSYM

clawserver-mod-lisp-p obj
(setf clawserver-mod-lisp-p) val obj

obj The CLAWSERVER instance
val The boolean value denoting the use of mod_lisp.

Returns and sets the server startup modality . If true (the default is NIL), the server will act as a back-end for mod_lisp, otherwise it will be a stand-alone web server. If the server is started and you try to change the listening value an error will be signaled

clawserver-use-apache-log-p obj
(setf clawserver-use-apache-log-p) val obj

obj The CLAWSERVER instance
val The boolean value denoting the use of Apache log.

Returns and sets where the server should log messages. This parameter has no effects if clawserver-mod-lisp-p is set to NIL. (default T if mod_lisp is activated. If the server is started and you try to change the listening value an error will be signaled

clawserver-input-chunking-p obj
(setf clawserver-input-chunking-p) val obj

obj The CLAWSERVER instance
val The boolean value denoting the ability to accept request bodies without a Content-Length header.

Returns and sets the ability to accept request bodies without a Content-Length header (default is T) If the server is started and you try to change the listening value an error will be signaled

clawserver-read-timeout obj
(setf clawserver-read-timeout) val obj

obj The CLAWSERVER instance
val The integer value denoting the server read timeout.

Returns and sets the server read timeout in seconds (default is T) (default to HUNCHENTOOT:*DEFAULT-READ-TIMEOUT* [20 seconds]). If the server is started and you try to change the listening value an error will be signaled

clawserver-write-timeout obj
(setf clawserver-write-timeout) val obj

obj The CLAWSERVER instance
val The integer value denoting the server write timeout.

Returns and sets the server write timeout in seconds (default is T) (default to HUNCHENTOOT:*DEFAULT-WRITE-TIMEOUT* [20 seconds]). If the server is started and you try to change the listening value an error will be signaled

clawserver-setuid obj
(setf clawserver-setuid) val obj

obj The CLAWSERVER instance
val The string or integer value of the UID with which the server instance will run.

Returns and sets the server instance UID (user id). If the server is started and you try to change the listening value an error will be signaled

clawserver-setgid obj
(setf clawserver-setgid) val obj

obj The CLAWSERVER instance
val The string or integer value of the GID with which the server instance will run.

Returns and sets the server instance GID (group id). If the server is started and you try to change the listening value an error will be signaled

clawserver-ssl-certificate-file obj
(setf clawserver-ssl-certificate-file) val obj

obj The CLAWSERVER instance
val Pathname designator(s) for the certificate file

Returns and sets the pathname designator(s) for the certificate file if the CLAWSERVER is SSL enabled If the server is started and you try to change the listening value an error will be signaled

clawserver-ssl-privatekey-file obj
(setf clawserver-ssl-privatekey-file) val obj

obj The CLAWSERVER instance
val Pathname designator(s) for the private key file

Returns and sets the pathname designator(s) for the private key file if the CLAWSERVER is SSL enabled If the server is started and you try to change the listening value an error will be signaled

clawserver-ssl-privatekey-password obj
(setf clawserver-ssl-privatekey-password) val obj

obj The CLAWSERVER instance
val Password for the private key file

Returns and sets the password for the private key file if the CLAWSERVER is SSL enabled If the server is started and you try to change the listening value an error will be signaled

clawserver-start obj

obj The CLAWSERVER instance

Make the CLAWSERVER begin to dispatch requests

clawserver-stop obj

obj The CLAWSERVER instance

Make the CLAWSERVER stop.

clawserver-register-lisplet clawserver lisplet-obj

obj The CLAWSERVER instance
lisplet-obj A LISPLET class instance

Registers a LISPLET, that is an `application container` for request dispatching.

clawserver-unregister-lisplet clawserver lisplet-obj

obj The CLAWSERVER instance
lisplet-obj A LISPLET class instance

Unregisters a LISPLET, that is an `application container`, an so all it's resources, from the CLAWSERVER instance.

2.2 Starting the server

Starting CLAW is very easy and requires a minimal effort. CLAW supports both http and https protocols, thought enabling SSL connection for CLAW requires a little more work then having it responding only to http calls.

2.2.1 Making CLAW work on http protocol

To simply start CLAW server, without enabling SSL requests handling, you just need few steps:

(defparameter *clawserver* (make-instance 'clawserver)) (clawserver-start *clawserver*)

This will start the web server on port 80 that is the default.

Of course you can create a parametrized version of CLAWSERVER instance for example specifying the listening port as the following:

(defparameter *clawserver* (make-instance 'clawserver :port 4242)) (clawserver-start *clawserver*)

2.2.2 Making CLAW work on both http and https protocols

To enable CLAW to https firt you need a certificate file. A quick way to get one on a Linux system is to use openssl to generate the a certificate PEM file, the following example explains how to do.

Firstly you'll generate the private key file:

#> openssl genrsa -out privkey.pem 2048

Generating RSA private key, 2048 bit long modulus ............................+++ ..................................................+++ e is 65537 (0x10001)

#>

Then the certificate file:

#> openssl req -new -x509 -key privkey.pem -out cacert.pem -days 1095

You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:IT State or Province Name (full name) [Some-State]: bla-bla Locality Name (eg, city) []: bla-bla Organization Name (eg, company) [Internet Widgits Pty Ltd]: mycompany Organizational Unit Name (eg, section) []: Common Name (eg, YOUR name) []:www.mycompany.com Email Address []:admin@mycompany.com

#>

Now you can start CLAWSERVER in both http and https mode:

(defparameter *clawserver* (make-instance 'clawserver :port 4242 :sslport 4443 :ssl-certificate-file #P"/path/to/certificate/cacert.pem" :ssl-privatekey-file #P"/path/to/certificate/privkey.pem"))) (clawserver-start *clawserver*)

CLAW is now up and you can browse it with your browser using address http://www.yourcompany.com:4242 and http://www.yourcompany.com:4443. Of course you will have only a 404 response page!