Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DICTD(8)							      DICTD(8)

NAME
       dictd - 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  ac-
       cess  dictionary	 definitions from a set	of natural language dictionary
       databases.

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

       Since  startup  time is significant, the	server is designed to run con-
       tinuously, 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 alphabeti-
       cally, 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-data-
       base-8bit-new" which indicates that the database	is encoded and	sorted
       according to a locale that uses an 8-bit	encoding.

BACKGROUND
       For many	years, the Internet community has relied on the	"webster" pro-
       tocol 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	incom-
       plete  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.)  Translat-
       ing and non-English dictionaries	are also becoming available (for exam-
       ple, the	FOLDOC dictionary is being translated into Spanish).

       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 (us-
       ing 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  ac-
       cess 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  my-
       self) have implemented clients in a variety of languages.

OPTIONS
       -V or --version
	      Display version information.

       --license
	      Display copyright	and license information.

       -h or --help
	      Display help information.

       -v or --verbose or  -dverbose
	      Be verbose.

       -c file or --config file
	      Specify	configuration	file.	 The   default	 is   /usr/lo-
	      cal/etc/dictd.conf , but may be changed in the  defs.h  file  at
	      compile time (DICTD_CONFIG_FILE).

       -p port or --port port
	      Overrides	the keyword port in Global Settings Specification sec-
	      tion of configuration file.

       -i or --inetd
	      Communicate on standard input/output, suitable for use from  in-
	      etd.   Although, due to its rather large startup time, this dae-
	      mon 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  de-
	      fault 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 Specifi-
	      cation of	configuration files.

       -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 -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 address
	      Overrides	the keyword listen_to 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 or --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  or --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	Speci-
	      fication section of configuration	file.

       --without-strategy strat1,strat2,...
	      The same as without_strategy keyword in Global Settings Specifi-
	      cation of	configuration files.

       --add-strategy strategy_name:description
	      The same as add_strategy keyword in Global  Settings  Specifica-
	      tion 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  Specifica-
	      tion 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 or --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 Specifica-
	      tion of configuration files.

CONFIGURATION FILE
       Introduction
	      The configuration	file defaults to /usr/local/etc/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 re-
	      ceived, which will cause dictd to	reread the configuration file.

	      The file is divided into sections.  The  Access  Section	should
	      come  first, followed by the Database Section, and the User Sec-
	      tion.  The Database Section is  required;	 the  others  are  op-
	      tional, but they must be in the order listed here.

       Syntax The  following  keywords	are valid in a configuration file: ac-
	      cess, allow, deny, group,	database, data,	 index,	 filter,  pre-
	      filter,  postfilter,  name, include, user, authonly, site.  Key-
	      words 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 con-
		     trol 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  distri-
		     bution.

		     NOTE:  If	the files specified in the database specifica-
		     tion 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	 exam-
		     ples/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	 exam-
		     ples/dictd_complex.conf files from	the distribution.

	      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 data-
		     base which	behaves	differently depending on  whether  OP-
		     TION  MIME	 command  was received from client or was not,
		     i.e. the database created by this section allows  to  re-
		     turn  to the client either	a plain	text or	specially for-
		     matted 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  dis-
		     tribution.

	      database_exit
		     Excludes  following  databases from the '*' database.  By
		     default '*' means all databases available.	 Look at  'ex-
		     amples/dictd_virtual.conf'	 file  for  example configura-
		     tion.

		     NOTE: If you use 'virtual'	dictionaries, you  should  use
		     this  directive,  otherwise you will search the same dic-
		     tionary 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 ver-
			    sion 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  de-
			    nied 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 fol-
		     lowed 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 spec-
		     ify 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  Ac-
			    cess  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  configura-
			    tion file.

		     deny string
			    The	 string	 specifies a domain name or IP address
			    which is denied access to the server (in  the  Ac-
			    cess  Section)  or	to a database (in the Database
			    Section).  Note that if reverse DNS	is  not	 work-
			    ing,  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 ex-
			    cept DEFINE, MATCH,	and SHOW  DB.	More  specifi-
			    cally  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  com-
			    mand 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 de-
		     fault 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 re-
		     sponse to the SHOW	SERVER command.

		     EXAMPLE: See examples/dictd4.conf file from the distribu-
		     tion.

	      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 informa-
		     tion about	databases, such	as a number of headwords,  in-
		     dex size and so on.  This option disables this.

	      delay number
		     Specifies	the number of seconds a	client may be idle be-
		     fore 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	speci-
		     fied 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  si-
		     multaneously.   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_DAE-
		     MON_LIMIT_CHILDS).

	      limit number
		     Synonym for  limit_childs.	  For  backward	 compatibility
		     only.

	      limit_matches number
		     Specifies	the  maximum number of matches that can	be re-
		     turned 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  de-
		     fault 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_DE-
		     FAULT_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	speci-
		     fied 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
		     Specify a logging option.	This is	effective only if log-
		     ging has been enabled with	the -s or -L option or in con-
		     figuration	file, or logging to the	console	has been acti-
		     vated with	a debugging option  (e.g.,  --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:
		     dictd -s --log stats --log	found --log notfound
		     is	a valid	command	line, and sets three logging options.

		     Some of the more verbose logging options are used primar-
		     ily  for debugging	the server code, and are not practical
		     for normal	use.

		     server Log	server diagnostics.  This  is  extremely  ver-
			    bose.

		     connect
			    Log	all connections.

		     stats  Log	all children terminations.

		     command
			    Log	all commands.  This is 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
			    that which syslog would  produce.	Otherwise,  no
			    timestamp is made, making 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  op-
			    tions  are	set,  then  the	minimal	set of options
			    will be used.  If options are set, then only those
			    options specified will be used.

		     all    Set	all of the options.

		     none   Clear all of the options.

		     To	 facilitate location of	interesting information	in the
		     log file, entries are marked with initial	letters	 indi-
		     cating the	class of the line being	logged:

		     I	    Information	about the server, connections, or ter-
			    mination 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.

		     To	preserve anonymity of the client, do not use the  con-
		     nect  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,	all of
		     which are only useful to developers.  They	are documented
		     here  for	completeness.  A list can be obtained interac-
		     tively by using -d	with an	illegal	option.

		     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 rou-
			    tines.

		     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 node-
			    tach, and is most useful for using a  debugger  to
			    find the point at which daemon processes are dump-
			    ing	core.

		     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 that  used  for  dictfmt
		     when the database was built (specifically,	the locale un-
		     der 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  ex-
		     pected.   Note  that if your database is not in ASCII7 or
		     UTF-8 format, then	the dictd server will not be compliant
		     to	RFC 2229.

		     NOTE  If  utf-8 or	8-bit dictionaries are included	in the
		     configuration file, and the appropriate --locale has  not
		     been  specified,  dictd will fail to start.  This implies
		     that dictd	will not run with both utf-8 and 8-bit dictio-
		     naries in the configuration file.

	      add_strategy strategy_name description
		     Adds strategy strategy_name with the description descrip-
		     tion.  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 MATCH	search
		     type.  The	compiled-in default is 'lev'.  It is also pos-
		     sible to set default  strategy  per  database.   See  de-
		     fault_strategy keyword in Database	specification section.

	      disable_strategy string
		     Disable specified strategies.  By default all implemented
		     search strategies are enabled.  It	is  also  possible  to
		     disable  strategies  per  database.  See disable_strategy
		     keyword in	Database specification section.

	      listen_to	string
		     Binds socket to the specified address.  If	 you  want  to
		     allow connections to dict server from localhost only, ap-
		     ply
		     listen_to 127.0.0.1

	      syslog string
		     Log using the syslog(3) facility.

	      syslog_facility string
		     Specifies the syslog facility to use.  The	 use  of  this
		     option  implies the -s option to turn on logging via sys-
		     log.  When	the operating system  libraries	 support  SYS-
		     LOG_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, lo-
		     cal1, local2, local3, local4, local5, local6, and local7.

	      log_file string
		     Specify the file for logging.  The	filename specified  is
		     recomputed	 on  each use using 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.
		     NOTE: If dictd does not have write	 permission  for  this
		     file, it will silently fail.

	      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 (in memory) additional index to
		     make the search faster.  This option disables this	behav-
		     iour and makes startup faster.

	      without_mmap
		     do	 not  use  the	mmap(2)	function and read entire files
		     into memory instead.  Use this option, if	you  know  ex-
		     actly what	you are	doing.

       Database	Specification
	      The database specification describes the database:

	      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 run-
		     ning ./configure --datadir=...

	      index string
		     Specifies	the  filename for the index file.  Path	matter
		     is	similar	to that	described above	in "data" option .

	      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 de-
		     scribed above in "data" option .

	      index_word string
		     This is optional index file to make 'word'	search	strat-
		     egy   faster   (binary   search).	 It  is	 generated  by
		     'dictfmt_index2word'. Run "dictfmt_index2word --help" for
		     more  information.	  Path	matter	is similar to that de-
		     scribed above in "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.

	      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.

	      filter string
		     Specifies the filter command.  After  the	entry  is  ex-
		     tracted  from the database, it will be filtered with this
		     filter.  This may be used to provide formatting  for  the
		     entry (e.g., for html).

	      name string
		     Specifies	the  short  name  of the database (e.g., "1913
		     Webster's").  If the string begins	with @,	then it	speci-
		     fies  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
		     defs.h file at compile time (DICT_SHORT_ENTRY_NAME).

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

	      invisible
		     Makes dictionary invisible	to the clients i.e. this  dic-
		     tionary will not be recognized or shown by	DEFINE,	MATCH,
		     SHOW INFO,	SHOW SERVER and	SHOW DB	commands. If some def-
		     initions  or  matches  are	found in invisible dictionary,
		     the name of the upper visible virtual dictionary  is  re-
		     turned.  Dictionaries '*' and '!' don't include invisible
		     ones.  NOTE: Invisible dictionaries are completely	 inac-
		     cessible  (and  invisible)	 to the	client unless they are
		     included to the virtual or	 MIME  dictionary  (See	 data-
		     base_virtual or database_mime database sections).

	      disable_strategy string
		     Disables  the  specified strategy for database.  This may
		     be	useful for slow	dictionaries (plugins) or for  dictio-
		     naries included to	virtual	ones.  For an example see file
		     examples/dictd_complex.conf.

	      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 data-
		     base. For example,	instead	of strategy lev	, the strategy
		     word may be preferred for databases mainly	containing the
		     multiword phrases but the single words.

       Virtual Database	Specification
	      The  virtual  database specification describes the virtual data-
	      base:

	      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.

	      name string
		     Specifies the short name of the  database.	 See  database
		     specification

	      info string
		     Specifies	the  information  about	database. See database
		     specification

	      invisible
		     Makes dictionary invisible	to the clients.	 See  database
		     specification

	      disable_strategy string
		     Disables  the specified strategy for database.  See data-
		     base specification

       Plugin Specification

	      plugin string
		     Specifies a filename of the plugin.

	      data string
		     Specifies data for	initializing plugin.

	      name string
		     Specifies the short name of the database.	 See  Database
		     Specification for more information.

	      info string
		     Specifies	the  information about database.  See Database
		     Specification for more information.

	      invisible
		     Makes dictionary invisible	to the clients.	 See  Database
		     Specification for more information.

	      disable_strategy string
		     Disables  the specified strategy for database.  See Data-
		     base Specification	for more information.

	      default_strategy string
		     Sets the default search strategy for database.  See Data-
		     base Specification	for more information.

       Mime Specification

	      dbname_nomime string
		     Specifies	the  real  database name which is used in case
		     OPTION MIME command was NOT received from a client.

	      dbname_mime string
		     Specifies the real	database name which is	used  in  case
		     OPTION MIME command WAS received from a client.  A	neces-
		     sary MIME header is set while creating a  database.   See
		     dictfmt(1)	for option --mime-header.

	      name string
		     Specifies	the  short name	of the database.  See Database
		     Specification for more information.

	      info string
		     Specifies the information about database.	 See  Database
		     Specification for more information.

	      invisible
		     Makes  dictionary invisible to the	clients.  See Database
		     Specification for more information.

	      disable_strategy string
		     Disables the specified strategy for database.  See	 Data-
		     base Specification	for more information.

	      default_strategy string
		     Sets the default search strategy for database.  See Data-
		     base 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 configu-
	      ration file.  Nested includes are	not permitted.

DETERMINATION OF ACCESS	LEVEL
       When a client connects, the global access specification is scanned,  in
       order,  until  a	specification matches.	If no access specification ex-
       ists, 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:
	      allow 10.42.*
	      authonly *.edu
	      deny *
       With  this  specification, all clients in the 10.42 network will	be al-
       lowed access to unrestricted databases; all clients  from  *.edu	 sites
       will be allowed to authenticate,	but will be denied access to all data-
       bases, 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.  However,
       after authentication, the client	has an associated username.  For exam-
       ple, consider the following 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  con-
       trast, if the client authenticated as u2, the client will only have ac-
       cess 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 is  pos-
       sible  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 do-
       main name match anything?  This is the more conservative	viewpoint, but
       it is not currently implemented.)

SEARCH ALGORITHMS
       The DICT	standard specifies a few search	algorithms that	must be	imple-
       mented, and permits others to be	supported on a server-dependent	basis.
       The  following  search  strategies  are supported by this server.  Note
       that all	strategies are case  insensitive.   Most  ignore  non-alphanu-
       meric, non-whitespace characters.

       exact  An  exact	match.	This algorithm uses a binary search and	is one
	      of the fastest search algorithms available.

       lev    The Levenshtein algorithm	(string	edit distance of  one).	  This
	      algorithm	 searches  for all words which are within an edit dis-
	      tance of one from	the target word.  An "edit"  means  an	inser-
	      tion, 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.

       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  ex-
	      ample,  when  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 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  ex-
	      pressions	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 required	more than 5 minutes of waiting
	      time, depending on the complexity	of the regular expression.

       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	speci-
	      fication (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.

       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	strat-
	      egy 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  configura-
	      tion 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 op-
	      tional 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.

       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	Inter-
       national	 Alphabet  IA5	discussed in RFC 1421 (printable encoding) and
       RFC 1522	(base64	MIME).	Encoding the offsets in	base 64	saves  consid-
       erable 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.

       Some headwords are used by dictd	especially

       00-database-info	Containts the information about	database which is  re-
       turned  by  SHOW	INFO command, unless it	is specified in	the configura-
       tion file.

       00-database-short Containts the short name of the database which	is re-
       turned  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  be-
       tween  60  and 80%.  Using a file compressed with gzip(1) is not	recom-
       mended, however,	because	random access on the file can only  be	accom-
       plished	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 charac-
       teristics of the	file.  Always compress data files using	dictzip(1).)

SIGNALS
       SIGHUP causes dictd to reread configuration file	and reinitialize data-
       bases.

       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 data-
       bases, update files, and	then send SUGHUP signal	to load	them again.

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 dis-
       tribute 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  li-
       braries	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 re-
       solve these issues.

BUGS
       The regular expression searches do not ignore  non-whitespace,  non-al-
       phanumeric  characters  as  do  the  other searches.  In	practice, this
       isn't much of a problem.

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.

FILES
       /usr/local/etc/dictd.conf
	      dictd configuration file

       /usr/local/sbin/dictd
	      dictd daemon itself

       /var/run/dictd.pid
	      File for storing pid of dictd daemon

       /usr/local/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

				 29 March 2002			      DICTD(8)

NAME | SYNOPSIS | DESCRIPTION | BACKGROUND | OPTIONS | CONFIGURATION FILE | DETERMINATION OF ACCESS LEVEL | SEARCH ALGORITHMS | DATABASE FORMAT | SIGNALS | COPYING | BUGS | WARNINGS | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dictd&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help