This page describes the file format of the main configuration file used by the Canopy Web server. In a standard installation, this file should be located at /usr/local/etc/canopy.conf. This configuration file is read and parsed every time the Canopy server starts or performs a self-restart.

• Overview
• Meta-Characters and Escaping
• Multi-line Statements
• Quoted Strings
• Variables
• Assignment
• Interpolation
• Directives
• include
• listen
• loadmod
• BNF Grammar

Overview

The configuration file is a standard free-form ASCII text file consisting of variable assignments and directives, each on a separate line. Comments can be placed anywhere in the file by putting a hash character ('#') and span to the end of the line.

# This is a comment

VAR = foo  # this is another comment

Meta-Characters and Escaping

The configuration parser recognizes several meta-characters that act as operators. They are called meta-characters because they have a special meaning and they trigger a special functionality of the parser instead of appearing like regular characters. Here is a table listing all of the configuration metacharacters:

Because of their special meaning, metacharacters are not actually part of the stream. This can be problematic in some situations; imagine that you have to assign a password to a variable, and that password contains a '$' character. When it sees the '$', the parser will attempt to read a variable name following it and replace that token with the variable's value, and this is definitely NOT what we want:

# The value of PASSWORD would end up being 'aB56-1', assuming there is no variable
# called 'jk'
PASSWORD = aB56$jk-1

To get the proper character as part of the value, you will need to escape it, using one of the metacharacters, the escape character ('\'), like in this example:

# In this example, PASSWORD will contain what we expect, 'aB56$jk-1'
PASSWORD = aB56\$jk-1

# You can also escape the escape character itself, like in the following example, where
# the variable will contain the value '\7y4'

PASSWORD = \\7y4

A more in-depth discussion of each operator follows.

Multi-line Statements

A single line can be split into multiple lines for readability by putting the escape character as the last character of the line. When the lines are joined, the newline is replaced by whitespace.

# a multi-line statement
directive_blah argument1 argument2 argument3 argument4 \
argument5 argument6 argument7 \
   argument8

Quoted Strings

Variables

Assignment

A variable can be created by assigning it a value. Assignment is done with the assignment operator (the equal character, '='); any amount of whitespace can be placed before or after the operator.

VARIABLE = foo

Interpolation

Directives

include

listen

Synopsis:

The listen directive tells the server to listen for incoming connection requests on a specific network address and port.

loadmod

The loadmod directive tells the server to load a DSO module

BNF Grammar

The following is a Bachus-Naur Form of the grammar for the configuration file: