Server Side Includes#Directives

Server Side Includes (SSI) is a simple interpreted server-side scripting language used almost exclusively for the World Wide Web. It is most useful for including the contents of one or more files into a web page on a web server (see below), using its #include directive. This could commonly be a common piece of code throughout a site, such as a page header, a page footer and a navigation menu. SSI also contains control directives for conditional features and directives for calling external programs. It is supported by Apache, LiteSpeed, nginx, IIS as well as W3C's Jigsaw.{{cite web |title=SSI Commands |url=https://www.w3.org/Jigsaw/Doc/User/SSI.html |website=W3C |access-date=24 March 2019}} It has its roots in NCSA HTTPd.

In order for a web server to recognize an SSI-enabled HTML file and therefore carry out these instructions, either the filename should end with a special extension, by default .shtml, .stm, .shtm, or, if the server is configured to allow this, set the execution bit of the file.{{cite web|title=Configuring your server to permit SSI|url=http://httpd.apache.org/docs/current/howto/ssi.html#configuring|website=Apache Tutorial: Introduction to Server Side Includes|publisher=The Apache Software Foundation|access-date=24 June 2015}}

Design

As a simple programming language, SSI supports only one type: text. Its control flow is rather simple, choice is supported, but loops are not natively supported and can only be done by recursion using include or using HTTP redirect.{{efn|Nevertheless found in some implementations, including Jigsaw.}} The simple design of the language makes it easier to learn and use than most server-side scripting languages, while complicated server-side processing is often done with one of the more feature-rich programming languages. SSI is Turing complete.{{cite web|url=http://www.janschejbal.de/projekte/ssituring/ |title=Server Side Includes Turing machine, Jan Schejbal. |publisher=Janschejbal.de |access-date=2012-12-06}}

SSI has a simple syntax: . Directives are placed in HTML comments so that if SSI is not enabled, users will not see the SSI directives on the page, unless they look at its source. Note that the syntax does not allow spaces between the leading "" that closes the element.{{cite web|url=http://httpd.apache.org/docs/current/howto/ssi.html#basic|title=Basic SSI Directives and Syntax|access-date=2018-02-09|date=2018-02-09}}

Examples

A web page containing a daily quotation could include the quotation by placing the following code into the file of the web page:

With one change of the quote.txt file, all pages that include the file will display the latest daily quotation. The inclusion is not limited to files, and may also be the text output from a program, or the value of a system variable such as the current time.

Directives

= Common =

The following are SSI directives from the times of NCSA HTTPd (the 1990s).{{cite web |title=Server Side Includes (SSI) |url=http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html |website=NCSA HTTPd Tutorial |access-date=24 March 2019 |archive-url=https://web.archive.org/web/19970303194503/http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html |archive-date=3 March 1997|url-status=dead}} Some implementations do not support all of them.{{cite web |title=Module ngx_http_ssi_module |url=http://nginx.org/en/docs/http/ngx_http_ssi_module.html |website=nginx documentation |access-date=16 November 2021}}

class="wikitable" \|+NCSA HTTPd SSI directives
Directive ! Parameters ! Description ! Example
`include` \| file or virtual \| This is probably the most used SSI directive. It allows the content of one document to be transcluded in another. The included document can itself be another SSI-enabled file. The `file` or `virtual` parameters specify the file (HTML page, text file, script, etc.) to be included. NCSA HTTPd did not support CGI via `include`, but later Apache HTTPd does.{{cite web \| url = http://httpd.apache.org/docs/current/mod/mod_include.html#element.include \| title = Apache Module mod_include \| work = Apache HTTP Server Version 2.4 Documentation \| publisher = Apache Software Foundation \| access-date = 2021-09-07 }} If the process does not have access to read the file or execute the script, the include will fail. The parameter "`virtual`" handles any directory paths as if part of the URL, while "`file`" handles any directory paths as in the underlying filesystem. When using "`file`" it is forbidden to reference absolute paths or `../` to access a parent directory. The Apache documentation recommends using "`virtual`" in preference to "`file`". \|
`exec` \| cgi or cmd \| This directive executes a program, script, or shell command on the server. The cmd parameter specifies a server-side command; the cgi parameter specifies the path to a CGI script. {{cns\|date=September 2021\|The `PATH_INFO` and `QUERY_STRING` of the current SSI script will be passed to the CGI script, as a result "exec cgi" should be used instead of "include virtual".}} \|
`echo` \| var \| This directive displays the contents of a specified HTTP environment variable. {{cns\|date=September 2021\|Variables include `HTTP_USER_AGENT`, `LAST_MODIFIED`, and `HTTP_ACCEPT`.}} \| Your IP address is:
`config` \| timefmt, sizefmt, or errmsg \| This directive configures the display formats for the date, time, filesize, and error message (returned when an SSI command fails). \|
`flastmod` and `fsize` \| file or virtual \| These directives display the date when the specified document was last modified, or the specified document's size. The file or virtual parameters specify the document to use. The file parameter defines the document as relative to the document path; the virtual parameter defines the document as relative to the document root. \|

class="wikitable"

|+NCSA HTTPd SSI directives

Directive

! Parameters

! Description

! Example

include

| file or virtual

| This is probably the most used SSI directive. It allows the content of one document to be transcluded in another. The included document can itself be another SSI-enabled file. The file or virtual parameters specify the file (HTML page, text file, script, etc.) to be included. NCSA HTTPd did not support CGI via include, but later Apache HTTPd does.{{cite web | url = http://httpd.apache.org/docs/current/mod/mod_include.html#element.include | title = Apache Module mod_include | work = Apache HTTP Server Version 2.4 Documentation | publisher = Apache Software Foundation | access-date = 2021-09-07 }} If the process does not have access to read the file or execute the script, the include will fail. The parameter "virtual" handles any directory paths as if part of the URL, while "file" handles any directory paths as in the underlying filesystem. When using "file" it is forbidden to reference absolute paths or ../ to access a parent directory. The Apache documentation recommends using "virtual" in preference to "file".

exec

| cgi or cmd

| This directive executes a program, script, or shell command on the server. The cmd parameter specifies a server-side command; the cgi parameter specifies the path to a CGI script. {{cns|date=September 2021|The PATH_INFO and QUERY_STRING of the current SSI script will be passed to the CGI script, as a result "exec cgi" should be used instead of "include virtual".}}

echo

| var

| This directive displays the contents of a specified HTTP environment variable. {{cns|date=September 2021|Variables include HTTP_USER_AGENT, LAST_MODIFIED, and HTTP_ACCEPT.}}

Your IP address is:

config

| timefmt, sizefmt, or errmsg

| This directive configures the display formats for the date, time, filesize, and error message (returned when an SSI command fails).

flastmod and fsize

| file or virtual

| These directives display the date when the specified document was last modified, or the specified document's size. The file or virtual parameters specify the document to use. The file parameter defines the document as relative to the document path; the virtual parameter defines the document as relative to the document root.

= Control directives =

Control directives are later added to SSI. They include the ubiquitous if-elif-else-endif flow control and variable writing as well as more exotic features like loops only found in some implementations.

class="wikitable"

class="wikitable"
Directive ! Parameters ! Description ! Example ! Found in
{{plainlist\| if elif else endif }} \| expr \| The if statement. Used for condition tests that may determine and generate multiple logical pages from one single physical page. `elif` is a shorthand for nested else-if. `else` and `endif` do not accept parameters. Expression syntax vary among implementations. Variable existence and equality/regex checks are commonly supported. Jigsaw uses expressions split over multiple attributes instead. \| \| Ubiquitous.
set \| var, value \| Sets the value of a SSI variable. Apache provides additional parameters for encodings. \| \| Apache,{{cite web \|title=mod_include \|url=https://httpd.apache.org/docs/current/mod/mod_include.html \|website=Apache HTTP Server \|access-date=25 March 2019}} Nginx{{cite web \|title=ngx_http_ssi_module \|url=https://nginx.org/en/docs/http/ngx_http_ssi_module.html \|website=nginx.org \|access-date=25 March 2019}}
`printenv` \| \| This directive outputs a list of all SSI variables and their values, including environmental and user-defined variables. It has no attributes. \| \| Apache

Directive

! Parameters

! Description

! Example

! Found in

{{plainlist|

if
elif
else
endif

}}

| expr

| The if statement. Used for condition tests that may determine and generate multiple logical pages from one single physical page. elif is a shorthand for nested else-if. else and endif do not accept parameters.

Expression syntax vary among implementations. Variable existence and equality/regex checks are commonly supported. Jigsaw uses expressions split over multiple attributes instead.

| Ubiquitous.

set

| var, value

| Sets the value of a SSI variable. Apache provides additional parameters for encodings.

| Apache,{{cite web |title=mod_include |url=https://httpd.apache.org/docs/current/mod/mod_include.html |website=Apache HTTP Server |access-date=25 March 2019}} Nginx{{cite web |title=ngx_http_ssi_module |url=https://nginx.org/en/docs/http/ngx_http_ssi_module.html |website=nginx.org |access-date=25 March 2019}}

printenv

| This directive outputs a list of all SSI variables and their values, including environmental and user-defined variables. It has no attributes.

| Apache

Notes

References

External links

Language reference from implementations:
Apache: [http://httpd.apache.org/docs/current/mod/mod_include.html Apache mod_include Reference]. Calls directives "elements".
Nginx: [https://nginx.org/en/docs/http/ngx_http_ssi_module.html Module ngx_http_ssi_module]. Calls directives "commands".
NCSA HTTPd: [https://web.archive.org/web/19971210170837/http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html Original NCSA HTTPd SSI Reference]. Calls directives "commands".
W3C Jigsaw: [https://www.w3.org/Jigsaw/Doc/User/SSI.html Server Side Include commands]. Calls directives "elements". Highly expanded with servlets, JDBC, HTTP cookie, and loops.
Tutorials:
[http://httpd.apache.org/docs/current/howto/ssi.html Apache SSI Tutorial]
[http://www.andreas.com/faq-ssi.html Plain-English Guide to SSI]
[http://www.ssi-developer.net/ssi/ SSI-Developer, Apache Server Side Includes]

Category:Scripting languages

Category:Web 1.0

Category:Web technology