Dynamic Configuration Files

Page Contents

• What is a dynamic configuration file (also known as a .htaccess file)?
• Add new MIME types
• Add password or host-based authentication to a file or directory
• Path to the .htpasswd file
• Create custom 404 error pages
• Redirections?
• Allowing .inc or .bak file type
• Show PHP errors
• Turn off PHP magic quotes
• Turn directory listings on or off

What is a dynamic configuration file (also known as a .htaccess file)?

A dynamic configuration file is an web server configuration file that allows certain aspects of the server's configuration to be modified when people view your web site in their browser. Dynamic configuration files are named .htaccess and may appear in any subdirectory of the web directory.

.htaccess files must be saved as ASCII or Plain Text, and must be uploaded to your web hosting account as text not binary.

Using dynamic configuration files, you can add new MIME type mappings, add user- and host-based authentication to files and directories, alter the form of server-parsed HTML used on your server, configure the text of messages returned when your server encounters an error, control URL mappings with redirections, and customize web response headers.

Apache documentation does not discuss dynamic configuration files explicitly, but the documentation for each configuration directive specifies whether the directive can appear in a .htaccess file. Visit the Apache Directives document and select Options. You'll see that .htaccess appears in the Context: header. This signifies that the Option directive can appear in .htaccess files.

Add new MIME types?

New MIME types can be added by including the AddType directive:

AddType <MIME type> <File extension list>

<MIME type> is the MIME type to add and <File extension list> is a list of file extensions to associate with the MIME type. A leading '.' (period) is optional preceding each file extension. The AddType directive is described in the Apache AddType directive documentation.

Add password protection to a file or directory?

Using dynamic configuration files, you can add authentication to files and directories underneath your server's web directory. Two general forms of authentication are available: user-based authentication, which requires users to enter a username and password in order to access a resource on your site, and host-based authentication, which requires that users access your site from a specific domain name, host name, or set of IP addresses. You can use either or both types of authentication on your site. Among other things, these forms of authentication can be used to implement security an intranet or add for-fee services to your otherwise-public web site.

User-based authentication

Adding user-based authentication involves two steps:

1. Create a password file containing usernames and passwords
2. Add appropriate directives to your dynamic configuration file (.htaccess)

Step 1: Create a password file containing usernames and passwords

The username/password file used in web authentication is a text file containing pairs of usernames and encrypted passwords, one per line, separated by a colon. It is usually named .htpasswd but you can name it any name that will help you remember that it's the password file. The following example illustrates the file format:

username1:encrypted-password1
username2:encrypted-password2


Notice that the passwords are encrypted, not in plain text. To create encrypted passwords, use our Handy Text Encryption Tool.

Handy Text Encryption Tool

For those adding password protection to their web pages hosted on our Shared Unix accounts, we have created this tool to allow you to encrypt your passwords for use with .htaccess and htpasswd files. More details about .htaccess can be found on the Apache web site.

Text to encrypt:

Passwords in web authentication use the same format as those in the Unix system password file, which are encrypted with the crypt(3) C system call or an equivalent function provided by a language such as Perl. The crypt(3) C function uses the standard DES encryption algorithm to turn plain text into cipher text. The encrypted password is always 13 characters long (regardless of the length of your plain text password) and may be composed of letters, numbers, '/', and '.'.

To improve security, you should place your .htpasswd file in a directory invisible to your web server, such as the private directory. Note that the file permissions must allow world reads (but not world writes) because the web server will open it as an unprivileged user.

Step 2: Add appropriate directives to your dynamic configuration file

If you haven't done so already, create a text file and name it .htaccess. Once created, put it the folder that you want to password protect. All pages in that folder will be protected. Make sure your .htaccess is a plain text file, which includes only the following directives:

AuthType Basic
AuthName "Log in now"
<limit GET PUT POST>
require valid-user
</limit>
AuthUserFile "Absolute Path to username/password File"

These directives perform the following functions:

• The require directive specifies which usernames in the password file can access the protected resource. The valid-user parameter instructs the server to accept any valid username and password that appears in the password file. If you specify the user parameter followed by individual usernames (separated by a space), only those usernames will be able to access the protected resource.
• The AuthType directive specifies the type of authentication that will occur. Basic authentication is the only type which is widely implemented, but this directive exists to support future authentication methods.
• The AuthName specifies what is known as the authorization realm or realm string. Log in now is the text displayed in the dialog box when your browser prompts you for a username and password. It is also used by the browser to determine which username and password to send when multiple authenticated resources are accessed in the same browser session. Names that include spaces must be bracketed with quotes(""). The authentication realm is also used by the browser to determine which username and password to send when multiple authenticated resources are accessed in the same browser session.
• The AuthUserFile directive specifies the path to the password file. This must be specified as an absolute path -- if specified as a relative path, the web server will look in its root directory, which is not where your content resides.

Host-based authentication

Host-based authentication is similar to user-based authentication. You can restrict access by host name (fully-qualified domain name or a subdomain) or IP address (a complete IP address or an IP network).

