SSI, for Server Side Includes, is actually a sort of server-side programming language interpreted by Nginx. Its name is based on the fact that the most used functionality of the language is the include command. Back in the 1990s, such languages were employed in order to render web pages dynamic, from simple static .html files with client-side scripts to complex pages with server-processed compositions. Within the HTML source code, webmasters could now insert server-interpreted directives, which would then lead the way to more advanced pre-processors such as PHP or ASP.

The most famous illustration of SSI is the quote of the day. In order to insert a new quote every day at the top of each page of their website, webmasters would have to edit out the HTML source of every page, replacing the former quote manually. With Server Side Includes, a single command suffices to simplify the task:

<html>
<head><title>My web page</title></head>
<body>
　　<h1>Quote of the day: <!--# include file="quote.txt" -->
　　</h1>
</body>
</html>

All you would have to do to insert a new quote is to edit the contents of the quote.txt file. Automatically, all pages would show the updated quote. As of today, most of the major web servers (Apache, IIS, Lighttpd, and so on) support Server Side Includes.

Module Directives and Variables

Having 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 be a waste of resources to parse binary files such as images (.gif, .jpg, .png) or other kinds of media. You need to make sure to configure Nginx correctly with the directives introduced by this module:

ssi

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;

ssi_types

Context: http, server, location

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

Syntax:

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

Default value: text/html

Example: ssi_types text/plain;

ssi_silent_errors

Context: http, server, location

Some SSI commands may generate errors; when that is the case, Nginx outputs a message at the location of the command — an error occurred while processing the directive. Enabling this option silences Nginx and the message does not appear.

Syntax: on or off

Default value: off

Example: ssi_silent_errors off;

ssi_value_length

Context: http, server, location

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

Syntax: Numeric

Default: 256 (characters)

Example: ssi_value_length 256;

ssi_ignore_recycled_buffers

Context: http, server, location

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

Syntax: on or off

Default: off

ssi_min_file_chunk

Context: http, server, location

If the size of a buffer is greater than ssi_min_file_chunk, data is stored in a file and then sent via sendfile. In other cases, it is 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 location or server block level, you enable parsing of at least all text/html files (pretty much any page to be displayed by the client browser). While the Nginx SSI module is efficiently optimized, you might want to disable parsing for files that do not require it.

Firstly, all your pages containing SSI commands should have the .shtml (Server HTML) extension. Then, in 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 {
　　server_name website.com;
　　location ~* \.shtml$ {
　　　　ssi on;
　　}
}

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

Finally, the SSI module enables two 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 have the SSI engine enabled for your web pages, you are 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 will insert SSI commands.

These commands respect a particular syntax — at first sight, they look like regular HTML comments: <!-- A comment -->, and that is the good thing about it — if you accidentally disable SSI parsing of your files, the SSI commands do not appear on the
client browser; they are 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 two different fashions.

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

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

This command generates an HTTP sub-request to be processed by Nginx. The body of the response that was 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 way that Nginx fetches the specified file (when using include file, the wait parameter is automatically enabled). Indeed, two parameters can be inserted within the include command tag. By default, all SSI requests are issued simultaneously, in parallel. This can cause slowdowns and timeouts in the case of heavy loads. Alternatively, you can use the wait="yes" parameter to specify that Nginx should wait for the completion of the request before moving on to other includes:

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

, 500, and so on), Nginx inserts the corresponding error page with its HTML: <html>[…]404 Not Found</body></html>. The message is displayed at the exact same place where you inserted the include command. If you wish to revise this behavior, you have the possibility to create a named block. By linking the block to the include command, the contents of the block will show at the location of the include command tag, in case an error occurs:

<html>
<head><title>SSI Example</title></head>
<body>
　　<center>
　　　　<!--# block name="error_footer" -->Sorry, the footer file was not found.<!--# endblock -->
　　　　<h1>Welcome to nginx</h1>
　　　　<!--# include file="footer.html" stub="error_footer" -->
　　</center>
</body>
</html>

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

As you can see, the contents of the error_footer block were inserted at the location of include command, after the <h1> tag.

Working with Variables

The Nginx SSI module also offers the possibility to work with variables. Displaying a variable (in other words, inserting the variable value into the final HTML source code) can be done 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 be 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), url (encode text like a URL — a blank space becomes %20, and so on) and entity (uses HTML entities: & becomes &amp;).

You may 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 are 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 that Nginx outputs for each of the three echo commands from the example above:

(none)
hello
hello there

Conditional Structure

The following set of commands will 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, the condition is true if the variable is not empty.
  • Comparing two strings: <!--# if expr="$variable = hello" -->. The condition is true if the first string is equal to the second string. Use != instead of = to revert the condition (the condition is true if the first string is not equal to the second string).
  • Matching a regular expression pattern: <!--# if expr="$variable = /pattern/" -->. Note that the pattern must be enclosed with / characters, otherwise it is considered to be a simple string (for example, <!-- # if expr="$MY_VARIABLE = /^/documents//" -->). Similar to the comparison, use != to negate the condition. Captures in regular expressions are 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.

Configuration

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

First, the message that appears when the SSI engine faces an error is malformed tags or invalid expressions. By default, Nginx displays [an 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 are 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 here is passed as the format string of the strftime C function. For more information about the arguments that can be used in the format string, please refer to the documentation of the strftime C language function at http://www.opengroup.org/onlinepubs/009695399/functions/strftime.html.

Nginx - SSI Module的更多相关文章

  1. Nginx - Rewrite Module

    Initially, the purpose of this module (as the name suggests) is to perform URL rewriting. This mecha ...

  2. nginx ssi 配置小细节（一）

    最近工作需要使用nginx的ssi (server side include)技术,在这里,将使用中的一点心得分享一下,也是一种备忘! 首先,nginx的ssi启用很简单,就只有三个最基本的指令: s ...

  3. How to Customize Server Header using NginX headers-more module

    http://wiki.nginx.org/HttpHeadersMoreModule#Version headers_more When you are browsing a website, yo ...

  4. nginx上传模块—nginx upload module-

    一. nginx upload module原理 官方文档: http://www.grid.net.ru/nginx/upload.en.html Nginx upload module通过ngin ...

  5. nginx upload module的使用

    现在的网站,总会有一点与用户交互的功能,例如允许用户上传头像,上传照片,上传附件这类的.PHP写的程序,对于上传文件效率不是很高.幸好,nginx有一个名为upload的module可以解决这个问题. ...

  6. Nginx Upload Module 上传模块

    传统站点在处理文件上传请求时,普遍使用后端编程语言处理,如:Java.PHP.Python.Ruby等.今天给大家介绍Nginx的一个模块,Upload Module上传模块,此模块的原理是先把用户上 ...

  7. Nginx Image Module图片缩略图 水印处理模块

    Nginx Image Module图片缩略图 水印处理模块 下载Tengine tar -zxvf tengine-1.4.5.tar.gz cd tengine-1.4.5 下载Nginx tar ...

  8. nginx ssi + ngx_pagespeed 实现micro frontends 开发

    nginx 的ssi 功能让我们可以将不同的拼接起来,ngx_pagespeed 是pagespeed 的nginx 模块,可以帮助 我们解决前端的一些性能优化的问题,通过简单的配置就可以搞定 一张参 ...

  9. 转：使用 Nginx Upload Module 实现上传文件功能

    普通网站在实现文件上传功能的时候,一般是使用Python,Java等后端程序实现,比较麻烦.Nginx有一个Upload模块,可以非常简单的实现文件上传功能.此模块的原理是先把用户上传的文件保存到临时 ...

随机推荐

  1. CodeForces 589D Boulevard （数学，相遇）

    题意:给定 n 个的在 x 轴上的坐标,和开始时间,结束坐标,从起点向终点走,如果和其他人相遇,就互相打招乎,问你每人打招乎的次数. 析:其实这一个数学题,由于 n 比较小,我们就可以两两暴力,这两个 ...

  2. linux的shell脚本入门

    Linux shell脚本入门教程 为什么要进行shell编程 在Linux系统中,虽然有各种各样的图形化接口工具,但是sell仍然是一个非常灵活 的工具.Shell不仅仅是命令的收集,而且是一门非常 ...

  3. [C#] Control.Invoke方法和跨线程访问控件

    在设计界面时,我们经常需要将一些需要时间才能完成的操作放在另一个线程(不同于UI主线程)中执行.但是这些操作可能需要将其结果或完成情况通知主线程,比如调用窗体的方法,或者触发事件(由界面响应事件),很 ...

  4. IIS功能查看、配置

    #获取所有IIS功能列表: get-webconfiguration -filter /system.webserver #查看目录浏览功能的配置信息:Get-WebConfiguration -fi ...

  5. Codeforces Round #115 B. Plane of Tanks: Pro 水题

    B. Plane of Tanks: Pro Time Limit: 20 Sec Memory Limit: 256 MB 题目连接 http://codeforces.com/contest/17 ...

  6. android Camera 数据流程分析

    这篇文章主要针对其数据流程进行分析.Camera一般用于图像浏览.拍照和视频录制.这里先对图像浏览和拍照的数据流进行分析,后面再对视频电话部分进行分析. 1.针对HAL层对摄像头数据处理补充一下 Li ...

  7. 和Timesten有个约会--Timesten技术专栏系列(一)

    作者: 三十而立 时间:2009年10月03日 12:08:42 本文出自 “inthirties(三十而立)”博客,转载请务必注明作者和保留出处http://blog.csdn.net/inthir ...

  8. iOS开发——UI篇OC篇&layoutSubviews和drawRect

    layoutSubviews和drawRect     首先两个方法都是异步执行.layoutSubviews方便数据计算,drawRect方便视图重绘.   layoutSubviews在以下情况下 ...

  9. JAXB完毕XML与Java对象的互转

    这段时间都老忙了,甚至连周末全部人员都在赶产品的进度,想想连续上12天班,人都有点晕了! 到这会儿最终有点时间.所以准备和大家分享一下JAXB,会不会有人认为有点陌生呢?没事,这里跟大伙儿简单的描写叙 ...

  10. 关于flash player debugger 无法弹窗报错的解决办法

    第一个是IE的插件, Download the Windows Flash Player 10.2 ActiveX control content debugger (for IE) (EXE, 2. ...