Novell is now a part of Micro Focus

How to Use eDirectory-Based Home Directories with the Apache Web Server

Articles and Tips: article

Brad Nicholes
Software Engineer
Core Operating System
bnicholes@novell.com

01 Sep 2001


This AppNote discusses how the two modules MOD_HDir, and MOD_RDir available for Apache for NetWare allows the Apache Web Server to serve pages from a user's home directory or from any remote NetWare file server within the same eDirectory tree.


Topics

NDS eDirectory, Apache Web Server

Products

Mod_HDirs, Mod_RDirs

Audience

network designers, administrators, consultants, integrators, developers

Level

intermediate

Prerequisite Skills

familiarity with NetWare and Apache Web Server

Operating System

NetWare

Tools

none

Sample Code

no

Introduction

One of the standard features of a network server such is NetWare, is the availability of user home directories. When an account is created in eDirectory, the user may be granted space on the network that belongs to them and is referred to as the user's home directory. This is usually an area where the user can copy files for purposes of backups, sharing or just temporary storage. The user has total control over the files that are placed in their home directory and which other users have access rights to those files. But why restrict this functionality to just LAN users? Why not expand user home directories to the web? This is actually not a new concept. Allowing a web server the ability to serve pages from a user home directory has been around for quite a while. So how can the Apache Web for NetWare take advantage of this functionality and allow access to the eDirectory based user home directories? This article will discuss two new modules available for Apache for NetWare that allows the Apache Web Server to serve pages from a user's home directory or from any remote NetWare file server within the same eDirectory tree.

What Is Required

First of all, the Apache Web Server for NetWare must be running. Since the Apache Web Server is an open source project, it is freely available on the Internet. To download a complete version of Apache for NetWare, go to http://www.apache.org/dist/httpd/binaries/netware/.This web site contains not only the latest version of Apache for NetWare, but also several previous versions. The .ZIP file includes instructions on how to install the Apache software as well as basic configuration. Additional information can be found on the Apache Foundation's web site at http://www.apache.org and by referring to the AppNotes article "How to Use NDS eDirectory to Secure Apache Web Server for NetWare" in the February 2001 issue (http://support.novell.com/techcenter/articles/ana20010202.html).

