SSI(8)

💖 NAME 💖

ssi — the Server-Side-Includes CGI program, bestie 🫶

---

✨ SYNOPSIS ✨

ssi

like. that's it. no flags. no args. she just is. 💅

---

🌸 DESCRIPTION 🌸

okay so picture this: ssi is an external CGI program that does literally the exact same thing as the built-in server-side-includes feature that lives inside a bunch of HTTP daemons. she was written to hang out with thttpd(8) and merecat(8), but she's lowkey easy to adapt to other systems too. flexible queen 👑

there are two ways to use her:

the modern way 🌈 — you use a .shtml pattern in merecat.conf(5) to trigger the SSI script, which means you gotta enable the SSI module. and the traditional thttpd(8) approach 🦋.

let's start with the relevant settings you need in merecat.conf:

ssi {
    enabled = true
    pattern = "**.shtml"        # default
    cgi-path = "cgi-bin/ssi"    # default, web server root is used
}

the traditional thttpd way runs ssi as a plain simple CGI script, which means you gotta place the ssi binary in the web server CGI area and enable CGI. then you set up URLs where the path to the document you wanna parse is the "pathinfo". that's the part of the URL that comes after the CGI program name. iykyk ✨

for example, if the URL to this program is:

http://www.acme.com/cgi-bin/ssi

and the url for the document is:

http://www.acme.com/users/wecoyote/doc.html

then the compound URL would be:

http://www.acme.com/cgi-bin/ssi/users/wecoyote/doc.html

periodt. that's the whole vibe 💅

---

🎀 INCLUDE FORMAT 🎀

the format description below is adapted from http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html. (not me linking my sources, academic icon behavior 📚)

all directives are formatted as SGML comments inside the document. why? just in case the document ever finds itself in the client's hands unparsed 🙈. every directive has this format:

<!--#command tag1="value1" tag2="value2" -->

note: see how there's no space between the initial HTML comment start and the #command? that's not a typo, bestie, that is explicitly stated in the standard and strictly enforced by all web servers implementing SSI. do not add a space. do not be cute about it. the server will not be cute back. 💀

each command takes different arguments, and most of them only accept one tag at a time. here's the breakdown of the commands and their associated tags:

🦋 config

the config directive controls various aspects of the file parsing. there are two valid tags... and also a third one that just kind of showed up, we'll get there:

• timefmt — gives the server a new format to use when providing dates. it's a string compatible with the strftime(3) library call. ⏰
• sizefmt — decides how the size of a file gets formatted. valid choices are bytes, for a formatted byte count (formatted like 1,234,567), or abbrev for an abbreviated version showing the number of kilobytes or megabytes the file occupies. 📏
• errmsg — overrides the default; "[an error occurred while processing this directive]". so iconic of her to have a default error message ready to go 😭

🌈 include

inserts the text of another document into the parsed document. and bestie, the inserted file gets parsed recursively, so it can contain server-side-include directives too. it's giving infinite nesting potential. this command accepts two tags:

• virtual — gives a virtual path to a document on the server.
• file — gives a pathname relative to the current directory. ../ cannot be used in this pathname, nor can absolute paths be used. nope. no escape attempts. the server said no 🚫

✨ echo

prints the value of one of the include variables (defined below). any dates get printed subject to the currently configured timefmt. the only valid tag for this command is var, whose value is the name of the variable you wish to echo. 🗣️

💜 fsize

prints the size of the specified file, subject to the sizefmt parameter of the config command. valid tags are the same as with the include command. 📐

👑

flastmod

prints the last modification date of the specified file, subject to the formatting preference given by the timefmt parameter to config. valid tags are the same as with the include command. 🕰️

---

🧚 VARIABLES 🧚

a whole bunch of variables are made available to parsed documents. on top of the CGI variable set, these following variables are also available:

• DOCUMENT_NAME — the current filename. 📄
• DOCUMENT_URI — the virtual path to this document (such as /~robm/foo.shtml). 🔗
• QUERY_STRING_UNESCAPED — the unescaped version of any search query the client sent. 🔍
• DATE_LOCAL — the current date, local time zone. subject to the timefmt parameter to the config command. 🌍
• DATE_GMT — same as DATE_LOCAL but in Greenwich mean time (GMT). 🌐
• LAST_MODIFIED — the last modification date of the current document. subject to timefmt like the others. 🕐

---

👀 SEE ALSO 👀

merecat(8), merecat.conf(5), strftime(3)

go read those too, bestie, they're part of the lore 📖✨

---

🫶 AUTHORS 🫶

• Jef Poskanzer <jef@mail.acme.com> wrote the original for use with thttpd. the OG, the blueprint, we stan 👑
• Joachim Wiberg <troglobit@gmail.com> added minor features and a trigger in merecat for .shtml pages. the upgrade arc 🌟

---

💀 BUGS 💀

does not implement all "modern" SSI directives are supported. e.g., exec cgi and exec cmd or any control directives like if, elif, else, endif, etc. so like... some of the fancy modern stuff is simply not here yet. she's doing her best. 😭

patches and pull-requests are welcome :) — for real, fr fr, slide into the repo 🫶

---

and that's the whole page, bestie! this little love letter to ssi shipped with merecat (2.32) back on Aug 3, 2019 💖 thank you for coming to my ted talk, now go parse some includes ✨🎀🦋