Provided by: dicod_2.4-1_amd64 
DESCRIPTION
dicod.conf is the configuration file for dicod(8).
NOTE
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
info dico
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
http://www.gnu.org.ua/software/dico/manual
If any discrepancies occur between this manpage and the GNU Dico Manual, the later shall
be considered the authoritative source.
LEXICAL STRUCTURE
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.
Words
A word is a sequence of letters, digits, and any of the following characters: _, -, ., /,
@, *, :, [, ].
Strings
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;
Comments
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.
#include <FILE>
#include FILE
Include the contents of the file file. Both forms are equivalent. The FILE must
be an absolute file name.
#include_once <FILE>
#include_once FILE
Same as #include, except that, if the FILE has already been included, it will not
be included again.
#line num
#line num "FILE"
This line causes the parser to believe, for purposes of error diagnostics, that the
line number of the next source line is given by num and the current input file is
named by FILE. If the latter is absent, the remembered file name does not change.
# num "FILE"
This is a special form of the #line statement, understood for compatibility with
the C preprocessor.
STATEMENTS
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:
number A number is a sequence of decimal digits.
boolean
A boolean value is one of the following: yes, true, t or 1, meaning true, and no,
false, nil, 0 meaning false.
word
quoted string
list A comma-separated list of values, enclosed in parentheses.
Block Statement
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.
SERVER SETTINGS
user NAME
Run with the privileges of this user. The argument is either a user name, or UID
prefixed with a plus sign.
group LIST
If the user statement is present, dicod will drop all supplementary groups and
switch to the principal group of that user. Sometimes, however, it may be
necessary to retain one or more supplementary groups. For example, this might be
necessary to access dictionary databases. The group statement retains the
supplementary groups listed in LIST. Each group can be specified either by its
name or by its GID number, prefixed with @samp{+}, e.g.:
user nobody;
group (man, dict +88);
This statement is ignored if no user statement is present or if dicod is running in inetd
mode.
mode daemon|inetd
Sets server operation mode.
listen LIST
Specify the IP addresses and ports to listen on in daemon mode. By default, dicod
will listen on port 2628 on all existing interfaces.
Elements of LIST can have the following forms:
HOST:PORT
Specifies an IP (version 4 or 6) socket to listen on. The HOST part is
either an IPv4 in ``dotted-quad'' notation, or an IPv6 address in square
brackets, or a host name. In the latter case, dicod will listen on all IP
addresses corresponding to its A and AAAA DNS records.
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.
inet://HOST:PORT, inet4://HOST:PORT
Listen on IPv4 socket. HOST is either an IP address or a host name. In the
latter case, dicod will start listening on all IP addresses from the A
records for this host.
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.
inet6://HOST:PORT
Listen on IPv6 socket. HOST is either an IPv6 address in square brackets,
or a host name. In the latter case, dicod will start listening on all IP
addresses from the AAAA records for this host.
Either HOST or PORT (but not both) can be omitted. Missing HOSTfdefaults to
IPv6 addresses on all available network interfaces, and missing PORT
defaults to 2628.
FILENAME, unix://FILENAME
Specifies the name of a UNIX socket to listen on. FILENAME must be an
absolute file name of the socket.
pidfile STRING
Store PID of the master process in this file. Default is /var/run/dicod.pid.
max-children NUMBER
Sets maximum number of subprocesses that can run simultaneously. This is
equivalent to the number of clients that can simultaneously use the server. The
default is 64.
inactivity-timeout NUMBER
Sets inactivity timeout to the NUMBER of seconds. The server disconnects
automatically if the remote client has not sent any command within this number of
seconds. Setting timeout to 0 disables inactivity timeout (the default).
This statement along with max-children allows you to control the server load.
shutdown-timeout NUMBER
When the master server is shutting down, wait this number of seconds for all
children to terminate. Default is 5 seconds.
identity-check BOOLEAN
Enable identification check using AUTH protocol (RFC 1413). The received user name
or UID can be shown in access log using the %l conversion (see below).
ident-keyfile STRING
Use encryption keys from the named file to decrypt AUTH replies encrypted using
DES.
ident-timeout NUMBER
Set timeout for AUTH input/output operation to NUMBER of seconds. Default timeout
is 3 seconds.
AUTHENTICATION SETTINGS
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:
TYPE Database type. Two types are supported: text and ldap.
USER User name, if necessary to access the database.
PASSWORD
User password, if necessary to access the database.
HOST Domain name or IP address of a machine running the database.
PATH A path to the database. The exact meaning of this element depends on the database
protocol. See the texinfo documentation.
PARAMS A list of protocol-dependent parameters. Each parameter is of the form
KEYWORD=NAME, multiple parameters are separated with semicolons.
The following statements can appear within the user-db block:
options STRING
Pass additional options to the underlying mechanism. The argument is treated as an
opaque string and passed to the authentication open procedure verbatim. Its exact
meaning depends on the type of the database.
password-resource ARG
A database resource which returns the user's password.
group-resource ARG
A database resource which returns the list of groups this user is member of.
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.
SASL AUTHENTICATION
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;
}
disable-mechanism MECH
Disable SASL mechanisms listed in MECH, which is a list of names.
enable-mechanism MECH
Enable SASL mechanisms listed in MECH, which is a list of names.
service NAME
Sets the service name for GSSAPI and Kerberos mechanisms.
realm NAME
Sets the realm name.
anon-group LIST
Declares the list of user groups considered anonymous.
ACCESS CONTROL LISTS
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:
all All users (the default).
authenticated
Only authenticated users.
group GROUPLIST
Authenticated users which are members of at least one of the groups listed in
GROUPLIST.
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:
any Matches any client address.
IP address
Matches if the request comes from the given IP (both IPv4 and IPv6 are allowed).
ADDR/NETLEN
Matches if first NETLEN bits from the client IP address equal to ADDR. The network
mask length, NETLEN must be an integer number between 0 and 32 for IPv4, and
between 0 and 128 for IPv6. The address part, ADDR, is as described above.
ADDR/NETMASK
The specifier matches if the result of logical AND between the client IP address
and NETMASK equals to ADDR. The network mask must be specified in a IP address
(either IPv4 or IPv6) notation.
SECURITY SETTINGS
connection-acl NAME
Use ACL NAME to control incoming connections. The ACL itself must be defined
before this statement. Using the group clause in this ACL makes no sense, because
the authentication itself is performed only after the connection have been
established.
show-sys-info NAME
Controls whether to show system information in reply to SHOW SERVER command. The
information will be shown only if ACL NAME allows it.
visibility-acl NAME
Sets name of the ACL that controls visibility of all databases.
LOGGING AND DEBUGGING
log-tag STRING
Prefix syslog messages with this string. By default, the program name is used.
log-facility STRING
Sets the syslog facility to use. Allowed values are: user, daemon, auth, authpriv,
mail, cron, local0 through local7 (case-insensitive), or a decimal facility number.
log-print-severity BOOLEAN
Prefix diagnostics messages with a string identifying their severity.
transcript BOOLEAN
Controls the transcript of user sessions.
ACCESS LOG
GNU Dico provides a feature similar to Apache's CustomLog, which keeps a log of MATCH and
DEFINE requests.
access-log-file STRING
Sets access log file name.
access-log-format STRING
Defines the format string. Its argument can contain literal characters, which are
copied into the log file verbatim, and format specifiers, i.e. special sequences
beginning with %, which are replaced in the log file as shown in the table below:
%% The percent sign.
%a Remote IP address.
%A Local IP address.
%B Size of response in bytes.
%b Size of response in bytes in CLF format, i.e. a dash rather than a 0 when no
bytes are sent.
%C Remote client (from the CLIENT command).
%D The time taken to serve the request, in microseconds.
%d Request command verb in abbreviated form, suitable for use in URLs, i.e. d
for DEFINE, and m for MATCH.
%h Remote host.
%H Request command verb (DEFINE or MATCH).
%l Remote logname (from identd(1), if supplied). This will return a dash
unless identity-check statement is set to true.
%m The search strategy.
%p The canonical port of the server serving the request.
%P The PID of the child that served the request.
%q The database from the request.
%r Full request.
%{N}R The Nth token from the request (N is 0-based).
%s Reply status. For multiple replies, the form %s returns the status of the
first reply, while %>s returns that of the last reply.
%t Time the request was received in the standard Apache format, e.g.:
[04/Jun/2008:11:05:22 +0300]
%{FORMAT}t
The time, in the form given by FORMAT, which should be a valid strftime(3)
format string. The standard %t format is equivalent to
[%d/%b/%Y:%H:%M:%S %z]
%T The time taken to serve the request, in seconds.
%u Remote user from AUTH command.
%v The host name of the server serving the request.
%V Actual host name of the server (in case it was overridden in configuration).
%W The word from the request.
The absence of access-log-format statement is equivalent to the following:
access-log-format "%h %l %u %t \"%r\" %>s %b";
GENERAL SETTINGS
initial-banner-text TEXT
Display TEXT in the textual part of the initial server reply.
hostname STRING
Sets the hostname. By default it is determined automatically.
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).
server-info TEXT
Sets the server description to be shown in reply to the SHOW SERVER command.
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;
help-text TEXT
Sets the text to be displayed in reply to the HELP command.
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.
default-strategy NAME
Sets the name of the default matching strategy (*note MATCH::). By default,
Levenshtein matching is used, which is equivalent to default-strategy lev;
CAPABILITIES
capability LIST
Requests additional capabilities from the LIST.
Capabilities are certain server features that can be enabled or disabled at the system
administrator's will. The following capabilities are defined:
auth The AUTH command is supported. See the section AUTHENTICATION, for its
configuration.
mime The OPTION MIME command is supported. Notice that RFC 2229 requires all servers to
support that command, so you should always specify this capability.
xversion
The XVERSION command is supported. It is a GNU extension that displays the dicod
implementation and version number.
xlev The XLEV command is supported. This command allows the remote party to set and
query maximal Levenshtein distance for the lev matching strategy.
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).
DATABASE MODULES
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:
1. Optional prefix search directories specified in the prepend-load-path statement
(see below);
2. GNU Dico module directory /usr/lib/x86_64-linux-gnu/dico;
3. Additional search directories specified in the module-load-path statement (see
below);
4. The value of the environment variable LTDL_LIBRARY_PATH;
5. The system dependent library search path (e.g. on GNU/Linux it is defined by the
file /etc/ld.so.conf and the environment variable LD_LIBRARY_PATH).
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:
1. the libtool archive suffix .la;
2. the suffix used for native dynamic libraries on the host platform, e.g., .so, .sl,
etc.
module-load-path LIST
Add directories from LIST to the end of the module load path.
prepend-load-path LIST
Add directories from LIST to the beginning of the module load path.
DATABASES
database {
name WORD;
description STRING;
info TEXT;
languages-from LANGLIST;
languages-to LANGLIST;
handler NAME;
visibility-acl NAME;
mime-headers TEXT;
}
name STRING
Sets the name of this database (a single word). This name will be used to identify
this database in DICT commands.
handler STRING
Specifies the handler name for this database and optional arguments for it. This
handler must be previously defined using the load-module statement (see above).
description STRING
Supplies a short description, to be shown in reply to the SHOW DB command. The
STRING may not contain newlines.
info STRING
Defines a full description of the database. This description is shown in reply to
the SHOW INFO command. It is usually a multi-line text, so it is common to use
here-document syntax.
content-type STRING
Sets the content type of the reply (for use in MIME headers).
content-transfer-encoding VALUE
Sets transfer encoding to use when sending MIME replies for this database. VALUE
is one of: base64, quoted-printable.
visibility-acl NAME
Sets name of the ACL that controls that database visibility.
STRATEGIES AND SEARCHES
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;
}
deny-all BOOL
Unconditionally deny the use of this strategy in default searches.
deny-word LIST
Deny this strategy if the search word matches one of the words from LIST.
deny-length-lt NUMBER
Deny if length of the search word is less than NUMBER.
deny-length-le NUMBER
Deny if length of the search word is less than or equal to NUMBER.
deny-length-gt NUMBER
Deny if length of the search word is greater than NUMBER.
deny-length-ge NUMBER
Deny if length of the search word is greater than or equal to NUMBER.
deny-length-eq NUMBER
Deny if length of the search word is equal to NUMBER.
deny-length-ne NUMBER
Deny if length of the search word is not equal to 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;
}
TUNING
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:
timing BOOLEAN
Provide timing information after successful completion of an operation.
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:
ND Number of processed define requests.
NM Number of processed match requests.
NC Number of comparisons made. This value may be inaccurate if the underlying
database module does not provide such information.
RT Real time spent serving the request.
UT Time in user space spent serving the request.
ST Time in kernel space spent serving the request.
You can also add timing information to your access log files. See the %T conversuion in
section ACCESS LOG.
COMMAND ALIASES
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:
alias WORD COMMAND
Creates a new alias.
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 "*";
SEE ALSO
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
AUTHORS
Sergey Poznyakoff
BUG REPORTS
Report bugs to <bug-dico@gnu.org.ua>.
COPYRIGHT
Copyright © 2008-2014 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.