      |
|
|
W3U Customer Support Using Server Side Includes (SSI) Note that this is a Chapter extracted from Eric Herrmann's Book, Teach Yourself PERL in a Week. This excellent book was on-line and available for downloading at the time it was placed it in the W3U FAQs.
Using Server Side Include Commands In the last chapter, you learned about the environment of CGI programming and the how the server communicates with the browser. Today, without using any special programming languages, gotos, if then else statements, or any other complex programming structures, you will learn how to build dynamic Web pages. In this chapter, you will discover Server Side Include commands. In particular, you will learn the following:
This transition from the unchanging Web page to the Web page that can interact with your Web client can begin with very little programming expertise. Instead of writing code to perform dynamic and useful tasks, you can make use of commands called server side includes. Server side includes are special HTML-like commands that your server executes for you as it parses your HTML file. Server side includes probably were started to handle the desire to include a common file inside a bunch of different files. The most common use for this utility is a signature file, or company logo, that you want to add to every file you create. The Include file resides on the server and is included whenever any HTML file that contains the include command is requested, which is how you get the term server side include (SSI). Using SSI NegativesAs with every other neat and cool thing you can do, server side includes are somewhat of a two-edged sword. The server has to do a lot more work to process these includes. When the server returns an HTML file, it generates the appropriate response headers and sends the HTML file back to the client. No fuss, and very little work. When the server executes a CGI program, a compiler or interpreter executes your program. Your CGI program should generate some HTTP response headers, and then the HTML file server's job is to generate any additional required HTTP response headers and pass the CGI-generated HTML back to the client/browser. When the server returns a file with SSI commands in it, however, it must read each line of the file looking for the special SSI command syntax. This is called parsing a file. SSI commands can appear anywhere in your HTML file. This means that your server must make a special effort to find the commands in your HTML file. This parsing of files puts an extra burden on your server. That also means that SSI files are slower when returned to your Web client than regular HTML files. The more SSI files your server has to handle, the more processing load on your server, and as a consequence, the slower your server operates. Do not let this stop you from using server side includes; just be aware of the cost and benefits from using SSI files. At this point, you should be wondering how the server knows whether to parse a file looking for SSI commands. How does the server know what those commands look like, anyway? And do SSI commands work on every server? First of all, there are special files on your server that define whether SSI commands will be allowed on your system. And then there are other files that define which files will be parsed for SSI commands, and which files will be treated as CGI programs. Understanding How Server Side Includes WorkBefore you go any further, you must be warned that server side includes do not work on the CERN server. By the time you read this book, that may no longer be true. There are rumors that CERN is coming out with a new version of its HTTP server that includes server side includes. The NCSA server—currently the most popular server on the Net—and several other HTTP servers support server side includes. Next, server side includes have to be enabled by your System Administrator before they will work. Server side includes require the server to do more work with every SSI document that is handled by the server. As you learned in the preceding chapter, the server is responsible for finding, reading, formatting, and outputting the headers and HTML files requested by the client. So the System Administrator for your server makes several decisions that affect whether you can use server side includes and how much of them are enabled for you. Enabling or Not Enabling Server Side IncludesThe first decision is whether to allow server side includes at all on the server. For the most part, your local Internet provider wants to give you all the freedom it can on your server. So most System Administrators decide to turn on server side includes. Because of the extra burden placed on the server, however, limitations are placed on the types of files that can have SSI commands. This limitation is based on the ending characters on each file name, called the file name extension. Usually, it's something like .shmtl. So any file that ends in .shmtl will be handled as an SSI file by the server. The filename extension is set using the AddType directive in the srm.conf file, both of which are described later in this chapter. In order for server side includes to work, the server has to read every line of every SSI file looking for the special SSI commands. There is a significant extra computing and disk-access burden placed on any server that has to parse its files before sending them back to the client. Usually, that burden is not so great that server side includes get turned off. But if a site is very, very, very busy, and it cannot handle all the traffic it is getting, one way to deal with server overload is to turn off server side includes. Using the Options DirectiveIn order to enable SSI commands at all, the various directories that can use SSI commands must be enabled. This is done by modifying a file called access.conf. The access.conf file controls each directory's capability to execute different types of WWW services. In this case, you are interested in SSI commands. The access.conf file is discussed in detail in Chapter 14, "Security." Your current interest is in enabling SSI commands for your server. This is done with the Options directive. On my server, the Options directive is set to All: Options All. This means that all features are enabled in the directory or directories identified with the Options All command. My server allows SSI commands in all directories under the document root. The document root consists of all the directories that are accessible to normal users and Web visitors. My life is a lot easier because of this, and it's one of the reasons I use this server. If your server is not enabled so that you can use server side includes, send e-mail to your System Administrator or find another server. If you are just interested in enabling SSI commands, you should set the Options directive to Includes: Options Includes. This enables all the available SSI features. For security reasons, you may see your server set to Options IncludesNoExec This enables you to use server side includes but disables the SSI exec command. The access.conf file and its directives are covered in detail in Chapter 14, so accept this outline of how to set up server side includes on your server. For a complete tutorial on setting up an NCSA HTTPd server, see http://hoohoo.ncsa.uiuc.edu/docs/tutorials Top Using the AddType Command for Server Side IncludesNow that you can add SSI commands to your directory, the server must decide whether to parse all files or just special files. Usually, the server limits SSI parsing to a special file type, as described previously. This is done by modifying the srm.conf file. The srm.conf file is usually in a directory named conf, below one of the top-level directories of your server. Conf stands for configuration, so all the files that manage the configuration of your server should be under the conf directory. This is not mandatory; it's just neater. Using The srm.conf FileIn the conf directory, there should be a file called srm.conf. This is the file that decides which files will be parsed for SSI commands. Remember that your goal is to allow the use of SSI commands but limit their impact on the server. Inside this file is the command AddType. The AddType command sets the file-name extension type for various applications. A typical srm.conf file is shown in Listing 3.1; this shows a partial listing of the srm.conf file so that you can get a good feel for how the AddType command fits into the overall srm.conf file. Only a few of the commands have been deleted. These deleted commands were adding similar types, and do not change the outline of the srm.conf file.
01: DocumentRoot /usr/local/business/http/accn.com
Toward the end of Listing 3.1, you can see several AddType commands. The first AddType command adds a subtype to the to the MIME text type. The AddType directive allows the server to add new MIME types or subtypes to its list of valid types. The MIME type tells the server what type of document it is managing. The srm.conf file is not responsible for telling the server about all the types it needs to handle. As you can see from Listing 3.1, however, several new types and subtypes have been added to the server's basic types. You should be interested in the x-server-parsed type. This is a subtype of the MIME text type. The beginning x in the subtype definition defines a new or experimental type. Any files with the extension shtml will be managed as x-parsed-HTML files. So any file with the shtml extension will be parsed by the server. Name all files that include SSI directives with the extension defined in your srm.conf file. This usually will be shtml. DON'T use just any extension for your files that include SSI commands. Do check out the srm.conf file. Look at the AddType directive to figure out what your SSI files should be named.Adding the Last Modification Date to Your Page AutomaticallyNow that you know what it takes to make server side includes work on your server, you might be asking yourself what good are they? Well, as you surf around the Web, I'm sure you've seen pages that include the last time they were modified, like the one shown in Figure 3.1. Figure 3.1. Including the last modified date on your Web page. At the bottom of Figure 3.1, the date the file was last modified is printed. If you try to look at the HTML source that produced this file, you will see only normal HTML commands and the date displayed on the Web page. I have deleted most of the HTML that builds this Web page, but the HTML you should be interested in is on line 14 of the snippet shown in Listing 3.2. It sure doesn't look special, does it? You can't guarantee that the author just isn't changing the date manually, but I suspect that an SSI is responsible for the date on line 14.
[prior HTML deleted]
The HTML that produced line 14 did not require the author to change the date every time the HTML file was modified. The SSI directive <!--#flastmod file="file.shtml" --> checks the last modified field of the HTML file—file.shtml—and sends it to the client along with the rest of the HTML in file.shtml. So, even though I'm not responsible for the HTML in Figure 3.1, I suspect line 14 looks something like 14: Last Updated and Validated on <!--#flastmod file="index.html" --> Notice something very special about server side includes: when your server processes the SSI command, it includes the result of the SSI command in your HTML in place of the command itself. That example is pretty simple, as are most of the SSI commands. And that is their purpose: to allow simple dynamic additions to your HTML files, with very little effort. And it puts a new perspective on some of the neat things you can do with your Web page without having to expend a lot of programming effort. Examining The Full Syntax of SSI CommandsSSI commands are easy. But make sure that you pay attention to the syntax of building an SSI command. Because the server is reading through every line, your SSI syntax has to be exact. Otherwise, the server can't separate it out from the regular HTML commands. In addition, the SSI syntax uses part of regular HTML syntax. SSI commands are an extension of the HTML comment command. This wasn't just an accident. This way, if you need to move your SSI HTML to another server that doesn't support server side includes, the rest of your Web page will still look fine. HTML comment fields are not displayed. So a server that doesn't understand server side includes will just ignore and not display your SSI command. The syntax of the HTML comment line is <!-- Anything can go here --> The opening <!-- and closing --> define an HTML comment. The syntax of an SSI command is very similar. And every SSI command follows the same format: <!--#command cmd_argument="argument_value" --> Warning: SSI commands are easy to add to your HTML, but you must follow the
syntax of SSI commands exactly. Your first SSI may have failed for lots of simple reasons.
One of the first is the ending --> characters of the SSI command. It must have a space
between it and the ending quotation character (") of the argument_value portion of
the command.
|
Command |
Description |
| config | Sets the time, size, or error message formats. |
| echo | Inserts the values of SSI variables in your Web page. |
| exec | Executes a system command or a CGI program and inserts the output of that command into a Web page. |
| fsize | Inserts the size of a file into your Web page. |
| flastmod | Inserts the date the last time a file was modified into your Web page. Include inserts the contents of HTML files into your Web page. |
The config command stands for configuration. You will never see this command appear anywhere in your Web page. But you will find it a very useful command for changing the look of other SSI commands in your Web page. The config command modifies the standard text output from an SSI error command. If you want to send back a friendlier message than ["an error occurred while processing this directive"]; if you want to use a different date format than Sunday, Oct 8 09:13:00 CDT 1995; or if you want to change the way the file size is returned to on your Web page; you will need to use the config command.
By now, you should be able to deduce that the config command modifies the output of other SSI commands. In particular, you should have learned the following:
Table 3.2 summarizes the command options for the SSI config command. The syntax of the command is similar to that of all other SSI commands: <!--#Command Command-Argument="Argument-Value" -->.
Command |
Command-Argument |
Argument-Value |
| config | errmsg | Any ASCII text |
| config | sizefmt | Bytes or abbrev |
| config | timefmt | Any of the date codes given in Table 3.3 |
Why would you want to use this command? The most common use for this command is to change the date printed when using the flastmod SSI command. The flastmod SSI command prints the last modified date of a file. If you use your SSI commands to do more complex tasks, however, like executing a CGI or system command, you might find it useful to return a polite error message.
Perhaps the requested CGI program is only available to registered users. You could change the error message to return a polite I'm sorry, this function is only available to registered users instead of the rather cryptic default error message of ["an error occurred while processing this directive"]. If you are changing the error message to try to debug your scripting errors, however, the error log is a better tool than the config errmsg command. The error log is covered in Chapter 13, "Debugging CGI Programs."
The syntax of the config errmsg follows:
<!--#config errmsg="You can put any message here" -->
The second valid command_argument affects mainly the fsize command. It changes whether the size returned by the fsize will be returned in bytes or in a rounded-up kilobyte format. The command_argument is sizefmt, which accepts either the argument values of bytes or abbrev.
The syntax of the config sizefmt follows:
<!--#config sizefmt="bytes" --> or <!--#config sizefmt="abbrev" -->
Finally, the timefmt command argument is quite useful. You can use this inside regular text to return a date or time formatted to your preference. Whether you want only the day of the week, the current hour, or a full GMT date stamp, timefmt enables you to format the current date to fit all your needs.
Table 3.3 shows all the possible variations for the date format. It's amazing how many varieties of time are available to you.
The format for configuring the time follows:
<!--#config timefmt="Any valid grouping of format codes" -->
If you want to print the day of the week, followed by the month, day of the month, and then the year, use the following SSI command:
<!--#config timefmt="%A, %B %d, %Y" -->
Format Command |
Meaning |
| %a | Abbreviated weekday name, according to the current locale |
| %A | Full weekday name, according to the current locale |
| %b | Abbreviated month name, according to the current locale |
| %B | Full month name, according to the current locale |
| %c | Preferred date and time representation for the current locale |
| %d | Day of the month as a decimal number (ranging from 0 to 31) |
| %m | Month as a decimal number (ranging from 10 to 12) |
| %U | Week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week |
| %W | Week number of the current year as a decimal number, starting with the first Monday as the first day of the first week |
| %w | Day of the week as a decimal, with Sunday being 0 |
| %x | Preferred date representation for the current locale without the time |
| %y | Year as a decimal number without a century (ranging from 00 to 99) |
| %Y | Year as a decimal number, including the century |
| %H | Hour as a decimal number using a 24-hour clock (ranging from 00 to 23) |
| %I | Hour as a decimal number, using a 12-hour clock (ranging from 01 to 12) |
| %j | Day of the year as a decimal number (ranging from 001 to 366) |
| %M | Minute as a decimal number |
| %p | Either am or pm, according to the given time value or the corresponding strings for the current locale |
| %S | Second as a decimal number |
| %X | Preferred time representation for the current locale without the date |
| %Z | Time zone, name, or abbreviation |
Figure 3.2 shows several uses of the config command—changing the error message, the appearance of the date, and the size of a file. The HTML and SSI commands used to generate this Web page are shown in Listing 3.3.
01: <html>
02: <head>
03: <title>Config command examples </title>
04: </head>
05: <body>
06: <h3>First let's demonstrate modifying the error message. </h3>
07: <!--#config errmsg="This command won't work because the relative path starts at the directory above the current path." -->
08:
09: <!--#flastmod file="../../signatures/pi_sig.html" -->
10:
11: <h3>Next we output the standard date. </h3>
12: The signature file was last modified on
13: <!--#flastmod virtual="/signatures/pi_sig.html" -->.
14: and is <!--#fsize virtual="/signatures/pi_sig.html" --> in size.
15: <h3> If you don't like that date format try outputting something more common. </h3>
16: <!--#config timefmt="%x" -->
17: The signature file was last modified on
18: <!--#flastmod virtual="/signatures/pi_sig.html" -->
19: <!--#config sizefmt="bytes" -->
20: and is <!--#fsize virtual="/signatures/pi_sig.html" --> bytes in size.
21: <br><hr>
22: Today is <!--#config timefmt="%A" --> <!--#echo var="DATE_LOCAL" -->,
23: it is day <!--#config timefmt="%d" --> <!--#echo var="DATE_LOCAL" -->
24: of the month of
25: <!--#config timefmt="%B" --> <!--#echo var="DATE_LOCAL" -->
26: in the year <!--#config timefmt="%Y" --> <!--#echo var="DATE_LOCAL" -->.
27: </body>
28: </html>
Figure 3.2. Using the config command.
The include command is where it all started for server side includes. Someone said, "I want to include another file in my HTML and I don't want to have to cut and paste every time I need to include it in my file." Of course, the signature file is the most common use for the include command but, overall, the include command can make your task as a Web page builder and administrator much easier. The include command used properly can decrease dramatically the amount of HTML you have to write and modify.
With the include command in your tool belt, you will never type your ending copyright notice or signature into your Web HTML again. Figure 3.3 shows the inclusion of my company's signature on a business Web page. When I added my company's tag to this Web page, I did not type it in; I used the server side include:
<!--#include virtual="/include_files/pi_signature.html" -->.
Figure 3.3. Including a signature file.
The SSI include command has two values for the command-argument parameter.
Remember that the syntax of all your SSI commands starts out the same:
<!--#command cmd_argument="argument_value" -->
The two command arguments for the include command are summarized in Table 3.4.
Command Argument |
Argument Value |
| file | Any path and file name that is in the current directory or a subdirectory of the current directory. |
| virtual | Any path and file name that begins at the sever root. |
Both the command arguments are used to tell the server how to find the file you want to include. The difference between the virtual command argument and file command argument is the location from which the server starts its search for the include file.
When you use the virtual command argument, the server begins its search for the file from the document root directory. The document root directory is defined by your System Administrator and can be found in the srm.conf file. You also can find out what the document root is by printing your CGI environment variables. Environment variables are covered in Chapter 6, "Using Environment Variables in Your Programs."
The argument value for the virtual command argument should always begin with a forward slash (/). The complete path to the file is required when using the virtual command argument.
The syntax of the include command when using the virtual command argument follows:
<!--#include virtual = "/full pathname/filename.html" -->
The file command argument should be used when including files that are in the same directory the SSI file is in (the current directory) or a subdirectory of the current directory.
When using the file command, you cannot include a path name that begins above the current directory. In other words, any path name that begins with "../" is illegal.
You cannot include CGI programs using the SSI include command, but you can include other SSI parsed files. This gives you a tremendous amount of flexibility, because your included files can execute SSI commands also, including executing a CGI program. In the next section, you will use this technique to show how each article in an electronic paper could identify when it was last modified.
This chapter started out with an example of the flastmod command. That was a pretty simple example to begin with, but the following example, although no more complex, illustrates the utility and power you can get with the simple flastmod command.
You can use this command to let everyone know that your Web page has been updated recently, or you can use it to identify the latest changes to each portion of your Web page. The following Web page uses the include command and the flastmod command to tell the reader when an article was last updated. I like this a lot more than the "new" images that have cropped up on the Net. This way, your Web visitor will know what is new to her, and you don't have to modify the main file each time you add a new article. If you're building an electronic newspaper, as illustrated in Figure 3.4, this is an excellent way to let your readers know which articles they have changed.
Figure 3.4. Including the date the article was written using server side includes.
The HTML for this page does not contain any of the articles on the page. The HTML, shown in Listing 3.4, is just a template for an electronic newspaper with the include directive for each article to be added.
01: <html>
02: <head>
03: <title>An electronic paper </title>
04: </head>
05: <body>
06: <h4>This paper was generated on <!--#config timefmt="%x" -->
07: <!--#echo var="DATE_LOCAL" -->, by including the following articles. </h4>
08: Each article has the date it was last modified.
09: <!--#include file="epaper-include-files/article1.shtml" -->
10: <!--#include file="epaper-include-files/article2.shtml" -->
11: <!--#include file="epaper-include-files/article3.shtml" -->
12: <hr>
13: The electronic paper main file was last modified on <!--#flastmod file="epaper.shtml" -->.
14: </body>
15: </html>
Notice on line 6 the setting of the date format using the config command. What's interesting here is the different date formats in Figure 3.4. The config command is supposed to affect all the SSI commands that print any type of date. It worked for line 7, where the current date that the e-paper was compiled is printed. And it worked on line 13, where the date of the template is printed. Why didn't it work for the included files? Listing 3.5 shows one of the included files and the answer to the question.
01: <p>
02: If you use this technique to build an e-paper just include the flastmod
03: in every new file you add to your epaper.
04: <p>
05: <em>
06: This article was last modified on <!--#flastmod file="article2.shtml" -->.
07: </em>
You can see on line 6 the flastmod command. Because the command is in a separate file, it is not affected by any previous commands from other SSI files. This works for two reasons. First, you can nest SSI files. The e-paper is an example of that type of nesting. The e-paper template is an SSI file and each article is an SSI file. Second, when the included SSI file is parsed, the server ignores any previous config format commands. The server parses the file looking for SSI commands, and because this file doesn't set the date format anywhere, the server uses the default format shown in Figure 3.4, underneath each article.
If this method of building your e-paper proves to be too slow, try moving the location of the flastmod command. Remember, it takes longer to parse files and all SSI files must be parsed. If you move the flastmod SSI command and its formatting commands to the e-paper template, then the articles themselves can be straight HTML files. The server won't have to parse the article files, and that should speed the loading of the entire e-paper up a bit.
The flastmod command has basically the same syntax as the include command. It accepts two command arguments: the virtual and file command arguments. And virtual and file have exactly the same meaning for the flastmod as for the include command. The virtual command argument defines the path to the file from the document root, and the file command argument defines the path to the file relative to the current directory.
Take note of how the relative path name works. If you look at lines 9 through 11 of Listing 3.4, you will notice that the included articles are in a subdirectory of the e-paper template. But on line 6 of Listing 3.5, the file command is used without indicating any directory. So when the server parsed the included file and executes the flastmod command, it looks in the current directory. The server has changed directories! While the server is parsing the included articles, the current directory is the directory in which it finds the included file. In this case, this is one subdirectory below the e-paper template, in the epaper-include-files directory.
This is one reason you might want to use the virtual command argument. If you are including other files in your SSI files, when you move one file, you will have to move or copy every file that you have included. If you use the virtual command, which gives the full path name to the file, you will only have to change any references to the file you are moving.
The fsize command is used to insert the size of a file into your Web page. Remember that these commands can operate on any file—the file the SSI command is in or some other file.
This really works great when you have a Web page with a lot of images on it. Instead of putting lots of large images on your main page (something that I find really irritating when surfing around the net), you can include thumbnails of each of your images on your home page. Then beside each thumbnail image, use the fsize command to indicate how large the full-sized image is. This speeds up the loading of your Web page. First, this means more people will wait to see what is on your Web page. Next, it lets your Web page visitor decide whether she wants to spend the time downloading the larger images. This always is considered proper etiquette on the Net. Your Web site will be a lot more successful if you use this technique.
The fsize command has basically the same syntax as the include and flastmod commands. It accepts two command arguments: the virtual and file command arguments. And virtual and file have exactly the same meaning for the flastmod as for the include command. The virtual command argument defines the path to the file from the document root, and the file command argument defines the path to the file relative to the current directory.
SSI commands are designed to make your Web tasks easier. Sometimes when dealing with Unix and programming, life can get pretty frustrating. The littlest error makes everything not work. SSI commands can seem like that sometimes. When you forget to leave a space before the closing SSI command HTML tag (-->), or when you add a space between the hash sign (#) and the SSI command (<!--# echo), nothing works, and you get that silly and ever-so-helpful error message ["an error occurred while processing this directive"]. That's a lot of help!
Well, whoever wrote the code for the echo SSI command took pity on us poor imprecise humans. Can you believe it? The five variables you can print using the echo command are NOT, I repeat NOT, case sensitive! I bet you just opened a bottle of Champagne and are dancing around the room right now. Well, sit down and get back to work; you're just getting started and this reprieve from case sensitivity only lasts for a few paragraphs. Just wait until you get to the exec command. Then you're in for it!
AS I stated in the last paragraph, there are five variables for use with the echo command. They are summarized in Table 3.5. "Why only five?" you ask? It does seem kinda weak, doesn't it? Well I don't really know the answer, but it actually makes a lot of sense. Remember that SSI commands are designed to include other files and to enable you a to do a little bit of dynamic Web page work. (That's creating Web pages on-the-fly, in Net slang.) These variables are the minimum set of variables you need to describe files that you are including, and to give you current information about the main file. Why not provide more? Well, the more you get, the more complex things become. Very quickly you might as well write a CGI program and forget about SSI commands altogether. And for the most part, you will. But SSI commands are very handy to have around, mainly because of their lack of complexity.
Variable |
Meaning |
| Date_Local | Current date and time in the local time zone. The time zone is determined by the location of the server and the server's software. The format is visible on Figure 3.5. This output of this command is configurable by the SSI command config timefmt. |
| Date_GMT | Current date and time in Greenwich Mean Time. Greenwich is used by the entire Net as a common time for communications purposes. Because you can never tell who will be using your Web page, this time format make a lot of sense. |
| Document_Name | File name of the main document. |
| Document_URI | Path name and file name of the main document. |
| Last_Modified | Date and time the main document was modified. |
Figure 3.5 shows the use of each of the variables available to the echo command. Notice at the end of the first line the word (none). This is what happens when you try to echo an invalid variable. Because the echo command can't see the variable, it prints (none), just as if you had asked it to echo nothing (which, as far as the echo command is concerned, you have).
Figure 3.5. Using the SSI echo command.
Listing 3.6 shows the HTML and SSI commands to print these variables. Most of this syntax is very similar to the other SSI commands, and therefore is self explanatory. But, as always, there is at least one trick you should be aware of. Notice the different dates on the last few lines in Figure 3.5. When you include files that use the echo command, the variables that the echo command uses are the ones defined by the main file. So the Last_Modified, Document_Name, and Document_URI variables all refer to the first file parsed by the server.
Why does this happen? Well, all the global variables available to this process are set when the process is started. The first file opened by the server defines the environment under which all the other files will operate. The variables the echo command refers to are set when the server opens the first file for parsing. These variables are not set again, regardless of how many new files the server might need to include in the first file. Listing 3.7 shows the small Include file included on line 15 of Listing 3.6. Notice that the first line prints the Last_modified variable, which still refers to the first file opened for parsing. The last line of Listing 3.7 refers to the itself and gives the date you would expect Last_Modified to print when echoed.
01: <html>
02: <head><title>The Server Side Include echo command</title></head>
03: <body>
04: <h3> When you try to echo something that is invalid
05: you get the following error message:
06: <!--#echo var="$env" --></h3>
07: <h3>This is the name of the document the echo command is in
08: <!--#echo var="DOCUMENT_NAME" --></h3>
09: The path to this file is <!--#echo var="DOCUMENT_uri" -->.<br>
10: The current local time is <!--#echo var="DATE_LOCAL" -->.<br>
11: The Greenwich Mean Time is <!--#echo var="DATE_GMT" -->.<br>
12: This file was last modified on <!--#echo var="last_modified" -->.<br>
13: If you include a file that has the echo commands in it
14: all of the echo commands refer to the main file.<br>
15: <!--#include file="server side include_last_mod.shtml" ->
16: </body>
17: </html>
Top
01: The <!--#echo var="DOCUMENT_NAME" --> file was last modified. 02: <!--#echo var="LAST_MODIFIED" -->.<br>
The syntax of the echo command follows the SSI command syntax, of course:
<!--#command cmd_argument="argument_value" -->
The command argument is var, and the argument values are the variables listed in Table 3.5. The exact syntax is visible in lines 8 through 12 of Listing 3.6. Remember that with this command, the variables of the argument value field are not case sensitive. Document_Name is the same as DOCUMENT_NAME, for example.
The exec command gives you the power of your operating system right in your SSI HTML. Most of system commands available to you from the command line also are available with the SSI exec command. As with server side includes themselves, the exec command can be turned off and made unavailable to you. Because the exec command opens up a variety of security issues, don't be too surprised if your System Administrator has disabled this option. SSI security concerns are discussed at the end of this chapter, in the section "Looking At Security Issues with Server Side Includes".
The exec command enables you to access the Unix Shell or CGI scripts without requiring the client to press a button. When you go to a Web site that looks like it is immediately using a CGI script to build the page, it probably is using an SSI exec CGI command to make that happen.
With the exec command, you can do anything that you can do from the command line. Now I'm not going to teach you Unix in this book. (It might be fun, but both of us have our deadlines to meet.). But let's explore a few of the simple commands that you can use and how you might use some of these tools.
Figure 3.6 shows the output from the SSI commands in Listing 3.8. Each of these commands is a simple Unix command that becomes available to you as soon as you understand how to use SSI commands. That should be now. The environment your commands will execute under includes all the normal environment variables you get at login. If you are using an SSI command to execute a CGI script, you get all the environment variables normally available to your CGI programs. Environment variables are covered in Chapter 6.
Figure 3.6. Using the SSI exec command to access the Unix Shell.
01: <head>
02: <title>Server Side Include exec command </title>
03: </head>
04: </body>
05: <!--#config timefmt="%x" -->
06: <!--#echo var="date_local" -->
07: <h3> The Unix date of the server is <!--#exec cmd="date" -->.</h3>
08: <h3>The current working directory is <!--#exec cmd="pwd" -->.</h3>
09: <h3>The files in the directory <!--#exec cmd="cd ..; pwd;" -->
10: are <!--#exec cmd="cd ..; ls" -->.</h3>
11: <h3>The directories in the directory <!--#exec cmd="cd ..; pwd;" -->
12: are:</h3> <!--#exec cmd="cd ..; ls -l |grep ^d" -->
13: <h3> That looks awful because you can't add any formatting commands.
14: The next example uses a CGI script to do the same command </h3>
15: <!--#exec cgi="server side include_cgi_dir.cgi" -->
16: </body>
17: </html>
Let's take a look at each one of these commands. Most of them are simple. The amazing thing is that you now can treat your SSI parsed file just like you were executing from the Unix command line. So you get the simple commands that enable you to do things like print the current date and print the current working directory. You can see each of these on lines 5 and 6. You've already seen several of the date commands, but notice that the date printed from the command line is not the same date printed with the "date_local" variable on line 6. The config command has no impact on anything you do at the command line. When you execute on the command line, each new command starts a new process.
This process is illustrated in lines 9 and 10. Notice the semicolons between the Change Directory command (cd) and the Print Working Directory command (pwd). This lets your SSI exec command execute more than one command in a row, with the next command keeping the state created from the previous command.
Suppose that you try to execute two SSI exec commands. The first one changes directories and the next one prints the current directory:
<!--#exec cmd="cd .." -->
and
<!--#exec cmd="pwd" -->
The result of the pwd command would not be the cgibook directory, as in Figure 3.6, but the same directory printed from line 8, cgibook/chap3.
On line 12, two Unix commands are executed at the same time without a semicolon. What happened here? Well, this takes advantage of something called a Unix pipe. The pipe passes the output created by the first command to the next command. Let's explore this example a little closer.
The Unix command is "ls -l |grep ^d", and it can be interpreted as saying "give me the listing of all the directories in this directory."
Let's break this one down into each of its parts. This is where the power of pipes and being on a Unix machine starts to become apparent:
If you want to explore Unix further, I can recommend several books. A good introductory book to the Unix C Shell, which is one of the common operating environments I recommend, is The UNIX C SHELL Desk Reference, by Martin R. Arick, published by QED Technical Publishing Group. If you are interested in learning how to create Unix scripts, I recommend UNIX Applications Programming Mastering the Shell, by Ray Swartz, published by Sams Publishing.
The exec command and the Unix shell have lots of power, but the exec command and CGI have even more. Using the exec command and Perl CGI scripts, you can do almost anything. This is where your imagination takes over and you start to let the power of your computer and your mind work together to wow your Web page visitor.
The syntax of the command just replaces the cmd keyword with cgi. The full format of the command is shown on line 15 of Listing 3.8:
<!--#exec cgi="server side include_cgi_dir.cgi" -->
There is very little that's special about CGI programs executed from within an SSI file. The server still expects your CGI program to output a Content-Type: header. All the HTML tags you expect to work still do. However, you cannot execute a non-parsed-header (nph) CGI program inside an SSI file. The nph-CGI program tells the server to not parse the returned response headers. The NPH-CGI program is supposed to return the correct response headers. This presents a conflict to the server because it already is returning HTTP response headers for the parsed HTML file. To prevent this server conflict, NPH-CGI programs are illegal in SSI files. NPH-CGI programs are covered in Chapter 4.
Is your server more secure with or without server side includes on? In short, it only matters if your server does not allow CGI programs. Most servers allow CGI programs, so if they follow the same restrictions for server side includes that are set for CGI programs, there just isn't any extra risk.
Some servers will allow includes, but turn off the exec command. This happens because someone thinks that the exec command gives you more power than CGI programs do. It doesn't. I can do a lot more inside my Perl script than I can with my SSI exec cmd.
Server side includes just let me start a program without the client having to click the Submit button. This seems kind of silly because you can activate a CGI program by just creating a link to a CGI program. So if your site allows CGI programs and not the exec command in server side includes, tell your System Administrator to turn the exec command back on (unless he plans on turning off CGI altogether).
In this chapter, you got your first usable Web Master tool. Server side includes can make your job as a Web Master much easier. No more cutting and pasting of your signature file into all the different Web pages that you have to create and maintain.
Server side includes are the first step to creating dynamic documents, and they require almost no programming knowledge. With server side includes, you can include the current date, print the date when your Web page was last modified, execute system commands, and access any CGI program you normally could run through other means.
SSI commands are made available on your server through a configuration file called srm.conf. Two commands in the srm.conf file enable the SSI commands. The Options Include directive actually enables the operation of server side includes. The AddType text/x-server-pared-html .shtml tells the server what types of files to parse for SSI commands.
Server side includes, in my opinion, create no more risk for your sever than CGI programs. So if your server allows CGI programs, it should allow server side includes. However, the fact that each SSI file requires parsing is a legitimate concern of you server's System Administrator. If your server is underpowered and overworked, one way to get a little relief is to turn off server side includes. Most sites don't suffer that much from the extra burden of parsing server side includes and therefore allow their users the advantages that server side includes give each user.
Q : Why don't the following three commands work?
Error 1: <!--#flastmod file="../cgi-bin/cgi-lib.pl" -->
A: This file command tells the server to use a relative path name to find the file you want to get the last modification date on. So if you are one directory down from the cgi-bin directory, this should work. But it doesn't. This type of path name is valid from within your CGI programs and from the command line. If you did an
ls -lat ../cgi-bin/cgi-lib.pl
you probably would get a valid response. In this case, however, the file command argument is valid only with the current directory and subdirectories. Use the virtual command to find the cgi-bin directory. Assuming that the cgi-bin directory is just below the server root, try this command:
<!--#flastmod virtual="/cgi-bin/cgi-lib.pl" -->
Error 2:
<--#exec cmd = "pwd" -->
I would expect you to suspect the spaces around the equal sign (=) in this command, but that's not the problem. The opening HTML tag (<--) is missing the exclamation point (!). The command will work if you type it as the following:
<!--#exec cmd = "pwd" -->
Error 3:
<!--#exec cgi = "/cgi-bin/env.pl"-->
This is an example of spacing problems, and is probably one of the most common mistakes made when trying to get SSI commands to work. You must include at least one space before the closing HTML tag (-->). The command will work if you type it as the following:
<!--#exec cgi = "/cgi-bin/env.pl" -->
Top
Q: Why don't I see an error message from my SSI command?
A: What is the file extension of the file that your SSI command is part of? I'll bet you that it's not .shtml. It's very easy to forget that the server ignores all SSI commands not in the correct file type. And because the SSI command is enclosed in a valid HTML comment tag (<-- Comment -->), the server sends your SSI command to the browser without trying to execute it. The browser reads the HTML and sees the HTML comment field and ignores the line altogether.
Q: Why can't I execute the system commands I can from the command line?
A: When your SSI exec command is executed by the server, your user group probably is set to a restricted access user group like NOBODY. Just like you have limited privileges to move around your sever, when someone accesses your Web page, the same thing happens. The Web server environment usually allows your Web pages to be accessed under the process group NOBODY. The process group NOBODY may have fewer privileges than you do as a normal user. If some of the system commands you are using as SSI commands work from the command line, but not within your SSI exec command, first check for all the usual SSI errors, and then e-mail your System Administrator to see whether those commands are enabled for the user group NOBODY. You can't test for this from the command line, because you will not be executing under the restricted NOBODY process name.
|| Back to FAQ's || W3U's Home ||
http://www.w3u.com/
