thttpd/cgi-src/ssi.8

.TH ssi 8 "18 October 1995"
.SH NAME
ssi - server-side-includes CGI program
.SH SYNOPSIS
.B ssi
.SH DESCRIPTION
.PP
This is an external CGI program that gives you the same functionality
as the built-in server-side-includes feature in some HTTP daemons.
It is written for use with thttpd(8), but should be easy to adapt
to other systems.
.PP
To use this program, first make sure it is installed in your server's
CGI area, and that CGI is enabled.
Then set up your URLs with the path to the document you want parsed
as the "pathinfo".
That's the part of the URL that comes after the CGI program name.
For example, if the URL to this program is:
.nf
  http://www.acme.com/cgi-bin/ssi
.fi
and the url for your document is:
.nf
  http://www.acme.com/users/wecoyote/doc.html
.fi
then the compound URL that gives you the document filtered through the
program would be:
.nf
  http://www.acme.com/cgi-bin/ssi/users/wecoyote/doc.html
.fi
.PP
The format description below is adapted from
http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
.SH "INCLUDE FORMAT"
.PP
All directives are formatted as SGML comments within the document.
This is in case the document should ever find itself in the client's
hands unparsed.
Each directive has the following format:
.nf
  <!--#command tag1="value1" tag2="value2" -->
