-
Notifications
You must be signed in to change notification settings - Fork 2
/
rfc2229.txt
1683 lines (1067 loc) · 58.2 KB
/
rfc2229.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group R. Faith
Request for Comments: 2229 U. North Carolina, Chapel Hill
Category: Informational B. Martin
Miranda Productions
October 1997
A Dictionary Server Protocol
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (1997). All Rights Reserved.
Abstract
The Dictionary Server Protocol (DICT) is a TCP transaction based
query/response protocol that allows a client to access dictionary
definitions from a set of natural language dictionary databases.
Table of Contents
1. Introduction ......................................... 2
1.1. Requirements ......................................... 3
2. Protocol Overview .................................... 3
2.1. Link Level ........................................... 3
2.2. Lexical Tokens ....................................... 3
2.3. Commands ............................................. 4
2.4. Responses ............................................ 5
2.4.1. Status Responses ..................................... 5
2.4.2. General Status Responses ............................. 6
2.4.3. Text Responses ....................................... 6
3. Command and Response Details ......................... 7
3.1. Initial Connection ................................... 7
3.2. The DEFINE Command ................................... 9
3.3. The MATCH Command .................................... 10
3.4. A Note on Virtual Databases .......................... 12
3.5. The SHOW Command ..................................... 13
3.5.1. SHOW DB .............................................. 13
3.5.2. SHOW STRAT ........................................... 13
3.5.3. SHOW INFO ............................................ 14
3.5.4. SHOW SERVER .......................................... 14
3.6. The CLIENT Command ................................... 15
Faith & Martin Informational [Page 1]
RFC 2229 A Dictionary Server Protocol October 1997
3.7. The STATUS Command ................................... 15
3.8. The HELP Command ..................................... 15
3.9. The QUIT Command ..................................... 16
3.10. The OPTION Command ................................... 16
3.10.1. OPTION MIME .......................................... 16
3.11. The AUTH Command ..................................... 18
3.12. The SASLAUTH Command ................................. 18
4. Command Pipelining ................................... 20
5. URL Specification .................................... 20
6. Extensions ........................................... 22
6.1. Experimental Command Syntax .......................... 22
6.2. Experimental Commands and Pipelining ................. 22
7. Summary of Response Codes ............................ 23
8. Sample Conversations ................................. 23
8.1. Sample 1 - HELP, DEFINE, and QUIT commands ........... 24
8.2. Sample 2 - SHOW commands, MATCH command .............. 25
8.3. Sample 3 - Server downtime ........................... 26
8.4. Sample 4 - Authentication ............................ 26
9. Security Considerations .............................. 26
10. References ........................................... 27
11. Acknowledgements ..................................... 29
12. Authors' Addresses ................................... 29
13. Full Copyright Statement ............................. 30
1. Introduction
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 [JARGON], the WordNet database [WORDNET], MICRA's
version of the 1913 Webster's Revised Unabridged Dictionary
[WEB1913], and the Free Online Dictionary of Computing [FOLDOC].
Translating and non-English dictionaries are also becoming available
(for example, the FOLDOC dictionary is being translated into
Spanish).
Faith & Martin Informational [Page 2]
RFC 2229 A Dictionary Server Protocol October 1997
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.
1.1. Requirements
In this document, we adopt the convention discussed in Section 1.3.2
of [RFC1122] of using the capitalized words MUST, REQUIRED, SHOULD,
RECOMMENDED, MAY, and OPTIONAL to define the significance of each
particular requirement specified in this document.
In brief: "MUST" (or "REQUIRED") means that the item is an absolute
requirement of the specification; "SHOULD" (or "RECOMMENDED") means
there may exist valid reasons for ignoring this item, but the full
implications should be understood before doing so; and "MAY" (or
"OPTIONAL") means that his item is optional, and may be omitted
without careful consideration.
2. Protocol Overview
2.1. Link Level
The DICT protocol assumes a reliable data stream such as provided by
TCP. When TCP is used, a DICT server listens on port 2628.
This server is only an interface between programs and the dictionary
databases. It does not perform any user interaction or
presentation-level functions.
2.2. Lexical Tokens
Commands and replies are composed of characters from the UCS
character set [ISO10646] using the UTF-8 [RFC2044] encoding. More
specifically, using the grammar conventions from [RFC822]:
Faith & Martin Informational [Page 3]
RFC 2229 A Dictionary Server Protocol October 1997
; ( Octal, Decimal.)
CHAR = <any UTF-8 character (1 to 6 octets)>
CTL = <any ASCII control ; ( 0- 37, 0.- 31.)
character and DEL> ; ( 177, 127.)
CR = <ASCII CR, carriage return> ; ( 15, 13.)
LF = <ASCII LF, linefeed> ; ( 12, 10.)
SPACE = <ASCII SP, space> ; ( 40, 32.)
HTAB = <ASCII HT, horizontal-tab> ; ( 11, 9.)
<"> = <ASCII quote mark> ; ( 42, 34.)
<'> = <ASCII single quote mark> ; ( 47, 39.)
CRLF = CR LF
WS = 1*(SPACE / HTAB)
dqstring = <"> *(dqtext/quoted-pair) <">
dqtext = <any CHAR except <">, "\", and CTLs>
sqstring = <'> *(dqtext/quoted-pair) <'>
sqtext = <any CHAR except <'>, "\", and CTLs>
quoted-pair = "\" CHAR
atom = 1*<any CHAR except SPACE, CTLs, <'>, <">, and "\">
string = *<dqstring / sqstring / quoted-pair>
word = *<atom / string>
description = *<word / WS>
text = *<word / WS>
2.3. Commands
Commands consist of a command word followed by zero or more
parameters. Commands with parameters must separate the parameters
from each other and from the command by one or more space or tab
characters. Command lines must be complete with all required
parameters, and may not contain more than one command.
Each command line must be terminated by a CRLF.
The grammar for commands is:
command = cmd-word *<WS cmd-param>
cmd-word = atom
cmd-param = database / strategy / word
database = atom
strategy = atom
Commands are not case sensitive.
Faith & Martin Informational [Page 4]
RFC 2229 A Dictionary Server Protocol October 1997
Command lines MUST NOT exceed 1024 characters in length, counting all
characters including spaces, separators, punctuation, and the
trailing CRLF. There is no provision for the continuation of command
lines. Since UTF-8 may encode a character using up to 6 octets, the
command line buffer MUST be able to accept up to 6144 octets.
2.4. Responses
Responses are of two kinds, status and textual.
2.4.1. Status Responses
Status responses indicate the server's response to the last command
received from the client.
Status response lines begin with a 3 digit numeric code which is
sufficient to distinguish all responses. Some of these may herald
the subsequent transmission of text.
The first digit of the response broadly indicates the success,
failure, or progress of the previous command (based generally on
[RFC640,RFC821]):
1yz - Positive Preliminary reply
2yz - Positive Completion reply
3yz - Positive Intermediate reply
4yz - Transient Negative Completion reply
5yz - Permanent Negative Completion reply
The next digit in the code indicates the response category:
x0z - Syntax
x1z - Information (e.g., help)
x2z - Connections
x3z - Authentication
x4z - Unspecified as yet
x5z - DICT System (These replies indicate the status of the
receiver DICT system vis-a-vis the requested transfer
or other DICT system action.)
x8z - Nonstandard (private implementation) extensions
The exact response codes that should be expected from each command
are detailed in the description of that command.
Certain status responses contain parameters such as numbers and
strings. The number and type of such parameters is fixed for each
response code to simplify interpretation of the response. Other
status responses do not require specific text identifiers. Parameter
Faith & Martin Informational [Page 5]
RFC 2229 A Dictionary Server Protocol October 1997
requirements are detailed in the description of relevant commands.
Except for specifically detailed parameters, the text following
response codes is server-dependent.
Parameters are separated from the numeric response code and from each
other by a single space. All numeric parameters are decimal, and may
have leading zeros. All string parameters MUST conform to the "atom"
or "dqstring" grammar productions.
If no parameters are present, and the server implementation provides
no implementation-specific text, then there MAY or MAY NOT be a space
after the response code.
Response codes not specified in this standard may be used for any
installation-specific additional commands also not specified.
These should be chosen to fit the pattern of x8z specified above.
The use of unspecified response codes for standard commands is
prohibited.
2.4.2. General Status Responses
In response to every command, the following general status responses
are possible:
500 Syntax error, command not recognized
501 Syntax error, illegal parameters
502 Command not implemented
503 Command parameter not implemented
420 Server temporarily unavailable
421 Server shutting down at operator request
2.4.3. Text Responses
Before text is sent a numeric status response line, using a 1yz code,
will be sent indicating text will follow. Text is sent as a series of
successive lines of textual matter, each terminated with a CRLF. A
single line containing only a period (decimal code 46, ".") is sent
to indicate the end of the text (i.e., the server will send a CRLF at
the end of the last line of text, a period, and another CRLF).
If a line of original text contained a period as the first character
of the line, that first period is doubled by the DICT server.
Therefore, the client must examine the first character of each line
received. Those that begin with two periods must have those two
periods collapsed into one period. Those that contain only a single
period followed by a CRLF indicate the end of the text response.
Faith & Martin Informational [Page 6]
RFC 2229 A Dictionary Server Protocol October 1997
If the OPTION MIME command has been given, all textual responses will
be prefaced by a MIME header [RFC2045] followed by a single blank
line (CRLF). See section 3.10.1 for more details on OPTION MIME.
Following a text response, a 2yz response code will be sent.
Text lines MUST NOT exceed 1024 characters in length, counting all
characters including spaces, separators, punctuation, the extra
initial period (if needed), and the trailing CRLF. Since UTF-8 may
encode a character using up to 6 octets, the text line input buffer
MUST be able to accept up to 6144 octets.
By default, the text of the definitions MUST be composed of
characters from the UCS character set [ISO10644] using the UTF-8
[RFC2044] encoding. The UTF-8 encoding has the advantage of
preserving the full range of 7-bit US ASCII [USASCII] values.
Clients and servers MUST support UTF-8, even if only in some minimal
fashion.
3. Command and Response Details
Below, each DICT command and appropriate responses are detailed.
Each command is shown in upper case for clarity, but the DICT server
is case-insensitive.
Except for the AUTH and SASLAUTH commands, every command described in
this section MUST be implemented by all DICT servers.
3.1. Initial Connection
When a client initially connects to a DICT server, a code 220 is sent
if the client's IP is allowed to connect:
220 text capabilities msg-id
The code 220 is a banner, usually containing host name and DICT
server version information.
The second-to-last sequence of characters in the banner is the
optional capabilities string, which will allow servers to declare
support for extensions to the DICT protocol. The capabilities string
is defined below:
capabilities = ["<" msg-atom *("." msg-atom) ">"]
msg-atom = 1*<any CHAR except SPACE, CTLs,
"<", ">", ".", and "\">
Faith & Martin Informational [Page 7]
RFC 2229 A Dictionary Server Protocol October 1997
Individual capabilities are described by a single msg-atom. For
example, the string <html.gzip> might be used to describe a server
that supports extensions which allow HTML or compressed output.
Capability names beginning with "x" or "X" are reserved for
experimental extensions, and SHOULD NOT be defined in any future DICT
protocol specification. Some of these capabilities may inform the
client that certain functionality is available or can be requested.
The following capabilities are currently defined:
mime The OPTION MIME command is supported
auth The AUTH command is supported
kerberos_v4 The SASL Kerberos version 4 mechanism is supported
gssapi The SASL GSSAPI [RFC2078] mechanism is supported
skey The SASL S/Key [RFC1760] mechanism is supported
external The SASL external mechanism is supported
The last sequence of characters in the banner is a msg-id, similar to
the format specified in [RFC822]. The simplified description is
given below:
msg-id = "<" spec ">" ; Unique message id
spec = local-part "@" domain
local-part = msg-atom *("." msg-atom)
domain = msg-atom *("." msg-atom)
Note that, in contrast to [RFC822], spaces and quoted pairs are not
allowed in the msg-id. This restriction makes the msg-id much easier
for the client to locate and parse but does not significantly
decrease any security benefits, since the msg-id may be arbitrarily
long (as bounded by the response length limits set forth elsewhere in
this document).
Note also that the open and close brackets are part of the msg-id and
should be included in the string that is used to compute the MD5
checksum.
This message id will be used by the client when formulating the
authentication string used in the AUTH command.
If the client's IP is not allowed to connect, then a code 530 is sent
instead:
530 Access denied
Transient failure responses are also possible:
420 Server temporarily unavailable
421 Server shutting down at operator request
Faith & Martin Informational [Page 8]
RFC 2229 A Dictionary Server Protocol October 1997
For example, response code 420 should be used if the server cannot
currently fork a server process (or cannot currently obtain other
resources required to proceed with a usable connection), but expects
to be able to fork or obtain these resources in the near future.
Response code 421 should be used when the server has been shut down
at operator request, or when conditions indicate that the ability to
service more requests in the near future will be impossible. This
may be used to allow a graceful operator-mediated temporary shutdown
of a server, or to indicate that a well known server has been
permanently removed from service (in which case, the text message
might provide more information).
3.2. The DEFINE Command
DEFINE database word
3.2.1. Description
This command will look up the specified word in the specified
database. All DICT servers MUST implement this command.
If the database name is specified with an exclamation point (decimal
code 33, "!"), then all of the databases will be searched until a
match is found, and all matches in that database will be displayed.
If the database name is specified with a star (decimal code 42, "*"),
then all of the matches in all available databases will be displayed.
In both of these special cases, the databases will be searched in the
same order as that printed by the "SHOW DB" command.
If the word was not found, then status code 552 is sent.
If the word was found, then status code 150 is sent, indicating that
one or more definitions follow.
For each definition, status code 151 is sent, followed by the textual
body of the definition. The first three space-delimited parameters
following status code 151 give the word retrieved, the name of the
database (which is the same as the first column of the SHOW DB
command), and a short description for the database (which is the same
as the second column of the SHOW DB command). The short name is
suitable for printing as:
From name:
before the definition is printed. This provides source information
for the user.
Faith & Martin Informational [Page 9]
RFC 2229 A Dictionary Server Protocol October 1997
The textual body of each definition is terminated with a CRLF period
CRLF sequence.
After all of the definitions have been sent, status code 250 is sent.
This command can provide optional timing information (which is server
dependent and is not intended to be parsable by the client). This
additional information is useful when debugging and tuning the
server.
3.2.2. Responses
550 Invalid database, use "SHOW DB" for list of databases
552 No match
150 n definitions retrieved - definitions follow
151 word database name - text follows
250 ok (optional timing information here)
Response codes 150 and 151 require special parameters as part of
their text. The client can use these parameters to display
information on the user's terminal.
For code 150, parameters 1 indicates the number of definitions
retrieved.
For code 151, parameter 1 is the word retrieved, parameter 2 is the
database name (the first name as shown by "SHOW DB") from which the
definition has been retrieved, and parameter 3 is the the short
database description (the second column of the "SHOW DB" command).
3.3. The MATCH Command
MATCH database strategy word
3.3.1. Description
This command searches an index for the dictionary, and reports words
which were found using a particular strategy. Not all strategies are
useful for all dictionaries, and some dictionaries may support
additional search strategies (e.g., reverse lookup). All DICT
servers MUST implement the MATCH command, and MUST support the
"exact" and "prefix" strategies. These are easy to implement and are
generally the most useful. Other strategies are server dependent.
The "exact" strategy matches a word exactly, although different
servers may treat non-alphanumeric data differently. We have found
that a case-insensitive comparison which ignores non-alphanumeric
Faith & Martin Informational [Page 10]
RFC 2229 A Dictionary Server Protocol October 1997
characters and which folds whitespace is useful for English-language
dictionaries. Other comparisons may be more appropriate for other
languages or when using extended character sets.
The "prefix" strategy is similar to "exact", except that it only
compares the first part of the word.
Different servers may implement these algorithms differently. The
requirement is that strategies with the names "exact" and "prefix"
exist so that a simple client can use them.
Other strategies that might be considered by a server implementor are
matches based on substring, suffix, regular expressions, soundex
[KNUTH73], and Levenshtein [PZ85] algorithms. These last two are
especially useful for correcting spelling errors. Other useful
strategies perform some sort of "reverse" lookup (i.e., by searching
definitions to find the word that the query suggests).
If the database name is specified with an exclamation point (decimal
code 33, "!"), then all of the databases will be searched until a
match is found, and all matches in that database will be displayed.
If the database name is specified with a star (decimal code 42, "*"),
then all of the matches in all available databases will be displayed.
In both of these special cases, the databases will be searched in the
same order as that printed by the "SHOW DB" command.
If the strategy is specified using a period (decimal code 46, "."),
then the word will be matched using a server-dependent default
strategy, which should be the best strategy available for interactive
spell checking. This is usually a derivative of the Levenshtein
algorithm [PZ85].
If no matches are found in any of the searched databases, then status
code 552 will be returned.
Otherwise, status code 152 will be returned followed by a list of
matched words, one per line, in the form:
database word
This makes the responses directly useful in a DEFINE command.
The textual body of the match list is terminated with a CRLF period
CRLF sequence.
Following the list, status code 250 is sent, which may include
server-specific timing and statistical information, as discussed in
the section on the DEFINE command.
Faith & Martin Informational [Page 11]
RFC 2229 A Dictionary Server Protocol October 1997
3.3.2. Responses
550 Invalid database, use "SHOW DB" for list of databases
551 Invalid strategy, use "SHOW STRAT" for a list of strategies
552 No match
152 n matches found - text follows
250 ok (optional timing information here)
Response code 152 requires a special parameter as part of its text.
Parameter 1 must be the number of matches retrieved.
3.4. A Note on Virtual Databases
The ability to search all of the provided databases using a single
command is given using the special "*" and "!" databases.
However, sometimes, a client may want to search over some but not all
of the databases that a particular server provides. One alternative
is for the client to use the SHOW DB command to obtain a list of
databases and descriptions, and then (perhaps with the help of a
human), select a subset of these databases for an interactive search.
Once this selection has been done once, the results can be saved, for
example, in a client configuration file.
Another alternative is for the server to provide "virtual" databases
which merge several of the regular databases into one. For example,
a virtual database may be provided which includes all of the
translating dictionaries, but which does not include regular
dictionaries or thesauri. The special "*" and "!" databases can be
considered as names of virtual databases which provide access to all
of the databases. If a server implements virtual databases, then the
special "*" and "!" databases should probably exclude other virtual
databases (since they merely provide information duplicated in other
databases). If virtual databases are supported, they should be
listed as a regular database with the SHOW DB command (although,
since "*" and "!" are required, they need not be listed).
Virtual databases are an implementation-specific detail which has
absolutely no impact on the DICT protocol. The DICT protocol views
virtual and non-virtual databases the same way.
We mention virtual databases here, however, because they solve a
problem of database selection which could also have been solved by
changes in the protocol. For example, each dictionary could be
assigned attributes, and the protocol could be extended to specify
searches over databases with certain attributes. However, this
needlessly complicates the parsing and analysis that must be
performed by the implementation. Further, unless the classification
Faith & Martin Informational [Page 12]
RFC 2229 A Dictionary Server Protocol October 1997
system is extremely general, there is a risk that it would restrict
the types of databases that can be used with the DICT protocol
(although the protocol has been designed with human-language
databases in mind, it is applicable to any read-only database
application, especially those with a single semi-unique alphanumeric
key and textual data).
3.5. The SHOW Command
3.5.1. SHOW DB
SHOW DB
SHOW DATABASES
3.5.1.1. Description
Displays the list of currently accessible databases, one per line, in
the form:
database description
The textual body of the database list is terminated with a CRLF
period CRLF sequence. All DICT servers MUST implement this command.
Note that some databases may be restricted due to client domain or
lack of user authentication (see the AUTH and SASLAUTH commands in
sections 3.11 and 3.12). Information about these databases is not
available until authentication is performed. Until that time, the
client will interact with the server as if the additional databases
did not exist.
3.5.1.2. Responses
110 n databases present - text follows
554 No databases present
Response code 110 requires a special parameter. Parameter 1
must be the number of databases available to the user.
3.5.2. SHOW STRAT
SHOW STRAT
SHOW STRATEGIES
Faith & Martin Informational [Page 13]
RFC 2229 A Dictionary Server Protocol October 1997
3.5.2.1. Description
Displays the list of currently supported search strategies, one per
line, in the form:
strategy description
The textual body of the strategy list is terminated with a CRLF
period CRLF sequence. All DICT servers MUST implement this command.
3.5.2.2. Responses
111 n strategies available - text follows
555 No strategies available
Response code 111 requires a special parameter. Parameter 1 must be
the number of strategies available.
3.5.3. SHOW INFO
SHOW INFO database
3.5.3.1. Description
Displays the source, copyright, and licensing information about the
specified database. The information is free-form text and is
suitable for display to the user in the same manner as a definition.
The textual body of the information is terminated with a CRLF period
CRLF sequence. All DICT servers MUST implement this command.
3.5.3.2. Responses
550 Invalid database, use "SHOW DB" for list of databases
112 database information follows
These response codes require no special parameters.
3.5.4. SHOW SERVER
SHOW SERVER
3.5.4.1. Description
Displays local server information written by the local administrator.
This could include information about local databases or strategies,
or administrative information such as who to contact for access to
databases requiring authentication. All DICT servers MUST implement
this command.
Faith & Martin Informational [Page 14]
RFC 2229 A Dictionary Server Protocol October 1997
3.5.4.2. Responses
114 server information follows
This response code requires no special parameters.
3.6. The CLIENT Command
CLIENT text
3.6.1. Description
This command allows the client to provide information about itself
for possible logging and statistical purposes. All clients SHOULD
send this command after connecting to the server. All DICT servers
MUST implement this command (note, though, that the server doesn't
have to do anything with the information provided by the client).
3.6.2. Responses
250 ok (optional timing information here)
This response code requires no special parameters.
3.7. The STATUS Command
STATUS
3.7.1. Description
Display some server-specific timing or debugging information. This
information may be useful in debugging or tuning a DICT server. All
DICT servers MUST implement this command (note, though, that the text
part of the response is not specified and may be omitted).
3.7.2. Responses
210 (optional timing and statistical information here)
This response code requires no special parameters.
3.8. The HELP Command
HELP
Faith & Martin Informational [Page 15]
RFC 2229 A Dictionary Server Protocol October 1997
3.8.1. Description
Provides a short summary of commands that are understood by this
implementation of the DICT server. The help text will be presented
as a textual response, terminated by a single period on a line by
itself. All DICT servers MUST implement this command.
3.8.2. Responses
113 help text follows
This response code requires no special parameters.
3.9. The QUIT Command
QUIT
3.9.1. Description
This command is used by the client to cleanly exit the server. All
DICT servers MUST implement this command.
3.9.2. Responses
221 Closing Connection
This response code requires no special parameters.
3.10. The OPTION Command
3.10.1. OPTION MIME
OPTION MIME
3.10.1.1. Description
Requests that all text responses be prefaced by a MIME header
[RFC2045] followed by a single blank line (CRLF).
If a client requests this option, then the client MUST be able to
parse Content-Type and Content-transfer-encoding headers, and MUST be
able to ignore textual responses which have an unsupported content or
encoding. A client MUST support the UTF-8 encoding [RFC2044], which
minimally means that the client MUST recognize UTF-8 multi-octet
encodings and convert these into some symbol that can be printed by
the client.
Faith & Martin Informational [Page 16]
RFC 2229 A Dictionary Server Protocol October 1997
If a client requests this option, then the server will provide a MIME
header. If the header is empty, the text response will start with a
single blank line (CRLF), in which case a client MUST interpret this
as a default header. The default header for SASL authentication is:
Content-type: application/octet-stream
Content-transfer-encoding: base64
The default header for all other textual responses is:
Content-type: text/plain; charset=utf-8
Content-transfer-encoding: 8bit
If OPTION MIME is not specified by the client, then the server may
restrict the information content provided to the client. For
example, a definition may be accompanied by an image and an audio
clip, but the server cannot transmit this information unless the
client is able to parse MIME format headers.
Note that, because of the line length restrictions and end-of-
response semantics, the "binary" content-transfer-encoding MUST NOT
be used. In the future, extensions to the protocol may be provided
which allow a client to request binary encodings, but the default
SHOULD always be that the client can look for a "CRLF . CRLF"
sequence to locate the end of the current text response. This allows
clients to easily skip over text responses which have unsupported
types or encodings.
In the future, after significant experience with large databases in
various languages has been gained, and after evaluating the need for
specifying character sets and other encodings (e.g., compressed or
BASE64 encoding), standard extensions to this protocol should be
proposed which allow the client to request certain content types or
encodings. Care should be taken that these extensions do not require
a handshake which defeats pipelining. In the mean time, private
extensions should be used to explore the parameter space to determine
how best to implement these extensions.
OPTION MIME is a REQUIRED server capability, all DICT servers MUST
implement this command.
3.10.1.2. Responses
250 ok (optional timing information here)
Note that some older server implementations, completed before this
document was finalized, will return a status code 500 if this command
is not implemented. Clients SHOULD be able to accept this behavior,
Faith & Martin Informational [Page 17]
RFC 2229 A Dictionary Server Protocol October 1997
making default assumptions. Clients may also examine the
capabilities string in the status code 220 header to determine if a
server supports this capability.
3.11. The AUTH Command
AUTH username authentication-string
3.11.1. Description
The client can authenticate itself to the server using a username and
password. The authentication-string will be computed as in the APOP
protocol discussed in [RFC1939]. Briefly, the authentication-string
is the MD5 checksum of the concatenation of the msg-id (obtained from
the initial banner) and the "shared secret" that is stored in the
server and client configuration files. Since the user does not have
to type this shared secret when accessing the server, the shared
secret can be an arbitrarily long passphrase. Because of the
computational ease of computing the MD5 checksum, the shared secret
should be significantly longer than a usual password.
Authentication may make more dictionary databases available for the
current session. For example, there may be some publicly
distributable databases available to all users, and other private
databases available only to authenticated users. Or, a server may
require authentication from all users to minimize resource
utilization on the server machine.
Authentication is an optional server capability. The AUTH command
MAY be implemented by a DICT server.
3.11.2. Responses
230 Authentication successful
531 Access denied, use "SHOW INFO" for server information
These response codes require no special parameters.
3.12. The SASLAUTH Command
SASLAUTH mechanism initial-response
SASLRESP response