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. poj 3635 Full Tank? ( bfs+dp思想 )

    Full Tank? Time Limit: 1000MS   Memory Limit: 65536K Total Submissions: 5857   Accepted: 1920 Descri ...

  2. 分析恶意驱动(进程启动apc注入dll)

    一.前言  用IDA也有好些时间了,以前就只会用F5功能玩无壳无保护的裸驱动,感觉太坑了,这两天就开始看网上大牛的逆向. 今天记录一下sudami曾经逆向过的fuck.sys.第一遍自己走的时候漏掉了 ...

  3. [IoC容器Unity] ：Unity预览

    1.引言 高内聚,低耦合成为一个OO架构设计的一个参考标准.高内聚是一个模块或者一个类中成员跟这个模块或者类的关系尽量高,低耦合是不同模块或者不同类之间关系尽量简单. 拿咱国家举例来说,假如你是中国人 ...

  4. Node.js：实现知乎(www.zhihu.com)模拟登陆，获取用户关注主题

    前一段时间,在瞎看看 Node.js,便研究通过 Node.js 实现知乎模拟登陆.相信,有很多网站有登陆权限设置,如若用户未登陆,将会跳转至首页提醒用户登陆,无法浏览部分页面. 如若是 b/s 架构 ...

  5. status pending状态

    开发采用ssh,注解的方式,事物也application.xml配置了,但是在业务层没有使用@Transactional造成浏览器一直处于status pending状态,为什么没有使用@Transa ...

  6. SSH登录失败：Host key verification failed

    转载自:https://help.aliyun.com/knowledge_detail/41471.html 注意:本文相关 Linux 配置及说明已在 CentOS 6.5 64 位操作系统中进行 ...

  7. CCLabelTTF、CCLabelAtlas和CCLabelBMFont的区别

    转自:http://blog.sina.com.cn/s/blog_67a5e47201018tj8.html 在Cocos2d以及Cocos2d-x中,我们经常会用到CCLabelTTF以及CCLa ...

  8. 记录一下在WinXP上搭建Apache的httpd+PHP+MySQL+Wordpress的过程

    实验室有台旧电脑,想用它一台服务器. 不知为何,U盘启动盘死活不能启动,所以放弃了安装Linux的念头,直接在原来的XP上弄一个服务器,毕竟用的人也不多,也就局域网的这几个人, 本来主要是搭建一个FT ...

  9. Uestc_suibian 暑假集训总结

    唉,终于组队了,终于可以只BB了,我就BB,我就不上! 和Xiper以及chenxh组队了- 下面是总结: day1 第一天吃饱喝足,然后就上路了,我一开始就看到了C题大水题,但是我不敢想象这道题居然 ...

  10. php 下载远程图片 的几种方法(转)

    1.获取远程文件大小及信息的函数 function getFileSize($url){          $url = parse_url($url);          if($fp = @fso ...