Mod ssi » History » Revision 27

Revision 26 (gstrauss, 2017-05-24 02:12) → Revision 27/28 (gstrauss, 2021-11-08 13:34)

h1. Server-Side Includes 


 *Module: mod_ssi* 

 h2. Description 

 SSI is a very old and cheap way to generate content dynamically on server-side.  

 The use of this module is strongly discouraged: 
 * the execution of a SSI script is done in the server-core 
 * a long-running SSI script blocks the handling of ALL connections 
 * as soon as you use #exec the performance gets worse than using CGI scripts directly 
 * lighttpd mod_ssi does not fully implement numerous SSI directives, such as #include virtual="...", which only includes file contents, and not output from other handlers 

 You should only use SSI for two reason: 
 * content assembling with #include for file inclusion only (*not* file execution via CGI or other handlers) 
 * legacy applications 

 [[Docs_ModMagnet|mod_magnet]] is recommended as a more powerful alternative to mod_ssi simple page construction. 
 A separate backend script (run as CGI, FastCGI, SCGI, etc) is recommended for any CPU intensive or database-backed page construction. 

 h2. Installation 

 You have to load the mod_ssi module and set the ssi.extension: 

 server.modules = ( ..., "mod_ssi", ... ) #Note that if you use mod_compress mod_ssi must come first to function. 

 h2. Options 

 h3. ssi.extension 

 List of file extensions that should be interpreted via mod_ssi. 


 ssi.extension = ( ".shtml" ) 

 h3. ssi.content-type 

 Content type of the pages being served via mod_ssi. 
 Default value: text/html 

 h3. ssi.conditional-requests 

 Enable/disable conditional request handling and generate ETag and Last-Modified response headers. 
 This should not be enabled unless the SSI requests are known to generate cacheable documents. An SSI page which only includes contents from other static files and/or which uses SSI commands that produce predictable output may be cacheable. 
 Default value: disable 

 h3. ssi.exec 

 Enable/disable #exec cmd="..." execution.    (lighttpd mod_ssi does not implement #exec cgi="...") 
 Default value: enable 

 h3. ssi.recursion-max (since 1.4.44) 

 Default value: 0 (disabled) 
 Set the max recursion depth for #include virtual="..." SSI processing.    The default, 0, preserves the existing behavior of simply including the file. 

 h2. Available Elements 


  <!--#echo var="..." --> 
  <!--#echo var="DOCUMENT_ROOT"--> 
  <!--#include file="..." file="..."\|virtual="..." --> 
  <!--#include virtual="..." --> 
  <!--#flastmod file="..." file="..."\|virtual="..." --> 
  <!--#flastmod virtual="..." --> 
  <!--#fsize file="..." file="..."\|virtual="..." --> 
  <!--#fsize virtual="..." --> 
  <!--#config timefmt="..." sizefmt="(bytes|abbrev)" --> 
  <!--#printenv --> 
  <!--#set var="..." value="..." --> 
  <!--#if expr="..." --> 
  <!--#elif expr="..." --> 
  <!--#else --> 
  <!--#endif --> 
  <!--#exec cmd="..." --> 
  <!--#exec cmd="date"--> 

 h2. Expression Handling 

 Every "expr" is interpreted: 
 * logical: AND, OR, ! 
 * compare: =, <, <=, >, =>, != 
 * precedence: (, ) 
 * quoted strings: 'string with a dollar: $FOO' 
 * variable substitution: $REMOTE_ADDR 
 * unquoted strings: string 

 h2. Flow Control 

 if, elif, else and endif can only be used to insert content under special conditions. 

 h2. Unsupported Features (Not Implemented) 

 The original SSI module from NCSA and Apache provided some more options which are not supported by this module for various reasons: 
 * config.errmsg 
 * echo.encoding 

 h2. Quick and Dirty Notes from the 90s or How to enable (Server Side Instruction) 

 * You need to activate the module `mod_ssi` berfor the module `mod_compress`! 
 * You need to set the variable in lighttpd.conf `ssi.extension = (".html")`. 
   (Here we say that every `.html` file can have `<!--#include file="something"-->` or other SSI instructions. The filetype extension of the included file is not relevant!) 
 * Cheers to the 90s