.fi
Each command takes different arguments, most only accept one tag at a time.
Here is a breakdown of the commands and their associated tags:
.IP * 4
.BR config :
The config directive controls various aspects of the file parsing.
There are two valid tags:
.IP o 8
.BR timefmt :
gives the server a new format to use when providing dates.
This is a string compatible with the strftime library call.
.IP o 8
.BR sizefmt :
determines the formatting to be used when displaying the
size of a file.
Valid choices are bytes, for a formatted byte count
(formatted as 1,234,567), or abbrev for an abbreviated version
displaying the number of kilobytes or megabytes the file occupies.
.IP * 4
.BR include :
Inserts the text of another document into the parsed document.
The inserted file is parsed recursively, so it can contain
server-side-include directives too.
This command accepts two tags:
.IP o 8
.BR virtual :
Gives a virtual path to a document on the server.
.IP o 8
.BR file :
Gives a pathname relative to the current directory. ../ cannot
be used in this pathname, nor can absolute paths be used.
.IP * 4
.BR echo :
Prints the value of one of the include variables (defined below).
Any dates are printed subject to the currently configured timefmt.
The only valid tag to this command is var, whose value is the name of the
variable you wish to echo.
.IP * 4
.BR fsize :
prints the size of the specified file,
subject to the sizefmt parameter to the config command.
Valid tags are the same as with the include command.
.IP * 4
.BR flastmod :
prints the last modification date of the specified file, subject
to the formatting preference given by the timefmt parameter to config.
Valid tags are the same as with the include command.
.SH VARIABLES
.PP
A number of variables are made available to parsed documents.
In addition to
the CGI variable set, the following variables are made available:
.IP * 4
.BR DOCUMENT_NAME :
The current filename.
.IP * 4
.BR DOCUMENT_URI :
The virtual path to this document (such as /~robm/foo.shtml).
.IP * 4
.BR QUERY_STRING_UNESCAPED :
The unescaped version of any search query the client sent.
.IP * 4
.BR DATE_LOCAL :
The current date, local time zone.
Subject to the timefmt parameter to the config command.
.IP * 4
.BR DATE_GMT :
Same as DATE_LOCAL but in Greenwich mean time.
.IP * 4
.BR LAST_MODIFIED :
The last modification date of the current document.
Subject to timefmt like the others.
.SH "BUGS / DEFICIENCIES"
.PP
Does not implement the "exec" directive.
Actually, I consider this neither a bug nor a deficiency, but some may.
.SH "SEE ALSO"
thttpd(8), strftime(3)
.SH AUTHOR
Copyright � 1995 by Jef Poskanzer <jef@acme.com>.
All rights reserved.
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
Revision:	1.1
Committed:	Mon Jun 18 21:11:58 2001 UTC (25 years, 3 months ago) by root
Branch:	MAIN
CVS Tags:	mp_j, dp_j, cp_j, HEAD
Branch point for:	connpatch, dirpatch, mmapppatch
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	.TH ssi 8 "18 October 1995"
2			.SH NAME
3			ssi - server-side-includes CGI program
4			.SH SYNOPSIS
5			.B ssi
6			.SH DESCRIPTION
7			.PP
8			This is an external CGI program that gives you the same functionality
9			as the built-in server-side-includes feature in some HTTP daemons.
10			It is written for use with thttpd(8), but should be easy to adapt
11			to other systems.
12			.PP
13			To use this program, first make sure it is installed in your server's
14			CGI area, and that CGI is enabled.
15			Then set up your URLs with the path to the document you want parsed
16			as the "pathinfo".
17			That's the part of the URL that comes after the CGI program name.
18			For example, if the URL to this program is:
19			.nf
20			http://www.acme.com/cgi-bin/ssi
21			.fi
22			and the url for your document is:
23			.nf
24			http://www.acme.com/users/wecoyote/doc.html
25			.fi
26			then the compound URL that gives you the document filtered through the
27			program would be:
28			.nf
29			http://www.acme.com/cgi-bin/ssi/users/wecoyote/doc.html
30			.fi
31			.PP
32			The format description below is adapted from
33			http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
34			.SH "INCLUDE FORMAT"
35			.PP
36			All directives are formatted as SGML comments within the document.
37			This is in case the document should ever find itself in the client's
38			hands unparsed.
39			Each directive has the following format:
40			.nf
41			<!--#command tag1="value1" tag2="value2" -->
42			.fi
43			Each command takes different arguments, most only accept one tag at a time.
44			Here is a breakdown of the commands and their associated tags:
45			.IP * 4
46			.BR config :
47			The config directive controls various aspects of the file parsing.
48			There are two valid tags:
49			.IP o 8
50			.BR timefmt :
51			gives the server a new format to use when providing dates.
52			This is a string compatible with the strftime library call.
53			.IP o 8
54			.BR sizefmt :
55			determines the formatting to be used when displaying the
56			size of a file.
57			Valid choices are bytes, for a formatted byte count
58			(formatted as 1,234,567), or abbrev for an abbreviated version
59			displaying the number of kilobytes or megabytes the file occupies.
60			.IP * 4
61			.BR include :
62			Inserts the text of another document into the parsed document.
63			The inserted file is parsed recursively, so it can contain
64			server-side-include directives too.
65			This command accepts two tags:
66			.IP o 8
67			.BR virtual :
68			Gives a virtual path to a document on the server.
69			.IP o 8
70			.BR file :
71			Gives a pathname relative to the current directory. ../ cannot
72			be used in this pathname, nor can absolute paths be used.
73			.IP * 4
74			.BR echo :
75			Prints the value of one of the include variables (defined below).
76			Any dates are printed subject to the currently configured timefmt.
77			The only valid tag to this command is var, whose value is the name of the
78			variable you wish to echo.
79			.IP * 4
80			.BR fsize :
81			prints the size of the specified file,
82			subject to the sizefmt parameter to the config command.
83			Valid tags are the same as with the include command.
84			.IP * 4
85			.BR flastmod :
86			prints the last modification date of the specified file, subject
87			to the formatting preference given by the timefmt parameter to config.
88			Valid tags are the same as with the include command.
89			.SH VARIABLES
90			.PP
91			A number of variables are made available to parsed documents.
92			In addition to
93			the CGI variable set, the following variables are made available:
94			.IP * 4
95			.BR DOCUMENT_NAME :
96			The current filename.
97			.IP * 4
98			.BR DOCUMENT_URI :
99			The virtual path to this document (such as /~robm/foo.shtml).
100			.IP * 4
101			.BR QUERY_STRING_UNESCAPED :
102			The unescaped version of any search query the client sent.
103			.IP * 4
104			.BR DATE_LOCAL :
105			The current date, local time zone.
106			Subject to the timefmt parameter to the config command.
107			.IP * 4
108			.BR DATE_GMT :
109			Same as DATE_LOCAL but in Greenwich mean time.
110			.IP * 4
111			.BR LAST_MODIFIED :
112			The last modification date of the current document.
113			Subject to timefmt like the others.
114			.SH "BUGS / DEFICIENCIES"
115			.PP
116			Does not implement the "exec" directive.
117			Actually, I consider this neither a bug nor a deficiency, but some may.
118			.SH "SEE ALSO"
119			thttpd(8), strftime(3)
120			.SH AUTHOR
121			Copyright � 1995 by Jef Poskanzer <jef@acme.com>.
122			All rights reserved.
123			.\" Redistribution and use in source and binary forms, with or without
124			.\" modification, are permitted provided that the following conditions
125			.\" are met:
126			.\" 1. Redistributions of source code must retain the above copyright
127			.\" notice, this list of conditions and the following disclaimer.
128			.\" 2. Redistributions in binary form must reproduce the above copyright
129			.\" notice, this list of conditions and the following disclaimer in the
130			.\" documentation and/or other materials provided with the distribution.
131			.\"
132			.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
133			.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
134			.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
135			.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
136			.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
137			.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
138			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
139			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
140			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
141			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
142			.\" SUCH DAMAGE.