Alwanza Home How To Linux - Apache Basics How To Linux
Basic Apache, Plus AccessFile Error Messages and Authentication

Starting point:  you have a recent Linux distribution loaded on your computer, and root access to it.

There are 2 basic steps to getting your Apache server running:
  • Start the Apache daemon (named httpd).
  • Make a world-readable index page.

Step 1.  Start the Apache Daemon

You start the Apache daemon in recent versions of RedHat with this command (requires root access):

service httpd start

If all went well, you saw a response that began with "Starting httpd" and ended with "[OK]":  you may skip over the next section.

If you saw a response that began with "Starting httpd" but ended in "[Failed]" or did not end in "[OK]" , it is possible that your Apache daemon is already running.  Confirm this by typing:

service httpd status

If that returns process ids, then Apache is already running.

If you received a failure notice with an error message, then you have a bug to track that is beyond the scope of these instructions.

If the "service" command was not recognized at all, make sure you are logged in as root.  On distributions other than the recent versions of RedHat, you might need to use an alternate method to start the daemon.  The alternate way is to find the httpd script (to get the path) and run it by typing its path and name on the command line.  If you don't know where the httpd script lives, you can use the following command to find it (you will need to be root):

find / -type f -name httpd

Since we might be using more information from this same find later (to set up automatic restarting of the Apache server whenever you reboot), you could also direct the results to a file.

find / -type f -name httpd>/home/username/httpd.fnd

Or better yet, send the output to both Standard Output (screen) and a file by "piping to tee".

find / -type f -name httpd | tee /home/username/httpd.fnd

Look at the list of files that were returned and find a likely candidate for starting Apache by seeing which one has "bin" or "sbin" in the path.  Then type that path and name at the command prompt.

/usr/sbin/httpd
or
/usr/sbin/httpd -k start

Substitute your path for the above.


If you want your httpd daemon to start automatically whenever you reboot, make sure to make an httpd file in the correct init directory according to your default boot level.  If you understood that, great; if not, it is a lengthy subject and I won't cover it here because different distributions handle initializing daemons at boot time in different ways.  If you used the find command above to find your httpd file, one of the responses that is not the script for starting your daemon from the command line, is your boot script.

Notice that if you have not previously provided a domain name, Apache will default to using "localhost" or "127.0.0.1" as your domain name.  This is a good beginning, and these instructions will go only a little further than that. 

Now it is time to test Apache from a browser.  Open a browser window and type the following into the address/location bar:

http://localhost

That's right, no "www", no ".com" just plain old localhost.  And while we are at it, you should also try the other default, the IP number:

http://127.0.0.1

Feather?  Is a feather showing on your Web page?  That's a good result.  If one URL produced the feather and the other one didn't, use the URL that points to the feather page as your base domain address.

If you did not get a feather at all, you are probably displaying either:
  • an index page that someone else loaded on your computer
  • a 404 (file not found error)
  • a 403 Access Forbidden error
  • "An error occurred while loading localhost. Could not connect"
For the first three errors, the solution is to create your own world-readable index page.  For the "Could not connect" error, there is a problem with your Apache daemon or your configuration file, and you will not be able to go to the next step until that issue is addressed.


Step 2.  Make a World-readable Index Page

Now we need to find your default HTML directory and put a Web page there.  If you attempt to use a find command to look for your default index.html page, you will be surprised at how many items are returned.  It seems that documentation for many of the utilities and programs on current versions of Linux are in HTML format.

A better idea is to use the find command to find your configuration file and to use the configuration file to find your default HTML directory.  Start learning to read your configuration file now, and you'll be ready for the next steps also.

find / -type f -name httpd.conf | tee /home/username/httpd_conf.fnd

If you have only one httpd.conf file you are lucky.  If you have several, you will have to test until you find the one that is working with the daemon you started.  Try starting with the one with the shortest path.

Use your favorite editor to open httpd.conf and search for an uncommented line that begins with "DocumentRoot".  This is the default HTML directory for localhost.  It is the place to put your HTML index page.

Change to your default HTML directory.  Open your favorite editor and write the following (unless you already have an index page to copy or something specific in mind).

<HTML>
<HEAD>
<title>My First Page
</title>
</HEAD>
<BODY>
<table width="90%" border="1">
<tr><td width="100%" align="center" valign="middle">
<H1>Hello World</h1>
</td></tr>
</table>
</BODY>
</HTML>


Now refresh your browser window and see if your new page is visible.  Even within localhost, the person who views the Web page through a browser, has the permissions of "world".  If your page is not visible, check to see that the permissions are set to be world-readable.  If they aren't, fix them:

chmod 644 index.html

If you have multiple httpd.conf files and you are still displaying either the feather page or a 404 rather than your own new index.html page, try another httpd.conf file, search for your DocumentRoot and copy your index.html file there.


Trick
If you start your Apache daemon using the filepath and filename method and you have multiple versions of Apache (that map to different httpd.conf configuration files on your computer), you might get the "feather" page again after creating a world-readable index page.  This is happening because your daemon has loaded a different configuration file and is pointing to a different default HTML directory.


Now that you have the Apache Web server working as "localhost", it is time to try to see if you already have it configured for Web access. 
  • If you have already arranged with your ISP to have their DNS configured to point to your server for a particular domain name, you should now try that domain name and see if you get the same page as your "localhost" page. 
  • If you do not have a domain name, but if you have a static IP address that you use for internet access (if you have DSL you might have static IP address - your ISP would know), try substituting your IP address for "localhost" and see if you get the same page.



HTACCESS Error Messages

If you have been successful so far and your index page is viewable through your browser (using either "localhost" or "127.0.0.1"), you have already identified your httpd.conf file.

In Apache, the httpd.conf file controls the Apache configuration including which directories are the default HTML directories, the default cgi-bin (and whether or not scripting is allowed at all on the Web site and what kind of scripting), and the Access file.  The httpd.conf file controls what files are displayed for error messages.

To view your default error messages, search in your httpd.conf file for "ErrorDocument".  You may have commented lines with examples.  If you also have uncommented lines, check out your default error messages by following the paths and viewing the file.  To create a custom error message the quick way, rename one of those original files and substitute your own error message in its place.  The disadvantage to using this method, is that if you are serving multiple domains, they will all display the same error message.

To use the AccessFile method instead, search in your httpd.conf file for an uncommented line that begins: AccessFileName.  Usually the default is ".htaccess".  Notice that it is possible to set a different filename as the access file name, just as it is possible to set a different default DocumentRoot.


Notes
We are about to make changes to your httpd.conf file.  Before editing your httpd.conf file, make a copy of the original:

cp httpd.conf httpd.conf_original

One more reminder:  do not put comments on the same line as commands in the httpd.conf file.


In the httpd.conf file, search for AuthConfig followed by an uncommented line beginning "AllowOverride" and change the line from:

AllowOverride None
to
AllowOverride All

If you don't have AuthConfig in your httpd.conf file, you may find it instead in a file named access.conf (in which case you have an older version of Apache).

You will have to restart your Apache daemon in order to have these changes take effect.  The Apache daemon reads the configuration file once when it starts and does not read it again until it is restarted.

service httpd restart
or
/usr/sbin/httpd -k restart    (substitute your path to httpd)

Next, create a world-readable .htaccess file in your base Web directory, and put the following line in it:

ErrorDocument    404    /custom404.html

This translates to "look in the same directory as this .htaccess file to find a file named "custom404.html".  Use that file to display 404 messages for any unassigned URL down from that path (in this directory or any of its subdirectories).

Create your own html file "custom404.html" so that the ErrorDocument defined in .htaccess is pointing to something.  Any links on that file should be absolute URLs because the 404 page can be accessed from any directory level.  If you haven't done much HTML before, just copy the index page supplied above, change the title from "My First Page" to "Error 404 - File Not Found" and change "Hello World" to "404 - File Not Found".  Then add a link (absolute URL) to your home page or a MailTo link to your email address.

for further info:

www.plinko.net/404/howto.asp?article=11



HTACCESS Authentication

For password protection, create a world-readable .htaccess file in the directory you want to protect.
Write the following in your .htaccess file:

AuthName "Protected Realm 1"
AuthType Basic
AuthUserFile /path/to/authentication/file

require valid-user


If you have not already done so, in the httpd.conf file change

AllowOverride None
to
AllowOverride All

If you have not already done so, restart your Apache daemon now to get it to reread the httpd.conf file.

Now you want to use htpasswd.   Find it in the man pages:

man htpasswd

Find your htpasswd file. 

find / -name htpasswd

If this file exists and is located in a directory on your PATH,

echo $PATH

then you can use it as a script, just by typing the filename htpasswd on your command line.  If the file is not in your path, there is a possibility that it is not compiled.  It needs to be compiled before you can use it.  Try typing the full path and filename without any arguments after it and see if you get a "help" response that begins with the word "Usage".  If you don't you will need to compile your htpasswd program.


Don't be Confused
Pay attention to the two different filenames, the hidden "flat file" virtual database, .htpasswd, and the binary script file htpasswd used to create .htpasswd.

The filename .htpasswd (like the filename .htaccess) is used by convention (and for consistency on sites that are managed by multiple administrators) rather than necessity. 

It is most intuitive that the file containing users and passwords should be in the same directory they are protecting, in a hidden file that cannot be accessed from the Web.  But it is also possible to hide the usernames and passwords in a file with an entirely different name in a directory that cannot be accessed from the Web or even with FTP.  For example, if your HTML default file was /var/www/html, you could choose either of these commands to create your virtual database:

htpasswd -c /var/www/html/protected_directory1/.htpasswd username
or
htpasswd -c /var/www/auth/directory1_users username

Just remember that the /path/to/authentication/file in the .htaccess file (or your customized equivalent) must point to the virtual database.

Inside the httpd.conf file (or access.conf file) are a few lines that prevent files beginning with ".ht" to be viewed through browsers.  This is also configurable.


To create the user authentication file and enter the first username into it, use the command:

htpasswd -c /directory/path/to/ht_users/filename username

Remember to replace "username" with a real username.  You will be prompted for a password for that user.  Enter the password, and then retype it when prompted for validation.  Next, examine the file you just created.

There is a possibility that this command did not create the file.  If it didn't, create the world-readable file yourself, retype the command, and examine the file.

What you should see is a file with one user name followed by a colon, followed by an MD5-encrypted password.  If the password is not encrypted, decide which encryption protocol you want to use and include the switch for that protocol in your commands to create the user authentication file and to add new users.

Begin your commands with:

htpasswd -m     for MD5 encryption
htpasswd -s     for SHA encryption

Test your authentication file by attempting to use your browser to display the index file in your protected directory.  Use the following HTML to create a default index page if you don't already have one:

<HTML>
<HEAD>
<title>Protected Realm #1
</title>
</HEAD>
<BODY>
<table width="100%" border="0">
<tr><td width="80%" align="center" valign="middle">
<H1>Protected Realm #1</h1>
</td></tr>
<tr><td width="80%" height="60" valign="bottom">
<H3>You have arrived in the protected directory.</H3> </td></tr>
</table>
</BODY>
</HTML>


When you attempt to link to the protected directory, you should be prompted for a password.  If you don't provide one, whether you select ok or cancel you should receive a 403 Access Forbidden page.  You will need to exit and reopen your browser in order to get the password prompt again.  This second time, provide the correct user name and password.  Now you should gain access.


Note
Authentication and encryption are two separate processes.  If you look at the URL on your password-protected page, you will notice that the URL begins with http and not https.  Without the additional process of encryption, whatever is sent over this connection (for example, user-provided information to complete Web forms) is sent in plain text and could be sniffed.


That covers basic password authentication.  For more information about your options using Apache authentication, this is a good tutorial:

www.apacheweek.com/features/userauth

 
To email please see:  contact.cgi if you have any comments or questions about this page.

Authored & created by Meryll Larkin:  12/15/02
Updated:  6/01/06