The next requirement is the Apache modules Mod_HDirs and Mod_RDirs, which provide Apache with the ability to access user home directories and remote file systems. These modules as well as several other modules can be downloaded from the Apache Modules for NetWare page of the Novell Developer Kit web site (http://developer.novell.com/ndk/modapach.htm). To install these modules, simply unzip the file "ModApach.zip" and copy the Mod_HDirs and Mod_RDirs NLMs to the "/Apache/Modules" directory on your NetWare server. Several other modules are also contained in the same download. These modules include Mod_NDS, Auth_LDAP, Mod_LCGI, and Mod_DAV. Installing these modules is easy and each one includes instructions that explain how to configure and use them.

MOD_HDIRS

Mod_HDirs is the module that allows the Apache Web Server to serve pages from a user's eDirectory based home directory. Once the NLM has been copied to the "/Apache/Modules" directory on your NetWare server, it is now ready to be configured. The module is set up with default values, so there really isn't much to do. The only requirement is that the Apache Web server load the module. Adding the following statement to the HTTPD.CONF file accomplishes this:

LoadModule hdirs_module modules/modhdirs.nlm

The LoadModule directive instructions the Apache Web server to load an external module. The name "HDirs_Module" is the symbol name of the external module and "modules/modhdirs.nlm" is the path and file name of the NLM to be loaded. The default settings are sufficient to allow Mod_HDirs to start serving pages from an eDirectory based user home directory and only need to be changed if a specific configuration is desired.

Every module that is loaded by the Apache Web server provides its own set of directives to allow it to be customized. Once a module is loaded, its directives are made available so that they can be included in Apache's HTTPD.CONF configuration file. There are three configuration directives that are implemented by Mod_HDirs. These three directives are as follows:

UserSubTag


Syntax

UserDirTag <tag>

Context

server config

Description

This sets the URI tag that indicates a user home directory. If omitted the default tag is '~'.

UserSubDir


Syntax

UserSubDir <Directory_Name>

Context

server config

Description

This sets the sub-directory of the user home directory that should be used for publishing HTML web pages. If omitted the default sub-directory is 'PUBLIC_HTML'. The sub-directory name must not be preceded by a slash.

SearchNDSContext


Syntax

SearchNDSContext context.to.search1 .context.to.search2 ...

Context

server config

Description

This creates a list of additional contexts to search when resolving the user ID. If omitted, only the root context will be searched.

Most implementations of eDirectory do not store all of their user objects within the root context or even a single context. For this reason Mod_HDirs provides the "SearchNDSContext" directive. This directive allows the administrator to define a list of contexts that should be searched whenever a user name needs to be resolved to a home directory path. This also requires that all user names within the search contexts listed must be unique. When a user name is resolved to a home directory path, Mod_HDirs simply starts searching through the listed contexts until it finds the first user name match. If the user names are not unique across all of the listed contexts, the home directory of the first user name found will always be returned even if it was not the intended user.

Built into Mod_HDirs is the ability to access web pages that do not reside on the web server's local file system. This means that the user's home directory can be stored on any file server that exists within the same eDirectory tree as the Apache Web server itself. When Mod_HDirs resolves the user name to a directory path, the path that is extracted from eDirectory contains a server specification in addition to the volume and path. Mod_HDirs sees the server specification, recognizes that it refers to a remote server and then proceeds to establish a connection. Once a connection has been established to a remote server, Mod_HDirs remembers this connection by caching it. The next time that a request is made to the same remote server, Mod_HDirs first checks its cache and uses an existing connection rather than spending the time to establish a new one. By caching the connection, only the first request to a remote server incurs the extra time to establish the connection. All subsequent requests to the same server are satisfied much quicker.

Remote connection.

Now that Mod_HDirs has been installed and configured, users can start publishing their web pages by simply creating the directory "/PUBLIC_HTML" within their home directory and placing their HTML files there. The user's web pages can be accessed from a browser by specifying the user's home directory as a URL address. For example, the URL http://www.myserver.com/~bnicholes would instruct Apache to resolve the user name BNICHOLES to the user home directory and then retrieve the default HTML page (ie. Index.html) from the sub-directory "/PUBLIC_HTML".

Whenever documents are retrieved from the file system, the Apache configuration should include directives that apply to the parent directory, location or file so that the web server knows exactly how the documents should be accessed and what restrictions, if any, should be in place. Additional configuration can be applied to all user directories by defining a <Directory >, <Location > or <Files > block within the HTTPD.CONF file. For example, the following configuration would be applied to all user home directories created under parent path "SYS:/Users/*":

<Directory Sys:/Users/*>
    AllowOverride FileInfo AuthConfig Limit
    Options MultiViews Indexes IncludesNoExec
    <Limit GET POST OPTIONS PROPFIND>
        Order allow,deny
        Allow from all
    </Limit>
    <LimitExcept GET POST OPTIONS PROPFIND>
        Order deny,allow
        Deny from all
    </LimitExcept>
</Directory>

The configuration above would apply to any user home directory created as a sub-directory of "Sys:/Users" on any server's file system whether local or remote. The "AllowOverride" directive specifies which directive types can be overridden by a .HTACCESS file that has been placed in a user's "/PUBLIC_HTML" sub-directory. The "Options" directive allows the home directory to emit an index listing of documents if a default web page (usually Index.html) is not found. It also disallows CGI scripts from being executed within a server-side include. The tags <Limit> and <LimitExcept> define which web access operations can be performed in a user home directory. The tags in the above example limit access to read-only for all documents accessed from parent directory "Sys:/Users/*".

If not all user home directories are contained within the specified user parent directory, more <Directory> tags can be defined to configure additional file locations. One advantage of creating multiple user parent directories is that each directory could be configured with different default directives. For example all users created under the user parent directory "Sys:/Users/Students/*" could be defined as in the example above which allows public read-only access to all documents placed in the user's "/PUBLIC_HTML" directory. While all users created under the user parent directory "Sys:/Users/Faculty/*" could be defined to require a valid login before allowing access to the documents:

<Directory Sys:/Users/Faculty/*>
        
        AuthType Basic
        AuthName User_Faculty_Dir
        AuthNDSTree eDirectory_Tree
        AuthNDSContext .eDirectory_Context
        require valid-user
</Directory>

In this manner, access to user home directories can be controlled simply by where they were created. If a student wanted to password protect their documents, this could also be done by defining additional security configuration in a .HTACCESS file that is placed in the "/PUBLIC_HTML" directory itself. We will talk more about how this could be done later in the article.

The Apache Web server also includes the standard module Mod_UserDir. This module is actually built into the ApacheC NLM at build time, which means that it is always available. Mod_UserDir is the standard Apache Web server way to access user home directories. On the NetWare operating system as well as several other OS's, Mod_UserDir's access to a user home directory is restricted to the local file system. It is also not capable of interacting with eDirectory so its home directory support must be managed manually. But if simple home directory support on the web server's local file system for a small number of users is all that is required, it does a very good job. For more information about how to configure and use Mod_UserDir, refer to the "UserDir" directive in the list of standard Apache runtime directives (http://www.apache.org/docs/mod/directives.html).

MOD_RDIRS

Now lets talk a little about accessing web documents that are not contained in a user home directory but still reside on a remote file system. Access to these documents is accomplished by loading the module Mod_RDirs using the following LoadModule statement:

LoadModule rdirs_module modules/modrdirs.nlm

Mod_RDirs does not implement any additional configuration directives. By simply loading the module, the Apache Web server is enhanced with the ability to access remote file systems whenever the server name is specified as part of the file path.

Server/Volume:/Path/File

Most file paths include a volume name as well as the full path to the directory or file. Including the server name as part of the path tells Mod_RDirs to make the appropriate connection to the remote server and retrieve the file once the connection has been established. In exactly the same way as Mod_HDirs, Mod_RDirs also caches remote connections so that only the first request has to pay the connection penalty. All subsequent requests to the same remote server simply reuse the connection that was previously established.

The only drawback to accessing files from a remote server is that all file names must be converted to their short 8.3 format. In addition, anytime a remote file path is included in the configuration of Apache, it must also be defined in 8.3 format. For example, the following configuration directives define an additional document directory that resides on a remote file server:

#Refers to NWServer/Sys:/MyWebPages/MyFiles
Alias   /remote   NWServer/Sys:/MyWebp~1/MyFiles
<Directory "Sys:/MyWeb~1/MyFiles">
    Options Indexes MultiViews
    Order deny,allow
    Allow from all
</Directory>

One important point to notice is that only the file path in the "Alias" directive includes the remote server name, the "<Directory>" tag does not. The reason for this is because Mod_RDirs will automatically establish the connection to the remote server whenever it sees a server specification for the first time. In this example, the "Alias" directive is the first time that Mod_RDirs will see the remote path. Once the connection has been established, the "<Directory>" tag only needs to know where the file is actually located on the remote server. The other point to notice is that both the "Alias" directive as well as the "<Directory>" tag use the 8.3 format when specifying the directory path. Hopefully this restriction can be eliminated in the future, but for now it is just something that has to be remembered.

Tips and Tricks

Whenever new functionality is introduced, the things that everybody wants to know are "What do I need to watch out for?" and "How can I make it work better?" Hopefully in this section, I can explain some of the tips and tricks that I have run into that might help you better utilize the Mod_HDirs and Mod_RDirs Apache modules.

How to include a large number of contexts as part of the Mod_HDirs "SearchNDSContext" directive. Since eDirectory is capable of storing billions of objects, it is not uncommon for administrators to divide the user objects up into many different contexts. In some cases there could be hundreds of user contexts defined in the directory. One way to flatten the tree into a manageable set of searchable contexts would be to create one or more contexts that contain alias objects to the real user objects. Then rather than listing all of the user contexts as part of the "Search NDSContext" list, just define the alias contexts.

Aliases also come in handy if there are user names that contain double-byte or extended characters. Since part of accessing a user home directory is specifying the user name as part of the URL, double-byte and extended characters don't always translate well from client to web server especially if the client and server are not in the same codepage. One way to overcome this problem would be to alias the user name with a name that does not contain double-byte or extended characters. This way the user's home directory will be globally accessible.

How to access a remote file system directory that is in long file name format. As mentioned previously, one of the drawbacks of remote file system access is the fact that all directory and file names must be converted to 8.3 format. The area that this restriction impacts the most is in the configuration of the web server itself. Whenever a directory path refers to a remote file system, that path must be specified in 8.3 format. Two examples of this would be when specifying additional configuration directives for your user home directories and when configuring additional document directories that reside on a remote server.

When defining a remote file system path, the most important point to remember is that the server name only needs to appear as part of the directory path the first time that the path is specified. All subordinate references should only include the volume and/or path and filename. For example, when defining additional directives for the user home directories, the <Directory> tag should only contain the volume and path. The reason for this is because the user home directory itself, when extracted from eDirectory, will include the file server name. The eDirectory user home directory is the first time that Apache sees the directory path and at that point the remote connection is established. The <Directory> tag will always be subordinate to the user home directory.

A second example is defining additional document directories using the directives such as the "Alias" directive. The "Alias" directive should include the server name along with the path since it will be the first time Apache sees the path definition. If a <Directory> tag is used in conjunction with the "Alias" directive, the file path that is used as part of the tag, should only include the volume and path since it is subordinate to the alias.

How to secure a user home directory that was initially defined as public. In many instances when user home directories are defined in the configuration file, they are configured as publicly accessible directories. This means that anybody can access the web documents contained in the "/PUBLIC_HTML" subdirectory by simply specifying the "~UserName" as part of the URL. If the user wants to secure their documents, they can do so by placing the security directives in a .HTACCESS file and putting that file in their "/PUBLIC_HTML" subdirectory. Whenever the Apache Web server finds a .HTACCESS file at the same location as the document that is being retrieved, it opens the file, reads the additional directives and applies the new configuration to the request being serviced. An example of a .HTACCESS file that implements the security configuration directives is as follows:

AuthType Basic
AuthName User_Secure_Docs
AuthNDSTree eDirectory_Tree
AuthNDSContext .Some_Context
Require valid-user

The directives used in the example above require that the Apache module Mod_NDS be loaded as part of the Apache Web server configuration. If other authentication modules have been loaded, the concept would still be the same but the actual directives used in the .HTACCESS file would be different. By implementing security in this manner, users have complete control over how documents are accessed and who is accessing them. In addition, if you are using Mod_NDS as the authentication module, the user can also control file level security by simply setting user file rights through eDirectory. Of course users may not want to deal with defining directives in a .HTACCESS file or the administrator may not want to give users the ability to alter the configuration. If this is the case then simply define a set of standard configuration directives for all users within the HTTPD.CONF file itself as in the example previously mentioned in this article. For more information about how to secure the Apache Web server through eDirectory, please refer to the article "How to Use NDS eDirectory to Secure Apache Web Server for NetWare" in the February 2001 issue of AppNotes.

Other Remote File System "Gotcha's"

There are several Apache directives that define how Apache retrieves documents from the file system. When a document is retrieved from a remote file system these directives need to be modified to make sure that the documents are accessed correctly. The first two directives that should be changed to allow for remote file system access are the "AccessFileName" and "IgnoreIndex". The "AccessFileName" directive tells Apache what the additional configuration file name is. By default this is set to ".HTACCESS". The thing to notice about the default access file name is that it begins with a dot and therefore violates the 8.3 format that is required by remote file system access. This problem can be fixed in one of two ways. The first fix would be to change the value of the "AccessFileName" directive to a file name that is in the 8.3 format. Another way to fix this problem would be to add the value "HTACCE~1" to the directive list.

AccessFileName  .htaccess  htacce~1

The "AccessFileName" directive will accept more than one value which makes it easy to handle differences between local and remote file systems. When Apache searches the remote file system for the .HTACCESS file, the file name is automatically converted by the OS to "HTACCE~1". By adding this value to the "AccessFileName" directive, .HTACCESS files in a remote document directory will still work as expected.

The "IgnoreIndex" directive tells Apache which files should not be included in a directory index listing. Since .HTACCESS files contain additional configuration directives, it is not a good idea to allow public access to these files. Just as in the case of the "AccessFileName" directive, "htacce*" must also be added to the "IgnoreIndex" directive so that these additional configuration files do not appear when a remote document directory is indexed.

IndexIgnore  .??*  *~  *#  HEADER*  README*  RCS  CVS  *,v  *,t  htacce*

Modifying these two directives enables .HTACCESS files to be used in remote document directories. But we still need to make sure that this file is not publicly accessible even though it resides in the user's home directory or an additional document directory. To ensure that this file is safe from being tampered with, the following configuration directives also need to be added:

<Files ~ "^\htacce~1">
    Order allow,deny
    Deny from all
</Files>

The default configuration of Apache already contains a similar set of directives to protect .HTACCESS files on the local file system. The above set of directives provides the same protection for the .HTACCESS files on a remote file system. These directives simply instruct Apache to deny access from all users to any file matching the specified expression. This means that users accessing the document directory that contains a .HTACCESS file, cannot modify or even view it.

Conclusion

One of the strong points of the Apache Web server is the ability to enhance the functionality by means of loadable modules. This article has introduced two new modules that allows Apache to retrieve web documents from user home directories and remote file systems. Using Mod_HDirs, users now have the ability to publish their own web pages without having to give them rights to the web server's document root. Users are already used to storing files in their home directories and now they can publish to the Internet from this directory as well.

The Mod_RDirs module allows the Apache Web server to extend itself beyond its own hard drive and access documents from any NetWare server within the same eDirectory tree as itself. Using this Apache module, documents can be published and accessed from anywhere in the net without having to worry about who has rights to the physical web server machine. Extending the Apache Web server in this way makes Apache a much more accessible and powerful tool. Rather than just being a self contained web server it can now spread its wings to become a service on the net.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates