Return-Path: Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org Received: (qmail 15467 invoked by uid 500); 22 Sep 2001 19:25:28 -0000 Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@httpd.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list cvs@httpd.apache.org Received: (qmail 15456 invoked by uid 500); 22 Sep 2001 19:25:28 -0000 Delivered-To: apmail-httpd-2.0-cvs@apache.org Date: 22 Sep 2001 19:18:26 -0000 Message-ID: <20010922191826.78686.qmail@icarus.apache.org> From: rbowen@apache.org To: httpd-2.0-cvs@apache.org Subject: cvs commit: httpd-2.0/docs/manual/howto auth.html cgi.html.en footer.html header.html ssi.html.en X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N rbowen 01/09/22 12:18:26 Modified: docs/manual/howto auth.html cgi.html.en footer.html header.html ssi.html.en Log: w3c tidy to convert to xhtml. Please verify that foreign language files in here have not been screwed up. Revision Changes Path 1.4 +139 -128 httpd-2.0/docs/manual/howto/auth.html Index: auth.html =================================================================== RCS file: /home/cvs/httpd-2.0/docs/manual/howto/auth.html,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- auth.html 2001/09/19 15:27:17 1.3 +++ auth.html 2001/09/22 19:18:26 1.4 @@ -1,20 +1,21 @@ - + - + - + Authentication - + - +

Authentication

- + -
+
- - - - - -
Related Modules
-
- mod_auth
- mod_access
- 		Related Directives
-
- Allow
- AuthGroupFile
- AuthName
- AuthType
- AuthUserFile
- Deny
- Options
- Require
- -
- + + + + + + +
Related Modules
+
+ mod_auth
+ mod_access
+ 		Related Directives
+
+ Allow
+ AuthGroupFile
+ AuthName
+ AuthType
+ AuthUserFile
+ Deny
+ Options
+ Require
+
-

Authentication

+

Authentication

Authentication is any process by which you verify that someone is who they claim they are. Authorization is any process by which someone is allowed to be where they want to go, or to have information that they want to have.

-

Introduction

+

Introduction

If you have information on your web site that is sensitive or intended for only a small group of people, the techniques in this article will help you make sure that the people that see those pages are the people that you wanted to see them.

-

This article covers the "standard" way of protecting parts of your - web site that most of you are going to use.

+

This article covers the "standard" way of protecting parts + of your web site that most of you are going to use.

-

The prerequisites

+

The + prerequisites

-

The directives discussed in this article will need to go either - in your main server configuration file (typically in a +

The directives discussed in this article will need to go + either in your main server configuration file (typically in a <Directory> section), or in per-directory configuration files (.htaccess files).

-

If you plan to use .htaccess files, you will need to - have a server configuration that permits putting authentication - directives in these files. This is done with the - AllowOverride - directive, which specifies which directives, if any, may be put in - per-directory configuration files.

+

If you plan to use .htaccess files, you will + need to have a server configuration that permits putting + authentication directives in these files. This is done with the + AllowOverride + directive, which specifies which directives, if any, may be put + in per-directory configuration files.

-

Since we're talking here about authentication, you will need an - AllowOverride directive like the following:

- +

Since we're talking here about authentication, you will need + an AllowOverride directive like the following:

       AllowOverride AuthConfig
-

Or, if you are just going to put the directives directly in your - main server configuration file, you will of course need to have - write permission to that file.

+

Or, if you are just going to put the directives directly in + your main server configuration file, you will of course need to + have write permission to that file.

And you'll need to know a little bit about the directory structure of your server, in order to know where some files are kept. This should not be terribly difficult, and I'll try to make this clear when we come to that point.

-

Getting it working

+

Getting it working

Here's the basics of password protecting a directory on your server.

You'll need to create a password file. This file should be - placed somewhere not accessible from the web. This is so - that folks cannot download the password file. For example, if - your documents are served out of + placed somewhere not accessible from the web. This is so that + folks cannot download the password file. For example, if your + documents are served out of /usr/local/apache/htdocs you might want to put the password file(s) in /usr/local/apache/passwd.

To create the file, use the htpasswd utility that came - with Apache. This be located in the bin directory of - wherever you installed Apache. To create the file, type:

+ with Apache. This be located in the bin directory + of wherever you installed Apache. To create the file, type:

           htpasswd -c /usr/local/apache/passwd/password rbowen
@@ -142,15 +147,15 @@ On my server, it's located at /usr/local/apache/bin/htpasswd

-

Next, you'll need to configure the server to request a password - and tell the server which users are allowed access. You can do - this either by editing the httpd.conf file or using - an .htaccess file. For example, if you wish to - protect the directory +

Next, you'll need to configure the server to request a + password and tell the server which users are allowed access. + You can do this either by editing the httpd.conf + file or using an .htaccess file. For example, if + you wish to protect the directory /usr/local/apache/htdocs/secret, you can use the following directives, either placed in the file - /usr/local/apache/htdocs/secret/.htaccess, or placed - in httpd.conf inside a <Directory + /usr/local/apache/htdocs/secret/.htaccess, or + placed in httpd.conf inside a <Directory /usr/local/apache/apache/htdocs/secret> section.

           AuthType Basic
  @@ -159,70 +164,73 @@
           require user rbowen
-

Let's examine each of those directives individually. The Let's examine each of those directives individually. The AuthType directive selects - that method that is used to authenticate the user. The most + that method that is used to authenticate the user. The most common method is Basic, and this is the method - implemented by mod_auth. It is - important to be aware, however, that Basic authentication sends - the password from the client to the browser unencrypted. This - method should therefore not be used for highly sensitive data. - Apache supports one other authentication method: AuthType - Digest. This method is implemented by mod_auth_digest and is much - more secure. Only the most recent versions of clients are known - to support Digest authentication.

- -

The AuthName directive - sets the Realm to be used in the authentication. The - realm serves two major functions. First, the client often - presents this information to the user as part of the password - dialog box. Second, it is used by the client to determine what - password to send for a given authenticated area. So, for example, - once a client has authenticated in the "Restricted - Files" area, it will automatically retry the same password - for any area on the same server that is marked with the - "Restricted Files" Realm. Therefore, you can prevent - a user from being prompted more than once for a password by - letting multiple restricted areas share the same realm. Of - course, for security reasons, the client will always need to ask - again for the password whenever the hostname of the server - changes.

+ implemented by mod_auth. It + is important to be aware, however, that Basic authentication + sends the password from the client to the browser unencrypted. + This method should therefore not be used for highly sensitive + data. Apache supports one other authentication method: + AuthType Digest. This method is implemented by mod_auth_digest and is + much more secure. Only the most recent versions of clients are + known to support Digest authentication.

+ +

The AuthName + directive sets the Realm to be used in the + authentication. The realm serves two major functions. First, + the client often presents this information to the user as part + of the password dialog box. Second, it is used by the client to + determine what password to send for a given authenticated area. + So, for example, once a client has authenticated in the + "Restricted Files" area, it will automatically + retry the same password for any area on the same server that is + marked with the "Restricted Files" Realm. + Therefore, you can prevent a user from being prompted more than + once for a password by letting multiple restricted areas share + the same realm. Of course, for security reasons, the client + will always need to ask again for the password whenever the + hostname of the server changes.

The AuthUserFile - directive sets the path to the password file that we just created - with htpasswd. If you have a large number of users, - it can be quite slow to search through a plain text file to - authenticate the user on each request. Apache also has the - ability to store user information in fast database files. The - modules mod_auth_db and mod_auth_dbm provide the htpasswd. If you have a large number + of users, it can be quite slow to search through a plain text + file to authenticate the user on each request. Apache also has + the ability to store user information in fast database files. + The modules mod_auth_db + and mod_auth_dbm provide + the AuthDBUserFile and AuthDBMUserFile - directives respectively. These files can be created and + directives respectively. These files can be created and manipulated with the dbmmanage program. Many + href="../programs/dbmmanage.html">dbmmanage program. Many other types of authentication options are available from third - party modules in the Apache - Modules Database.

+ party modules in the Apache Modules + Database.

Finally, the require directive provides the authorization part of the process by setting the user that is allowed to access this region of the - server. In the next section, we discuss various ways to - use the require directive.

- -

Letting more than - one person in

+ server. In the next section, we discuss various ways to use the + require directive.

-

The directives above only let one person (specifically someone - with a username of rbowen) into the directory. In - most cases, you'll want to let more than one person in. This is - where the AuthGroupFile comes - in.

+

Letting more than one + person in

+ +

The directives above only let one person (specifically + someone with a username of rbowen) into the + directory. In most cases, you'll want to let more than one + person in. This is where the AuthGroupFile + comes in.

If you want to let more than one person in, you'll need to create a group file that associates group names with a list of @@ -279,7 +287,8 @@ files, and remember to reference th right one in the AuthUserFile directive.

-

Possible problems

+

Possible + problems

Because of the way that Basic authentication is specified, your username and password must be verified every time you @@ -291,16 +300,17 @@ it has to open up that file, and go down the list of users until it gets to your name. And it has to do this every time a page is loaded.

- -

A consequence of this is that there's a practical limit to how many - users you can put in one password file. This limit will vary - depending on the performance of your particular server machine, but - you can expect to see slowdowns once you get above a few hundred - entries, and may wish to consider a different authentication method - at that time.

-

What other neat - stuff can I do?

+

A consequence of this is that there's a practical limit to + how many users you can put in one password file. This limit + will vary depending on the performance of your particular + server machine, but you can expect to see slowdowns once you + get above a few hundred entries, and may wish to consider a + different authentication method at that time.

+ +

What other neat stuff can + I do?

Authentication by username and password is only part of the story. Frequently you want to let people in based on something @@ -360,12 +370,13 @@ addition to letting everyone in. What you want is to let only those folks in.

-

More information

+

More + information

-

You should also read the documentation for - mod_auth and - mod_access - which contain some more information about how this all works.

+

You should also read the documentation for mod_auth and mod_access which + contain some more information about how this all works.

1.2 +487 -434 httpd-2.0/docs/manual/howto/cgi.html.en Index: cgi.html.en =================================================================== RCS file: /home/cvs/httpd-2.0/docs/manual/howto/cgi.html.en,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- cgi.html.en 2000/12/09 19:57:35 1.1 +++ cgi.html.en 2001/09/22 19:18:26 1.2 @@ -1,405 +1,454 @@ - - - -Apache Tutorial: Dynamic Content with CGI - - - - - -

Dynamic Content with CGI

+ - - + + + + + Apache Tutorial: Dynamic Content with CGI + + + + + + + +

Dynamic Content with CGI

+ + + + + +
+ +

Dynamic Content with CGI

+ + + + + + + +
Related Modules
+
+ mod_alias
+ mod_cgi
+ 		Related Directives
+
+ AddHandler
+ Options
+ ScriptAlias
+
+ +

The CGI (Common Gateway Interface) defines a way for a web + server to interact with external content-generating programs, + which are often referred to as CGI programs or CGI scripts. It + is the simplest, and most common, way to put dynamic content on + your web site. This document will be an introduction to setting + up CGI on your Apache web server, and getting started writing + CGI programs.

+
+ +

Configuring Apache to + permit CGI

+ +

In order to get your CGI programs to work properly, you'll + need to have Apache configured to permit CGI execution. There + are several ways to do this.

+ +

ScriptAlias

+ +

The ScriptAlias directive tells Apache that a + particular directory is set aside for CGI programs. Apache will + assume that every file in this directory is a CGI program, and + will attempt to execute it, when that particular resource is + requested by a client.

- - - -
-

Dynamic Content with -CGI

- - -
-Related Modules

- -mod_alias
-mod_cgi
- -		 -Related Directives

- -AddHandler
-Options
-ScriptAlias
- -
- -

The CGI (Common Gateway Interface) defines a way for a web server -to interact with external content-generating programs, which are often -referred to as CGI programs or CGI scripts. It is the simplest, and -most common, way to put dynamic content on your web site. This -document will be an introduction to setting up CGI on your Apache web -server, and getting started writing CGI programs.

- -
-

Configuring Apache to -permit CGI

- -

In order to get your CGI programs to work properly, you'll need to -have Apache configured to permit CGI execution. There are several ways -to do this.

- -

ScriptAlias

- -

The ScriptAlias directive tells Apache that a -particular directory is set aside for CGI programs. Apache will assume -that every file in this directory is a CGI program, and will attempt to -execute it, when that particular resource is requested by a client.

- -

The ScriptAlias directive looks like:

- +

The ScriptAlias directive looks like:

           ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
- -

The example shown is from your default httpd.conf -configuration file, if you installed Apache in the default location. -The ScriptAlias directive is much like the -Alias directive, which defines a URL prefix that is to -mapped to a particular directory. Alias and -ScriptAlias are usually used for directories that are -outside of the DocumentRoot directory. The difference -between Alias and ScriptAlias is that -ScriptAlias has the added meaning that everything under -that URL prefix will be considered a CGI program. So, the example above -tells Apache that any request for a resource beginning with -/cgi-bin/ should be served from the directory -/usr/local/apache/cgi-bin/, and should be treated as a CGI -program.

- -

For example, if the URL -http://dev.rcbowen.com/cgi-bin/test.pl is requested, -Apache will attempt to execute the file -/usr/local/apache/cgi-bin/test.pl and return the output. -Of course, the file will have to exist, and be executable, and return -output in a particular way, or Apache will return an error message.

- -

CGI outside of -ScriptAlias directories

- -

CGI programs are often restricted to ScriptAlias'ed -directories for security reasons. In this way, administrators can -tightly control who is allowed to use CGI programs. However, if the -proper security precautions are taken, there is no reason why -CGI programs cannot be run from arbitrary directories. For example, -you may wish to let users have web content in their home directories -with the UserDir directive. If they want to have their -own CGI programs, but don't have access to the main -cgi-bin directory, they will need to be able to run CGI -programs elsewhere.

- -

Explicitly using -Options to permit CGI execution

- -

You could explicitly use the Options directive, inside -your main server configuration file, to specify that CGI execution was -permitted in a particular directory:

+

The example shown is from your default + httpd.conf configuration file, if you installed + Apache in the default location. The ScriptAlias + directive is much like the Alias directive, which + defines a URL prefix that is to mapped to a particular + directory. Alias and ScriptAlias are + usually used for directories that are outside of the + DocumentRoot directory. The difference between + Alias and ScriptAlias is that + ScriptAlias has the added meaning that everything + under that URL prefix will be considered a CGI program. So, the + example above tells Apache that any request for a resource + beginning with /cgi-bin/ should be served from the + directory /usr/local/apache/cgi-bin/, and should + be treated as a CGI program.

+ +

For example, if the URL + http://dev.rcbowen.com/cgi-bin/test.pl is + requested, Apache will attempt to execute the file + /usr/local/apache/cgi-bin/test.pl and return the + output. Of course, the file will have to exist, and be + executable, and return output in a particular way, or Apache + will return an error message.

+ +

CGI outside of + ScriptAlias directories

+ +

CGI programs are often restricted to + ScriptAlias'ed directories for security reasons. + In this way, administrators can tightly control who is allowed + to use CGI programs. However, if the proper security + precautions are taken, there is no reason why CGI programs + cannot be run from arbitrary directories. For example, you may + wish to let users have web content in their home directories + with the UserDir directive. If they want to have + their own CGI programs, but don't have access to the main + cgi-bin directory, they will need to be able to + run CGI programs elsewhere.

+ +

Explicitly + using Options to permit CGI execution

+ +

You could explicitly use the Options directive, + inside your main server configuration file, to specify that CGI + execution was permitted in a particular directory:

           <Directory /usr/local/apache/htdocs/somedir>
                   Options +ExecCGI
           </Directory>
- -

The above directive tells Apache to permit the execution of CGI -files. You will also need to tell the server what files are CGI files. -The following AddHandler directive tells the server -to treat all files with the cgi or pl -extension as CGI programs:

+

The above directive tells Apache to permit the execution of + CGI files. You will also need to tell the server what files are + CGI files. The following AddHandler directive + tells the server to treat all files with the cgi + or pl extension as CGI programs:

        AddHandler cgi-script cgi pl
-

.htaccess files

+

.htaccess + files

-

A .htaccess file is a way to set configuration -directives on a per-directory basis. When Apache serves a resource, it -looks in the directory from which it is serving a file for a file -called .htaccess, and, if it finds it, it will apply -directives found therein. .htaccess files can be permitted -with the AllowOverride directive, which specifies what -types of directives can appear in these files, or if they are not -allowed at all. To permit the directive we will need for this purpose, -the following configuration will be needed in your main server -configuration:

- +

A .htaccess file is a way to set configuration + directives on a per-directory basis. When Apache serves a + resource, it looks in the directory from which it is serving a + file for a file called .htaccess, and, if it finds + it, it will apply directives found therein. + .htaccess files can be permitted with the + AllowOverride directive, which specifies what + types of directives can appear in these files, or if they are + not allowed at all. To permit the directive we will need for + this purpose, the following configuration will be needed in + your main server configuration:

           AllowOverride Options
- -

In the .htaccess file, you'll need the following -directive:

+

In the .htaccess file, you'll need the + following directive:

           Options +ExecCGI
- -

which tells Apache that execution of CGI programs is permitted in -this directory.

-
-

Writing a CGI program

- -

There are two main differences between ``regular'' programming, and -CGI programming.

- -

First, all output from your CGI program must be preceded by a -MIME-type header. This is HTTP header that tells the client what sort -of content it is receiving. Most of the time, this will look like:

- +

which tells Apache that execution of CGI programs is + permitted in this directory.

+
+ +

Writing a CGI program

+ +

There are two main differences between ``regular'' + programming, and CGI programming.

+ +

First, all output from your CGI program must be preceded by + a MIME-type header. This is HTTP header that tells the client + what sort of content it is receiving. Most of the time, this + will look like:

           Content-type: text/html
-

Secondly, your output needs to be in HTML, or some other format that -a browser will be able to display. Most of the time, this will be HTML, -but occasionally you might write a CGI program that outputs a gif -image, or other non-HTML content.

- -

Apart from those two things, writing a CGI program will look a lot -like any other program that you might write.

- -

Your first CGI program

- -

The following is an example CGI program that prints one line to your -browser. Type in the following, save it to a file called -first.pl, and put it in your cgi-bin -directory.

- +

Secondly, your output needs to be in HTML, or some other + format that a browser will be able to display. Most of the + time, this will be HTML, but occasionally you might write a CGI + program that outputs a gif image, or other non-HTML + content.

+ +

Apart from those two things, writing a CGI program will look + a lot like any other program that you might write.

+ +

Your + first CGI program

+ +

The following is an example CGI program that prints one line + to your browser. Type in the following, save it to a file + called first.pl, and put it in your + cgi-bin directory.

           #!/usr/bin/perl
           print "Content-type: text/html\r\n\r\n";
           print "Hello, World.";
- -

Even if you are not familiar with Perl, you should be able to see -what is happening here. The first line tells Apache (or whatever shell -you happen to be running under) that this program can be executed by -feeding the file to the interpreter found at the location -/usr/bin/perl. The second line prints the content-type -declaration we talked about, followed by two carriage-return newline -pairs. This puts a blank line after the header, to indicate the end of -the HTTP headers, and the beginning of the body. The third line prints -the string ``Hello, World.'' And that's the end of it.

-

If you open your favorite browser and tell it to get the address

+

Even if you are not familiar with Perl, you should be able + to see what is happening here. The first line tells Apache (or + whatever shell you happen to be running under) that this + program can be executed by feeding the file to the interpreter + found at the location /usr/bin/perl. The second + line prints the content-type declaration we talked about, + followed by two carriage-return newline pairs. This puts a + blank line after the header, to indicate the end of the HTTP + headers, and the beginning of the body. The third line prints + the string ``Hello, World.'' And that's the end of it.

+

If you open your favorite browser and tell it to get the + address

           http://www.example.com/cgi-bin/first.pl
- -

or wherever you put your file, you will see the one line -Hello, World. appear in your browser window. It's not very -exciting, but once you get that working, you'll have a good chance of -getting just about anything working.

- -
-

But it's still not -working!

- -

There are four basic things that you may see in your browser when -you try to access your CGI program from the web:

- -
-
The output of your CGI program
-
Great! That means everything worked fine.

- -
The source code of your CGI program or a "POST Method Not Allowed" -message
-
That means that you have not properly configured -Apache to process your CGI program. Reread the section on configuring Apache and try to -find what you missed.

- -
A message starting with "Forbidden"
That means that there -is a permissions problem. Check the Apache -error log and the section below on file permissions.

- -
A message saying "Internal Server Error"
If you check the -Apache error log, you will probably find -that it says "Premature end of script headers", possibly along with an -error message generated by your CGI program. In this case, you will -want to check each of the below sections to see what might be preventing -your CGI program from emitting the proper HTTP headers.
-
- - -

File permissions

- -

Remember that the server does not run as you. That is, when the -server starts up, it is running with the permissions of an unprivileged -user - usually ``nobody'', or ``www'' - and so it will need extra -permissions to execute files that are owned by you. Usually, the way to -give a file sufficient permissions to be executed by ``nobody'' is to -give everyone execute permission on the file:

+

or wherever you put your file, you will see the one line + Hello, World. appear in your browser window. It's + not very exciting, but once you get that working, you'll have a + good chance of getting just about anything working.

+
+ +

But it's still not + working!

+ +

There are four basic things that you may see in your browser + when you try to access your CGI program from the web:

+ +
+
The output of your CGI program
+ +
Great! That means everything worked fine.
+
+
+ +
The source code of your CGI program or a "POST Method Not + Allowed" message
+ +
That means that you have not properly configured Apache + to process your CGI program. Reread the section on configuring Apache + and try to find what you missed.
+
+
+ +
A message starting with "Forbidden"
+ +
That means that there is a permissions problem. Check the + Apache error log and the section + below on file + permissions.
+
+
+ +
A message saying "Internal Server Error"
+ +
If you check the Apache error + log, you will probably find that it says "Premature end + of script headers", possibly along with an error message + generated by your CGI program. In this case, you will want to + check each of the below sections to see what might be + preventing your CGI program from emitting the proper HTTP + headers.
+
+ +

File + permissions

+ +

Remember that the server does not run as you. That is, when + the server starts up, it is running with the permissions of an + unprivileged user - usually ``nobody'', or ``www'' - and so it + will need extra permissions to execute files that are owned by + you. Usually, the way to give a file sufficient permissions to + be executed by ``nobody'' is to give everyone execute + permission on the file:

           chmod a+x first.pl
-

Also, if your program reads from, or writes to, any other files, -those files will need to have the correct permissions to permit -this.

- -

The exception to this is when the server is configured to use suexec. This program allows CGI programs to -be run under different user permissions, depending on which virtual -host or user home directory they are located in. Suexec has very -strict permission checking, and any failure in that checking will -result in your CGI programs failing with an "Internal Server Error". -In this case, you will need to check the suexec log file to see what -specific security check is failing.

- -

Path information

- -

When you run a program from your command line, you have certain -information that is passed to the shell without you thinking about it. -For example, you have a path, which tells the shell where it can look -for files that you reference.

- -

When a program runs through the web server as a CGI program, it does -not have that path. Any programs that you invoke in your CGI program -(like 'sendmail', for example) will need to be specified by a full -path, so that the shell can find them when it attempts to execute your -CGI program.

- -

A common manifestation of this is the path to the script interpreter -(often perl) indicated in the first line of your CGI -program, which will look something like:

- +

Also, if your program reads from, or writes to, any other + files, those files will need to have the correct permissions to + permit this.

+ +

The exception to this is when the server is configured to + use suexec. This program allows + CGI programs to be run under different user permissions, + depending on which virtual host or user home directory they are + located in. Suexec has very strict permission checking, and any + failure in that checking will result in your CGI programs + failing with an "Internal Server Error". In this case, you will + need to check the suexec log file to see what specific security + check is failing.

+ +

Path + information

+ +

When you run a program from your command line, you have + certain information that is passed to the shell without you + thinking about it. For example, you have a path, which tells + the shell where it can look for files that you reference.

+ +

When a program runs through the web server as a CGI program, + it does not have that path. Any programs that you invoke in + your CGI program (like 'sendmail', for example) will need to be + specified by a full path, so that the shell can find them when + it attempts to execute your CGI program.

+ +

A common manifestation of this is the path to the script + interpreter (often perl) indicated in the first + line of your CGI program, which will look something like:

        #!/usr/bin/perl
- -

Make sure that this is in fact the path to the interpreter.

-

Syntax errors

+

Make sure that this is in fact the path to the + interpreter.

-

Most of the time when a CGI program fails, it's because of a problem -with the program itself. This is particularly true once you get the -hang of this CGI stuff, and no longer make the above two mistakes. -Always attempt to run your program from the command line before you -test if via a browser. This will eliminate most of your problems.

- -

Error logs

- -

The error logs are your friend. Anything that goes wrong generates -message in the error log. You should always look there first. If the -place where you are hosting your web site does not permit you access to -the error log, you should probably host your site somewhere else. Learn -to read the error logs, and you'll find that almost all of your -problems are quickly identified, and quickly solved.

- -
-

What's going on behind -the scenes?

- -

As you become more advanced in CGI programming, it will become -useful to understand more about what's happening behind the scenes. -Specifically, how the browser and server communicate with one another. -Because although it's all very well to write a program that prints -``Hello, World.'', it's not particularly useful.

- -

Environment variables

- -

Environment variables are values that float around you as you use -your computer. They are useful things like your path (where the -computer searches for a the actual file implementing a command when you -type it), your username, your terminal type, and so on. For a full list -of your normal, every day environment variables, type env -at a command prompt.

- -

During the CGI transaction, the server and the browser also set -environment variables, so that they can communicate with one another. -These are things like the browser type (Netscape, IE, Lynx), the server -type (Apache, IIS, WebSite), the name of the CGI program that is being -run, and so on.

- -

These variables are available to the CGI programmer, and are half of -the story of the client-server communication. The complete list of -required variables is at http://hoohoo.ncsa.uiuc.edu/cgi/env.html

- -

This simple Perl CGI program will display all of the environment -variables that are being passed around. Two similar programs are -included in the cgi-bin directory of the Apache -distribution. Note that some variables are required, while others are -optional, so you may see some variables listed that were not in the -official list. In addition, Apache provides many different ways for -you to add your own environment variables to -the basic ones provided by default.

+

Syntax + errors

+

Most of the time when a CGI program fails, it's because of a + problem with the program itself. This is particularly true once + you get the hang of this CGI stuff, and no longer make the + above two mistakes. Always attempt to run your program from the + command line before you test if via a browser. This will + eliminate most of your problems.

+ +

Error logs

+ +

The error logs are your friend. Anything that goes wrong + generates message in the error log. You should always look + there first. If the place where you are hosting your web site + does not permit you access to the error log, you should + probably host your site somewhere else. Learn to read the error + logs, and you'll find that almost all of your problems are + quickly identified, and quickly solved.

+
+ +

What's going on behind the + scenes?

+ +

As you become more advanced in CGI programming, it will + become useful to understand more about what's happening behind + the scenes. Specifically, how the browser and server + communicate with one another. Because although it's all very + well to write a program that prints ``Hello, World.'', it's not + particularly useful.

+ +

Environment variables

+ +

Environment variables are values that float around you as + you use your computer. They are useful things like your path + (where the computer searches for a the actual file implementing + a command when you type it), your username, your terminal type, + and so on. For a full list of your normal, every day + environment variables, type env at a command + prompt.

+ +

During the CGI transaction, the server and the browser also + set environment variables, so that they can communicate with + one another. These are things like the browser type (Netscape, + IE, Lynx), the server type (Apache, IIS, WebSite), the name of + the CGI program that is being run, and so on.

+ +

These variables are available to the CGI programmer, and are + half of the story of the client-server communication. The + complete list of required variables is at http://hoohoo.ncsa.uiuc.edu/cgi/env.html

+ +

This simple Perl CGI program will display all of the + environment variables that are being passed around. Two similar + programs are included in the cgi-bin directory of + the Apache distribution. Note that some variables are required, + while others are optional, so you may see some variables listed + that were not in the official list. In addition, Apache + provides many different ways for you to add your own environment variables to + the basic ones provided by default.

        #!/usr/bin/perl
        print "Content-type: text/html\n\n";
  @@ -407,93 +456,97 @@
             print "$key --> $ENV{$key}<br>";
        }
- -

STDIN and STDOUT

-

Other communication between the server and the client happens over -standard input (STDIN) and standard output -(STDOUT). In normal everyday context, STDIN -means the keyboard, or a file that a program is given to act on, and -STDOUT usually means the console or screen.

- -

When you POST a web form to a CGI program, the data in -that form is bundled up into a special format and gets delivered to -your CGI program over STDIN. The program then can process -that data as though it was coming in from the keyboard, or from a -file

- -

The ``special format'' is very simple. A field name and its value -are joined together with an equals (=) sign, and pairs of values are -joined together with an ampersand (&). Inconvenient characters like -spaces, ampersands, and equals signs, are converted into their hex -equivalent so that they don't gum up the works. The whole data string -might look something like:

+

STDIN and + STDOUT

+

Other communication between the server and the client + happens over standard input (STDIN) and standard + output (STDOUT). In normal everyday context, + STDIN means the keyboard, or a file that a program + is given to act on, and STDOUT usually means the + console or screen.

+ +

When you POST a web form to a CGI program, the + data in that form is bundled up into a special format and gets + delivered to your CGI program over STDIN. The + program then can process that data as though it was coming in + from the keyboard, or from a file

+ +

The ``special format'' is very simple. A field name and its + value are joined together with an equals (=) sign, and pairs of + values are joined together with an ampersand (&). + Inconvenient characters like spaces, ampersands, and equals + signs, are converted into their hex equivalent so that they + don't gum up the works. The whole data string might look + something like:

        name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
- -

You'll sometimes also see this type of string appended to the a URL. -When that is done, the server puts that string into the environment -variable called QUERY_STRING. That's called a -GET request. Your HTML form specifies whether a -GET or a POST is used to deliver the data, by -setting the METHOD attribute in the FORM -tag.

- -

Your program is then responsible for splitting that string up into -useful information. Fortunately, there are libraries and modules -available to help you process this data, as well as handle other of the -aspects of your CGI program.

- -
-

CGI modules/libraries

- -

When you write CGI programs, you should consider using a code -library, or module, to do most of the grunt work for you. This leads to -fewer errors, and faster development.

- -

If you're writing CGI programs in Perl, modules are available on CPAN. The most popular module for this -purpose is CGI.pm. You might also consider CGI::Lite, which implements -a minimal set of functionality, which is all you need in most -programs.

- -

If you're writing CGI programs in C, there are a variety of options. -One of these is the CGIC library, from http://www.boutell.com/cgic/

- -
-

For more information

- -

There are a large number of CGI resources on the web. You can -discuss CGI problems with other users on the Usenet group -comp.infosystems.www.authoring.cgi. And the -servers mailing list from -the HTML Writers Guild is a great source of answers to your questions. -You can find out more at http://www.hwg.org/lists/hwg-servers/

- -

And, of course, you should probably read the CGI specification, -which has all the details on the operation of CGI programs. You can -find the original version at the NCSA and there is -an updated draft at the Common Gateway Interface RFC -project.

- -

When you post a question about a CGI problem that you're having, -whether to a mailing list, or to a newsgroup, make sure you provide -enough information about what happened, what you expected to happen, -and how what actually happened was different, what server you're -running, what language your CGI program was in, and, if possible, the -offending code. This will make finding your problem much simpler.

- -

Note that questions about CGI problems should never -be posted to the Apache bug database unless you are sure you have found -a problem in the Apache source code.

- - - +

You'll sometimes also see this type of string appended to + the a URL. When that is done, the server puts that string into + the environment variable called QUERY_STRING. + That's called a GET request. Your HTML form + specifies whether a GET or a POST is + used to deliver the data, by setting the METHOD + attribute in the FORM tag.

+ +

Your program is then responsible for splitting that string + up into useful information. Fortunately, there are libraries + and modules available to help you process this data, as well as + handle other of the aspects of your CGI program.

+
+ +

CGI + modules/libraries

+ +

When you write CGI programs, you should consider using a + code library, or module, to do most of the grunt work for you. + This leads to fewer errors, and faster development.

+ +

If you're writing CGI programs in Perl, modules are + available on CPAN. The most + popular module for this purpose is CGI.pm. You might also + consider CGI::Lite, which implements a minimal set of + functionality, which is all you need in most programs.

+ +

If you're writing CGI programs in C, there are a variety of + options. One of these is the CGIC library, from http://www.boutell.com/cgic/

+
+ +

For + more information

+ +

There are a large number of CGI resources on the web. You + can discuss CGI problems with other users on the Usenet group + comp.infosystems.www.authoring.cgi. And the -servers mailing + list from the HTML Writers Guild is a great source of answers + to your questions. You can find out more at http://www.hwg.org/lists/hwg-servers/

+ +

And, of course, you should probably read the CGI + specification, which has all the details on the operation of + CGI programs. You can find the original version at the NCSA + and there is an updated draft at the Common Gateway Interface + RFC project.

+ +

When you post a question about a CGI problem that you're + having, whether to a mailing list, or to a newsgroup, make sure + you provide enough information about what happened, what you + expected to happen, and how what actually happened was + different, what server you're running, what language your CGI + program was in, and, if possible, the offending code. This will + make finding your problem much simpler.

+ +

Note that questions about CGI problems should + never be posted to the Apache bug database + unless you are sure you have found a problem in the Apache + source code.

+ + 1.2 +17 -6 httpd-2.0/docs/manual/howto/footer.html Index: footer.html =================================================================== RCS file: /home/cvs/httpd-2.0/docs/manual/howto/footer.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- footer.html 2000/12/09 19:57:35 1.1 +++ footer.html 2001/09/22 19:18:26 1.2 @@ -1,8 +1,19 @@ -
+ -

- Apache HTTP Server Version 2.0 -

+ + + -Index -Home + + + + +
+ +

Apache HTTP Server Version 2.0

+ Index + Home + + + 1.2 +19 -6 httpd-2.0/docs/manual/howto/header.html Index: header.html =================================================================== RCS file: /home/cvs/httpd-2.0/docs/manual/howto/header.html,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- header.html 2000/12/09 19:57:35 1.1 +++ header.html 2001/09/22 19:18:26 1.2 @@ -1,6 +1,19 @@ -
- [APACHE DOCUMENTATION] -

- Apache HTTP Server Version 2.0 -

-
+ + + + + + + + + + +
+ [APACHE DOCUMENTATION] + +

Apache HTTP Server Version 2.0

+
+ + + 1.7 +419 -392 httpd-2.0/docs/manual/howto/ssi.html.en Index: ssi.html.en =================================================================== RCS file: /home/cvs/httpd-2.0/docs/manual/howto/ssi.html.en,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- ssi.html.en 2001/09/05 01:26:24 1.6 +++ ssi.html.en 2001/09/22 19:18:26 1.7 @@ -1,464 +1,490 @@ - - - -Apache Tutorial: Introduction to Server Side Includes - - - - - -

Apache Tutorial: Introduction to Server Side -Includes

- - - - - - - -
-

Apache -Tutorial: Introduction to Server Side Includes

