.\" dictd.8 -- 
.\" Created: Mon Mar 10 16:10:03 1997 by faith@dict.org
.\" Copyright 1997, 1998, 2002 Rickard E. Faith (faith@dict.org)
.\" Copyright 2002-2008 Aleksey Cheusov (vle@gmx.net)
.\" 
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\" 
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" 
.TH DICTD 8 "29 March 2002" "" ""
.SH "NAME"
dictd - a dictionary database server
.SH "SYNOPSIS"
.nf
.BI dictd " [options]"
.fi
.SH "DESCRIPTION"
.B dictd
is a server for the Dictionary Server Protocol (DICT), a TCP transaction
based query/response protocol that allows a client to access dictionary
definitions from a set of natural language dictionary databases.
.P
For security reasons, dictd drops root permissions after startup.  If
user
.B dictd
exists on the system, the daemon will run as that user, group
.BR dictd ", otherwise it will run as user 
.BR nobody ", group" 
.BR nobody " or " nogroup
(depending on the operating system distribution).
.P
Since startup time is significant, the server is designed to run
continuously, and should
.I not
be run from
.BR inetd (8).
(However, with a fast processor, it is feasible to do so.)
.P
Databases are distributed separately from the server.
.P
By default, 
.B dictd
assumes that the index files are sorted alphabetically, and only
alphanumeric characters from the 7-bit ASCII character set are used
for search.  This default may be overridden by a header in the data
file.  The only such features implemented at this time are the headers
"00-database-allchars" which tells
.B dictd 
that non-alphanumeric characters may also be used for search, the
header "00-database-utf8" which indicates that the database uses utf8
encoding, and the "00-database-8bit-new" which indicates that the database
is encoded and sorted according to a locale that uses an 8-bit
encoding.
.SH "BACKGROUND"
For many years, the Internet community has relied on the "webster" protocol
for access to natural language definitions.  The webster protocol supports
access to a single dictionary and (optionally) to a single thesaurus.  In
recent years, the number of publicly available webster servers on the
Internet has dramatically decreased.
.P
Fortunately, several freely-distributable dictionaries and lexicons have
recently become available on the Internet.  However, these
freely-distributable databases are not accessible via a uniform interface,
and are not accessible from a single site.  They are often small and
incomplete individually, but would collectively provide an interesting and
useful database of English words.  Examples include the Jargon file, the
WordNet database, MICRA's version of the 1913 Webster's Revised Unabridged
Dictionary, and the Free Online Dictionary of Computing.  (See the DICT
protocol specification (RFC) for references.)  Translating and non-English
dictionaries are also becoming available (for example, the FOLDOC
dictionary is being translated into Spanish).
.P
The webster protocol is not suitable for providing access to a large
number of separate dictionary databases, and extensions to the current
webster protocol were not felt to be a clean solution to the
dictionary database problem.
.P
The DICT protocol is designed to provide access to multiple databases.
Word definitions can be requested, the word index can be searched
(using an easily extended set of algorithms), information about the
server can be provided (e.g., which index search strategies are
supported, or which databases are available), and information about a
database can be provided (e.g., copyright, citation, or distribution
information).  Further, the DICT protocol has hooks that can be used
to restrict access to some or all of the databases.
.P
.BR dictd (8)
is a server that implements the DICT protocol.  Bret Martin implemented
another server, and several people (including Bret and myself) have
implemented clients in a variety of languages.
.SH "OPTIONS"
.TP
.BR \-V " or " \-\-version
Display version information.
.TP
.B \-\-license
Display copyright and license information.
.TP
.BR \-h " or " \-\-help
Display help information.
.TP
.BR \-v " or " \-\-verbose " or " " \-dverbose"
Be verbose.
.TP
.BI \-c " file\fR or "  \-\-config " file"
Specify configuration file.  The default is
.I @SYSCONFDIR@/dictd.conf
, but may be changed in the
.I defs.h
file at compile time (DICTD_CONFIG_FILE).
.TP
.BI \-p " port\fR or " \-\-port " port"
Overrides the keyword
.B port
in
.I Global Settings Specification
section of configuration file.
.TP
.BR \-i " or " \-\-inetd
Communicate on standard input/output, suitable for use from inetd.
Although, due to its rather large startup time, this daemon was not
intended to run from inetd, with a fast processor it is feasible to do
so. This option also implies \-\-fast-start.
.TP
.BI \-\-pp " prog"
Sets a preprocessor for configuration file.
like
.I " m4"
or
.I " cpp".
See examples/dictd_complex.conf file
from distribution. By default configuration file is parsed without
preprocessor.
.TP
.BI \-\-depth " length"
Overrides the keyword
.B depth
in
.I Global Settings Specification
section of configuration file.
.TP
.BI \-\-delay " seconds"
Overrides the keyword
.B delay
in
.I Global Settings Specification
section of configuration file.
.TP
.BI \-\-facility " facility"
The same as
.B syslog_facility
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BR \-f " or " \-\-force
Force the daemon to start even if an instance of the daemon is already
running.  (This is of little value unless a non-default port is
specified with
.BR \-p ,
since, if one instance is bound to a port, the second one fails when it
can not bind to the port.)
.TP
.BI \-\-limit " children"
Overrides the keyword
.B limit
in
.I Global Settings Specification
section of configuration file.
.TP
.BI \-\-listen\-to " host"
Overrides the keyword
.B listen\_to
in
.I Global Settings Specification
section of configuration file.
.TP
.BI \-\-address\-family " family"
Overrides the keyword
.B address\_family
in
.I Global Settings Specification
section of configuration file.
.TP
.BI \-\-locale " locale"
Overrides the keyword
.B locale
in
.I Global Settings Specification
section of configuration file.
.TP
.B \-s
The same as
.B syslog
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BI \-L " file\fR or " \-\-logfile " file"
The same as
.B log_file
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BI \-\-pid\-file " file"
The same as
.B pid_file
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BI \-m  " minutes \fR or "\-\-mark " minutes"
Overrides the keyword
.B timestamp
in
.I Global Settings Specification
section of configuration file.
.TP
.BI \-\-default\-strategy " strategy"
Overrides the keyword
.B default_strategy
in
.I Global Settings Specification
section of configuration file.
.TP
.BI \-\-without-strategy " strat1,strat2,..."
The same as
.B without_strategy
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BI \-\-add-strategy " strategy_name:description"
The same as
.B add_strategy
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BI \-\-fast-start
The same as
.B fast_start
keyword in
.I Global Settings Specification
of configuration files.
.TP
.B \-\-without-mmap
The same as
.B without_mmap
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BR \-\-stdin2stdout
When applied with \-\-inetd, each command obtained from stdin is output
to stdout. This option is useful for debugging.
.TP
.BI \-l " option\fR or " \-\-log " option"
The same as
.B log_option
keyword in
.I Global Settings Specification
of configuration files.
.TP
.BI \-d " option"
The same as
.B debug_option
keyword in
.I Global Settings Specification
of configuration files.
.RE
.SH "CONFIGURATION FILE"
.TP
.B Introduction
The configuration file defaults to
.I @SYSCONFDIR@/dictd.conf 
but can be specified on the command line with the
.B \-c
option (see above).
.RS
.P
The configuration file is read into memory at startup, and is not
referenced again by
.B dictd
unless a signal 1 
.B (SIGHUP)
is received, which will cause 
.B dictd 
to reread the configuration file.
.P
The file is divided into sections.  The Access Section should come
first, followed by the Database Section, and the
User Section.  The Database Section is required; the others are
optional, but they must be in the order listed here.
.RE
.TP
.B Syntax
The following keywords are valid in a configuration file: access,
allow, deny, group, database, data, index, filter, prefilter,
postfilter, name, include, user, authonly, site.  Keywords are case
sensitive.  String arguments that contain spaces should be surrounded
by double quotes.  Without quoting, strings may contain alphanumeric
characters and _, -, ., and *, but not spaces.  Strings can be
continued between lines.  \\", \\\\, \\n, \\<NL> are treated as double
quote, backslash, new line and no symbol respectively.  Comments start
with # and extend to the end of the line.
.TP
.B Global Settings Section
.RS
.TP
.BI "global {" " global settings specification " "}"
Used to set global
.B dictd
setting such as log file, syslog facility, locale and so on.
.TP
.B EXAMPLE:
See
.I examples/dictd4.conf
file from the distribution.
.RE
.TP
.B Access Section
.RS
.TP
.BI "access {" " access specification " "}"
This section contains access
restrictions for the server and all of the databases collectively.
Per-database control is specified in the Database Section.
.TP
.B EXAMPLE:
See
.I examples/dictd3.conf
file from the distribution.
.RE
.TP
.B Database Section
.RS
.TP
.BI database " string " "{ " "database specification " "}"
The string specifies the name of the database
(e.g., wn or web1913).  (This is an arbitrary name selected by the
administrator, and is not necessarily related to the file name or any
name listed in the data file.  A short, easy to type name is often
selected for easy use with 
.BR "dict -d".)
.P
.RS
.B EXAMPLE:
See
.I examples/dictd*.conf
files from the distribution.
.RE
.RS
.P
.B NOTE:
If the files specified in the database specification do not exist on the
system, dictd may silently fail.
.RE
.TP
.BI database_virtual " string " "{ " "virtual database specification " "}"
This section specifies the virtual database.
The
.I string
specifies the name of the database (e.g., en-ru or fren).
.P
.RS
.B EXAMPLE:
See
.I examples/dictd_virtual.conf
or
.I examples/dictd_complex.conf
files from the distribution.
.RE
.TP
.BI database_plugin " string " "{ " "plugin specification " "}"
This section specifies the plugin.
The
.I string
specifies the name of the database.
.P
.RS
.B EXAMPLE:
See
.I examples/dictd_plugin_dbi.conf
or
.I examples/dictd_complex.conf
files from the distribution.
.RE
.TP
.BI database_mime " string " "{ " "mime specification " "}"
Traditionally, databases created for
.I dictd
contained plain text only because
.B dictd
releases before 1.10.0 didn't have full support of
.I OPTION MIME
option (consult with RFC-2229).
This section describes the special database which behaves
differently depending on whether
.I OPTION MIME
command was received from client or was not,
i.e. the database created by this section
allows one to return to the client either a plain text or
specially formatted content depending on whether DICT client supports
(or wants to receive) MIMEized content or doesn't.
The
.I string
specifies the name of the database.
.RS
.P
.B NOTE:
All this is about
.I DEFINE
command only.
.I MATCH, SHOW DB, SHOW STRAT, SHOW INFO, SHOW SERVER and HELP
commands return texts prepended with empty line only.
.RE
.P
.RS
.B EXAMPLE:
See
.I examples/dictd_mime.conf
file from the distribution.
.RE
.TP
.BI database_exit
Excludes following databases from the '*' database.
By default '*' means all databases available.
Look at 'examples/dictd_virtual.conf' file for example configuration.
.RS
.P
.B NOTE:
If you use 'virtual' dictionaries, you should use this directive,
otherwise you will search the same dictionary twice.
.RE
.TP
.B User Section
.RS
.TP
.BI user " string" " string"
The first string specifies the username, and the second string specifies
the shared secret for this username.  When the AUTH command is used, the
client will provide the username and a hashed version of the shared
secret.  If the shared secret matches, the user is said to have
authenticated, and will have access to databases whose access
specifications allow that user (by name, or by wildcard).  If present, this
section must appear last in the configuration file.  There may be many user
entries.  The shared secret should be kept secret, as anyone who has access
to it can access the shared databases (assuming access is not denied by
domain name).
.RE
.TP
.B Access Specification
.RS
Access specifications may occur in the Access Section or in the Database
Section.  The access specification will be described here.
.P
For allow, deny, and authonly, a star (*) may be used as a wild card that
matches any number of characters.  A question mark (?) may be used as a
wildcard that matches a single character.  For example, 10.0.0.* and *.edu
are valid strings.
.P
Further, a range of IP addresses and an IP address followed by a netmask
may be specified.  For example, 10.0.0.0:10.0.0.255, 10.0.0.0/24, and
10.0.0.* all specify the same range of IP numbers.  Notation cannot be
combined on the same line.  If the notation does not make sense, access
will be denied by default.  Use the
.I "--debug auth"
option to debug related problems.
.P
Note that these specifications take only one string per specification
line.  However, you can have multiple lines of each type.
.P
The syntax is as follows:
.TP
.BI allow " string"
The string specifies a domain name or IP address which is allowed access
to the server (in the Access Section) or to a database (in the Database
Section).  Note that more than one string is not permitted for a single
"allow" line, but more than one "allow" lines are permitted in the
configuration file.
.TP
.BI deny " string"
The string specifies a domain name or IP address which is denied access to
the server (in the Access Section) or to a database (in the Database
Section).  Note that if reverse DNS is not working, then only the IP number
will be checked.  Therefore, it is essential to deny networks based on IP
number, since a denial based on domain name may not always be checked.
.TP
.BI authonly " string"
This form is only useful in the Access Section.  The string specifies a
domain name or IP address which is allowed access to the server but not to
any of the databases.  All commands are valid except DEFINE, MATCH, and
SHOW DB.  More specifically AUTH is a valid command, and commands which
access the databases are not allowed.
.TP
.BI user " string"
This form is only useful in the Database Section.  The string specifies a
username that is allowed to access this database after a successful AUTH
command is executed.
.RE
.RE
.TP
.B Global Settings Specification
.RS
This section describes the following parameters:
.TP
.BI port " string\_or\_number"
Specifies the port or service name (e.g., 2628).
The default is 2628, as specified in the DICT Protocol RFC, but may be
changed in the
.I defs.h
file at compile time (DICT_DEFAULT_SERVICE).
.TP
.BI site " string"
Used to specify the filename for the site information file, a flat text
file which will be displayed in response to the SHOW SERVER command.
.RS
.P
.B EXAMPLE:
See
.I examples/dictd4.conf
file from the distribution.
.RE
.TP
.BI site_no_banner " boolean"
By default SHOW SERVER command outputs information about
.I dictd
version and an operating system type.
This option disables this.
.TP
.BI site_no_uptime " boolean"
By default SHOW SERVER command outputs information about
uptime of
.I dictd
, a number of forks since startup and forks per hour.
This option disables this.
.TP
.BI site_no_dblist " boolean"
By default SHOW SERVER command outputs internal information about
databases, such as a number of headwords, index size and so on.
This option disables this.
.TP
.BI delay " number"
Specifies the number of seconds a client may be idle before the server will
close the connection.  Idle time is defined to be the time the server is
waiting for input and does not include the time the server spends searching
the database. The default is 0 seconds (no limit),
but may be changed in the
.I defs.h
file at compile time (DICT_DEFAULT_DELAY).
.P
.RS
.B NOTE:
Setting
.I delay
option disables
.I limit_time
option. Only one of them (last specified in
.B dictd.conf
) is in effect.
.P
.B NOTE:
Connections are closed without warning since no provision
for premature connection termination is specified in the DICT protocol
RFC.
.RE
.TP
.BI depth " number"
Specify the queue length for
.BR listen (2).
Specifies the number of pending socket connections which are queued by the
operating system.  Some operating systems may silently limit this value to
5 (older BSD systems) or 128 (Linux).  The default is 10 but may be changed
in the
.I defs.h
file at compile time (DICT_QUEUE_DEPTH).
.TP
.BI limit_childs " number"
Specifies the number of daemons that may be running simultaneously.  Each
daemon services a single connection.  If the limit is exceeded, a
(serialized) connection will be made by the server process, and a response
code 420 (server temporarily unavailable) will be sent to the client.  This
parameter should be adjusted to prevent the server machine from being
overloaded by dict clients, but should not be set so low that many clients
are denied useful connections. The default is 100, but may be changed in
the
.I defs.h
file at compile time (DICT_DAEMON_LIMIT_CHILDS).
.TP
.BI limit " number"
Synonym for
.B limit_childs.
For backward compatibility only.
.TP
.BI limit_matches " number"
Specifies the maximum number of matches that can be returned
by MATCH query. Zero means no limit. The default is 2000.
.TP
.BI limit_definitions " number"
Specifies the maximum number of definitions that can be returned
by DEFINE query. Zero means no limit. The default is 200.
.TP
.BI limit_time " number"
Specifies the number of seconds a client may talk to the server
before the server will close the connection.
The default is 600 seconds (10 minutes), but may be changed in the
.I defs.h
file at compile time (DICT_DEFAULT_LIMIT_TIME).
.RS
.P
.B NOTE:
Setting
.I limit_time
option disables
.I delay
option. Only one of them (last specified in
.B dictd.conf
) is in effect.
.P
.B NOTE:
Connections are closed without warning since no provision
for premature connection termination is specified in the DICT protocol
RFC.
.RE
.TP
.BI limit_queries " number"
Specifies the number of queries (MATCH, DEFINE, SHOW DB etc.)
that client may send to the server
before the server will close the connection.
Zero means no limit.
The default is 2000, but may be changed in the
.I defs.h
file at compile time (DICT_DEFAULT_LIMIT_QUERIES).
.TP
.BI timestamp " number"
How often a timestamp should be logged (int minutes).
(This is effective only if
logging has been enabled with the \-s or \-L option, or with a debugging
option.)
.TP
.BI log_option " option"
Specify a logging option.  This is effective only if logging has been
enabled with the
.BR \-s " or " \-L
option or in configuration file, or logging
to the console has been activated with a debugging
option (e.g.,
.BR "\-\-debug nodetach" .
Only one option may be set with each invocation of this option; however,
multiple invocations of this option may be made in configuration file
or dictd command
line.  For instance:
.br
dictd \-s \-\-log stats \-\-log found \-\-log notfound
.br
is a valid command line, and sets three logging options.
.RS
.P
Some of the more verbose logging options are used primarily for
debugging the server code, and are not practical for normal use.
.TP
.B server
Log server diagnostics.  This is extremely verbose.
.TP
.B connect
Log all connections.
.TP
.B stats
Log all children terminations.
.TP
.B command
Log all commands.  This is extremely verbose.
.TP
.B client
Log results of CLIENT command.
.TP
.B found
Log all words found in the databases.
.TP
.B notfound
Log all words not found in the databases.
.TP
.B timestamp
When logging to a file, use a full timestamp like that which syslog would
produce.  Otherwise, no timestamp is made, making the files shorter.
.TP
.B host
Log name of foreign host.
.TP
.B auth
Log authentication failures.
.TP
.B min
Set a minimal number of options.  If logging is activated (to a file, or
via syslog), and no options are set, then the minimal set of options will
be used.  If options are set, then only those options specified will be
used.
.TP
.B all
Set all of the options.
.TP
.B none
Clear all of the options.
.P
To facilitate location of interesting information in the log file, entries
are marked with initial letters indicating the class of the line being
logged:
.TP
.B I
Information about the server, connections, or termination statistics.
These lines are generally not designed to be parsed automatically.
.TP
.B E
Error messages.
.TP
.B C
CLIENT command information.
.TP
.B D
Definitions found in the databases searched.
.TP
.B M
Matches found in the database searched.
.TP
.B N
Matches which were not found in the databases searched.
.TP
.B T
Trace of exact line sent by client.
.TP
.B A
Authentication information.
.P
To preserve anonymity of the client, do
.I not
use the
.B connect
or
.B host
options.  Clients may or may not send host information using the CLIENT
command, but this should be an option that is selectable on the client
side.
.RE
.TP
.BI debug_option " string"
Activate a debugging option.  There are several, all of which are only
useful to developers.  They are documented here for completeness.  A list
can be obtained interactively by using
.B \-d
with an illegal option.
.RS
.TP
.B verbose
The same as
.BR \-v " or " \-\-verbose .
Adds verbosity to other options.
.TP
.B scan
Debug the scanner for the configuration file.
.TP
.B parse
Debug the parser for the configuration file.
.TP
.B search
Debug the character folding and binary search routines.
.TP
.B init
Report database initialization.
.TP
.B port
Log client-side port number to the log file.
.TP
.B lev
Debug Levenshtein search algorithm.
.TP
.B auth
Debug the authorization routines.
.TP
.B nodetach
Do not detach as a background process.  Implies that a copy of the log
file will appear on the standard output.
.TP
.B nofork
Do not fork daemons to service requests.  Be a single-threaded server.
This option implies
.BR nodetach ,
and is most useful for using a debugger to find the point at which daemon
processes are dumping core.
.TP
.B alt
Debugs
.B altcompare
in
.IR index.c .
.RE
.TP
.BI locale " string"
Specifies the locale used for searching.  If no locale is specified, the
"C" locale is used.  The locale used for the server should be the same
as that used for dictfmt when the database was built (specifically, the
locale under which the index was sorted). The locale should be specified
for both 8-bit and UTF-8 formats. If locale contains utf8 or utf-8
substring, UTF-8 format is expected.
Note that if your database is not in ASCII7 or UTF-8 format,
then the dictd server will not be compliant to RFC 2229.
.RS
.P
.BI NOTE 
If utf-8 or 8-bit dictionaries are included in the configuration file,
and the appropriate \-\-locale has not been specified,
.B dictd
will fail to start.  This implies that
.B dictd 
will not run with both utf-8 and 8-bit dictionaries in the
configuration file.
.RE
.TP
.BI add_strategy " strategy_name" "" " description"
Adds strategy
.I strategy_name
with the description
.I description.
This new search strategy may be implemented with a help of plugins.
Both
.I strategy_name
and
.I description
are
.I strings.
.TP
.BI default_strategy " string"
Set the server's default search strategy for MATCH search type.
The compiled-in default is 'lev'.
It is also possible to set default strategy per database.
See
.I default_strategy
keyword in
.I Database specification
section.
.TP
.BI disable_strategy " string"
Disable specified strategies.
By default all implemented search strategies are enabled.
It is also possible to disable strategies per database.
See
.I disable_strategy
keyword in
.I Database specification
section.
.TP
.BI listen_to " host"
Local host name or IP address for bind.  If unspecified or
.IR * ,
dictd will bind to all interfaces.  Otherwise, dictd
will bind to this address only.
.TP
.BI address_family " family"
If
.IR 4 ,
address family is IPv4 (the default), if
.IR 6 ,
address family is IPv6.
.TP
.BI syslog " string"
Log using the
.BR syslog (3)
facility.
.TP
.BI syslog_facility " string"
Specifies the syslog facility to use.  The use of this option implies the
.B \-s
option to turn on logging via syslog.  When the operating system
libraries support SYSLOG_NAMES, the names used for this option should be
those listed in
.BR syslog.conf (5).
Otherwise, the following names are used (assuming the particular
facility is defined in the header files): auth, authpriv, cron, daemon,
ftp, kern, lpr, mail, news, syslog, user, uucp, local0, local1, local2,
local3, local4, local5, local6, and local7.
.TP
.BI log_file " string"
Specify the file for logging.  The filename specified is recomputed on
each use using the
.BR strftime (3)
call.  For example, a filename ending in ".%Y%m%d" will write to log
files ending in the year, month, and date that the log entry was
written.
.RS
.B NOTE:
If
.B dictd
does not have write permission for this file, it will silently fail.
.RE
.TP
.BI pid_file " string"
The specified filename will be created to contain
the process id of the main
.B dictd
process. The default is
.I /var/run/dictd.pid
.TP
.BI fast\_start
By default, dictd creates (in memory) additional index
to make the search faster.
This option disables this behaviour and makes startup faster.
.TP
.BI without\_mmap
do not use the mmap(2) function and read entire files into memory instead.
Use this option, if you know exactly what you are doing.
.RE
.TP
.B Database Specification
.RS
The database specification describes the database:
.TP
.BI data " string"
Specifies the filename for the flat text database.
If the filename does not begin with '.' or '/', it is prepended with
$datadir/. It is a compile time option. You can change this behaviour
by editing Makefile or running ./configure \-\-datadir=...
.TP
.BI index " string"
Specifies the filename for the index file.
Path matter is similar to that described above in "data" option .
.TP
.BI index_suffix " string"
This is optional index file to make 'suffix'
search strategy faster (binary search).
It is generated by 'dictfmt_index2suffix'. Run "dictfmt_index2suffix \-\-help"
for more information.
Path matter is similar to that described above in "data" option .
.TP
.BI index_word " string"
This is optional index file to make 'word'
search strategy faster (binary search).
It is generated by 'dictfmt_index2word'. Run "dictfmt_index2word \-\-help"
for more information.
Path matter is similar to that described above in "data" option .
.TP
.BI prefilter " string"
Specifies the  prefilter command.  When  a chunk of the compressed database
is  read, it will be filtered  with  this filter before being decompressed.
This may be  used to provide  some additional compression  that knows about
the data and can provide better compression than the LZ77 algorithm used by
zlib.
.TP
.BI postfilter " string"
Specifies the postfilter command.  When a chunk of the compressed database
is read, it will be filtered with this filter before the offset and length
for the entry are used to access data.  This is provided for symmetry with
the prefilter command, and may also be useful for providing additional
database compression.
.TP
.BI filter " string"
Specifies the filter command.  After the entry is extracted from the
database, it will be filtered with this filter.  This may be used to
provide formatting for the entry (e.g., for html).
.TP
.BI name " string"
Specifies the short name of the database (e.g., "1913 Webster's").  If the
string begins with @, then it specifies the headword to look up in the
dictionary to find the short name of the database.  The default is
"@00-database-short", but this may be changed in the
.I defs.h
file at compile time (DICT_SHORT_ENTRY_NAME).
.TP
.BI info " string"
Specifies the information about database.  If the
string begins with @, then it specifies the headword to look up in the
dictionary to find information.  The default is
"@00-database-info", but this may be changed in the
.I defs.h
file at compile time (DICT_INFO_ENTRY_NAME).
.TP
.BI invisible
Makes dictionary invisible to the clients i.e. this dictionary
will not be recognized or shown by DEFINE, MATCH, SHOW INFO, SHOW SERVER and
SHOW DB commands. If some definitions or matches are found in invisible
dictionary,
the name of the upper visible virtual dictionary is returned.
Dictionaries '*' and '!' don't include invisible ones.
.B NOTE:
Invisible dictionaries are completely
inaccessible (and invisible) to the client
unless they are included
to the virtual or MIME dictionary
(See
.I database_virtual
or
.I database_mime
database sections).
.TP
.BI disable_strategy " string"
Disables the specified strategy for database.
This may be useful for slow dictionaries (plugins)
or for dictionaries included to virtual ones.
For an example see file examples/dictd_complex.conf.
.TP
.BI default_strategy " string"
Specifies the strategy which will be used
if the database is accessed using the strategy '.'.
I.e. this directive is the way to set the preferred search strategy
per database. For example, instead of strategy
.I lev
, the strategy
.I word
may be preferred for databases mainly containing
the multiword phrases but the single words.
.RE
.TP
.B Virtual Database Specification
.RS
The virtual database specification describes the virtual database:
.TP
.BI database_list " string"
Specifies a list of databases which are included into the virtual database.
Database names are in the string and are separated by comma.
.TP
.BI name " string"
Specifies the short name of the database. See
.I database specification
.TP
.BI info " string"
Specifies the information about database. See
.I database specification
.TP
.BI invisible
Makes dictionary invisible to the clients. See
.I database specification
.TP
.BI disable_strategy " string"
Disables the specified strategy for database.
See
.I database specification
.RE
.TP
.B Plugin Specification
.RS
.TP
.BI plugin " string"
Specifies a filename of the plugin.
.TP
.BI data " string"
Specifies data for initializing plugin.
.TP
.BI name " string"
Specifies the short name of the database.
See
.I Database Specification
for more information.
.TP
.BI info " string"
Specifies the information about database.
See
.I Database Specification
for more information.
.TP
.BI invisible
Makes dictionary invisible to the clients.
See
.I Database Specification
for more information.
.TP
.BI disable_strategy " string"
Disables the specified strategy for database.
See
.I Database Specification
for more information.
.TP
.BI default_strategy " string"
Sets the default search strategy for database.
See
.I Database Specification
for more information.
.RE

.B Mime Specification
.RS
.TP
.BI dbname_nomime " string"
Specifies the real database name which is used
in case
.I OPTION MIME
command was NOT received from a client.
.TP
.BI dbname_mime " string"
Specifies the real database name which is used
in case
.I OPTION MIME
command WAS received from a client.
A necessary MIME header is set while creating a database.
See
.I dictfmt(1)
for option
.I --mime-header.
.TP
.BI name " string"
Specifies the short name of the database.
See
.I Database Specification
for more information.
.TP
.BI info " string"
Specifies the information about database.
See
.I Database Specification
for more information.
.TP
.BI invisible
Makes dictionary invisible to the clients.
See
.I Database Specification
for more information.
.TP
.BI disable_strategy " string"
Disables the specified strategy for database.
See
.I Database Specification
for more information.
.TP
.BI default_strategy " string"
Sets the default search strategy for database.
See
.I Database Specification
for more information.
.RE
.TP
.BI include " string"
The text of the file "string" (usually a database specification)
will be read as if it appeared at this location in the configuration file.
Nested includes are not permitted.
.SH "DETERMINATION OF ACCESS LEVEL"
When a client connects, the global access specification is scanned, in
order, until a specification matches.  If no access specification exists,
all access is allowed (e.g., the action is the same as if "allow *" was the
only item in the specification).  For each item, both the hostname and IP
are checked. For example, consider the following access specification:
.RS
allow 10.42.*
.br
authonly *.edu
.br
deny *
.RE
With this specification, all clients in the 10.42 network will be allowed
access to unrestricted databases; all clients from *.edu sites will be
allowed to authenticate, but will be denied access to all databases, even
those which are otherwise unrestricted; and all other clients will have
their connection terminated immediately.  The 10.42 network clients can
send an AUTH command and gain access to restricted databases.  The *.edu
clients must send an AUTH command to gain access to any databases,
restricted or unrestricted.
.P
When the AUTH command is sent, the access list for each database is
scanned, in order, just as the global access list is scanned.  However,
after authentication, the client has an associated username.  For example,
consider the following access specification:
.RS
user u1
.br
deny *.com
.br
user u2
.br
allow *
.RE
If the client authenticated as u1, then the client will have access to this
database, even if the client comes from a *.com site.  In contrast, if the
client authenticated as u2, the client will only have access if it does not
come from a *.com site.  In this case, the "user u2" is redundant, since
that client would also match "allow *".
.P
.B Warning:
Checks are performed for domain names and for IP addresses.  However, if
reverse DNS for a specific site is not working, it is possible that a
domain name may not be available for checking.  Make sure that all denials
use IP addresses.  (And consider a future enhancement: if a domain name is
not available, should denials that depend on a domain name match anything?
This is the more conservative viewpoint, but it is not currently
implemented.)
.SH "SEARCH ALGORITHMS"
The DICT standard specifies a few search algorithms that must be
implemented, and permits others to be supported on a server-dependent
basis.  The following search strategies are supported by this server.  Note
that
.I all
strategies are case insensitive.  Most ignore non-alphanumeric,
non-whitespace characters.
.TP
.B exact
An exact match.  This algorithm uses a binary search and is one of the
fastest search algorithms available.
.TP
.B lev
The Levenshtein algorithm (string edit distance of one).  This algorithm
searches for all words which are within an edit distance of one from the
target word.  An "edit" means an insertion, deletion, or transposition.
This is a rapid algorithm for correcting spelling errors, since many
spelling errors are within a Levenshtein distance of one from the original
word.
.TP
.B prefix
Prefix match.  This algorithm also uses a binary search and is very fast.
.TP
.B nprefix
Like
.I prefix
but returns the specified range of matches. For example,
when
.I prefix
strategy returns 1000 matches,
you can get only 100 ones skipping the first 800 matches.
This is made by specified these limits in a query like this:
800#100#app, where 800 is skip count, 100 is a number of matches
you want to get and "app" is your query.
This strategy allows one to implement DICT client with fast autocompletion
(although it is not trivial)
just like many standalone dictionary programs do.
.P
.RS
.B NOTE:
If you access the dictionary "*" (or virtual one) with
.I nprefix
strategy,
the same range is set for each database in it,
but globally for all matches found in all databases.
.RE
.P
.RS
.B NOTE:
In case you access non-english dictionary the returned matches
may be (and mostly will be) NOT ordered in alphabetic order.
.RE
.TP
.B re
POSIX 1003.2 (modern) regular expression search.  Modern regular
expressions are the ones used by
.BR egrep (1).
These regular expressions allow predefined character classes (e.g.,
[[:alnum:]], [[:alpha:]], [[:digit:]], and [[:xdigit:]] are useful for this
application); uses * to match a sequence 0 or more matches of the previous
atom; uses + to match a sequence of 1 or more matches of the previous atom;
uses ? to match a sequence of 0 or 1 matches of the previous atom; used ^ to
match the beginning of a word, uses $ to match the end of a word, and
allows nested subexpression and alternation with () and |.  For example,
"(foo|bar)" matches all words that contain either "foo" or "bar".  To match
these special characters, they must be quoted with two backslashes (due to
the quoting characteristics of the server).
.B Warning:
Regular expression matches can take 10 to 300 times longer than substring
matches.  On a busy server, with many databases, this can required more
than 5 minutes of waiting time, depending on the complexity of the regular
expression.
.TP
.B regexp
Old (basic) regular expressions.  These regular expressions don't support
|, +, or ?.  Groups use escaped parentheses.  While modern regular
expressions are generally easier to use, basic regular expressions have a
back reference feature.  This can be used to match a second occurrence of
something that was already matched.  For example, the following expression
finds all words that begin and end with the same three letters:
.RS
.nf
    ^\\\\(...\\\\).*\\\\1$
.fi
.P
Note the use of the double backslashes to escape the special characters.
This is required by the DICT protocol string specification (a single
backslash quotes the next character -- we use two to get a single backslash
through to the regular expression engine).
.B Warning:
Note that the use of backtracking is even slower than the use of general
regular expressions.
.RE
.TP
.B soundex
The Soundex algorithm, a classic algorithm for finding words that sound
similar to each other.  The algorithm encodes each word using the first
letter of the word and up to three digits.  Since the first letter is
known, this search is relatively fast, and it sometimes good for correcting
spelling errors when the Levenshtein algorithm doesn't help.
.TP
.B substring
Match a substring anywhere in the headword.  This search strategy uses a
modified Boyer-Moore-Horspool algorithm.  Since it must search the whole
index file, it is not as fast as the exact and prefix matches.
.TP
.B suffix
Suffix match.  This search strategy also uses a modified
Boyer-Moore-Horspool algorithm, and is as fast as the substring
search.  If the optional index_suffix string file is listed in the
configuration file this search is much faster.
.TP
.B word
Match any single word, even if part of a multi-word entry.  If the
optional index_word string file is listed in the configuration file
this search strategy works much faster.
.TP
.B first
Match the first word that begins a multi-word entry.
.TP
.B last
Match the last word that ends a multi-word entry.
If the optional index_suffix string file is listed in the configuration file
this search strategy works much faster.
.SH "DATABASE FORMAT"
Databases for
.B dictd
are distributed separately.  A database consists of two files.  One is a
flat text file, the other is the index.
.P
The flat text file contains dictionary entries (or any other suitable
data), and the index contains tab-delimited tuples consisting of the
headword, the byte offset at which this entry begins in the flat text file,
and the length of the entry in bytes.  The offset and length are encoded
using base 64 encoding using the 64-character subset of International
Alphabet IA5 discussed in RFC 1421 (printable encoding) and RFC 1522
(base64 MIME).  Encoding the offsets in base 64 saves considerable space
when compared with the usual base 10 encoding, while still permitting tab
characters (ASCII 9) to be used for delimiting fields in a record.  Each
record ends with a newline (ASCII 10), so the index file is human readable.
.P
Some headwords are used by
.I dictd
especially
.P
.BI 00\-database\-info
Contains the information about database
which is 
returned by SHOW INFO command,
unless it is specified in the configuration file.
.P
.BI 00\-database\-short
Contains the short name of the database
which is
returned by SHOW DB command,
unless it is specified in the configuration file.
See dictfmt \-s.
.P
.BI 00\-database\-url
URL where original dictionary sources were obtained from.
See dictfmt \-u.
This headword is not used by
.I dictd
.P
.BI 00\-database\-utf8
Presents if dictionary is encoded using UTF-8.
See dictfmt \-\-utf8
.P
.BI 00\-database\-8bit\-new
Presents if dictionary is encoded using 8-BIT character set
(not ASCII and not UTF8).
See dictfmt \-\-locale.
.P
The flat text file may be compressed using
.BR gzip (1)
(not recommended) or
.BR dictzip (1)
(highly recommended).  Optimal speed will be obtained using an uncompressed
file.  However, the
.B gzip
compression algorithm works very well on plain text, and can result in
space savings typically between 60 and 80%.  Using a file compressed with
.BR gzip (1)
is not recommended, however, because random access on the file can only be
accomplished by serially decompressing the whole file, a process which is
prohibitively slow.
.BR dictzip (1)
uses the same compression algorithm and file format as does
.BR gzip (1),
but provides a table that can be used to randomly access compressed blocks
in the file.  The use of 50-64kB blocks for compression typically degrades
compression by less than 10%, while maintaining acceptable random access
capabilities for all data in the file.  As an added benefit, files
compressed with
.BR dictzip (1)
can be decompressed with
.BR gzip (1)
or
.BR zcat (1).
(Note: recompressing a
.BR dictzip 'd
file using, for example,
.BR znew (1)
will destroy the random access characteristics of the file.  Always
compress data files using
.BR dictzip (1).)
.SH "SIGNALS"
.P
.B SIGHUP
causes dictd to reread configuration file and reinitialize databases.
.P
.B SIGUSR1
causes dictd to unload databases. Then
.I dictd
returns 420 status (instead of 220). To load databases again, send
.B SIGHUP
signal. Because database files are
.I mmap'ed(2)
, it is impossible
to update them while
.I dictd
is running.
So, if you need to update database files and reread configuration file,
first, send
.B SIGUSR1
signal
to
.I dictd
to unload databases,
update files, and then send
.B SUGHUP
signal to load them again.
.SH "COPYING"
The main source files for the
.B dictd
server and the
.B dictzip
compression program were written by Rik Faith (faith@dict.org) and are
distributed under the terms of the GNU General Public License.  If you need
to distribute under other terms, write to the author.
.P
The main libraries used by these programs (zlib, regex, libmaa) are
distributed under different terms, so you may be able to use the libraries
for applications which are incompatible with the GPL -- please see the
copyright notices and license information that come with the libraries for
more information, and consult with your attorney to resolve these issues.
.SH "BUGS"
The regular expression searches do not ignore non-whitespace,
non-alphanumeric characters as do the other searches.  In practice, this
isn't much of a problem.
.SH "WARNINGS"
Conformance of regular expressions
(used by 're' and 'regexp' search strategies)
to ERE and BRE depends on
library you build dictd with.
Whether 're' and 'regex' strategies support utf8 depends on 
library you build dictd with.
.SH "FILES"
.TP
.I @SYSCONFDIR@/dictd.conf
.B dictd
configuration file
.TP
.I @SBINDIR@/dictd
.B dictd
daemon itself
.TP
.I /var/run/dictd.pid
File for storing pid of
.B dictd
daemon
.TP
.I @DATADIR@
The default directory for
.B dictd
databases (.index and .dict[.dz] files)
.SH "SEE ALSO"
.BR examples/dictd*.conf,
.BR dictfmt (1),
.BR dict (1),
.BR dictzip (1),
.BR gunzip (1),
.BR zcat (1),
.BR webster (1),
.B RFC 2229