Configuration Files

Note: you can usually avoid ever dealing with profile files by using Sawmill through the web browser interface. You only need to know about profile files if you want to edit them directly (which is usually faster than using the web interface), or use them from the command line, or if you need to change options which are not available through the web interface.

All Sawmill options are stored in text files called configuration files (or profile files if they contain the options of a particular profile). Configuration files use a very simple format; each option is give in the format

  name = value

and options can be grouped like this:

  groupname = {
    name1 = value1
    name2 = value2
    name3 = value3
  } # groupname

Within this group, you can refer to the second value using the syntax groupname.name2. Groups can be within groups like this:

  groupname = {
    name1 = value1
    subgroupname = {
      subname1 = subvalue1
      subname2 = subvalue2
    } # subgroupname
    name3 = value3
  } # groupname

Hash characters (#) are comment markers; everything after a # is ignored, until the end of the line. Multiline comments can be created using {# before the command and #} after it. In this case, the subgroup name has been listed as a comment on the closing bracket; this is customary, and improves legibility, but is not required. In this case, subvalue2 can be referred to as groupname.subgroupname.subname.

There are no limits to the number of levels, the number of values per level, the length of names or labels, or anything else.

In addition to groupings within a file, groupings also follow the directory structure on the disk. The LogAnalysisInfo folder is the root of the configuration hierarchy, and files and directories within it function exactly as though they were curly-bracket groups like the ones above. For instance, the preferences.cfg file (cfg stands for configuration group) can be referred to as preferences; the server group within preferences.cfg can be referred to as preferences.server, and the web_server_port option within the server group can be referred to as preferences.server.web_server_port. So for instance, in a web server command line you can change the default port like this:

  sawmill -ws t -preferences.server.web_server_port 8111

If you happen to know that the shortcut for web_server_port is wsp, you could also shorten this:

  sawmill -ws t -wsp 8111

(-ws t is required to tell Sawmill to start its server).

Through this type of hierarchical grouping by directories within LogAnalysisInfo, and by curly-bracket groups within each configuration file, all configuration options in the entire hierarchy can be uniquely specified by a sequence of group names, separated by dots, and ending with an option name. All options in Sawmill are specified in this way, including profile options, preferences, language module (translation) variables, users, scheduling options, documentation, spider/worm/search engines information, command line and internal options, and more.

Sawmill creates a profile file in the profiles subdirectory of the Sawmill directory when you create a profile from the graphical interface (see The Administrative Menu). Profile files can also be created by hand using a text editor, though the large number of options makes this a difficult task to do manually -- it is best scripted, or done by copying an existing profile file and editing it. To use files as profile files, you will need to put them in the profiles directory.

Any profile which can be specified in a profile file can also be specified in The Command Line by using the same profile options. Command line syntax is longer if full profile names are used, because each option on the command line must be specified using the full group1.group2.group3.option, when in the profile it appears only as option (within the groups). However, most options have shortcuts which can be used instead; see the option documentation for each option's shortcut (All Options),

To see a sample profile file, use the web browser interface to create a profile, and then examine the file in the profile directory.