- - - - - - -
Related Modules
-
- mod_include
-mod_cgi
-mod_expires
- 		Related Directives
-
- Options
-XBitHack
-AddType
-SetOutputFilter
-BrowserMatchNoCase
- -
- -

This article deals with Server Side Includes, usually called simply -SSI. In this article, I'll talk about configuring your server to permit -SSI, and introduce some basic SSI techniques for adding dynamic content -to your existing HTML pages.

- -

In the latter part of the article, we'll talk about some of the -somewhat more advanced things that can be done with SSI, such as -conditional statements in your SSI directives.

- -
-

What are SSI?

- -

SSI (Server Side Includes) are directives that are placed in HTML -pages, and evaluated on the server while the pages are being served. -They let you add dynamically generated content to an existing HTML -page, without having to serve the entire page via a CGI program, or -other dynamic technology.

- -

The decision of when to use SSI, and when to have your page entirely -generated by some program, is usually a matter of how much of the page -is static, and how much needs to be recalculated every time the page is -served. SSI is a great way to add small pieces of information, such as -the current time. But if a majority of your page is being generated at -the time that it is served, you need to look for some other -solution.

- -
-

Configuring your -server to permit SSI

- -

To permit SSI on your server, you must have the following directive -either in your httpd.conf file, or in a -.htaccess file:

+ + + + + + Apache Tutorial: Introduction to Server Side + Includes + + + + + + + +

Apache Tutorial: Introduction to Server Side + Includes

+ + + + + +
+ +

Apache + Tutorial: Introduction to Server Side Includes

+ + + + + + + +
Related Modules
+
+ mod_include
+ mod_cgi
+ mod_expires
+ 		Related Directives
+
+ Options
+ XBitHack
+ AddType
+ SetOutputFilter
+ BrowserMatchNoCase
+
+ +

This article deals with Server Side Includes, usually called + simply SSI. In this article, I'll talk about configuring your + server to permit SSI, and introduce some basic SSI techniques + for adding dynamic content to your existing HTML pages.

+ +

In the latter part of the article, we'll talk about some of + the somewhat more advanced things that can be done with SSI, + such as conditional statements in your SSI directives.

+
+ +

What are SSI?

+ +

SSI (Server Side Includes) are directives that are placed in + HTML pages, and evaluated on the server while the pages are + being served. They let you add dynamically generated content to + an existing HTML page, without having to serve the entire page + via a CGI program, or other dynamic technology.

+ +

The decision of when to use SSI, and when to have your page + entirely generated by some program, is usually a matter of how + much of the page is static, and how much needs to be + recalculated every time the page is served. SSI is a great way + to add small pieces of information, such as the current time. + But if a majority of your page is being generated at the time + that it is served, you need to look for some other + solution.

+
+ +

Configuring your server + to permit SSI

+ +

To permit SSI on your server, you must have the following + directive either in your httpd.conf file, or in a + .htaccess file:

           Options +Includes
-

This tells Apache that you want to permit files to be parsed for SSI -directives.

+

This tells Apache that you want to permit files to be parsed + for SSI directives.

-

Not just any file is parsed for SSI directives. You have to tell -Apache which files should be parsed. There are two ways to do this. You -can tell Apache to parse any file with a particular file extension, -such as .shtml, with the following directives:

- +

Not just any file is parsed for SSI directives. You have to + tell Apache which files should be parsed. There are two ways to + do this. You can tell Apache to parse any file with a + particular file extension, such as .shtml, with + the following directives:

           AddType text/html .shtml
           <FilesMatch "\.shtml(\..+)?$">
             SetOutputFilter INCLUDES
           </FilesMatch>
- -

One disadvantage to this approach is that if you wanted to add SSI -directives to an existing page, you would have to change the name of -that page, and all links to that page, in order to give it a -.shtml extension, so that those directives would be -executed.

-

The other method is to use the XBitHack directive:

+

One disadvantage to this approach is that if you wanted to + add SSI directives to an existing page, you would have to + change the name of that page, and all links to that page, in + order to give it a .shtml extension, so that those + directives would be executed.

+

The other method is to use the XBitHack + directive:

           XBitHack on
-

XBitHack tells Apache to parse files for SSI directives -if they have the execute bit set. So, to add SSI directives to an -existing page, rather than having to change the file name, you would -just need to make the file executable using chmod.

- +

XBitHack tells Apache to parse files for SSI + directives if they have the execute bit set. So, to add SSI + directives to an existing page, rather than having to change + the file name, you would just need to make the file executable + using chmod.

           chmod +x pagename.html
- -

A brief comment about what not to do. You'll occasionally see people -recommending that you just tell Apache to parse all .html -files for SSI, so that you don't have to mess with .shtml -file names. These folks have perhaps not heard about -XBitHack. The thing to keep in mind is that, by doing -this, you're requiring that Apache read through every single file that -it sends out to clients, even if they don't contain any SSI directives. -This can slow things down quite a bit, and is not a good idea.

- -

Of course, on Windows, there is no such thing as an execute bit to -set, so that limits your options a little.

- -

In its default configuration, Apache does not send the last modified -date or content length HTTP headers on SSI pages, because these values are -difficult to calculate for dynamic content. This can prevent your -document from being cached, and result in slower perceived client -performance. There are two ways to solve this:

- -
    - -
  1. Use the XBitHack Full configuration. This tells -Apache to determine the last modified date by looking only at the date -of the originally requested file, ignoring the modification date of -any included files.
    2. - -
  2. Use the directives provided by mod_expires to set an explicit -expiration time on your files, thereby letting browsers and proxies -know that it is acceptable to cache them.
    3. -
+

A brief comment about what not to do. You'll occasionally + see people recommending that you just tell Apache to parse all + .html files for SSI, so that you don't have to + mess with .shtml file names. These folks have + perhaps not heard about XBitHack. The thing to + keep in mind is that, by doing this, you're requiring that + Apache read through every single file that it sends out to + clients, even if they don't contain any SSI directives. This + can slow things down quite a bit, and is not a good idea.

+ +

Of course, on Windows, there is no such thing as an execute + bit to set, so that limits your options a little.

+ +

In its default configuration, Apache does not send the last + modified date or content length HTTP headers on SSI pages, + because these values are difficult to calculate for dynamic + content. This can prevent your document from being cached, and + result in slower perceived client performance. There are two + ways to solve this:

+ +
    +
  1. Use the XBitHack Full configuration. This + tells Apache to determine the last modified date by looking + only at the date of the originally requested file, ignoring + the modification date of any included files.
    2. + +
  2. Use the directives provided by mod_expires to set an + explicit expiration time on your files, thereby letting + browsers and proxies know that it is acceptable to cache + them.
    3. +
+
+

Basic + SSI directives

-
-

Basic SSI directives

- -

SSI directives have the following syntax:

- +

SSI directives have the following syntax:

           <!--#element attribute=value attribute=value ... -->
- -

It is formatted like an HTML comment, so if you don't have SSI -correctly enabled, the browser will ignore it, but it will still be -visible in the HTML source. If you have SSI correctly configured, the -directive will be replaced with its results.

- -

The element can be one of a number of things, and we'll talk some -more about most of these in the next installment of this series. For -now, here are some examples of what you can do with SSI

-

Today's date

+

