Bricolage Configuration Directives

by David Wheeler
January 06, 2005

In my previous article, I provided a guided tour of the Bricolage installation process. If you followed along, you should now have a nice, functioning installation of Bricolage 1.8 all ready to go. But as Mr. Popeil used to say, "But wait, there's more!"

Like many other applications, Bricolage comes with a runtime configuration file. This file, named bricolage.conf, lives in the conf subdirectory of your Bricolage root. It contains a list of settings that tell Bricolage how to find things, how to connect to the database, which optional features to include, and other good stuff. This article provides a guided tour of all of the configuration settings in bricolage.conf to enable you to configure things exactly the way you need them, so that you can manage your sites more effectively with Bricolage.

Configuration Format

The format of bricolage.conf, derived from the Perl Cookbook, is quite simple. A directive appears on a single line, followed by a space, an equal sign, and then the value. Anything after a pound sign (#) is a comment. Typical entries look like this:

APACHE_BIN   = /usr/local/apache/bin/httpd
APACHE_CONF  = /usr/local/bricolage/conf/httpd.conf
LISTEN_PORT  = 80
SSL_PORT     = 443
SSL_ENABLE   = No

Most bricolage.conf configuration options are one of two types: Boolean values or strings. A Boolean configuration directive can be either enabled or disabled, but you have several ways in which to do so. To enable a Boolean directive, simply set its value to Yes, On, or 1 (the number one). To disable it, set it to No, Off, or 0 (zero). String values follow the equal sign. They can be as long as necessary, but cannot break across lines.

Apache Configuration

0

The first section of bricolage.conf configures Bricolage to use the Apache web server. Because Bricolage runs on top of Apache but uses its own startup scripts, it needs to know where to find Apache resources so that it can configure and start Apache properly. Bricolage's default method of dynamically configuring Apache therefore relies on these directives. The installation sets many of them for you, but not all, so it's worth it to have a look to see if you need to tweak any of them:

APACHE_BIN

This directive tells Bricolage where to find your Apache httpd executable, which it uses to start itself up.

APACHE_CON

This directive points to the httpd.conf file. This, of course, is the famous Apache configuration file. It, too, needs configuration to run Bricolage (the Bricolage installer configures the default httpd.conf in the conf subdirectory of your Bricolage root directory), and Bricolage, in turn, uses this directive to tell httpd where to find the configuration file when it starts up.

LISTEN_PORT

This is the TCP/IP port on which Bricolage will listen for requests. It uses the HTTP standard port 80 by default, but you can change Bricolage to use another port if you already have another server listening on port 80.

SSL_PORT

This is the TCP/IP port on which Bricolage will listen for secure sockets layer (SSL) requests. It defaults to the standard HTTP SSL port 443, but again, you can change it to another port if something else is already using port 443. SSL is disabled by default, however, so read on for details on how to turn it on.

SSL_ENABLE

This directive turns on SSL support. You must have either mod_ssl or Apache-SSL installed and properly configured in your Apache server. Not quite a Boolean configuration directive, the possible values for SSL_ENABEL are No (or Off or 0 [zero]), mod_ssl, or apache-ssl. SSL is a useful feature for keeping communications encrypted between the server and users' browsers.

ALWAYS_USE_SSL

By default, an SSL-enabled Bricolage installation uses SSL only for logging in to Bricolage and in the user profile (where users can change their passwords). Users can elect to encrypt all communications by checking the Always use SSL checkbox when logging in, but some security policies may require the encryption of all communications. In such cases, enable this Boolean directive to force the encryption of all communications between the Bricolage server and users' browsers.

SSL_CERTIFICATE_KEY_FILE

SSL_CERTIFICATE_FILE

These directives specify the location of your SSL keys. If you've configured mod_ssl or Apache-SSL, you should already be familiar with these files. They help to encrypt and decrypt requests between the server and the browser. If you use make certificate to generate your SSL certificate during the Apache build process, by default your server key file will be server.key in the conf/ssl.key subdirectory of your Apache root directory, while the server public key file will be server.crt and in the conf/ssl.crt subdirectory. Bricolage uses these directives to set the Apache SSLCertificateKeyFile and SSLCertificateFile directives, respectively, in its dynamic configuration of Apache.

NAME_VHOST

This directive roughly corresponds to the Apache httpd.conf NameVirtualHost directive. Set it to the IP address on which the Bricolage Apache server will listen for requests. If you have only one IP address on your server, the simplest thing to do is to leave this directive set to *, which applies to all IP addresses. Again, Bricolage uses this directive in its dynamic configuration of Apache.

VHOST_SERVER_NAME

This is the virtual host name under which to run Bricolage. Bricolage requires a full host or virtual host to run and will use this directive to configure the virtual host dynamically. Leave it set to _default_ to use the default host name set in your httpd.conf file.

MANUAL_APACHE

Bricolage uses Apache::ReadConfig to configure the httpd daemon. There is no httpd.conf include file. If you want to take control of your Bricolage Apache server by manually configuring it, enable this Boolean directive. It will generate a file, bric_httpd.conf, in the bricolage subdirectory of your temporary directory (see the TEMP_DIR directive for the location of the temporary directory). This file will contain all of the Apache configuration directives that Bricolage uses to configure Apache dynamically. Restarting Bricolage will rewrite this file, but if you want to use it and edit it manually, copy it to the conf subdirectory of your Bricolage root directory, disable the MANUAL_APACHE directive, and then change the section of the httpd.conf file that configures Bricolage from:

PerlPassEnv BRICOLAGE_ROOT
PerlModule Bric::App::ApacheConfig

To:

Include /usr/local/bricolage/conf/bric_httpd.conf
PerlPassEnv BRICOLAGE_ROOT
PerlModule Bric::App::ApacheStartup

Here /usr/local/bricolage/conf/bric_httpd.conf is the full path name to the newly generated bric_httpd.conf file. You can now tweak this file to your heart's content. Just be sure to generate a new one after each upgrade of Bricolage, as certain directives may change between releases.

SYS_USER

SYS_GROUP

These directives configure the system user and group used by Bricolage. They should contain the same value as the User and Group httpd.conf directives, usually nobody or www. Any files written to the file system by Bricolage will be owned by this user and group.

Database Configuration

The next major section of the Bricolage configuration file configures the database. Bricolage uses PostgreSQL 7.3 or later for its data store. Connecting to that database requires several attributes, not least of which are the username and password. These are all set during installation, but it's worth being familiar with them in case things change down the line.

DB_NAME

The name of the database that stores Bricolage's data. The installer will set this for you. The default value, bric, works well in most situations, but it might be set to a different name if you entered one during installation, perhaps because you already had another database named bric; Why would you want to do that? Perhaps you have multiple Bricolage installations on the same host. Another reason it might be different is that your ISP provides you with a single database that they name according to their own naming conventions. At any rate, you're unlikely to need to change the value of this directive.

DB_USER

The username that Bricolage will use when connecting to the database. Again, you are unlikely to need to change this directive, especially because, when Bricolage creates the database, it specifically assigns permissions for this user to access the appropriate tables, sequences, and such. Note that, for security reasons, you should never use the PostgreSQL superuser for this directive.

DB_PASS

The password for the DB_USER to use to connect to the PostgreSQL database. You'll need to change this directive if the password ever changes in the database. Depending on your PostgreSQL server's security model, it might not matter what the password is. For example, if the PostgreSQL is on the same host as your Bricolage server and trusts local users (the default configuration), it will ignore the password. Consult your PostgreSQL authentication settings (in the server's pg_hba.conf file) or check with your PostgreSQL DBA if you have questions.

DB_HOST

This is the host name of your PostgreSQL server. If it's on the same host as your Bricolage server, it will likely be commented out, thereby letting Bricolage default to localhost. Otherwise, it will be a different host name or IP address. Change this setting if ever your PostgreSQL server moves to a different host or has its host name or IP address changed.

DB_PORT

The TCP/IP port on which your PostgreSQL server listens for connections. This directive will be commented out if you've installed PostgreSQL locally and you're using Unix sockets instead of TCP/IP for its connectivity (a good idea for security-conscious environments). It will also be commented out if Bricolage should use the default PostgreSQL port of 5432. Otherwise, if Bricolage must connect to the PostgreSQL server via TCP/IP on a port other than 5432, set this directive to the appropriate port number.

Pages: 1, 2, 3, 4

Next Page