Setting Up Web Directories

CL-HTTP supports HTTP methods beyond GET that enable you to write files (PUT) and delete them (DELETE) over the Web. In order to use these capabilities you will need to set up appropriate Web directories on your server. This section explains how to configure a CL-HTTP server for writing URLs, assuming the background provided by the Security & Authentication documentation.

First, you need to set up an authentication realm to keep track of access control information. For this application, a digest authentication realm provides better security because passwords do not travel in clear text over the Internet.

(http:add-realm :web-directory :digest)

Second, you need a group in the realm for users that will write files to the Web directory.

(http:add-group :web-directory :users)

Third, you can define a set of capabilities within the realm that can be attached to each directory that you export. Here, the group, users, within the realm, web- directory, have the capability to use all HTTP methods on URLs within the directory.

(http:add-access-control-group :web-directory-capabilities 
			       :web-directory
			       :capabilities '((:default :users)))

Fourth, you are now ready to add a user into the group, users, who will be able to read, write, and delete URLs within the directory.

(http:add-user "JaneHacker" 
	       :web-directory
	       :groups '(:users)
	       :password "*****"
	       :personal-name "Jane Q. Hacker"
	       :email-address "JaneHacker@mac.com")

Fifth, you need to save all of this authentication information persistently. By evaluating the following form, all authentication data in the dynamic Lisp environment is saved to disk for automatic reload upon server relaunch. Additionally, passwords are saved as one-way hashes for added security.

Sixth, you are ready to export directories with access control. Here, the presence of access-control capabilities enables the potentially dangerous methods of writing and deleting URLs only for authorized users. For additional security you may restrict access further based on subnets that are allowed to read (:read-subnets) or write (:write-subnets) to the directory. See the documentation for http:export-url for further details.

(http:export-url #u"/web-directory/"
                 :directory
                 :pathname (pathname "http:web-directory;")
                 :recursive-p t	 ;recursively descend directory levels
                 :authentication-realm :web-directory
                 :capabilities :web-directory-capabilities)

This export form should be evaluated in fresh server environment to make sure that all the URLs within the directory have the correct authentication information. Alternatively, you can supply non-null values for either of the keyword arguments to http:export-url :recache or :immediate-export.

Access control groups do not allow you to specify that an HTTP method should be open to the world. If want open access with restricted write access, you can either export the same file system structure via a different external URL, such as:

(http:export-url #u"/public-directory/"
                 :directory
                 :pathname (pathname "http:web-directory;")
                 :recursive-p t)  ;recursively descend directory levels

Or, you can use subnet access control to restrict write access (:PUT, :POST, :DELETE) to certain Internet addresses, for example:

(http:export-url #u"/web-directory/"
                 :directory
                 :pathname (pathname "http:web-directory;")
                 :recursive-p t	 ;recursively descend directory levels
                 :write-subnets (list (local-host-ip-address)));trusted hosts

Finally, you are now ready to use popular HTML authoring tools (e.g., http:copy-file, or use the basic client functions http:put-url and http:delete-url. Additionally, you can obtain directory listings beyond the standard CL-HTTP HTML formats by supplying the accept header to http:show-url and specifying either text/uri-list or text/x-directory-list as an acceptable media type.

(http:show-url #u"/web-directory/"
               :headers '(:accept ((:text :x-directory-list) 
                                   (:text :uri-list)
                                   (:* :*))))

While text/uri-list provides just a sequence of URIs in the directory, text/x-directory-list returns a sequence of properties lists containing the URL, size, modification date, as well as the creation date and author on some platforms.