It is formatted like an HTML comment, so if you don't have + SSI correctly enabled, the browser will ignore it, but it will + still be visible in the HTML source. If you have SSI correctly + configured, the directive will be replaced with its + results.

+ +

The element can be one of a number of things, and we'll talk + some more about most of these in the next installment of this + series. For now, here are some examples of what you can do with + SSI

+

Today's + date

           <!--#echo var="DATE_LOCAL" -->
-

The echo element just spits out the value of a -variable. There are a number of standard variables, which include the -whole set of environment variables that are available to CGI programs. -Also, you can define your own variables with the set -element.

- -

If you don't like the format in which the date gets printed, you can -use the config element, with a timefmt -attribute, to modify that formatting.

- +

The echo element just spits out the value of a + variable. There are a number of standard variables, which + include the whole set of environment variables that are + available to CGI programs. Also, you can define your own + variables with the set element.

+ +

If you don't like the format in which the date gets printed, + you can use the config element, with a + timefmt attribute, to modify that formatting.

           <!--#config timefmt="%A %B %d, %Y" -->
           Today is <!--#echo var="DATE_LOCAL" -->
- -

Modification date of the -file

+

Modification date of the + file

           This document last modified <!--#flastmod file="index.html" -->
- -

This element is also subject to timefmt format -configurations.

- -

Including the -results of a CGI program

-

This is one of the more common uses of SSI - to output the results -of a CGI program, such as everybody's favorite, a ``hit counter.''

+

This element is also subject to timefmt format + configurations.

+

Including the results + of a CGI program

+ +

This is one of the more common uses of SSI - to output the + results of a CGI program, such as everybody's favorite, a ``hit + counter.''

           <!--#include virtual="/cgi-bin/counter.pl" -->
+
-
-

Additional examples

+

Additional examples

-

Following are some specific examples of things you can do in your -HTML documents with SSI.

- -
-

When was this document -modified?

- -

Earlier, we mentioned that you could use SSI to inform the user when -the document was most recently modified. However, the actual method for -doing that was left somewhat in question. The following code, placed in -your HTML document, will put such a time stamp on your page. Of course, -you will have to have SSI correctly enabled, as discussed above.

- +

Following are some specific examples of things you can do in + your HTML documents with SSI.

+
+ +

When was this document + modified?

+ +

Earlier, we mentioned that you could use SSI to inform the + user when the document was most recently modified. However, the + actual method for doing that was left somewhat in question. The + following code, placed in your HTML document, will put such a + time stamp on your page. Of course, you will have to have SSI + correctly enabled, as discussed above.

           <!--#config timefmt="%A %B %d, %Y" -->
           This file last modified <!--#flastmod file="ssi.shtml" -->
- -

Of course, you will need to replace the ssi.shtml with -the actual name of the file that you're referring to. This can be -inconvenient if you're just looking for a generic piece of code that -you can paste into any file, so you probably want to use the -LAST_MODIFIED variable instead:

+

Of course, you will need to replace the + ssi.shtml with the actual name of the file that + you're referring to. This can be inconvenient if you're just + looking for a generic piece of code that you can paste into any + file, so you probably want to use the + LAST_MODIFIED variable instead:

           <!--#config timefmt="%D" -->
           This file last modified <!--#echo var="LAST_MODIFIED" -->
-

For more details on the timefmt format, go to your -favorite search site and look for ctime. The syntax is the -same.

- -
-

Including a standard -footer

- -

If you are managing any site that is more than a few pages, you may -find that making changes to all those pages can be a real pain, -particularly if you are trying to maintain some kind of standard look -across all those pages.

- -

Using an include file for a header and/or a footer can reduce the -burden of these updates. You just have to make one footer file, and -then include it into each page with the include SSI -command. The include element can determine what file to -include with either the file attribute, or the -virtual attribute. The file attribute is a -file path, relative to the current directory. That means that -it cannot be an absolute file path (starting with /), nor can it -contain ../ as part of that path. The virtual attribute is -probably more useful, and should specify a URL relative to the document -being served. It can start with a /, but must be on the same server as -the file being served.

- +

For more details on the timefmt format, go to + your favorite search site and look for ctime. The + syntax is the same.

+
+ +

Including a standard + footer

+ +

If you are managing any site that is more than a few pages, + you may find that making changes to all those pages can be a + real pain, particularly if you are trying to maintain some kind + of standard look across all those pages.

+ +

Using an include file for a header and/or a footer can + reduce the burden of these updates. You just have to make one + footer file, and then include it into each page with the + include SSI command. The include + element can determine what file to include with either the + file attribute, or the virtual + attribute. The file attribute is a file path, + relative to the current directory. That means that it + cannot be an absolute file path (starting with /), nor can it + contain ../ as part of that path. The virtual + attribute is probably more useful, and should specify a URL + relative to the document being served. It can start with a /, + but must be on the same server as the file being served.

           <!--#include virtual="/footer.html" -->
- -

I'll frequently combine the last two things, putting a -LAST_MODIFIED directive inside a footer file to be -included. SSI directives can be contained in the included file, and -includes can be nested - that is, the included file can include another -file, and so on.

-
-

What else can I config?

+

I'll frequently combine the last two things, putting a + LAST_MODIFIED directive inside a footer file to be + included. SSI directives can be contained in the included file, + and includes can be nested - that is, the included file can + include another file, and so on.

+
-

In addition to being able to config the time format, -you can also config two other things.

+

What + else can I config?

-

Usually, when something goes wrong with your SSI directive, you get -the message

+

In addition to being able to config the time + format, you can also config two other things.

+

Usually, when something goes wrong with your SSI directive, + you get the message

           [an error occurred while processing this directive]
-

If you want to change that message to something else, you can do so -with the errmsg attribute to the config -element:

- +

If you want to change that message to something else, you + can do so with the errmsg attribute to the + config element:

           <!--#config errmsg="[It appears that you don't know how to use SSI]" -->
- -

Hopefully, end users will never see this message, because you will -have resolved all the problems with your SSI directives before your -site goes live. (Right?)

- -

And you can config the format in which file sizes are -returned with the sizefmt attribute. You can specify -bytes for a full count in bytes, or abbrev -for an abbreviated number in Kb or Mb, as appropriate.

- -
-

Executing commands

- -

