DICTD(8)

🎀 NAME 🎀

okay so bestie, meet dictd — star of the DICTD(8) manual page — a dictionary database server. 💖

✨ SYNOPSIS ✨

dictd [options]

💅 DESCRIPTION 💅

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. literally the whole point. 🫶

For security reasons, dictd drops root permissions after startup. If user dictd exists on the system, the daemon will run as that user, group dictd, otherwise it will run as user nobody, group nobody or nogroup (depending on the operating system distribution). safety first, bestie. 🔐

Since startup time is significant, the server is designed to run continuously, and should not be run from inetd(8). (However, with a fast processor, it is feasible to do so.) 👑

Databases are distributed separately from the server. 🍓

By default, 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 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. ✨

🌸 BACKGROUND 🌸

okay history lesson, but make it cute. 💜

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. 😭

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). the multilingual slay is real. 🌈

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. 💀

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. 👑

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. 🦋

🔥 OPTIONS 🔥

• -V, --version — display version information. ⭐
• --license — display copyright and license information. 📜
• -h, --help — display help information. 🫶
• -v, --verbose, -dverbose — be verbose. yap mode: on. 💬
• -c file, --config file — specify configuration file. The default is /etc/dict/dictd.conf, but may be changed in the defs.h file at compile time (DICTD_CONFIG_FILE). 🗂️
• -p port, --port port — overrides the keyword port in Global Settings Specification section of configuration file. 🔌
• -i, --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. ⚡
• --pp prog — sets a preprocessor for configuration file. like m4 or cpp. See examples/dictd_complex.conf file from distribution. By default configuration file is parsed without preprocessor. 🧚
• --depth length — overrides the keyword depth in Global Settings Specification section of configuration file. 📏
• --delay seconds — overrides the keyword delay in Global Settings Specification section of configuration file. ⏳
• --facility facility — the same as syslog_facility keyword in Global Settings Specification of configuration files. 🛰️
• -f, --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 -p, since, if one instance is bound to a port, the second one fails when it can not bind to the port.) 💥
• --limit children — overrides the keyword limit in Global Settings Specification section of configuration file. 👯
• --listen-to host — overrides the keyword listen_to in Global Settings Specification section of configuration file. 👂
• --address-family family — overrides the keyword address_family in Global Settings Specification section of configuration file. 🌐
• --locale locale — overrides the keyword locale in Global Settings Specification section of configuration file. 🌍
• -s — the same as syslog keyword in Global Settings Specification of configuration files. 📡
• -L file, --logfile file — the same as log_file keyword in Global Settings Specification of configuration files. 🧾
• --pid-file file — the same as pid_file keyword in Global Settings Specification of configuration files. 🪪
• -m minutes, --mark minutes — overrides the keyword timestamp in Global Settings Specification section of configuration file. ⏰
• --default-strategy strategy — overrides the keyword default_strategy in Global Settings Specification section of configuration file. 🎯
• --without-strategy strat1,strat2,... — the same as without_strategy keyword in Global Settings Specification of configuration files. 🚫
• --add-strategy strategy_name:description — the same as add_strategy keyword in Global Settings Specification of configuration files. ➕
• --fast-start — the same as fast_start keyword in Global Settings Specification of configuration files. 🏃‍♀️
• --without-mmap — the same as without_mmap keyword in Global Settings Specification of configuration files. 🧠
• --stdin2stdout — when applied with --inetd, each command obtained from stdin is output to stdout. This option is useful for debugging. 🐛
• -l option, --log option — the same as log_option keyword in Global Settings Specification of configuration files. 📝
• -d option — the same as debug_option keyword in Global Settings Specification of configuration files. 🔍

🗂️ CONFIGURATION FILE 🗂️

📖 Introduction 📖

The configuration file defaults to /etc/dict/dictd.conf but can be specified on the command line with the -c option (see above). 🫶

The configuration file is read into memory at startup, and is not referenced again by dictd unless a signal 1 (SIGHUP) is received, which will cause dictd to reread the configuration file. soft reload moment. 🔄

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. 📚

🔤 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. ✨

🌍 Global Settings Section 🌍

• global { global settings specification } — used to set global dictd setting such as log file, syslog facility, locale and so on. 🌐
  • EXAMPLE: See examples/dictd4.conf file from the distribution. 🍓

🔐 Access Section 🔐

• 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. 🛡️
  • EXAMPLE: See examples/dictd3.conf file from the distribution. 💜

💾 Database Section 💾

• 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 dict -d.) 👑
  • EXAMPLE: See examples/dictd*.conf files from the distribution. 🌟
  • NOTE: If the files specified in the database specification do not exist on the system, dictd may silently fail. 😭
• database_virtual string { virtual database specification } — this section specifies the virtual database. The string specifies the name of the database (e.g., en-ru or fren). 🦋
  • EXAMPLE: See examples/dictd_virtual.conf or examples/dictd_complex.conf files from the distribution. 🌸
• database_plugin string { plugin specification } — this section specifies the plugin. The string specifies the name of the database. 🧩
  • EXAMPLE: See examples/dictd_plugin_dbi.conf or examples/dictd_complex.conf files from the distribution. 🎀

okay so back into the config-file directives, bestie, and these next ones are lowkey iconic 💅

• database_mime string { mime specification } — Traditionally, databases created for dictd contained plain text only because dictd releases before 1.10.0 didn't have full support of OPTION MIME option (consult with RFC-2229). This section describes the special database which behaves differently depending on whether OPTION MIME command was received from client or was not, i.e. the database created by this section allows 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 string specifies the name of the database.

NOTE: All this is about DEFINE command only. MATCH, SHOW DB, SHOW STRAT, SHOW INFO, SHOW SERVER and HELP commands return texts prepended with empty line only.

EXAMPLE: See examples/dictd_mime.conf file from the distribution.

• database_exit — Excludes following databases from the '*' database. By default '*' means all databases available. Look at 'examples/dictd_virtual.conf' file for example configuration.

NOTE: If you use 'virtual' dictionaries, you should use this directive, otherwise you will search the same dictionary twice.

💖 User Section 💖

• 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).

🌸 Access Specification 🌸

Access specifications may occur in the Access Section or in the Database Section. The access specification will be described here.

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.

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 --debug auth option to debug related problems.

Note that these specifications take only one string per specification line. However, you can have multiple lines of each type.

The syntax is as follows:

• 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.
• 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.
• 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.
• 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.

✨ Global Settings Specification ✨

This section describes the following parameters:

• 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 defs.h file at compile time (DICT_DEFAULT_SERVICE).
• 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.

EXAMPLE: See examples/dictd4.conf file from the distribution.

• site_no_banner boolean — By default SHOW SERVER command outputs information about dictd version and an operating system type. This option disables this.
• site_no_uptime boolean — By default SHOW SERVER command outputs information about uptime of dictd , a number of forks since startup and forks per hour. This option disables this.
• 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.
• 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 defs.h file at compile time (DICT_DEFAULT_DELAY).

NOTE: Setting delay option disables limit_time option. Only one of them (last specified in dictd.conf ) is in effect.

NOTE: Connections are closed without warning since no provision for premature connection termination is specified in the DICT protocol RFC.

• depth number — Specify the queue length for 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 defs.h file at compile time (DICT_QUEUE_DEPTH).
• 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 defs.h file at compile time (DICT_DAEMON_LIMIT_CHILDS).
• limit number — Synonym for limit_childs. For backward compatibility only.
• limit_matches number — Specifies the maximum number of matches that can be returned by MATCH query. Zero means no limit. The default is 2000.
• limit_definitions number — Specifies the maximum number of definitions that can be returned by DEFINE query. Zero means no limit. The default is 200.
• 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 defs.h file at compile time (DICT_DEFAULT_LIMIT_TIME).

NOTE: Setting limit_time option disables delay option. Only one of them (last specified in dictd.conf ) is in effect.

NOTE: Connections are closed without warning since no provision for premature connection termination is specified in the DICT protocol RFC.

• 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 defs.h file at compile time (DICT_DEFAULT_LIMIT_QUERIES).
• 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.)

log_option option

okay so this one lets you pick a logging option 💖 but bestie, it literally only does anything if you've already turned logging on with -s or -L, or in the configuration file, or if you've activated logging to the console via a debugging option (like --debug nodetach). Only one option can be set per invocation of this thing — but you can invoke it multiple times, on the config file or the dictd command line. Like so:

dictd -s --log stats --log found --log notfound

that's a totally valid command line, and it sets three logging options. slay 💅

ngl, some of the more verbose logging options exist mainly for debugging the server code itself — they are not practical for normal use, so don't come for me if your logs get huge 😭

• server — Log server diagnostics. This is extremely verbose. like, buckle up.
• connect — Log all connections.
• stats — Log all children terminations.
• command — Log all commands. Again: extremely verbose.
• client — Log results of CLIENT command.
• found — Log all words found in the databases.
• notfound — Log all words not found in the databases.
• timestamp — When logging to a file, use a full timestamp like the one syslog would produce. Otherwise there's no timestamp at all, which keeps the files shorter.
• host — Log name of foreign host.
• auth — Log authentication failures.
• min — Set a minimal number of options. If logging is activated (to a file, or via syslog) and no options are set, the minimal set of options gets used. If options are set, then only the options you specified get used. periodt.
• all — Set all of the options. all of them. every single one 🌈
• none — Clear all of the options.

---

To make it easier to find the interesting bits in the log file, entries are marked with an initial letter that tells you the class of the line being logged 🔍:

• I — Information about the server, connections, or termination statistics. These lines are generally not designed to be parsed automatically.
• E — Error messages.
• C — CLIENT command information.
• D — Definitions found in the databases searched.
• M — Matches found in the database searched.
• N — Matches which were not found in the databases searched.
• T — Trace of exact line sent by client.
• A — Authentication information.

🫶 privacy check, bestie: to preserve anonymity of the client, do not use the connect or 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.

debug_option string

Activate a debugging option ✨ There are several, and honestly all of them are only useful to developers — they're documented here purely for completeness. You can get a list interactively by using -d with an illegal option. cheeky but it works 💀

• verbose — The same as -v or --verbose. Adds verbosity to other options.
• scan — Debug the scanner for the configuration file.
• parse — Debug the parser for the configuration file.
• search — Debug the character folding and binary search routines.
• init — Report database initialization.
• port — Log client-side port number to the log file.
• lev — Debug Levenshtein search algorithm.
• auth — Debug the authorization routines.
• nodetach — Do not detach as a background process. Implies that a copy of the log file will appear on the standard output.
• nofork — Do not fork daemons to service requests. Be a single-threaded server. This option implies nodetach, and is most useful for using a debugger to find the point at which daemon processes are dumping core. very much a "when things go feral" tool 🙈
• alt — Debugs altcompare in index.c.

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 the one 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 as a substring, UTF-8 format is expected. And note: if your database isn't in ASCII7 or UTF-8 format, then the dictd server will not be compliant to RFC 2229. facts are facts ✨

😭 NOTE: if utf-8 or 8-bit dictionaries are included in the configuration file and the appropriate --locale hasn't been specified, dictd will fail to start. This implies that dictd will not run with both utf-8 and 8-bit dictionaries in the configuration file. so pick a lane, bestie.

add_strategy strategy_name description

Adds strategy strategy_name with the description description. This new search strategy may be implemented with a help of plugins 🧚 Both strategy_name and description are strings.

default_strategy string

Set the server's default search strategy for the MATCH search type. The compiled-in default is 'lev'. It's also possible to set the default strategy per database — see the default_strategy keyword in the Database specification section. 👑

disable_strategy string

Disable specified strategies. By default all implemented search strategies are enabled. It's also possible to disable strategies per database — see the disable_strategy keyword in the Database specification section. 💅

listen_to host

Local host name or IP address for bind. If unspecified or *, dictd will bind to all interfaces. Otherwise, dictd will bind to this address only.

address_family family

If 4, the address family is IPv4 (that's the default). If 6, the address family is IPv6. two icons, one choice 🦋

syslog string

Log using the syslog(3) facility.

syslog_facility string

Specifies the syslog facility to use. Using this option implies the -s option, which turns on logging via syslog ⭐ When the operating system libraries support SYSLOG_NAMES, the names used for this option should be those listed in 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. that's the whole roster 🎀

log_file string

Specify the file for logging. The filename specified is recomputed on each use via the 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. cute, right?

NOTE: if dictd does not have write permission for this file, it will silently fail. no error, no warning, just vibes and nothing in your log. devastating 💀

pid_file string

The specified filename will be created to contain the process id of the main dictd process. The default is

/var/run/dictd.pid

fast_start

By default, dictd creates an additional index (in memory) to make the search faster. This option disables that behaviour and makes startup faster 🚀

without_mmap

Do not use the mmap(2) function and read entire files into memory instead.

⚠️ use this option only if you know exactly what you are doing. like, genuinely. this is not a "try it and see" situation bestie 😭

---

🗂️ Database Specification 🗂️

The database specification describes the database, and honestly it's giving main character energy for each dict you add 💜

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=...

index string

Specifies the filename for the index file. The path rules are similar to the ones described above in the "data" option ☝️

index_suffix string

This is an optional index file that makes the 'suffix' search strategy faster (binary search) ✨ It's generated by 'dictfmt_index2suffix'. Run

dictfmt_index2suffix --help

for more information. The path rules are similar to the ones described above in the "data" option.

index_word string

This is an optional index file that makes the 'word' search strategy faster (binary search) 🦋 It's generated by 'dictfmt_index2word'. Run

dictfmt_index2word --help

for more information. The path rules are similar to the ones described above in the "data" option.

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. fancy 💅

• postfilter string — sets the postfilter command, bestie. When a chunk of the compressed database gets read, it’s filtered with this filter before the offset and length for the entry are used to access data. It’s here for symmetry with the prefilter command, and it may also be useful for extra database compression. ✨
• filter string — sets the filter command. After the entry is pulled out of the database, it gets filtered with this filter. You can use it to format the entry (e.g., for html). 💅
• name string — the short name of the database (e.g., "1913 Webster's"). If the string starts with @, then it specifies the headword to look up in the dictionary to find the short name of the database. Default is "@00-database-short", but that can be changed in the defs.h file at compile time (DICT_SHORT_ENTRY_NAME). 🎀
• info string — the information about the database. If the string starts with @, then it specifies the headword to look up in the dictionary to find the info. Default is "@00-database-info", but that can be changed in the defs.h file at compile time (DICT_INFO_ENTRY_NAME). 🦋
• invisible — makes the dictionary invisible to clients, meaning 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 an invisible dictionary, the name of the upper visible virtual dictionary is returned. Dictionaries '*' and '!' don’t include invisible ones. NOTE: invisible dictionaries are completely inaccessible (and invisible) to the client unless they’re included in the virtual or MIME dictionary (see database_virtual or database_mime database sections). 🙈
• disable_strategy string — disables the specified strategy for the database. This may be useful for slow dictionaries (plugins) or for dictionaries included in virtual ones. For an example, see the file examples/dictd_complex.conf. 💀
• default_strategy string — specifies the strategy that’ll 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 lev, the strategy word may be preferred for databases mainly containing multiword phrases but single words. 🔥

🌈 Virtual Database Specification 🌈

The virtual database specification describes the virtual database:

• database_list string — specifies a list of databases that are included in the virtual database. Database names are in the string and separated by comma. 🍓
• name string — the short name of the database. See database specification. 💖
• info string — the information about the database. See database specification. ✨
• invisible — makes the dictionary invisible to the clients. See database specification. 🫶
• disable_strategy string — disables the specified strategy for the database. See database specification. 💅

🧚 Plugin Specification 🧚

• plugin string — specifies a filename of the plugin. 🌸
• data string — specifies data for initializing the plugin. 🎀
• name string — the short name of the database. See Database Specification for more information. 🦋
• info string — the information about the database. See Database Specification for more information. 💜
• invisible — makes the dictionary invisible to the clients. See Database Specification for more information. 🙈
• disable_strategy string — disables the specified strategy for the database. See Database Specification for more information. 💀
• default_strategy string — sets the default search strategy for the database. See Database Specification for more information. 🔥

👑 Mime Specification 👑

• dbname_nomime string — the real database name used in case the OPTION MIME command was NOT received from a client. 🍓
• dbname_mime string — the real database name used in case the OPTION MIME command WAS received from a client. A necessary MIME header is set while creating a database. See dictfmt(1) for option --mime-header. 🌟
• name string — the short name of the database. See Database Specification for more information. 💖
• info string — the information about the database. See Database Specification for more information. ✨
• invisible — makes the dictionary invisible to the clients. See Database Specification for more information. 🫶
• disable_strategy string — disables the specified strategy for the database. See Database Specification for more information. 💅
• default_strategy string — sets the default search strategy for the database. See Database Specification for more information. 🔥
• 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. 🚫

---

⭐ DETERMINATION OF ACCESS LEVEL ⭐

Okay so when a client connects, the global access specification gets 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 this access specification:

allow 10.42.*
authonly *.edu
deny *

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. 😤

When the AUTH command is sent, the access list for each database is scanned, in order, just as the global access list is scanned. But after authentication, the client has an associated username. For example, consider this access specification:

user u1
deny *.com
user u2
allow *

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 *". 💀

Warning: Checks are performed for domain names and for IP addresses. However, if reverse DNS for a specific site is not working, it’s 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.) 😭

🔍 SEARCH ALGORITHMS 🔍

Okay so the DICT standard says a server has to implement a few search algorithms, and it can support extra ones depending on the server. This server supports the following search strategies. Important vibe check: all strategies are case insensitive. Most of them ignore non-alphanumeric, non-whitespace characters.

• exact — An exact match. This algorithm uses a binary search and is one of the fastest search algorithms available. Slay, honestly.
• lev — The Levenshtein algorithm (string edit distance of one). It 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. Spelling-error cleanup icon.
• prefix — Prefix match. This algorithm also uses a binary search and is very fast.
• nprefix — Like prefix but returns the specified range of matches. For example, when prefix strategy returns 1000 matches, you can get only 100 ones skipping the first 800 matches. This is made by specifying 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 to implement DICT client with fast autocompletion (although it is not trivial) just like many standalone dictionary programs do.
  • NOTE: If you access the dictionary * (or virtual one) with nprefix strategy, the same range is set for each database in it, but globally for all matches found in all databases.
  • NOTE: In case you access non-english dictionary the returned matches may be (and mostly will be) NOT ordered in alphabetic order.
• re — POSIX 1003.2 (modern) regular expression search. Modern regular expressions are the ones used by 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).

Warning: Regular expression matches can take 10 to 300 times longer than substring matches. On a busy server, with many databases, this can require more than 5 minutes of waiting time, depending on the complexity of the regular expression. Girl, that’s a whole snack break.

• 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:

^\\(...\\).*\\1$

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).

Warning: Note that the use of backtracking is even slower than the use of general regular expressions. Backtracking said “I’ll take my time,” fr fr.

• 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.
• 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.
• 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.
• 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.
• first — Match the first word that begins a multi-word entry.
• 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.

---

🗂️ DATABASE FORMAT 🗂️

Databases for dictd are distributed separately. A database consists of two files. One is a flat text file, the other is the index. Two-file energy, very minimal, very chic.

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. Data structure with people skills? Obsessed.

Some headwords are used by dictd especially:

• 00-database-info — Contains the information about database which is returned by SHOW INFO command, unless it is specified in the configuration file.
• 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.
• 00-database-url — URL where original dictionary sources were obtained from. See dictfmt -u. This headword is not used by dictd.
• 00-database-utf8 — Presents if dictionary is encoded using UTF-8. See dictfmt --utf8.
• 00-database-8bit-new — Presents if dictionary is encoded using 8-BIT character set (not ASCII and not UTF8). See dictfmt --locale.

The flat text file may be compressed using gzip(1) (not recommended) or dictzip(1) (highly recommended). Optimal speed will be obtained using an uncompressed file. However, the 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 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. dictzip(1) uses the same compression algorithm and file format as does 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 dictzip(1) can be decompressed with gzip(1) or zcat(1). (Note: recompressing a dictzip'd file using, for example, znew(1) will destroy the random access characteristics of the file. Always compress data files using dictzip(1).) Do not betray the random access, bestie. Do not.

---

📡 SIGNALS 📡

• SIGHUP — Causes dictd to reread configuration file and reinitialize databases.
• SIGUSR1 — Causes dictd to unload databases. Then dictd returns 420 status (instead of 220). To load databases again, send SIGHUP signal. Because database files are mmap'ed(2), it is impossible to update them while dictd is running. So, if you need to update database files and reread configuration file, first, send SIGUSR1 signal to dictd to unload databases, update files, and then send SUGHUP signal to load them again. (The page spells it SUGHUP there — that’s the load-them-again move, iykyk.)

---

📜 COPYING 📜

The main source files for the dictd server and the 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.

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. Legal bestie says: read the receipts.

---

🐛 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. Small chaos, not a crisis.

---

⚠️ 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. So your regex mileage may vary depending on the library glow-up.

---

📁 FILES 📁

• /etc/dict/dictd.conf — dictd configuration file
• /usr/bin/dictd — dictd daemon itself
• /var/run/dictd.pid — File for storing pid of dictd daemon
• /usr/share — The default directory for dictd databases (.index and .dict[.dz] files)

---

👀 SEE ALSO 👀

• examples/dictd*.conf
• dictfmt(1)
• dict(1)
• dictzip(1)
• gunzip(1)
• zcat(1)
• webster(1)
• RFC 2229

---

That’s the whole DICTD(8) page, bestie! Source/version: DICTD(8), dated 29 March 2002. Now go be iconic with your dictionaries 💅📚✨