| DICOD.CONF(5) | GNU Dico Reference | DICOD.CONF(5) |
dicod.conf - GNU dictionary server configuration file.
The file /etc/dicod.conf contains configuration settings and database definitions for the GNU dictionary server dicod(8). The server reads this file once, upon startup, and uses the settings until it is shut down or the HUP signal is delivered, in which case previous configuration settings are discarded and the file is re-read.
This manpage is a short description of the dicod.conf configuration file. For a detailed discussion, including examples and usage recommendations, refer to the GNU Dico Manual available in texinfo format. If the info reader and GNU Dico documentation are properly installed on your system, the command
should give you access to the complete manual.
You can also view the manual using the info mode in emacs(1), or find it in various formats online at
If any discrepancies occur between this manpage and the GNU Dico Manual, the later shall be considered the authoritative source.
There are three classes of lexical tokens: words, quoted strings, and separators. Blanks, tabs, newlines and comments, collectively called white space are ignored except as they serve to separate tokens. Some white space is required to separate otherwise adjacent keywords and values.
A word is a sequence of letters, digits, and any of the following characters: _, -, ., /, @, *, :, [, ].
A quoted string is any sequence of characters enclosed in double-quotes ("). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:
Sequence Expansion ASCII \\ \ 134 \" " 042 \a audible bell 007 \b backspace 010 \f form-feed 014 \n new line 012 \r charriage return 015 \t horizontal tabulation 011 \v vertical tabulation 013
In addition, the sequence \newline is removed from the string. This allows to split long strings over several physical lines, e.g.:
"a long string may be\
split over several lines"
If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued.
Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as the example above:
"a long string may be" " split over several lines"
A here-document is a special construct that allows to introduce strings of text containing embedded newlines.
The <<word construct instructs the parser to read all the following lines up to the line containing only word, with possible trailing blanks. Any lines thus read are concatenated together into a single string. For example:
<<EOT A multiline string EOT
The body of a here-document is interpreted the same way as a double-quoted string, unless word is preceded by a backslash (e.g. <<\EOT) or enclosed in double-quotes, in which case the text is read as is, without interpretation of escape sequences.
If word is prefixed with - (a dash), then all leading tab characters are stripped from input lines and the line containing word. Furthermore, - is followed by a single space, all leading whitespace is stripped from them. This allows to indent here-documents in a natural fashion. For example:
<<- TEXT
The leading whitespace will be
ignored when reading these lines. TEXT
It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a here-document appears as the last element of a statement. In this case a semicolon can be placed on the same line with its terminating delimiter, as in:
help-text <<-EOT
A sample help text. EOT;
The usual comment styles are supported:
C style: /* */
C++ style: // to end of line
Unix style: # to end of line
Pragmatic comments are similar to the usual single-line comments, except that they cause some changes in the way the configuration is parsed. Pragmatic comments begin with a # sign and end with the next physical newline character.
A simple statement consists of a keyword and value separated by any amount of whitespace. Some statements take more than one value. Simple statement is terminated with a semicolon (;).
The following is a simple statement:
pidfile /var/run/direvent.pid;
See below for a list of valid simple statements.
A value can be one of the following:
A block statement introduces a logical group of statements. It consists of a keyword, followed by an optional value, called a tag, and a sequence of statements enclosed in curly braces, as shown in the example below:
acl global {
allow all from 198.51.100.0/24;
deny all;
}
The closing curly brace may be followed by a semicolon, although this is not
required.
user nobody; group (man, dict +88);
This statement is ignored if no user statement is present or if dicod is running in inetd mode.
Elements of LIST can have the following forms:
The PORT part is either a numeric port number or a symbolic service name from the /etc/services file.
Either of the two parts may be omitted. If HOST is omitted, the server will listen on all interfaces. If PORT is omitted, the default port 2628 will be used.
Either HOST or PORT (but not both) can be omitted. Missing HOST defaults to IPv4 addresses on all available network interfaces, and missing PORT defaults to 2628.
Either HOST or PORT (but not both) can be omitted. Missing HOST defaults to IPv6 addresses on all available network interfaces, and missing PORT defaults to 2628.
This statement along with max-children allows you to control the server load.
The authentication database is defined as:
user-db URL {
# Additional configuration options.
options STRING;
# Name of the password resource.
password-resource RESOURCE;
# Name of the resource returning user group information.
group-resource RESOURCE;
}
The URL consists of the following parts (square brackets denoting optional ones):
TYPE://[[USER[:PASSWORD]@]HOST]/PATH[PARAMS]
where:
The following statements can appear within the user-db block:
The exact semantics of the database resource depends on the type of database being used. For flat text databases, it means the name of a text file that contains these data, for LDAP databases, the resource is the filter string, etc. Please refer to the GNU Dico Manual, subsection 4.3.3 Authentication for a detailed discussion.
The SASL authentication is available if the server was compiled with GNU SASL. It is configured using the following statement:
sasl {
# Disable SASL mechanisms listed in MECH.
disable-mechanism MECH;
# Enable SASL mechanisms listed in MECH.
enable-mechanism MECH;
# Set service name for GSSAPI and Kerberos.
service NAME;
# Set realm name for GSSAPI and Kerberos.
realm NAME;
# Define groups for anonymous users.
anon-group GROUPS;
}
Define an ACL:
acl NAME {
DEFINITION...
}
The parameter NAME assigns a unique name to that ACL. This name will be used by another configuration statements to refer to that ACL (see SECURITY SETTINGS, and Database Visibility).
Each DEFINITION is:
allow|deny [all|authenticated|group GROUPLIST] [acl NAME] [from ADDRLIST]
A definition starting with allow allows access to the resource, and the one starting with deny denies it.
The next part controls what users have access to the resource:
The acl part refers to an already defined ACL.
The from keyword declares that the client IP must be within the ADDRLIST in order for the definition to apply. Elements of ADDRLIST are:
GNU Dico provides a feature similar to Apache's CustomLog, which keeps a log of MATCH and DEFINE requests.
[04/Jun/2008:11:05:22 +0300]
[%d/%b/%Y:%H:%M:%S %z]
The absence of access-log-format statement is equivalent to the following:
access-log-format "%h %l %u %t \"%r\" %>s %b";
The server hostname is used, among others, in the initial reply after the 220 and may also be displayed in the access log file using the %v escape (see ACCESS LOG).
It is common for TEXT to use the here-document syntax, e.g.:
server-info <<EOT
Welcome to the FOO dictionary service.
Contact <dict@foo.example.org> if you have questions or
suggestions.
EOT;
The default reply displays a list of commands understood by the server with a short description of each.
If TEXT begins with a plus sign, it will be appended to the default reply.
Capabilities are certain server features that can be enabled or disabled at the system administrator's will. The following capabilities are defined:
The capabilities set using this directive are displayed in the initial server reply, and their descriptions are added to the HELP command output (unless specified otherwise by the help-text statement).
A database module is an external piece of software designed to handle a particular format of dictionary databases. This piece of software is built as a shared library that `dicod' loads at run time.
A handler is an instance of the database module loaded by dicod and configured for a specific database or a set of databases.
Database handlers are defined using the following block statement:
load-module NAME {
command CMD;
}
The load-module statement creates an instance of a database module. The NAME argument specifies a unique name which will be used by subsequent parts of the configuration to refer to this handler. The command line for this handler is supplied with the command statement. It must begin with the name of the module (without the library suffix) and can contain any additional arguments. If the module name is not an absolute file name, the module will be searched in the module load path.
For example:
load-module dict {
command "dictorg dbdir=/var/dicodb";
}
A simplified form of this statement:
load-module NAME;
is equivalent to:
load-module NAME {
command NAME;
}
A module load path is an internal list of directories which dicod scans in order to find a loadable file name specified in the command statement. By default the search order is as follows:
The value of LTDL_LIBRARY_PATH and LD_LIBRARY_PATH must be a colon-separated list of absolute directory names.
In each of these directories, dicod first attempts to find and load the given filename. If this fails, it tries to append the following suffixes to it:
database {
name WORD;
description STRING;
info TEXT;
languages-from LANGLIST;
languages-to LANGLIST;
handler NAME;
visibility-acl NAME;
mime-headers TEXT;
}
A default search is a MATCH request with * or ! as the database argument. The former means search in all available databases, and the latter means search in all databases until a match is found.
Default searches cabd be quite expensive and can cause considerable strain on the server. For example, the command MATCH * priefix "" returns all entries from all available databases, which would consume a lot of resources both on the server and on the client side.
To minimize harmful effects from such potentially dangerous requests, the following statement makes it possible to limit the use of certain strategies in default searches:
strategy NAME {
deny-all BOOL;
deny-word CONDLIST;
deny-length-lt NUMBER;
deny-length-le NUMBER;
deny-length-gt NUMBER;
deny-length-ge NUMBER;
deny-length-eq NUMBER;
deny-length-ne NUMBER;
}
For example, the following statement denies the use of prefix strategy in default searches if its argument is an empty string:
strategy prefix {
deny-length-eq 0;
}
While tuning your server, it is often necessary to get timing information which shows how much time is spent serving certain requests. This can be achieved using the following configuration directive:
This information is displayed after replies to the following requests: MATCH, DEFINE, and QUIT. The format is:
[d/m/c = ND/NM/NC RTr UTu STs]
where:
You can also add timing information to your access log files. See the %T conversuion in section ACCESS LOG.
Aliases allow a string to be substituted for a word when it is used as the first word of a command. The daemon maintains a list of aliases that are created using the alias configuration file statement:
Aliases may be recursive, i.e. the first word of COMMAND may refer to another alias. To prevent endless loops, recursive expansion is stopped if the first word of the replacement text is identical to an alias expanded earlier.
Aliases are useful to facilitate manual interaction with the server, as they allow the administrator to create abbreviations for some frequently typed commands. For example, the following alias creates new command d which is equivalent to DEFINE *:
alias d DEFINE "*";
dicod(1), RFC 2229.
Complete GNU Dico manual: run info dico or use emacs(1) info mode to read it.
Online copies of GNU Dico documentation in various formats can be found at:
http://www.gnu.org.ua/software/dico/manual
Sergey Poznyakoff
Report bugs to <bug-dico@gnu.org.ua>.
Copyright © 2008-2018 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it. There is NO
WARRANTY, to the extent permitted by law.
| August 20, 2018 | GNU DICO |