I expect that I'll have an article some time in the coming months -about using SSI with small CGI programs. For now, here's something else -that you can do with the exec element. You can actually -have SSI execute a command using the shell (/bin/sh, to be -precise - or the DOS shell, if you're on Win32). The following, for -example, will give you a directory listing.

+

Hopefully, end users will never see this message, because + you will have resolved all the problems with your SSI + directives before your site goes live. (Right?)

+ +

And you can config the format in which file + sizes are returned with the sizefmt attribute. You + can specify bytes for a full count in bytes, or + abbrev for an abbreviated number in Kb or Mb, as + appropriate.

+
+ +

Executing commands

+ +

I expect that I'll have an article some time in the coming + months about using SSI with small CGI programs. For now, here's + something else that you can do with the exec + element. You can actually have SSI execute a command using the + shell (/bin/sh, to be precise - or the DOS shell, + if you're on Win32). The following, for example, will give you + a directory listing.

           <pre>
           <!--#exec cmd="ls" -->
           </pre>
-

or, on Windows

- +

or, on Windows

           <pre>
           <!--#exec cmd="dir" -->
           </pre>
- -

You might notice some strange formatting with this directive on -Windows, because the output from dir contains the string -``<dir>'' in it, which confuses browsers.

- -

Note that this feature is exceedingly dangerous, as it will execute -whatever code happens to be embedded in the exec tag. If -you have any situation where users can edit content on your web pages, -such as with a ``guestbook'', for example, make sure that you have this -feature disabled. You can allow SSI, but not the exec -feature, with the IncludesNOEXEC argument to the -Options directive.

- -
-

Advanced SSI techniques

- -

In addition to spitting out content, Apache SSI gives you the option -of setting variables, and using those variables in comparisons and -conditionals.

- -

Caveat

- -

Most of the features discussed in this article are only available to -you if you are running Apache 1.2 or later. Of course, if you are not -running Apache 1.2 or later, you need to upgrade immediately, if not -sooner. Go on. Do it now. We'll wait.

- -
-

Setting variables

- -

Using the set directive, you can set variables for -later use. We'll need this later in the discussion, so we'll talk about -it here. The syntax of this is as follows:

+

You might notice some strange formatting with this directive + on Windows, because the output from dir contains + the string ``<dir>'' in it, which confuses + browsers.

+ +

Note that this feature is exceedingly dangerous, as it will + execute whatever code happens to be embedded in the + exec tag. If you have any situation where users + can edit content on your web pages, such as with a + ``guestbook'', for example, make sure that you have this + feature disabled. You can allow SSI, but not the + exec feature, with the IncludesNOEXEC + argument to the Options directive.

+
+ +

Advanced SSI techniques

+ +

In addition to spitting out content, Apache SSI gives you + the option of setting variables, and using those variables in + comparisons and conditionals.

+ +

Caveat

+ +

Most of the features discussed in this article are only + available to you if you are running Apache 1.2 or later. Of + course, if you are not running Apache 1.2 or later, you need to + upgrade immediately, if not sooner. Go on. Do it now. We'll + wait.

+
+ +

Setting + variables

+ +

Using the set directive, you can set variables + for later use. We'll need this later in the discussion, so + we'll talk about it here. The syntax of this is as follows:

           <!--#set var="name" value="Rich" -->
- -

In addition to merely setting values literally like that, you can -use any other variable, including, for example, environment variables, -or some of the variables we discussed in the last article (like -LAST_MODIFIED, for example) to give values to your -variables. You will specify that something is a variable, rather than a -literal string, by using the dollar sign ($) before the name of the -variable.

+

In addition to merely setting values literally like that, + you can use any other variable, including, for example, + environment variables, or some of the variables we discussed in + the last article (like LAST_MODIFIED, for example) + to give values to your variables. You will specify that + something is a variable, rather than a literal string, by using + the dollar sign ($) before the name of the variable.

           <!--#set var="modified" value="$LAST_MODIFIED" -->
-

To put a literal dollar sign into the value of your variable, you -need to escape the dollar sign with a backslash.

- +

To put a literal dollar sign into the value of your + variable, you need to escape the dollar sign with a + backslash.

           <!--#set var="cost" value="\$100" -->
- -

Finally, if you want to put a variable in the midst of a longer -string, and there's a chance that the name of the variable will run up -against some other characters, and thus be confused with those -characters, you can place the name of the variable in braces, to remove -this confusion. (It's hard to come up with a really good example of -this, but hopefully you'll get the point.)

+

Finally, if you want to put a variable in the midst of a + longer string, and there's a chance that the name of the + variable will run up against some other characters, and thus be + confused with those characters, you can place the name of the + variable in braces, to remove this confusion. (It's hard to + come up with a really good example of this, but hopefully + you'll get the point.)

           <!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" -->
- -
-

Conditional expressions

+
-

Now that we have variables, and are able to set and compare their -values, we can use them to express conditionals. This lets SSI be a -tiny programming language of sorts. mod_include provides -an if, elif, else, -endif structure for building conditional statements. This -allows you to effectively generate multiple logical pages out of one -actual page.

+

Conditional expressions

-

The structure of this conditional construct is:

+

Now that we have variables, and are able to set and compare + their values, we can use them to express conditionals. This + lets SSI be a tiny programming language of sorts. + mod_include provides an if, + elif, else, endif + structure for building conditional statements. This allows you + to effectively generate multiple logical pages out of one + actual page.

+

The structure of this conditional construct is:

           <!--#if expr="test_condition" -->
       <!--#elif expr="test_condition" -->
  @@ -466,25 +492,27 @@
       <!--#endif -->
-

A test_condition can be any sort of logical comparison - -either comparing values to one another, or testing the ``truth'' of a -particular value. (A given string is true if it is nonempty.) For a -full list of the comparison operators available to you, see the -mod_include documentation. Here are some examples of how -one might use this construct.

+

A test_condition can be any sort of logical + comparison - either comparing values to one another, or testing + the ``truth'' of a particular value. (A given string is true if + it is nonempty.) For a full list of the comparison operators + available to you, see the mod_include + documentation. Here are some examples of how one might use this + construct.

-

In your configuration file, you could put the following line:

- +

In your configuration file, you could put the following + line:

           BrowserMatchNoCase macintosh Mac
           BrowserMatchNoCase MSIE InternetExplorer
- -

This will set environment variables ``Mac'' and ``InternetExplorer'' -to true, if the client is running Internet Explorer on a Macintosh.

-

Then, in your SSI-enabled document, you might do the following:

+

This will set environment variables ``Mac'' and + ``InternetExplorer'' to true, if the client is running Internet + Explorer on a Macintosh.

+

Then, in your SSI-enabled document, you might do the + following:

           <!--#if expr="${Mac} && ${InternetExplorer}" -->
           Apologetic text goes here
  @@ -492,28 +520,27 @@
           Cool JavaScript code goes here
           <!--#endif -->
- -

Not that I have anything against IE on Macs - I just struggled for a -few hours last week trying to get some JavaScript working on IE on a -Mac, when it was working everywhere else. The above was the interim -workaround.

- -

Any other variable (either ones that you define, or normal -environment variables) can be used in conditional statements. With -Apache's ability to set environment variables with the -SetEnvIf directives, and other related directives, this -functionality can let you do some pretty involved dynamic stuff without -ever resorting to CGI.

- -
-

Conclusion

- -

SSI is certainly not a replacement for CGI, or other technologies -used for generating dynamic web pages. But it is a great way to add -small amounts of dynamic content to pages, without doing a lot of extra -work.

- - +

Not that I have anything against IE on Macs - I just + struggled for a few hours last week trying to get some + JavaScript working on IE on a Mac, when it was working + everywhere else. The above was the interim workaround.

+ +

Any other variable (either ones that you define, or normal + environment variables) can be used in conditional statements. + With Apache's ability to set environment variables with the + SetEnvIf directives, and other related directives, + this functionality can let you do some pretty involved dynamic + stuff without ever resorting to CGI.

+
+ +

Conclusion

+ +

SSI is certainly not a replacement for CGI, or other + technologies used for generating dynamic web pages. But it is a + great way to add small amounts of dynamic content to pages, + without doing a lot of extra work.

+ +