Nginx-ssi Module

Source: Internet
Author: User
Tags first string mime file

SSI, for Server Side includes, was actually a sort of server-side programming language interpreted by Nginx. Its name was based on the fact, the most used functionality of the language are the include command. Back in the 1990s, such languages were employed on order to render Web pages dynamic, from simple static . html fi Les with client-side scripts to complex pages with server-processed compositions. Within the HTML source code, webmasters could now inserts server-interpreted directives, which would then leads the the-the-the-m Ore advanced pre-processors such as PHP or ASP.

The most famous illustration of SSI are the quoteof the day. In order to insert a new quote every day on the top of each page of their website, webmasters would has to edit the H TML source of every page, replacing the former quote manually. With Server Side includes, a single command suffices to simplify the task:



All would has to does to insert a new quote are to edit the contents of the quote.txt file. Automatically, all pages would show the updated quote. As of today, the most of the major Web servers (Apache, IIS, LIGHTTPD, and so on) support Server Side includes.

Module directives and Variables

have directives inserted within the actual content of files that Nginx serves raises one major issue-what files should Nginx parse for SSI commands? It would is a waste of resources to parse binary files such as images (. gif, . jpg, . png) or oth ER kinds of media. You need-make sure-configure Nginx correctly with the directives introduced by this module:


Context: http, server, location, if

Enables parsing files for SSI commands. Nginx only parses files corresponding to MIME types selected with the ssi_types directive.

Syntax: on or off

Default value: off

Example: SSI on;


Context: http, server, location

Defines the MIME file types that should is eligible for SSI parsing. The text/html type is always included.


Ssi_types type1 [type2] [type3 ...];
Ssi_types *;

Default value: text/html

Example: ssi_types text/plain;


Context: http, server, location

Some SSI commands may generate errors; When that's the case, Nginx outputs a message at the location of the Command-an error occurred while processing the Dir Ective. Enabling this option silences Nginx and the message does not appear.

Syntax: on or off

Default value: off

Example: ssi_silent_errors off;


Context: http, server, location

SSI commands has arguments that accept a value (for example, <!--# include file= "value"--). This parameter defines the maximum length accepted by Nginx.

Syntax: Numeric

Default: (characters)

Example: ssi_value_length;


Context: http, server, location

When set to on, the this directive prevents the Nginx from making use of recycled buffers.

Syntax: on or off

Default: off


Context: http, server, location

If the size of a buffer is greater than ssi_min_file_chunk, data was stored in a file and then sent via SENDF Ile. In other cases, it's transmitted directly from the memory.

Syntax: Numeric value (size)

Default: 1,024

A Quick note regarding possible concerns about the SSI engine resource usage-by enabling the SSI module at the locat Ion or server block level, you enable parsing in least all text/html files (pretty much any page To being displayed by the client browser). While the Nginx SSI module is efficiently optimized, you might want to disable parsing for files that does not require it.

Firstly, all your pages containing SSI commands should has the . sHTML (Server HTML) extension. Then, with your configuration, at the location block level, enable the SSI engine under a specific condition. The name of the served file must end with . sHTML:

server {
Location ~* \.shtml$ {
SSI on;

On one hand, all HTTP requests submitted to Nginx would go through an additional regular expression pattern matching. On the other hand, static HTML files or files to being processed by other interpreters (. PHP, for instance) would not be parsed unnecessarily.

Finally, the SSI module enables the variables:

    • $date _local: Returns The current time according to the current system time zone
    • $date _gmt: Returns The current GMT time, regardless of the server time zone

SSI Commands

Once you has the SSI engine enabled for your Web pages, your is ready to start writing your first dynamic HTML page. Again, the principle is simple-design the pages of your website using regular HTML code, inside which you'll insert SS I commands.

These commands respect a particular syntax-at first sight, they look like regular HTML comments: <!--a comme NT--and that's the good thing about it-if you accidentally disable SSI parsing of your files, the SSI comma NDS do not appear on the
client browser; They is only visible in the source code as actual HTML comments. The full syntax is as follows:

<!--# command param1= "value1" param2= "value2" ...--

File includes

The main command of the Server Side include module is obviously the include command. It comes in the different fashions.

First, you is allowed to make a simple file include:

<!--# include file= "header.html"-

This command generates a HTTP sub-request to is processed by Nginx. The body of the response that's generated is inserted instead of the command itself.

The second possibility is to use the Include virtual command:

<!--# include virtual= "/sources/header.php?id=123"-

This also performs a sub-request to the server; The difference lies within the fetches the specified file (when using include file, the wait parameter is automatically enabled). Indeed, parameters can be inserted within the include command tag. by default, all SSI requests is issued simultaneously, in parallel. This can cause slowdowns and timeouts in the case of heavy loads. Alternatively, can use the wait= "yes" parameter-specify that Nginx should wait for the completion of the R Equest before moving on to other includes:

<!--# include virtual= "header.php" wait= "yes"-

if The result of your include command is empty or triggered an error (404 , 500 , and so on ), Nginx inserts the corresponding error page with its HTML: . The message is displayed at the exact same place where you inserted the include Comm and. If you wish to revise this behavior, you are the possibility to create a named block. By linking the block to the include command, the contents of the block would show at The location of the include command tag , in case an error occurs:

<!--# block name= "Error_footer"-->sorry, the footer file is not found.<!--# Endblock-

<!--# include file= "footer.html" stub= "Error_footer"-

The result as output in the client browser is shown as follows:

As can see, the contents of the error_footer block were inserted at the location of the include command, after th E tag.

Working with Variables

The Nginx SSI module also offers the possibilityto work with variables. Displaying a variable (in other words, inserting the variable value to the final HTML source code) can be do with the Echo Command:

<!--# echo var= "Variable_name"-

The command accepts the following three parameters:

    • var : The name of the variable you want to display, for example, REMOTE_ADDR to display the IP address of the client.
    • default : A string to being displayed in case the variable is empty. If you don't specify this parameter, the output is (none ).
    • encoding : Encoding method for the string. The accepted values are none (no particular encoding), %20 , and so on) and entity (uses HTML entities: & becomes &amp; ).

Also affect your own variables with the SET command:

<!--# set var= "my_variable" value= "Your value here"-

The value parameter is itself parsed by the engine; As a result, you is allowed to make use of existing variables:

<!--# echo var= "My_variable"-
<!--# set var= "my_variable" value= "Hello"-
<!--# echo var= "My_variable"-
<!--# set var= "my_variable" value= "$MY _variable There"-
<!--# echo var= "My_variable"-

Here is the code this Nginx outputs for each of the three echoes commands from the example above:

Hello there

Conditional Structure

The following set of commands would allow you to include text or other directives depending on a condition. The conditional structure can be established with the following syntax:

<!--# if expr= "Expression1"-
<!--# elif expr= "Expression2"-
<!--# Else--
<!--# endif

The expression can be formulated in three different ways:

  • Inspecting a variable: <!--# if expr= "$variable"-- Similar to the if block in the Rewrite Module, and the condition is true if the variable are not empty.
  • Comparing strings: <!--# if expr= "$variable = Hello"-. The condition is true if the first string was equal to the second string. Use ! = instead of = to revert the condition (the condition is true if the first string was not equal to T He second string).
  • Matching a regular expression pattern: <!--# if expr= "$variable =/pattern/"--. Note that the pattern must was enclosed with / characters, otherwise it was considered to being a simple string (for E Xample, <!--# if expr= "$MY _variable =/^/documents//"-). Similar to the comparison, use! = to negate the condition. Captures in regular expressions is supported.

The content that you insert within a condition block can contain regular HTML code or additional SSI directives, with one exception-you cannot nest if blocks.


Last and probably least (for once) of the SSI commands offered by Nginx is the Config command. IT allows you to configure the simple parameters.

First, the message that appears when the SSI engine faces a error is malformed tags or invalid expressions. By default, Nginx displays [a error occurred while processing the directive]. If you want it to display something else, enter the following:

<!--# config errmsg= "Something terrible happened"-

Additionally, you can configure the format of the dates that is returned by the $date _local and $date _gmt variables using the timefmt parameter:

<!--# config timefmt= "%A,%d-%b-%y%h:%m:%s%Z"-

The string you specify this is passed as the format string of the strftime C function. For more information on the arguments that can is used in the format string, please refer to the documentation of the C2>strftime C language function at .

Nginx-ssi Module

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.