Assume you want to create an intranet on your EasyStreet Web site in the subdirectory intranet. Also assume your organization's domain name is example.tv. You want all hosts in your domain to be able to access this resource, as well as all hosts in the IP network 192.168.1, which is outside your domain. You would set this up with the following dynamic configuration file directives:

<FILES intranet>
order		deny, allow
deny		from all
allow		from example.tv 192.168.1
</FILES>

The deny and allow directives instruct the server which hosts should be allowed to access the given resource, in this case the intranet folder.

Further documentation on each of the directives used above:

• <Files>
• order
• deny
• allow

Absolute path to the password file?

The Absolute Path to the username/password File is in the form /services/webpages/[first_letter_of_domain]/[second_letter_of_domain]/[yourdomain.com]/[pathtofile].

With the domain hahnmeyerphotos.org, for example, placing the .htpasswd file in the private directory, the Absolute Path would be:

/services/webpages/h/a/hahnmeyerphotos.org/private/.htpasswd

You would need to change the end of the path above for your specicific domain and adjusting the end path for the directory where you've placed your .htpasswd file. Also, make sure that .htpasswd has world readable permissions.

Creating Custom 404 and other error pages

The document returned by the web server when it encounters an error can be configured via dynamic configuration files. This is done via the ErrorDocument configuration directive. Using this directive, you can associate a URL with each web error code. The URL can be a static document (such as an HTML file) or a CGI program. A complete list of web error codes can be found in the HTTP/1.1 specification (RFC 2616), but the most common error codes are:

Code	Description
401 Unauthorized	The client lacks proper authorization to access the requested document.
403 Forbidden	File permissions prevent the web server from returning the requested document.
404 Not Found	The requested document was not found.
500 Internal Server Error	The server encountered an unspecified error attempting to satisfy the client's request.

Given these codes, directives similar to the following could be used to associate a URL with each code:

ErrorDocument 401 "Denial is not just a river in Egypt. -- Stuart Smalling
ErrorDocument 403 /cgi-bin/errors.cgi
ErrorDocument 404 /not-found.html
ErrorDocument 500 http://www.acme.org/cgi-error/


Refer to the Apache ErrorDocument documentation for more details.

Set up redirections

Redirections can be used to point browsers at a new location when a resource has moved. This is accomplished with the Redirect directive, which you can include in a dynamic configuration file. The syntax of the Redirect directive is as follows:

Redirect	/<Path>		<URL>

/<Path> is the path to the file or directory that moved (specified relative to your server's document root) and <URL> is the URL to which browsers should be redirected.

Further details about the syntax of this directive can be found in the Apache Redirect documentation.

Allowing .inc or .bak files

By default, files with extensions .inc or .bak are disallowed on this server. If you have JavaScript navigation or a Server Side Include that uses files with extension .inc you will need to override this setting on our server.

1. Create a plain text file named .htaccess with the following lines:

   <Files ~ "\.(inc|bak)$">
     Order allow,deny
     Allow from all
</Files>

2. Upload this .htaccess file to your / directory. This is the level above public. Note: If you already have a file named .htaccess there, simply add the above lines to that file rather than replacing it.

Show PHP Errors

PHP error reporting is turned off by default in our server environment. To turn it on you must add an .htaccess file to your site.

1. Create a plain text file named .htaccess with the following lines or add the following lines to an existing .htaccess file:

   php_flag display_errors on
php_value error_reporting 7

2. Upload this .htaccess file to your / directory. This is the level above public. Note: If you already have a file named .htaccess there, simply add the above lines to that file rather than replacing it.

Turn off PHP magic quotes

PHP magic_quotes_gpc is turned on by default. If your database inserts have too many escapes, you need to turn this setting off by adding the following .htaccess file to your site:

1. Create a plain text file named .htaccess with the following lines or add to an existing .htaccess file:

   php_value magic_quotes_gpc 0

2. Upload this .htaccess file to your / directory. This is the level above public. Note: If you already have a file named .htaccess there, simply add the above lines to that file rather than replacing it.

Turn directory listings on or off

Normally when you navigate to a directory or folder on this web server, the files in that directory will not display because directory listings are turned off by default. If you do not have a file named index.html or other acceptable home page name, you will get an error that indicates you do not have permission to view that directory. However, if your site was migrated to this server from another EasyStreet server, we may have enabled directory listings since they were allowed in the previous environment.

Turn directory listings on

1. Create a plain text file named .htaccess with the following line or add to an existing .htaccess file:

   Options +Indexes

2. Upload this .htaccess file to your / directory. This is the level above public. Note: If you already have a file named .htaccess there, simply add the above lines to that file rather than replacing it.

Turn directory listings off

1. At the top level of your site, /, find the file named .htaccess and remove the line which reads:

   Options +Indexes

2. Upload this modified .htaccess file to your / directory. This returns your site to the default behavior, which has directory listings turned off.