tipidee
Software
skarnet.org

The /etc/tipidee.conf configuration file

Goal and usage

/etc/tipidee.conf is a text file written by the web administrator to configure the tipideed server. After writing or modifying this file, the administrator is expected to run the tipidee-config program, that will read /etc/tipidee.conf and output a /etc/tipidee.conf.cdb file that will be suitable for tipideed to use.

tipidee-config provides sane defaults, so an empty /etc/tipidee.conf file is perfectly usable for purely static installations. But an empty file still needs to be created, unless tipidee-config is run with the -i /dev/null option.

Description

The /etc/tipidee.conf file contains a series of lines; every line is an instruction. Lines do not wrap around and there is no quoting, so a newline is always the end of an instruction. Empty lines, or lines containing only whitespace, or lines beginning with # (comments), are ignored. If a line contains a # that is not in the middle or end of a word, the rest of the line is also considered a comment, and ignored.

Words on a line are separated by whitespace (spaces or tabs). Instructions are one directive, the first word in the line, followed by one or more arguments. Most directives take a fixed number of arguments; some of them take a variable number. There are several types of directives.

Preprocessing directives

These are meta-directives: they do not control tipideed's behaviour directly, but tell tipidee-config to include other files. They allow administrators and packagers to write modular, pluggable configuration files. Preprocessing directives always start with a ! (exclamation point, or bang) character.

You will probably never see preprocessing directives in simple configuration files. They are meant for bigger or more generic configurations.

The !include directive

!include file

The !includedir directive

!includedir dir

The !included: directive

!included: unique
!included: multiple

Simple global settings

Global directives control global aspects of tipideed — values that apply to the server itself, no matter what domain it is serving.

Some global directives are introduced by their own keywords, see below. Others are simple configuration values that would clutter up the directive namespace, so we put them together under a unique umbrella, the global directive. global takes two arguments: the name of a setting and its value.

read_timeout

global read_timeout t

write_timeout

global write_timeout t

cgi_timeout

global cgi_timeout t

max_request_body_length

global max_request_body_length n

max_cgi_body_length

global max_cgi_body_length n

The index-file directive

index-file file1 file2 ...

index-file is a global directive, the first one in this list that is introduced by its own keyword and does not use global.

The log directive

log is a global directive, introduced by the keyword log. It allows the user to control what will appear in tipideed's log output.

log nothing
log keyword1 keyword2 ...

Here is the full list of keywords and what they do:

nothing
Don't log anything else than warning and error messages. This keyword cannot be given with other keywords.
start
Log a start line when tipideed starts and an exit exitcode line when it exits.
ip
Add an ip client_ip field to the start line. This is potentially PII, so make sure to stay compliant with your local laws if you activate it. client_ip is read from the TCPREMOTEIP environment variable. This keyword has no effect when given without the start keyword.
hostname
Add a host client_hostname field to the start line. This is potentially PII, so make sure to stay compliant with your local laws if you activate it. client_hostname is read from the TCPREMOTEHOST environment variable if it exists, or made up from TCPREMOTEIP otherwise. Make sure to invoke s6-tcpserver-access before tipideed in order to get meaningful values for this field. This keyword has no effect when given without the start keyword.
host_as_prefix
Prepend all request, resource and answer lines with a host host field. (This field will not be repeated in the request line, so it changes the order of the fields in that line.) host is the virtual host the request is addressed to. host_as_prefix is useful when you want to log entries for different virtual hosts to different locations: for instance, if you're using s6-log, and want entries for example.com and example.org to be logged to different backends, you would use the host_as_prefix directive, and use - +"^tipidee: pid [[:digit:]]*: info: host example\\.com " in your logging script to select example.com-related lines, and - +"^tipidee: pid [[:digit:]]*: info: host example\\.org " to select example.org-related lines. Note that warning and error messages would still need an additional backend, as well as potential start and exit lines.
request
Log a request line when tipideed receives a request from its client. The line looks like request method host host path "path" http version. The path is decoded, but if there are non-printable characters in it, they are encoded as hexadecimal values \0xab. If the request line includes a query, a query query field is added before the http field.
referrer
Add a referrer "referrer" field to the request line, for requests that include a Referer: header. referrer is quoted like path, to avoid malicious clients messing with log lines. This keyword has no effect when given without the request keyword.
user-agent
Add a user-agent "user-agent" field to the request line, for requests that include a User-Agent: header. user-agent is quoted like path, to avoid malicious clients messing with log lines. This keyword has no effect when given without the request keyword.
resource
Log a resource line when tipideed has found a resource corresponding to the URI and is willing to serve it. The line looks like resource file type type. file is the path to the served file; the first component of that path is always the document root of the virtual host. type is nph for an NPH script, cgi for a CGI script, or the Content-Type for a regular file. If it's a CGI or NPH script being called with a non-empty PATH_INFO, an additional path_info path_info field is added to the log line. If a served CGI script outputs a local redirection, several resource lines may appear for a single request.
answer
Log an answer line when tipideed answers the currently processed request. The line looks like answer status, where status is the 3-digit status code returned to the client. Note that there will be no answer line when a NPH script is being run (because tipideed execs into the NPH script).
answer_size
Add a size size field to the answer line, containing the Content-Length of the answer. This keyword has no effect when given without the answer keyword.
debug
Log debug information. You should not need this in regular use.

The content-type directive

content-type is a global directive, introduced by the keyword content-type. It allows the user to define mappings from a document's extension to a standard Content-Type.

content-type type extension1 extension2 ...

The custom-header directive

custom-header is global directive, introduced by the keyword custom-header. It allows the user to define custom headers that are to be added to every response. It takes a subcommand, that is used to define what should be done with the header:

custom-header add name value
custom-header always name value
custom-header remove name
custom-header never name

Local directives

All the other directives are local: they only apply to the current domain. Except for domain, they can only be used after a domain directive.

domain

domain domain

cgi

cgi directory
cgi file

noncgi

noncgi directory
noncgi file

nph-prefix

nph-prefix prefix

nph

nph directory
nph file

nonnph

nonnph directory
nonnph file

basic-auth

basic-auth directory
basic-auth file

no-auth

no-auth directory
no-auth file

file-type

file-type directory type
file-type file type

redirect

redirect resource rtype target

custom-response

custom-response status file