Bricolage Configuration Directives
by David Wheeler
|
Pages: 1, 2, 3, 4
Directory Settings
Bricolage stores a lot of files on your server's file system, generally in well-named directories below your Bricolage root directory. Sometimes you may want them installed elsewhere, perhaps for the purposes of conserving disk space or distributing I/O between different partitions. If you want to move any of these directories to a location other than that set by the installer, copy over any existing files to ensure that Bricolage continues to operate correctly.
TEMP_DIR-
Bricolage creates several temporary files as it runs, for its cache, user sessions, and the like. If you selected the
multi
option when installing Bricolage, this directive will point to a directory named tmp under your Bricolage root. Otherwise, it will point to your system's global tmp directory. MASON_COMP_ROOT-
The Bricolage UI uses HTML::Mason. All of the components to power the UI live in this directory, generally a subdirectory of your Bricolage root named comp. However, media files uploaded to Bricolage also go in this directory, which means that it can become quite large if you manage a lot of media documents. It might be useful, therefore, to move this directory to a separate partition.
MASON_DATA_ROOT-
Mason compiles the Bricolage UI components into object files and stores them in this directory. For the most part you don't need to worry about where these files live (the default is the data directory under the Bricolage root directory), although Bricolage will read from it quite a lot as it loads the object files into memory, so disk I/O is important. It's unlikely to grow too except...
BURN_ROOT-
This directive tells Bricolage where to store formatting templates, object files, and burned files that are ready for distribution. As such, it can also grow quite large, especially if you've published or previewed a lot of documents. Bricolage never deletes these files so that you always have a canonical directory of the distribution files output by Bricolage. However, the default location for the
BURN_ROOTis under the directory specified by theMASON_DATA_ROOTdirective. If you encounter disk space problems, you might want to move this directory to another partition.
XML::Writer Configuration
The Bricolage Mason burner is responsible for pushing documents through Mason formatting templates. If you're writing templates that output XML (and I'll demonstrate writing templates in a later article, so hang in there!), you might want to simplify things by using an XML::Writer object to generate the XML. Bricolage simplifies things by providing these directives to create a globally available XML::Writer object for use in all Mason templates.
INCLUDE_XML_WRITER-
Enable this Boolean directive to tell Bricolage to create an XML::Writer object that's globally available as
$writerto all Mason templates. Bricolage is smart enough to configure the XML::Writer object to output XML to Mason's buffer, so that you can even mix standard Mason output in your templates with XML::Writer output. XML_WRITER_ARGS-
Use this directive to specify a list of options to pass to the XML::Writer constructor when
INCLUDE_XML_WRITERis enabled. This directive is a string containing a Perl expression to pass to XML::Writer. The XML::Writer documentation has the full list of possible parameters. Common parameters includeNEWLINESto trigger the output of new lines between XML elements, andDATA_INDENTto indent nested XML elements by a certain number of characters.
Authentication Configuration
Several configuration directives affect the behavior and security of the Bricolage authentication system. Bricolage handles its own authentication, storing passwords in the database as MD5-encrypted hashes and recording authentication in a browser cookie. In a security-conscious environment, it pays to be familiar with these directives and even to review their settings periodically.
AUTH_TTL-
This directive specifies the time-to-live, in seconds, for an authentication session. Each time an authenticated user sends a request to the server, the elapsed time resets to zero. You could therefore set
AUTH_TTLto 3600 seconds for a one-hour time-to-live, and a user would be able to use Bricolage all day, as long as each request was less than an hour apart (but she might have to re-authenticate after lunch). This directive is especially useful in environments where users access Bricolage from public workstations and forget to log out. The default value of 28800 (eight hours) is probably too long in a production environment. AUTH_SECRET-
Bricolage stores the user authentication session locally and keys it off of an MD5 string stored in a browser cookie. The MD5 string comes from the browser's IP subnet, the expiration time, the user name, and the last access time. Because such a string is potentially replicable by someone trying to crack the system, Bricolage also uses a random string of characters to salt the MD5 string.
AUTH_SECRETis the string used for this purpose. The installer generates it for you, but you might want to change it now and then, in order to keep it random and meet the specifications of your security policy. All users will need to re-authenticate after you changeAUTH_SECRETand restart Bricolage. LOGIN_LENGTH-
This directive specifies a minimum user name length. Each user must have a user name of at least this number of characters. The default,
5
, is generally adequate, and allows the defaultadmin
user name to work properly. PASSWD_LENGTH-
This directive corresponds to the
LOGIN_LENGTHdirective, but applies to passwords. The password length in Bricolage is unlimited, but it's generally a good idea to ensure that they all contain a minimum number of characters. The default is5
.
Distribution Configuration
When Bricolage previews or publishes documents, it pushes them through formatting templates (written in Mason, Template Toolkit, or HTML::Template) and writes the resulting files to disk. It then distributes those files to the appropriate servers specified in the destination manager in the user interface. (A later article will explain more of the Bricolage administrative interface.) Many run-time configuration directives affect the behavior of the Bricolage distribution server.
ENABLE_DIST-
This Boolean directive enables Bricolage distribution. The only reason to disable distribution is if you set up a separate distribution server. To my knowledge, no one has actually done this, even though Bricolage supports it. The QUEUE_PUBLISH_JOBS directive is more popular to reduce Bricolage server overhead.
DIST_ATTEMPTS-
Bricolage distributes files via file system copy, FTP, SFTP, or WebDAV—depending on your destination configuration. We all know that failures can occasionally occur. Bricolage will attempt to distribute a file after a failed distribution and will do it multiple times. Set the
DIST_ATTEMPTSdirective to the number of times it should attempt to distribute a file before giving up. PREVIEW_LOCAL-
This Boolean directive enables Bricolage's internal preview server. This is just a URI in the Bricolage UI that knows to serve previewed content rather than the UI. This is handy for evaluating Bricolage, but be sure to disable it in a production environment, especially if your front-end server needs to serve something other than static HTML. The recommended approach is to set up a separate preview server that is identical to your production server and configure a destination to distribute and redirect previews to that server.
PREVIEW_MASON-
With the
PREVIEW_LOCALdirective enabled, if the content you're generating includes Mason calls, you can enable this boolean directive to make Bricolage's internal preview server evaluate the Mason code before serving documents. DEF_MEDIA_TYPE-
This string directive identifies the default media type (also called a
MIME type
) of files for which Bricolage cannot determine the media type. The default value,text/html
, covers a lot of typical files in a Web content management environment, such as .php or .jsp files. To add new types for Bricolage to recognize, use the media type manager in the UI. ENABLE_SFTP_MOVER-
By default, Bricolage does not support distribution via secure FTP (SFTP). If you need it, install the required Net::SFTP module, enable this directive, and restart Bricolage.
SFTP_HOME-
If you've enabled SFTP distribution, use this directive specify a home directory for SFTP to use, especially if you want to use public and private SSH keys. Consult the Net::SFTP documentation for details.
ENABLE_SFTP_V2-
Enable this directive to prefer SSH2 support for SFTP distribution. You'll also need to install more Perl modules from CPAN. Consult the Net::SFTP documentation for details.
SFTP_MOVER_CIPHER-
Net::SFTP uses the Net::SSH::Perl module to handle the SSH side of things. This module supports multiple encryption ciphers. If you prefer one, specify it via this directive.
ENABLE_WEBDAV_MOVER-
Bricolage also supports distribution via WebDAV, a standard for distributing documents via the HTTP protocol. DAV, as it is also known, has support in multiple web servers including Microsoft's IIS and Apache 2. If you'd like to distribute document files to your production server or servers via DAV, install the HTTP::DAV module, enable this Boolean directive and restart Bricolage.
QUEUE_PUBLISH_JOBS-
By default, when a user schedules a document to publish immediately, the Bricolage server will immediately execute the distribution. If users publish a lot of documents or you're bulk publishing large sections of your site at once, this can really slow down the Bricolage UI for other users. This is even true even if you've scheduled a bulk of documents to publish at a future date and time, because the way the default bric_dist_mon script works is to tickle the Bricolage server to distribute documents.
The way around this problem is to enable the
QUEUE_PUBLISH_JOBSboolean directive and then use the bric_queued program instead of bric_dist_mon. WithQUEUE_PUBLISH_JOBSenabled, the Bricolage server will never burn and distribute documents, even if a user schedules them to publish yesterday. Instead, bric_queued handles all of the burning and distribution itself, without having the Bricolage server expend resources on the task. With this approach, be sure to run bric_queued from a fairly aggressive cron job. FTP_UNLINK_BEFORE_MOVE-
When Bricolage distributes files via FTP, it uploads them with a temporary file name, and then, when the transfer is complete, it renames the file to the final name. However, if an earlier version of the file is already present, the rename might fail. (This depends on your FTP server, but Microsoft's IIS is the server that led us to add this feature.) In such a case, enable this directive and Bricolage will delete any existing instance of the file before renaming the temporary file.
