* Replaced all "Citadel/UX" references with "Citadel"
[citadel] / citadel / techdoc / session.txt
1                 SESSION LAYER PROTOCOL FOR THE CITADEL SYSTEM
2          (c) 1995-2004 by Art Cancro et. al.    All Rights Reserved
3
4
5  INTRODUCTION
6  ------------
7
8  This is an attempt to document the session layer protocol used by the
9 Citadel system, beginning with version 4.00, which is the first version
10 to implement a client/server paradigm.  It is intended as a resource for
11 programmers who intend to develop their own Citadel clients, but it may have
12 other uses as well.
13
14
15  IMPORTANT NOTE TO DEVELOPERS!
16  -----------------------------
17
18  Anyone who wants to add commands or other functionality to this protocol,
19 *please* get in touch so that these efforts can be coordinated.  New
20 commands added by other developers can be added to this document, so we
21 don't end up with new server commands from multiple developers which have
22 the same name but perform different functions.  If you don't coordinate new
23 developments ahead of time, please at least send in an e-mail documenting
24 what you did, so that your new commands can be added to this document.
25
26  The coordinator of the Citadel project is Art Cancro
27 <ajc@uncensored.citadel.org>.
28
29
30  CONNECTING TO A SERVER
31  ----------------------
32
33  The protocols used below the session layer are beyond the scope of this
34 document, but we will briefly cover the methodology employed by Citadel.
35
36  Citadel offers Citadel BBS service using TCP/IP.  It does so via a
37 multithreaded server listening on a TCP port.  Local connections may also
38 be made using the same protocol using Unix domain sockets.
39
40  The port number officially assigned to Citadel by the IANA is 504/tcp.  Since
41 our session layer assumes a clean, reliable, sequenced connection, the use
42 of UDP would render the server unstable and unusable, so we stick with TCP.
43
44
45  GENERAL INFORMATION ABOUT THE SERVER
46  ------------------------------------
47
48  The server is connection-oriented and stateful: each client requires its own
49 connection to a server process, and when a command is sent, the client must
50 read the response, and then transfer data or change modes if necessary.
51
52  The session layer is very much like other Internet protocols such as SMTP
53 or NNTP.  A client program sends one-line commands to the server, and the
54 server responds with a three-digit numeric result code followed by a message
55 describing what happened.  This cycle continues until the end of the
56 session.
57
58  Unlike protocols such as FTP, all data transfers occur in-band.  This means
59 that the same connection that is used for exchange of client/server
60 messages, will also be used to transfer data back and forth.  (FTP opens a
61 separate connection for data transfers.)  This keeps protocol administration
62 straightforward, as it can traverse firewalls without any special protocol
63 support on the firewall except for opening the port number.
64
65
66  RESULT CODES
67  ------------
68
69  The server will respond to all commands with a 3-digit result code, which
70 will be the first three characters on the line.  The rest of the line may
71 contain a human-readable string explaining what happened.  (Some client
72 software will display some of these strings to the user.)
73
74  The first digit is the most important.  The following codes are defined for
75 this position: ERROR, OK, MORE_DATA, LISTING_FOLLOWS, and SEND_LISTING.
76
77  The second and third digits may provide a reason as to why a command
78 succeeded or failed.  See ipcdef.h for the available codes.
79
80  ERROR means the command did not complete.
81  OK means the command executed successfully.
82  MORE_DATA means the command executed partially.  Usually this means that
83 another command needs to be executed to complete the operation.  For example,
84 sending the USER command to log in a user usually results in a MORE_DATA
85 result code, because the client needs to execute a PASS command to send the
86 password and complete the login.
87  LISTING_FOLLOWS means that after the server response, the server will
88 output a listing of some sort.  The client *must* read the listing, whether
89 it wants to or not.  The end of the listing is signified by the string
90 "000" on a line by itself.
91  SEND_LISTING is the opposite of LISTING_FOLLOWS.  It means that the client
92 should begin sending a listing of some sort.  The client *must* send something,
93 even if it is an empty listing.  Again, the listing ends with "000" on a line
94 by itself.
95  BINARY_FOLLOWS and SEND_BINARY mean that the client must immediately send
96 or receive a block of binary data.  The first parameter will always be the
97 number of bytes.
98  ASYNC_MESSAGE_FOLLOWS means that an asynchronous, or unsolicited, message
99 follows.  The next line will be one of the above codes, and if a data transfer
100 is involved it must be handled immediately.  Note that the client will not
101 receive this type of response unless it indicates to the server that it is
102 capable of handling them; see the writeup of the ASYN command later in this
103 document.
104
105  PARAMETERIZATION
106  ----------------
107
108  Zero or more parameters may be passed to a command.  When more than one
109 parameter is passed to a command, they should be separated by the "|"
110 symbol like this:
111   SETU 80|24|260
112  In this example, we're using the "SETU" command and passing three
113 parameters: 80, 24, and 260.
114
115  When the server spits out data that has parameters, if more than one
116 parameter is returned, they will be separated by the "|" symbol like
117 this:
118   200 80|24|260
119  In this example, we just executed the "GETU" command, and it returned us
120 an OK result code (the '2' in the 200) and three parameters: 80, 24, and
121 260.
122
123
124  COMMANDS
125  --------
126
127  This is a listing of all the commands that a Citadel server can execute.
128
129
130  NOOP   (NO OPeration)
131
132  This command does nothing.  It takes no arguments and always returns
133 OK.  It is intended primarily for testing and development, but it might also
134 be used as a "keep alive" command to prevent the server from timing out, if
135 it's running over a transport that needs this type of thing.
136
137
138  ECHO   (ECHO something)
139
140  This command also does nothing.  It simply returns OK followed by whatever
141 its arguments are.
142
143
144  QUIT   (QUIT)
145
146  Terminate the server connection.  This command takes no arguments.  It
147 returns OK and closes the connection immediately.
148
149
150  LOUT   (LogOUT)
151
152  Log out the user without closing the server connection.  It always returns
153 OK even if no user is logged in.
154
155
156  USER   (send USER name)
157
158  The first step in logging in a user.  This command takes one argument: the
159 name of the user to be logged in.  If the user exists, a MORE_DATA return
160 code will be sent, which means the client should execute PASS as the next
161 command.  If the user does not exist, ERROR + NO_SUCH_USER is returned.
162
163
164  PASS   (send PASSword)
165
166  The second step in logging in a user.  This command takes one argument: the
167 password for the user we are attempting to log in.  If the password doesn't
168 match the correct password for the user we specified for the USER command,
169 ERROR + PASSWORD_REQUIRED is returned.  If a USER command has not been
170 executed yet, ERROR + USERNAME_REQUIRED is returned.  If a user is already
171 logged in, ERROR + ALREADY_LOGGED_IN is returned.  If the password is
172 correct, OK is returned and the user is now logged in... and most of the
173 other server commands can now be executed.  Along with OK, the following
174 parameters are returned:
175
176  0 - The user's name (in case the client wants the right upper/lower casing)
177  1 - The user's current access level
178  2 - Times called
179  3 - Messages posted
180  4 - Various flags (see citadel.h)
181  5 - User number
182  6 - Time of last call (UNIX timestamp)
183
184
185  NEWU   (create NEW User account)
186
187  This command creates a new user account AND LOGS IT IN.  The argument to
188 this command will be the name of the account.  No case conversion is done
189 on the name.  Note that the new account is installed with a default
190 configuration, and no password, so the client should immediately prompt the
191 user for a password and install it with the SETP command as soon as this
192 command completes.  This command returns OK if the account was created and
193 logged in, ERROR + ALREADY_EXISTS if another user already exists with this
194 name, ERROR + NOT_HERE if self-service account creation is disabled,
195 ERROR + MAX_SESSIONS_EXCEEDED if too many users are logged in, ERROR +
196 USERNAME_REQUIRED if a username was not provided, or ERROR + ILELGAL_VALUE
197 if the username provided is invalid.  If OK, it will also return the same
198 parameters that PASS returns.
199
200  Please note that the NEWU command should only be used for self-service
201 user account creation.  For administratively creating user accounts, please
202 use the CREU command.
203
204
205  SETP   (SET new Password)
206
207  This command sets a new password for the currently logged in user.  The
208 argument to this command will be the new password.  The command always
209 returns OK, unless the client is not logged in, in which case it will return
210 ERROR + NOT_LOGGED_IN, or if the user is an auto-login user, in which case
211 it will return ERROR + NOT_HERE.
212
213
214  CREU   (CREate new User account)
215
216  This command creates a new user account AND DOES NOT LOG IT IN.  The first
217 argument to this command will be the name of the account.  No case conversion
218 is done on the name.  Note that the new account is installed with a default
219 configuration, and no password.  The second argument is optional, and will be
220 an initial password for the user.  This command returns OK if the account was
221 created, ERROR + HIGHER_ACCESS_REQUIRED if the user is not an Aide, ERROR +
222 USERNAME_REQUIRED if no username was specified, or ERROR + ALREADY_EXISTS if
223 another user already exists with this name.
224
225  Please note that CREU is intended to be used for activities in which a
226 system administrator is creating user accounts.  For self-service user
227 account creation, use the NEWU command.
228
229
230  LKRN   (List Known Rooms with New messages)
231
232  List known rooms with new messages.  If the client is not logged in, ERROR +
233 NOT_LOGGED_IN is returned.  Otherwise, LISTING_FOLLOWS is returned, followed
234 by the room listing.  Each line in the listing contains the full name of a
235 room, followed by the '|' symbol, and then a number that may contain the
236 following bits:
237
238 #define QR_PERMANENT    1               /* Room does not purge              */
239 #define QR_PRIVATE      4               /* Set for any type of private room */
240 #define QR_PASSWORDED   8               /* Set if there's a password too    */
241 #define QR_GUESSNAME    16              /* Set if it's a guessname room     */
242 #define QR_DIRECTORY    32              /* Directory room                   */
243 #define QR_UPLOAD       64              /* Allowed to upload                */
244 #define QR_DOWNLOAD     128             /* Allowed to download              */
245 #define QR_VISDIR       256             /* Visible directory                */
246 #define QR_ANONONLY     512             /* Anonymous-Only room              */
247 #define QR_ANON2        1024            /* Anonymous-Option room            */
248 #define QR_NETWORK      2048            /* Shared network room              */
249 #define QR_PREFONLY     4096            /* Preferred status needed to enter */
250 #define QR_READONLY     8192            /* Aide status required to post     */
251
252  Then it returns another '|' symbol, followed by a second set of bits comprised
253 of the following:
254
255 #define QR2_SYSTEM      1               /* System room; hide by default     */
256 #define QR2_SELFLIST    2               /* Self-service mailing list mgmt   */
257
258  Other bits may be defined in the future.  The listing terminates, as with
259 all listings, with "000" on a line by itself.
260
261  Starting with version 4.01 and above, floors are supported.  The first
262 argument to LKRN should be the number of the floor to list rooms from.  Only
263 rooms from this floor will be listed.  If no arguments are passed to LKRN, or
264 if the floor number requested is (-1), rooms on all floors will be listed.
265
266  The third field displayed on each line is the number of the floor the room
267 is on.  The LFLR command should be used to associate floor numbers with
268 floor names.
269
270  The fourth field displayed on each line is a "room listing order."  Unless
271 there is a compelling reason not to, clients should sort any received room
272 listings by this value.
273  
274  The fifth field is a special bit bucket containing fields which pertain to
275 room access controls:
276
277 #define UA_KNOWN                2       /* Known room */
278 #define UA_GOTOALLOWED          4       /* Access will be granted to this room
279                                          * if the user calls it up by name */
280 #define UA_HASNEWMSGS           8       /* Unread messages exist in room */
281 #define UA_ZAPPED              16       /* Zapped from known rooms list */
282  
283  
284  
285  LKRO   (List Known Rooms with Old [no new] messages)
286
287  This follows the same usage and format as LKRN.
288
289
290  LZRM   (List Zapped RooMs)
291
292  This follows the same usage and format as LKRN and LKRO.
293
294
295  LKRA   (List All Known Rooms)
296
297  Same format.  Lists all known rooms, with or without new messages.
298
299
300  LRMS   (List all accessible RooMS)
301
302  Again, same format.  This command lists all accessible rooms, known and
303 forgotten, with and without new messages.  It does not, however, list
304 inaccessible private rooms.
305
306
307  LPRM   (List all Public RooMs)
308
309  Again, same format.  This command lists all public rooms, and nothing else.
310 Unlike the other list rooms commands, this one can be executed without logging
311 in.
312
313
314  GETU   (GET User configuration)
315
316  This command retrieves the screen dimensions and user options for the
317 currently logged in account.  ERROR + NOT_LOGGED_IN will be returned if no
318 user is logged in, of course.  Otherwise, OK will be returned, followed by
319 four parameters.  The first parameter is the user's screen width, the second
320 parameter is the user's screen height, and the third parameter is a bag of
321 bits with the following meanings:
322
323  #define US_LASTOLD     16              /* Print last old message with new  */
324  #define US_EXPERT      32              /* Experienced user                 */
325  #define US_UNLISTED    64              /* Unlisted userlog entry           */
326  #define US_NOPROMPT    128             /* Don't prompt after each message  */
327  #define US_DISAPPEAR   512             /* Use "disappearing msg prompts"   */
328  #define US_PAGINATOR   2048            /* Pause after each screen of text  */
329
330  There are other bits, too, but they can't be changed by the user (see below).
331
332
333  SETU   (SET User configuration)
334
335  This command does the opposite of SETU: it takes the screen dimensions and
336 user options (which were probably obtained with a GETU command, and perhaps
337 modified by the user) and writes them to the user account.  This command
338 should be passed three parameters: the screen width, the screen height, and
339 the option bits (see above).  It returns ERROR + NOT_LOGGED_IN if no user is
340 logged in, and ERROR + ILLEGAL_VALUE if the parameters are incorrect.
341
342  Note that there exist bits here which are not listed in this document.  Some
343 are flags that can only be set by Aides or the system administrator.  SETU
344 will ignore attempts to toggle these bits.  There also may be more user
345 settable bits added at a later date.  To maintain later downward compatibility,
346 the following procedure is suggested:
347
348  1. Execute GETU to read the current flags
349  2. Toggle the bits that we know we can toggle
350  3. Execute SETU to write the flags
351
352  If we are passed a bit whose meaning we don't know, it's best to leave it
353 alone, and pass it right back to the server.  That way we can use an old
354 client on a server that uses an unknown bit without accidentally clearing
355 it every time we set the user's configuration.
356
357
358  GOTO   (GOTO a room)
359
360  This command is used to goto a new room.  When the user first logs in (login
361 is completed after execution of the PASS command) this command is
362 automatically and silently executed to take the user to the first room in the
363 system (usually called the Lobby).
364
365  This command can be passed one or two parameters.  The first parameter is,
366 of course, the name of the room.  Although it is not case sensitive, the
367 full name of the room must be used.  Wildcard matching or unique string
368 matching of room names should be the responsibility of the client.
369
370  Note that the reserved room name "_BASEROOM_" can be passed to the server
371 to cause the goto command to take the user to the first room in the system,
372 traditionally known as the Lobby>.   As long as a user is logged in, a
373 GOTO command to _BASEROOM_ is guaranteed to succeed.  This is useful to
374 allow client software to return to the base room when it doesn't know
375 where else to go.
376
377  There are also two additional reserved room names:
378  "_MAIL_" translates to the system's designated room for e-mail messages.
379  "_BITBUCKET_" goes to whatever room has been chosen for messages
380 without a home.
381
382  The second (and optional) parameter is a password, if one is required for
383 access to the room.  This allows for all types of rooms to be accessed via
384 this command: for public rooms, invitation-only rooms to which the user
385 has access, and preferred users only rooms to which the user has access, the
386 room will appear in a room listing.  For guess-name rooms, this command
387 will work transparently, adding the room to the user's known room list when
388 it completes.  For passworded rooms, access will be denied if the password
389 is not supplied or is incorrect, or the command will complete successfully
390 if the password is correct.
391
392  The third (and also) optional parameter is a "transient" flag.  Normally,
393 when a user enters a private and/or zapped room, the room is added to the
394 user's known rooms list.  If the transient flag is set to non-zero, this is
395 called a "transient goto" which causes the user to enter the room without
396 adding the room to the known rooms list.
397
398  The possible result codes are:
399
400  OK    - The command completed successfully.  User is now in the room.
401          (See the list of returned parameters below)
402
403  ERROR - The command did not complete successfully.  Check the second and
404 third positions of the result code to find out what happened:
405
406    NOT_LOGGED_IN     -  Of course you can't go there.  You didn't log in.
407    PASSWORD_REQUIRED -  Either a password was not supplied, or the supplied
408 password was incorrect.
409    ROOM_NOT_FOUND    -  The requested room does not exist.
410
411  The typical procedure for entering a passworded room would be:
412
413  1. Execute a GOTO command without supplying any password.
414  2. ERROR + PASSWORD_REQUIRED will be returned.  The client now knows that
415 the room is passworded, and prompts the user for a password.
416  3. Execute a GOTO command, supplying both the room name and the password.
417  4. If OK is returned, the command is complete.  If, however,
418 ERROR + PASSWORD_REQUIRED is still returned, tell the user that the supplied
419 password was incorrect.  The user remains in the room he/she was previously
420 in.
421
422  When the command succeeds, these parameters are returned:
423    0. The name of the room
424    1. Number of unread messages in this room
425    2. Total number of messages in this room
426    3. Info flag: set to nonzero if the user needs to read this room's info
427       file (see RINF command below)
428    4. Various flags associated with this room.  (See LKRN cmd above)
429    5. The highest message number present in this room
430    6. The highest message number the user has read in this room
431    7. Boolean flag: 1 if this is a Mail> room, 0 otherwise.
432    8. Aide flag: 1 if the user is either the Room Aide for this room, *or* is
433 a regular Aide (this makes access checks easy).
434    9. The number of new Mail messages the user has (useful for alerting the
435 user to the arrival of new mail during a session)
436   10. The floor number this room resides on
437   11. The *current* "view" for this room (see views.txt for more info)
438   12. The *default* "view" for this room
439  
440  The default view gives the client a hint as to what views the user should
441 be allowed to select.  For example, it would be confusing to allow messages
442 in a room intended for calendar items.  The server does not enforce these
443 restrictions, though.
444
445
446  MSGS   (get pointers to MeSsaGeS in this room)
447
448  This command obtains a listing of all the messages in the current room
449 which the client may request.  This command may be passed a single parameter:
450 either "all", "old", or "new" to request all messages, only old messages, or
451 new messages.  Or it may be passed two parameters: "last" plus a number, in
452 which case that many message pointers will be returned, or "first" plus a
453 number, for the corresponding effect.  If no parameters are specified, "all"
454 is assumed.
455
456  In Citadel 5.00 and above, the client may also specify "gt" plus a number,
457 to list all messages in the current room with a message number greater than
458 the one specified.
459
460  The third argument, valid only in Citadel 5.60 and above, may be either
461 0 or 1.  If it is 1, this command behaves differently: before a listing is
462 returned, the client must transmit a list of fields to search for.  The field
463 headers are listed below in the writeup for the "MSG0" command.
464
465  This command can return three possible results.  ERROR + NOT_LOGGED_IN will
466 be returned if no user is currently logged in.  Otherwise, LISTING_FOLLOWS
467 will be returned, and the listing will consist of zero or more message
468 numbers, one per line.  The listing ends, as always, with the string "000"
469 alone on a line by itself.  The listed message numbers can be used to request
470 messages from the system.  If "search mode" is being used, the server will
471 return START_CHAT_MODE, and the client is expected to transmit the search
472 criteria, and then read the message list.
473
474  Since this is somewhat complex, here are some examples:
475
476  Example 1: Read all new messages
477
478  Client:   MSGS NEW
479  Server:   100 Message list...
480            523218
481            523293
482            523295
483            000
484
485  Example 2: Read the last five messages
486
487  Client:   MSGS LAST|5
488  Server:   100 Message list...
489            523190
490            523211
491            523218
492            523293
493            523295
494            000
495
496  Example 3: Read all messages written by "IGnatius T Foobar"
497
498  Client:   MSGS ALL|0|1
499  Server:   800 Send template then receive message list
500  Client:   from|IGnatius T Foobar
501            000
502  Server:   518604
503            519366
504            519801
505            520201
506            520268
507            520805
508            520852
509            521579
510            521720
511            522571
512            000
513
514  Note that in "search mode" the client may specify any number of search
515 criteria.  These criteria are applied with an AND logic.
516
517
518  MSG0   (read MeSsaGe, mode 0)
519
520  This is a command used to read the text of a message.  "Mode 0" implies that
521 other MSG commands (MSG1, MSG2, etc.) will probably be added later on to read
522 messages in more robust formats.  This command should be passed two arguments.
523 The first is the message number of the message being requested.  The second
524 argument specifies whether the client wants headers and/or message body:
525  0 = Headers and body
526  1 = Headers only
527  2 = Body only
528  3 = Headers only, with MIME information suppressed (this runs faster)
529
530  If the request is denied, ERROR + NOT_LOGGED_IN or ERROR + MESSAGE_NOT_FOUND
531 will be returned.  Otherwise, LISTING_FOLLOWS will be returned, followed by
532 the contents of the message.  The following fields may be sent:
533
534  type=   Formatting type.  The currently defined types are:
535   0 = "traditional" Citadel formatting.  This means that newlines should be
536 treated as spaces UNLESS the first character on the next line is a space.  In
537 other words, only indented lines should generate a newline on the user's screen
538 when the message is being displayed.  This allows a message to be formatted to
539 the reader's screen width.  It also allows the use of proportional fonts.
540   1 = a simple fixed-format message.  The message should be displayed to
541 the user's screen as is, preferably in a fixed-width font that will fit 80
542 columns on a screen.
543   4 = MIME format message.  The message text is expected to contain a header
544 with the "Content-type:" directive (and possibly others).
545
546  msgn=   The message ID of this message on the system it originated on.
547  path=   An e-mailable path back to the user who wrote the message.
548
549  time=   The date and time of the message, in Unix format (the number of
550 seconds since midnight on January 1, 1970, GMT).
551
552  from=   The name of the author of the message.
553  rcpt=   If the message is a private e-mail, this is the recipient.
554  room=   The name of the room the message originated in.
555  node=   The short node name of the system this message originated on.
556  hnod=   The long node name of the system this message originated on.
557  zaps=   The id/node of a message which this one zaps (supersedes).
558
559  part=   Information about a MIME part embedded in this message.
560  pref=   Information about a multipart MIME prefix such as "multipart/mixed"
561          or "multipart/alternative".  This will be output immediately prior
562          to the various "part=" lines which make up the multipart section.
563  suff=   Information about a multipart MIME suffix.  This will be output
564          immediately following the various "part=" lines which make up the
565          multipart section.
566
567  text    Note that there is no "=" after the word "text".  This string
568 signifies that the message text begins on the next line.
569
570
571  WHOK   (WHO Knows room)
572
573  This command is available only to Aides.  ERROR + HIGHER_ACCESS_REQUIRED 
574 will be returned if the user is not an Aide.  Otherwise, it returns
575 LISTING_FOLLOWS and then lists, one user per line, every user who has
576 access to the current room.
577
578
579  INFO   (get server INFO)
580
581  This command will *always* return LISTING_FOLLOWS and then print out a
582 listing of zero or more strings.  Client software should be written to expect
583 anywhere from a null listing to an infinite number of lines, to allow later
584 backward compatibility.  The current implementation defines the following
585 parts of the listing:
586
587  Line 1  - Your unique session ID on the server
588  Line 2  - The node name of the server BBS
589  Line 3  - Human-readable node name of the server BBS
590  Line 4  - The fully-qualified domain name (FQDN) of the server
591  Line 5  - The name of the server software, i.e. "Citadel 4.00"
592  Line 6  - (The revision level of the server code) * 100
593  Line 7  - The geographical location of the BBS (city and state if in the US)
594  Line 8  - The name of the system administrator
595  Line 9  - A number identifying the server type (see below)
596  Line 10 - The text of the system's paginator prompt
597  Line 11 - Floor Flag.  1 if the system supports floors, 0 otherwise.
598  Line 12 - Paging level.  0 if the system only supports inline paging,
599            1 if the system supports "extended" paging (check-only and
600            multiline modes).  See the SEXP command for further information.
601  Line 13 - The "nonce" for this session, for support of APOP-style
602            authentication.  If this field is present, clients may authenticate
603            in this manner.
604  Line 14 - Set to nonzero if this server supports the QNOP command.
605  Line 15 - Set to nonzero if this server is capable of connecting to a
606            directory service using LDAP.
607
608  *** NOTE! ***   The "server type" code is intended to promote global
609 compatibility in a scenario in which developers have added proprietary
610 features to their servers or clients.  We are attempting to avoid a future
611 situation in which users need to keep different client software around for
612 each BBS they use.  *Please*, if you are a developer and plan to add
613 proprietary features:
614
615  -> Your client programs should still be able to utilize servers other than
616 your own.
617  -> Clients other than your own should still be able to utilize your server,
618 even if your proprietary extensions aren't supported.
619  -> Please contact Art Cancro <ajc@uncensored.citadel.org> and obtain a unique
620 server type code, which can be assigned to your server program.
621  -> If you document what you did in detail, perhaps it can be added to a
622 future release of the Citadel program, so everyone can enjoy it.  Better
623 yet, just work with the Citadel development team on the main source tree.
624
625  If everyone follows this scheme, we can avoid a chaotic situation with lots
626 of confusion about which client program works with which server, etc.  Client
627 software can simply check the server type (and perhaps the revision level)
628 to determine ahead of time what commands may be utilized.
629
630  Please refer to "developers.txt" for information on what codes belong to whom.
631
632
633
634  RDIR   (Read room DIRectory)
635
636  Use this command to read the directory of a directory room.  ERROR + NOT_HERE
637 will be returned if the room has no directory, ERROR + HIGHER_ACCESS_REQUIRED
638 will be returned if the room's directory is not visible and the user does not
639 have Aide or Room Aide privileges, ERROR + NOT_LOGGED_IN will be returned if
640 the user is not logged in; otherwise LISTING_FOLLOWS will be returned,
641 followed by the room's directory.  Each line of the directory listing will
642 contain three fields: a filename, the length of the file, and a description.
643
644  The server message contained on the same line with LISTING_FOLLOWS will
645 contain the name of the system and the name of the directory, such as:
646
647   uncensored.citadel.org|/usr/bbs/files/my_room_directory
648
649
650  SLRP   (Set Last-message-Read Pointer)
651
652  This command marks all messages in the current room as read (seen) up to and
653 including the specified number.  Its sole parameter is the number of the last
654 message that has been read.  This allows the pointer to be set at any
655 arbitrary point in the room.  Optionally, the parameter "highest" may be used
656 instead of a message number, to set the pointer to the number of the highest
657 message in the room, effectively marking all messages in the room as having
658 been read (ala the Citadel <G>oto command).
659
660  The command will return OK if the pointer was set, or ERROR + NOT_LOGGED_IN
661 if the user is not logged in.  If OK is returned, it will be followed by a
662 single argument containing the message number the last-read-pointer was set to.
663
664
665  INVT   (INViTe a user to a room)
666
667  This command may only be executed by Aides, or by the room aide for the
668 current room.  It is used primarily to add users to invitation-only rooms,
669 but it may also be used in other types of private rooms as well.  Its sole
670 parameter is the name of the user to invite.
671
672  The command will return OK if the operation succeeded.  ERROR + NO_SUCH_USER
673 will be returned if the user does not exist, ERROR + HIGHER_ACCESS_REQUIRED
674 will be returned if the operation would have been possible if the user had
675 higher access, and ERROR + NOT_HERE may be returned if the room is not a
676 private room.
677
678
679  KICK   (KICK a user out of a room)
680
681  This is the opposite of INVT: it is used to kick a user out of a private
682 room.  It can also be used to kick a user out of a public room, but the
683 effect will only be the same as if the user <Z>apped the room - a non-stupid
684 user can simply un-zap the room to get back in.
685
686
687  GETR   (GET Room attributes)
688
689  This command is used for editing the various attributes associated with a
690 room.  A typical "edit room" command would work like this:
691  1. Use the GETR command to get the current attributes
692  2. Change some of them around
693  3. Use SETR (see below) to save the changes
694  4. Possibly also change the room aide using the GETA and SETA commands
695
696  GETR takes no arguments.  It will only return OK if the SETR command will
697 also return OK.  This allows client software to tell the user that he/she
698 can't edit the room *before* going through the trouble of actually doing the
699 editing.  Possible return codes are:
700
701  ERROR+NOT_LOGGED_IN          - No user is logged in.
702  ERROR+HIGHER_ACCESS_REQUIRED - Not enough access.  Typically, only aides
703 and the room aide associated with the current room, can access this command.
704  OK                           - Command succeeded.  Parameters are returned.
705
706  If OK is returned, the following parameters will be returned as well:
707
708  0. The name of the room
709  1. The room's password (if it's a passworded room)
710  2. The name of the room's directory (if it's a directory room)
711  3. Various flags (bits) associated with the room (see LKRN cmd above)
712  4. The floor number on which the room resides
713  5. The room listing order
714  6. The default view for the room (see views.txt)
715  7. A second set of flags (bits) associated with the room
716
717
718  SETR   (SET Room attributes)
719
720  This command sets various attributes associated with the current room.  It
721 should be passed the following arguments:
722
723  0. The name of the room
724  1. The room's password (if it's a passworded room)
725  2. The name of the room's directory (if it's a directory room)
726  3. Various flags (bits) associated with the room (see LKRN cmd above)
727  4. "Bump" flag (see below)
728  5. The floor number on which the room should reside
729  6. The room listing order
730  7. The default view for the room (see views.txt)
731  8. A second set of flags (bits) associated with the room
732
733  *Important: You should always use GETR to retrieve the current attributes of
734 the room, then change what you want to change, and then use SETR to write it
735 all back.  This is particularly important with respect to the flags: if a
736 particular bit is set, and you don't know what it means, LEAVE IT ALONE and
737 only toggle the bits you want to toggle.  This will allow for upward
738 compatibility.
739
740  The _BASEROOM_, user's Mail> and Aide> rooms can only be partially edited.
741 Any changes which cannot be made will be silently ignored.
742
743  If the room is a private room, you have the option of causing all users who
744 currently have access, to forget the room.  If you want to do this, set the
745 "bump" flag to 1, otherwise set it to 0.
746
747
748  GETA
749
750  This command is used to get the name of the Room Aide for the current room.
751 It will return ERROR + NOT_LOGGED_IN if no user is logged in, or OK if the
752 command succeeded.  Along with OK there will be returned one parameter: the
753 name of the Room Aide.  A conforming server must guarantee that the user is
754 always in some room.
755
756
757  SETA
758
759  The opposite of GETA, used to set the Room Aide for the current room.  One
760 parameter should be passed, which is the name of the user who is to be the
761 new Room Aide.  Under Citadel, this command may only be executed by Aides
762 and by the *current* Room Aide for the room.  Return codes possible are:
763  ERROR + NOT_LOGGED_IN          (Not logged in.)
764  ERROR + HIGHER_ACCESS_REQUIRED (Higher access required.)
765  ERROR + NOT_HERE               (Room cannot be edited.)
766  OK                             (Command succeeded.)
767
768
769  ENT0   (ENTer message, mode 0)
770
771  This command is used to enter messages into the system.  It accepts four
772 arguments:
773
774   0  -  Post flag.  This should be set to 1 to post a message.  If it is
775 set to 0, the server only returns OK or ERROR (plus any flags describing
776 the error) without reading in a message.  Client software should, in fact,
777 perform this operation at the beginning of an "enter message" command
778 *before* starting up its editor, so the user does not end up typing a message
779 in vain that will not be permitted to be saved.  If it is set to 2, the
780 server will accept an "apparent" post name if the user is privileged enough.
781 This post name is arg 5.
782   1  -  Recipient.  This argument is utilized only for private mail messages.
783 It is ignored for public messages.  It contains, of course, the name of the
784 recipient of the message.
785   2  -  Anonymous flag.  This argument is ignored unless the room allows
786 anonymous messages.  In such rooms, this flag may be set to 1 to flag a
787 message as anonymous, otherwise 0 for a normal message.
788   3  -  Format type.  Any valid Citadel format type may be used (this will
789 typically be 0; see the MSG0 command above).
790   4  -  Subject.  If present, this argument will be used as the subject of
791 the message.
792   5  -  Post name.  When postflag is 2, this is the name you are posting as.
793 This is an Aide only command.
794
795  Possible result codes:
796   OK  -  The request is valid.  (Client did not set the "post" flag, so the
797 server will not read in message text.)   If the message is an e-mail with
798 a recipient, the text that follows the OK code will contain the exact name
799 to which mail is being sent.  The client can display this to the user.  The
800 implication here is that the name that the server returns will contain the
801 correct upper and lower case characters.  In addition, if the recipient is
802 having his/her mail forwarded, the forwarding address will be returned.
803   SEND_LISTING  -  The request is valid.  The client should now transmit
804 the text of the message (ending with a 000 on a line by itself, as usual).
805   ERROR + NOT_LOGGED_IN  -  Not logged in.
806   ERROR + HIGHER_ACCESS_REQUIRED  -  Higher access is required.  An
807 explanation follows, worded in a form that can be displayed to the user.
808   ERROR + NO_SUCH_USER  -  The specified recipient does not exist.
809
810
811  RINF   (read Room INFormation file)
812
813  Each room has associated with it a text file containing a description of
814 the room, perhaps containing its intended purpose or other important
815 information.  The info file for the Lobby> (the system's base room) is
816 often used as a repository for system bulletins and the like.
817
818  This command, which accepts no arguments, is simply used to read the info
819 file for the current room.  It will return LISTING_FOLLOWS followed by
820 the text of the message (always in format type 0) if the request can be
821 honored, or ERROR if no info file exists for the current room (which is
822 often the case).  Other error description codes may accompany this result.
823
824  When should this command be used?  This is, of course, up to the discretion
825 of client software authors, but in Citadel it is executed in two situations:
826 the first time the user ever enters a room; and whenever the contents of the
827 file change.  The latter can be determined from the result of a GOTO command,
828 which will tell the client whether the file needs to be read (see GOTO above).
829
830
831  DELE   (DELEte a message)
832
833  Delete a message from the current room.  The one argument that should be
834 passed to this command is the message number of the message to be deleted.
835 The return value will be OK if the message was deleted, or an ERROR code.
836 If the delete is successful, the message's reference count is decremented, and
837 if the reference count reaches zero, the message is removed from the message
838 base.
839
840
841  MOVE   (MOVE or copy a message to a different room)
842
843  Move or copy a message to a different room.  This command expects to be
844 passed three arguments:
845  0: the message number of the message to be moved or copied.
846  1: the name of the target room.
847  2: flag: 0 to move the message, 1 to copy it without deleting from the
848     source room.
849  
850  This command never creates or deletes copies of a message; it merely moves
851 around links.  When a message is moved, its reference count remains the same.
852 When a message is copied, its reference count is incremented.
853
854
855  KILL   (KILL current room)
856
857  This command deletes the current room.  It accepts a single argument, which
858 should be nonzero to actually delete the room, or zero to merely check
859 whether the room can be deleted.
860
861  Once the room is deleted, the current room is undefined.  It is suggested
862 that client software immediately GOTO another room (usually _BASEROOM_)
863 after this command completes.
864
865  Possible return codes:
866
867  OK  -  room has been deleted (or, if checking only, request is valid).
868  ERROR+NOT_LOGGED_IN  -  no user is logged in.
869  ERROR+HIGHER_ACCESS_REQUIRED  -  not enough access to delete rooms.
870  ERROR+NOT_HERE  -  this room can not be deleted.
871
872
873  CRE8   (CRE[ate] a new room)
874
875  This command is used to create a new room.  Like some of the other
876 commands, it provides a mechanism to first check to see if a room can be
877 created before actually executing the command.  CRE8 accepts the following
878 arguments:
879
880  0  -  Create flag.  Set this to 1 to actually create the room.  If it is
881 set to 0, the server merely checks that there is a free slot in which to
882 create a new room, and that the user has enough access to create a room.  It
883 returns OK if the client should go ahead and prompt the user for more info,
884 or ERROR or ERROR+HIGHER_ACCESS_REQUIRED if the command will not succeed.
885  1  -  Name for new room.
886  2  -  Access type for new room:
887        0  -  Public
888        1  -  Private; can be entered by guessing the room's name
889        2  -  Private; can be entered by knowing the name *and* password
890        3  -  Private; invitation only (sometimes called "exclusive")
891        4  -  Personal (mailbox for this user only)
892  3  -  Password for new room (if it is a type 2 room)
893  4  -  Floor number on which the room should reside (optional)
894  5  -  Set to 1 to avoid automatically gaining access to the created room.
895
896  If the create flag is set to 1, the room is created (unless something
897 went wrong and an ERROR return is sent), and the server returns OK, but
898 the session is **not** automatically sent to that room.  The client still
899 must perform a GOTO command to go to the new room.
900
901
902  FORG   (FORGet the current room)
903
904  This command is used to forget (zap) the current room.  For those not
905 familiar with Citadel, this terminology refers to removing the room from
906 a user's own known rooms list, *not* removing the room itself.  After a
907 room is forgotten, it no longer shows up in the user's known room list,
908 but it will exist in the user's forgotten room list, and will return to the
909 known room list if the user goes to the room (in Citadel, this is
910 accomplished by explicitly typing the room's name in a <.G>oto command).
911
912  The command takes no arguments.  If the command cannot execute for any
913 reason, ERROR will be returned.  ERROR+NOT_LOGGED_IN or ERROR+NOT_HERE may
914 be returned as they apply.
915
916  If the command succeeds, OK will be returned.  At this point, the current
917 room is **undefined**, and the client software is responsible for taking
918 the user to another room before executing any other room commands (usually
919 this will be _BASEROOM_ since it is always there).
920
921
922  MESG    (read system MESsaGe)
923
924  This command is used to display system messages and/or help files.  The
925 single argument it accepts is the name of the file to display.  IT IS CASE
926 SENSITIVE.  Citadel looks for these files first in the "messages"
927 subdirectory and then in the "help" subdirectory.
928
929  If the file is found, LISTING_FOLLOWS is returned, followed by a pathname
930 to the file being displayed.  Then the message is printed, in format type 0
931 (see MSG0 command for more information on this).  If the file is not found,
932 ERROR is returned.
933
934  There are some "well known" names of system messages which client software
935 may expect most servers to carry:
936
937  hello        -  Welcome message, to be displayed before the user logs in.
938  changepw     -  To be displayed whenever the user is prompted for a new
939                  password.  Warns about picking guessable passwords and such.
940  register     -  Should be displayed prior to the user entering registration.
941                  Warnings about not getting access if not registered, etc.
942  help         -  Main system help file.
943  goodbye      -  System logoff banner; display when user logs off.
944  roomaccess   -  Information about how public rooms and different types of
945                  private rooms function with regards to access.
946  unlisted     -  Tells users not to choose to be unlisted unless they're
947                  really paranoid, and warns that aides can still see
948                  unlisted userlog entries.
949
950  Citadel provides these for the Citadel Unix text client.  They are
951 probably not very useful for other clients:
952
953  mainmenu     -  Main menu (when in idiot mode).
954  aideopt      -  .A?
955  readopt      -  .R?
956  entopt       -  .E?
957  dotopt       -  .?
958  saveopt      -  Options to save a message, abort, etc.
959  entermsg     -  Displayed just before a message is entered, when in
960                  idiot mode.
961
962
963  GNUR   (Get Next Unvalidated User)
964
965  This command shows the name of a user that needs to be validated.  If there
966 are no unvalidated users, OK is returned.  Otherwise, MORE_DATA is returned
967 along with the name of the first unvalidated user the server finds.  All of
968 the usual ERROR codes may be returned as well (for example, if the user is
969 not an Aide and cannot validate users).
970
971  A typical "Validate New Users" command would keep executing this command,
972 and then validating each user it returns, until it returns OK when all new
973 users have been validated.
974
975
976  GREG   (Get REGistration for user)
977
978  This command retrieves the registration info for a user, whose name is the
979 command's sole argument.  All the usual error messages can be returned.  If
980 the command succeeds, LISTING_FOLLOWS is returned, followed by the user's name
981 (retrieved from the userlog, with the right upper and lower case etc.)  The
982 contents of the listing contains one field per line, followed by the usual
983 000 on the last line.
984
985  The following lines are defined.  Others WILL be added in the futre, so all
986 software should be written to read the lines it knows about and then ignore
987 all remaining lines:
988
989  Line 1:  User number
990  Line 2:  Password
991  Line 3:  Real name
992  Line 4:  Street address or PO Box
993  Line 5:  City/town/village/etc.
994  Line 6:  State/province/etc.
995  Line 7:  ZIP Code
996  Line 8:  Telephone number
997  Line 9:  Access level
998  Line 10: Internet e-mail address
999  Line 11: Country
1000
1001  Users without Aide privileges may retrieve their own registration using
1002 this command.  This can be accomplished either by passing the user's own
1003 name as the argument, or the string "_SELF_".  The command will always
1004 succeed when used in this manner, unless no user is logged in.
1005
1006
1007  VALI   (VALIdate user)
1008
1009  This command is used to validate users.  Obviously, it can only be executed
1010 by users with Aide level access.  It should be passed two parameters: the
1011 name of the user to validate, and the desired access level
1012
1013  If the command succeeds, OK is returned.  The user's access level is changed
1014 and the "need validation" bit is cleared.  If the command fails for any
1015 reason, ERROR, ERROR+NO_SUCH_USER, or ERROR+HIGHER_ACCESS_REQUIRED will be
1016 returned.
1017
1018
1019  EINF   (Enter INFo file for room)
1020
1021  Transmit the info file for the current room with this command.  EINF uses
1022 a boolean flag (1 or 0 as the first and only argument to the command) to
1023 determine whether the client actually wishes to transmit a new info file, or
1024 is merely checking to see if it has permission to do so.
1025
1026  If the command cannot succeed, it returns ERROR.
1027  If the client is only checking for permission, and permission will be
1028 granted, OK is returned.
1029  If the client wishes to transmit the new info file, SEND_LISTING is
1030 returned, and the client should transmit the text of the info file, ended
1031 by the usual 000 on a line by itself.
1032
1033
1034  LIST   (user LISTing)
1035
1036  This is a simple user listing.  It always succeeds, returning
1037 LISTING_FOLLOWS followed by zero or more user records, 000 terminated.  The
1038 fields on each line are as follows:
1039
1040  1. User name
1041  2. Access level
1042  3. User number
1043  4. Date/time of last login (Unix format)
1044  5. Times called
1045  6. Messages posted
1046  7. Password (listed only if the user requesting the list is an Aide)
1047
1048  Unlisted entries will also be listed to Aides logged into the server, but
1049 not to ordinary users.
1050
1051
1052  REGI   (send REGIstration)
1053
1054  Clients will use this command to transmit a user's registration info.  If
1055 no user is logged in, ERROR+NOT_LOGGED_IN is returned.  Otherwise,
1056 SEND_LISTING is returned, and the server will expect the following information
1057 (terminated by 000 on a line by itself):
1058
1059  Line 1:  Real name
1060  Line 2:  Street address or PO Box
1061  Line 3:  City/town/village/etc.
1062  Line 4:  State/province/etc.
1063  Line 5:  ZIP Code
1064  Line 6:  Telephone number
1065  Line 7:  e-mail address
1066  Line 8:  Country
1067
1068
1069  CHEK   (CHEcK various things)
1070
1071  When logging in, there are various things that need to be checked.   This
1072 command will return ERROR+NOT_LOGGED_IN if no user is logged in.  Otherwise
1073 it returns OK and the following parameters:
1074
1075  0: Number of new private messages in Mail>
1076  1: Nonzero if the user needs to register
1077  2: (Relevant to Aides only) Nonzero if new users require validation
1078  3: The user's preferred Internet e-mail address
1079
1080
1081  DELF   (DELete a File)
1082
1083  This command deletes a file from the room's directory, if there is one.  The
1084 name of the file to delete is the only parameter to be supplied.  Wildcards
1085 are not acceptable, and any slashes in the filename will be converted to
1086 underscores, to prevent unauthorized access to neighboring directories.  The
1087 possible return codes are:
1088
1089  OK                            -  Command succeeded.  The file was deleted.
1090  ERROR+NOT_LOGGED_IN           -  Not logged in.
1091  ERROR+HIGHER_ACCESS_REQUIRED  -  Not an Aide or Room Aide.
1092  ERROR+NOT_HERE                -  There is no directory in this room.
1093  ERROR+FILE_NOT_FOUND          -  Requested file was not found.
1094
1095
1096  MOVF   (MOVe a File)
1097
1098  This command is similar to DELF, except that it moves a file (and its
1099 associated file description) to another room.  It should be passed two
1100 parameters: the name of the file to move, and the name of the room to move
1101 the file to.  All of the same return codes as DELF may be returned, and also
1102 one additional one: ERROR+NO_SUCH_ROOM, which means that the target room
1103 does not exist.  ERROR+NOT_HERE could also mean that the target room does
1104 not have a directory.
1105
1106
1107  NETF   (NETwork send a File)
1108
1109  This command is similar to MOVF, except that it attempts to send a file over
1110 the network to another system.  It should be passed two parameters: the name
1111 of the file to send, and the node name of the system to send it to.  All of
1112 the same return codes as MOVF may be returned, except for ERROR+NO_SUCH_ROOM.
1113 Instead, ERROR+NO_SUCH_SYSTEM may be returned if the name of the target
1114 system is invalid.
1115
1116  The name of the originating room will be sent along with the file.  Most
1117 implementations will look for a room with the same name at the receiving end
1118 and attempt to place the file there, otherwise it goes into a bit bucket room
1119 for miscellaneous files.  This is, however, beyond the scope of this document;
1120 see elsewhere for more details.
1121
1122
1123  RWHO   (Read WHO's online)
1124
1125  Displays a list of all users connected to the server.  No error codes are
1126 ever returned.  LISTING_FOLLOWS will be returned, followed by zero or more
1127 lines containing the following three fields:
1128
1129  0 - Session ID.  Citadel fills this with the pid of a server program.
1130  1 - User name.
1131  2 - The name of the room the user is currently in.  This field might not
1132 be displayed (for example, if the user is in a private room) or it might
1133 contain other information (such as the name of a file the user is
1134 downloading).
1135  3 - (server v4.03 and above) The name of the host the client is connecting
1136 from, or "localhost" if the client is local.
1137  4 - (server v4.04 and above) Description of the client software being used
1138  5 - The last time, locally to the server, that a command was received from
1139      this client (Note: NOOP's don't count)
1140  6 - The last command received from a client. (NOOP's don't count)
1141  7 - Session flags.  These are: + (spoofed address), - (STEALTH mode), *
1142      (posting) and . (idle).
1143  8 - Actual user name, if user name is masqueraded and viewer is an Aide.
1144  9 - Actual room name, if room name is masqueraded and viewer is an Aide.
1145  10 - Actual host name, if host name is masqueraded and viewer is an Aide.
1146  11 - Nonzero if the session is a logged-in user, zero otherwise.
1147
1148  The listing is terminated, as always, with the string "000" on a line by
1149 itself.
1150
1151
1152  OPEN   (OPEN a file for download)
1153
1154  This command is used to open a file for downloading.  Only one download
1155 file may be open at a time.  The only argument to this command is the name
1156 of the file to be opened.  The user should already be in the room where the
1157 file resides.  Possible return codes are:
1158
1159  ERROR+NOT_LOGGED_IN
1160  ERROR+NOT_HERE                (no directory in this room)
1161  ERROR+FILE_NOT_FOUND          (could not open the file)
1162  ERROR                         (misc errors)
1163  OK                            (file is open)
1164
1165  If the file is successfully opened, OK will be returned, along with the
1166 size (in bytes) of the file, the time of last modification (if applicable),
1167 the filename (if known), and the MIME type of the file (if known).
1168
1169
1170  CLOS   (CLOSe the download file)
1171
1172  This command is used to close the download file.  It returns OK if the
1173 file was successfully closed, or ERROR if there wasn't any file open in the
1174 first place.
1175
1176
1177  READ   (READ from the download file)
1178
1179  Two arguments are passed to this command.  The first is the starting position
1180 in the download file, and the second is the total number of bytes to be
1181 read.  If the operation can be performed, BINARY_FOLLOWS will be returned,
1182 along with the number of bytes to follow.  Then, immediately following the
1183 newline, will be that many bytes of binary data.  The client *must* read
1184 exactly that number of bytes, otherwise the client and server will get out
1185 of sync.
1186
1187  If the operation cannot be performed, any of the usual error codes will be
1188 returned.
1189
1190
1191  UOPN   (OPeN a file for Uploading)
1192
1193  This command is similar to OPEN, except that this one is used when the
1194 client wishes to upload a file to the server.  The first argument is the name
1195 of the file to create, and the second argument is a one-line comment
1196 describing the contents of the file.  Only one upload file may be open at a
1197 time.  Possible return codes are:
1198
1199  ERROR+NOT_LOGGED_IN
1200  ERROR+NOT_HERE               (no directory in this room)
1201  ERROR+FILE_NOT_FOUND         (a name must be specified)
1202  ERROR                        (miscellaneous errors)
1203  ERROR+ALREADY_EXISTS         (a file with the same name already exists)
1204  OK
1205
1206  If OK is returned, the command has succeeded and writes may be performed.
1207
1208
1209  UCLS   (CLoSe the Upload file)
1210
1211  Close the file opened with UOPN.  An argument of "1" should be passed to
1212 this command to close and save the file; otherwise, the transfer will be
1213 considered aborted and the file will be deleted.  This command returns OK
1214 if the operation succeeded or ERROR if it did not.
1215
1216
1217  WRIT   (WRITe to the upload file)
1218
1219  If an upload file is open, this command may be used to write to it.  The
1220 argument passed to this command is the number of bytes the client wishes to
1221 transmit.  An ERROR code will be returned if the operation cannot be
1222 performed.
1223
1224  If the operation can be performed, SEND_BINARY will be returned, followed
1225 by the number of bytes the server is expecting.  The client must then transmit
1226 exactly that number of bytes.  Note that in the current implementation, the
1227 number of bytes the server is expecting will always be the number of bytes
1228 the client requested to transmit, but the client software should never assume
1229 that this will always happen, in case changes are made later.
1230
1231
1232  QUSR   (Query for a USeR)
1233
1234  This command is used to check to see if a particular user exists.  The only
1235 argument to this command is the name of the user being searched for.  If
1236 the user exists, OK is returned, along with the name of the user in the userlog
1237 (so the client software can learn the correct upper/lower casing of the name
1238 if necessary).  If the user does not exist, ERROR+NO_SUCH_USER is returned.
1239 No login or current room is required to utilize this command.
1240
1241
1242  OIMG   (Open an IMaGe file)
1243
1244  Open an image (graphics) file for downloading.  Once opened, the file can be
1245 read as if it were a download file.  This implies that an image and a download
1246 cannot be opened at the same time.  OIMG returns the same result codes as OPEN.
1247
1248  All images will be in GIF (Graphics Interchange Format).  In the case of
1249 Citadel, the server will convert the supplied filename to all lower case,
1250 append the characters ".gif" to the filename, and look for it in the "images"
1251 subdirectory.  As with the MESG command, there are several "well known"
1252 images which are likely to exist on most servers:
1253
1254  hello        - "Welcome" graphics to be displayed alongside MESG "hello"
1255  goodbye      - Logoff banner graphics to be displayed alongside MESG "goodbye"
1256  background   - Background image (usually tiled) for graphical clients
1257
1258  The following "special" image names are defined in Citadel server version
1259 5.00 and above:
1260
1261  _userpic_    - Picture of a user (send the username as the second argument)
1262  _floorpic_   - A graphical floor label (send the floor number as the second
1263                 argument).  Clients which request a floor picture will display
1264                 the picture *instead* of the floor name.
1265  _roompic_    - A graphic associated with the *current* room.  Clients which
1266                 request a room picture will display the picture in *addition*
1267                 to the room name (i.e. it's used for a room banner, as
1268                 opposed to the floor picture's use in a floor listing).
1269
1270
1271  NETP   (authenticate as network session with connection NET Password)
1272
1273  This command is used by client software to identify itself as a transport
1274 session for IGnet/Open BBS to BBS networking.  It should be called with
1275 two arguments: the node name of the calling system, and the "shared secret"
1276 password for that connection.  If the authentication succeeds, NETP will
1277 return OK, otherwise, it returns ERROR.
1278
1279  
1280  NSYN   (Network SYNchronize room)
1281  
1282  This command can be used to synchronize the contents of a room on the
1283 network.  It is only usable by Aides.  It accepts one argument: the name of
1284 a network node (which must be a valid one).
1285  
1286  When NSYN is run, the *entire* contents of the current room will be spooled
1287 to the specified node, without regard to whether any of the messages have
1288 already undergone network processing.  It is up to the receiving node to
1289 check for duplicates (the Citadel networker does handle this) and avoid
1290 posting them twice.
1291  
1292  The command returns OK upon success or ERROR if the user is not an Aide.
1293   
1294  
1295  NUOP   (Network Upload OPen file)
1296
1297  Open a network spool file for uploading.  The client must have already
1298 identified itself as a network session using the NETP command.  If the command
1299 returns OK, the client may begin transmitting IGnet/Open spool data using
1300 a series of WRIT commands.  When a UCLS command is issued, the spooled data
1301 is entered into the BBS if the argument to UCLS is 1 or discarded if the
1302 argument to UCLS is 0.  If the client has not authenticated itself with a
1303 NETP command, ERROR+HIGHER_ACCESS_REQUIRED will be returned.
1304
1305
1306  NDOP   (Network Download OPen file)
1307
1308  Open a network spool file for downloading.  The client must have already
1309 identified itself as a network session using the NETP command.  If the command
1310 returns OK, the client may begin receiving IGnet/Open spool data using
1311 a series of READ commands.  When a CLOS command is issued, the spooled data
1312 is deleted from the server and may not be read again.  If the client has not
1313 authenticated itself with a NETP command, ERROR+HIGHER_ACCESS_REQUIRED will
1314 be returned.
1315
1316
1317  LFLR   (List all known FLooRs)
1318
1319  On systems supporting floors, this command lists all known floors.  The
1320 command accepts no parameters.  It will return ERROR+NOT_LOGGED_IN if no
1321 user is logged in.  Otherwise it returns LISTING_FOLLOWS and a list of
1322 the available floors, each line consisting of three fields:
1323
1324  1. The floor number associated with the floor
1325  2. The name of the floor
1326  3. Reference count (number of rooms on this floor)
1327
1328
1329  CFLR   (Create a new FLooR)
1330
1331  This command is used to create a new floor.  It should be passed two
1332 arguments: the name of the new floor to be created, and a 1 or 0 depending
1333 on whether the client is actually creating a floor or merely checking to
1334 see if it has permission to create the floor.   The user must be logged in
1335 and have Aide privileges to create a floor.
1336
1337  If the command succeeds, it will return OK followed by the floor number
1338 associated with the new floor.  Otherwise, it will return ERROR (plus perhaps
1339 HIGHER_ACCESS_REQUIRED, ALREADY_EXISTS, or INVALID_FLOOR_OPERATION)
1340 followed by a description of why the command failed.
1341
1342
1343  KFLR   (Kill a FLooR)
1344
1345  This command is used to delete a floor.  It should be passed two
1346 argument: the *number* of the floor to be deleted, and a 1 or 0 depending
1347 on whether the client is actually deleting the floor or merely checking to
1348 see if it has permission to delete the floor.  The user must be logged in
1349 and have Aide privileges to delete a floor.
1350
1351  Floors that contain rooms may not be deleted.  If there are rooms on a floor,
1352 they must be either deleted or moved to different floors first.  This implies
1353 that the Main Floor (floor 0) can never be deleted, since Lobby>, Mail>, and
1354 Aide> all reside on the Main Floor and cannot be deleted.
1355
1356  If the command succeeds, it will return OK.  Otherwise it will return
1357 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1358 followed by a description of why the command failed.
1359
1360
1361  EFLR   (Edit a FLooR)
1362
1363  Edit the parameters of a floor.  The client may pass one or more parameters
1364 to this command:
1365
1366  1. The number of the floor to be edited
1367  2. The desired new name
1368
1369  More parameters may be added in the future.  Any parameters not passed to
1370 the server will remain unchanged.  A minimal command would be EFLR and a
1371 floor number -- which would do nothing.  EFLR plus the floor number plus a
1372 floor name would change the floor's name.
1373
1374  If the command succeeds, it will return OK.  Otherwise it will return
1375 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1376
1377
1378 IDEN (IDENtify the client software)
1379
1380  The client software has the option to identify itself to the server.
1381 Currently, the server does nothing with this information except to write
1382 it to the syslog to satisfy the system administrator's curiosity.  Other
1383 uses might become apparent in the future.
1384
1385  The IDEN command should contain five fields: a developer ID number (same as
1386 the server developer ID numbers in the INFO command -- please obtain one if
1387 you are a new developer), a client ID number (which does not have to be
1388 globally unique - only unique within the domain of the developer number),
1389 a version number, a free-form text string describing the client, and the name
1390 of the host the user is located at.
1391
1392  It is up to the server to determine whether to accept the host name or to
1393 use the host name it has detected itself.  Generally, if the client is
1394 running on a trusted host (either localhost or a well-known publically
1395 accessible client) it should use the host name transmitted by IDEN,
1396 otherwise it should use the host name it has detected itself.
1397
1398  IDEN always returns OK, but since that's the only way it ever returns
1399 there's no point in checking the result code.
1400
1401
1402 IPGM (identify as an Internal ProGraM)
1403
1404  IPGM is a low-level command that should not be used by normal user clients.
1405 It is used for various utilities to communicate with the server on the same
1406 host.  For example, the "sendcommand" utility logs onto the server as an
1407 internal program in order to run arbitrary server commands.  Since user clients
1408 do not utilize this command (or any of its companion commands), developers
1409 writing Citadel-compatible servers need not implement it.
1410
1411  The sole argument to IPGM is the system's internal program password.  This
1412 password is generated by the setup program and stored in the config file.
1413 Since internal programs have access to the config file, they know the correct
1414 password to use.
1415
1416  IPGM returns OK for a correct authentication or ERROR otherwise.
1417
1418
1419 CHAT (enter CHAT mode)
1420
1421  This command functions differently from every other command in the system.  It
1422 is used to implement multi-user chat.  For this to function, a new transfer
1423 mode, called START_CHAT_MODE, is implemented.  If a client does not support
1424 chat mode, it should never send a CHAT command!
1425
1426  In chat mode, messages may arrive asynchronously from the server at any
1427 time.  The client may send messages at any time.  This allows the arrival of
1428 messages without the client having to poll for them.  Arriving messages will
1429 be of the form  "user|message", where the "user" portion is, of course, the
1430 name of the user sending the message, and "message" is the message text.
1431
1432  Chat mode ends when the server says it ends.  The server will signal the end
1433 of chat mode by transmitting "000" on a line by itself.  When the client reads
1434 this line, it must immediately exit from chat mode without sending any
1435 further traffic to the server.  The next transmission sent to the server
1436 will be a regular server command.
1437
1438  The Citadel server understands the following commands:
1439  /quit   -   Exit from chat mode (causes the server to do an 000 end)
1440  /who    -   List users currently in chat
1441  /whobbs -   List users currently in chat and on the bbs
1442  /me     -   Do an irc-style action.
1443  /join   -   Join a new "room" in which all messages are only heard by
1444              people in that room.
1445  /msg    -   /msg <user> <msg> will send the msg to <user> only.
1446  /help   -   Print help information
1447  NOOP    -   Do nothing (silently)
1448
1449  Any other non-empty string is treated as message text and will be broadcast
1450 to other users currently in chat.
1451
1452
1453  SEXP   (Send instant message)
1454
1455  This is one of two commands which implement instant messages (also known
1456 as "paging").  Commands ending in "...EXP" are so-named because we called
1457 them "express messages" before the industry standardized on the term
1458 "instant messages."  When an instant message is sent, it will be
1459 logged in user to another.  When an instant message is sent, it will be
1460 displayed the next time the target user executes a PEXP or GEXP command.
1461
1462  The SEXP command accepts two arguments: the name of the user to send the
1463 message to, and the text of the message.  If the message is successfully
1464 transmitted, OK is returned.  If the target user is not logged in or if
1465 anything else goes wrong, ERROR is returned.
1466
1467  If the server supports extended paging, sending a zero-length message
1468 merely checks for the presence of the requested user without actually sending
1469 a message.  Sending a message consisting solely of a "-" (hyphen) will cause
1470 the server to return SEND_LISTING if the requested user is logged in, and the
1471 client can then transmit a multi-line page.
1472
1473  The reserved name "broadcast" may be used instead of a user name, to
1474 broadcast an instant message to all users currently connected to the server.
1475
1476  Do be aware that if an instant message is transmitted to a user who is logged
1477 in using a client that does not check for instant messages, the message will
1478 never be received.  Also, instant messages are NOT sent via the following
1479 transports:  SMTP, POP3.
1480
1481
1482  PEXP   (Print instant messages)   ***DEPRECATED***
1483
1484  This command is deprecated; it will eventually disappear from the protocol and
1485 its use is not recommended.  Please use the GEXP command instead.
1486
1487  Called without any arguments, PEXP simply dumps out the contents
1488 of any waiting instant messages.  It returns ERROR if there is a problem,
1489 otherwise it returns LISTING_FOLLOWS followed by all messages.
1490
1491  So how does the client know there are instant messages waiting?  It could
1492 execute a random PEXP every now and then.  Or, it can check the byte in
1493 server return code messages, between the return code and the parameters.  In
1494 much the same way as FTP uses "-" to signify a continuation, Citadel uses
1495 an "*" in this position to signify the presence of waiting instant messages.
1496
1497
1498  EBIO   (Enter BIOgraphy)
1499
1500  Transmit to the server a free-form text file containing a little bit of
1501 information about the user for other users to browse.  This is typically
1502 referred to as a 'bio' online.  EBIO returns SEND_LISTING if it succeeds,
1503 after which the client is expected to transmit the file, or any of the usual
1504 ERROR codes if it fails.
1505
1506
1507  RBIO   (Read BIOgraphy)
1508
1509  Receive from the server a named user's bio.  This command should be passed
1510 a single argument - the name of the user whose bio is requested.  RBIO returns
1511 LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file.
1512 The return has the following parameters:  the user name, user number, access
1513 level, date of last call, times called, and messages posted.  This command
1514 returns ERROR+NO_SUCH_USER if the named user does not exist.
1515
1516  RBIO no longer considers a user with no bio on file to be an error condition.
1517 It now returns a message saying the user has no bio on file as the text of the
1518 bio.  This allows newer servers to operate with older clients.
1519
1520
1521  STEL   (enter STEaLth mode)
1522
1523  When in "stealth mode," a user will not show up in the "Who is online"
1524 listing (the RWHO server command).  Only Aides may use stealth mode.  The
1525 STEL command accepts one argument: a 1 indicating that the user wishes to
1526 enter stealth mode, or a 0 indicating that the user wishes to exit stealth
1527 mode.  STEL returns OK if the command succeeded, ERROR+NOT_LOGGED_IN if no
1528 user is logged in, or ERROR+HIGHER_ACCESS_REQUIRED if the user is not an Aide;
1529 followed by a 1 or 0 indicating the new state.
1530
1531  If any value other than 1 or 0 is sent by the client, the server simply
1532 replies with 1 or 0 to indicate the current state without changing it.
1533
1534 The STEL command also makes it so a user does not show up in the chat room
1535 /who.
1536
1537
1538  LBIO   (List users who have BIOs on file)
1539
1540  This command is self-explanatory.  Any user who has used EBIO to place a bio
1541 on file is listed.  LBIO almost always returns LISTING_FOLLOWS followed by
1542 this listing, unless it experiences an internal error in which case ERROR
1543 is returned.
1544
1545
1546  MSG2   (read MeSsaGe, mode 2)
1547
1548  MSG2 follows the same calling convention as MSG0.  The difference between
1549 the two commands is that MSG2 outputs messages in standard RFC822 format
1550 rather than in Citadel proprietary format.
1551
1552  This command was implemented in order to make various gateway programs
1553 easier to implement, and to provide some sort of multimedia support in the
1554 future.  Keep in mind that when this command is used, all messages will be
1555 output in fixed 80-column format.
1556
1557
1558  MSG3   (read MeSsaGe, mode 3 -- internal command)
1559
1560  MSG3 is for use by internal programs only and should not be utilized by
1561 user-mode clients.  It does require IPGM authentication.  MSG3 follows the
1562 same calling convention as the other MSG commands, but upon success returns
1563 BINARY_FOLLOWS followed by a data block containing the _raw_ message format
1564 on disk.
1565
1566
1567  TERM   (TERMinate another session)
1568
1569  In a multithreaded environment, it sometimes becomes necessary to terminate
1570 a session that is unusable for whatever reason.  The TERM command performs
1571 this task.  Naturally, only Aides can execute TERM.  The command should be
1572 called with a single argument: the session ID (obtained from an RWHO command)
1573 of the session to be terminated.
1574
1575  TERM returns OK if the session was terminated, or ERROR otherwise.  Note that
1576 a client program is prohibited from terminating the session it is currently
1577 running on.
1578
1579  See also: REQT
1580
1581
1582  DOWN   (shut DOWN the server)
1583
1584  This command, which may only be executed by an Aide, immediately shuts down
1585 the server.  It is only implemented on servers on which such an operation is
1586 possible, such as a multithreaded Citadel engine.  The server does not restart.
1587 DOWN returns OK if the user is allowed to shut down the server, in which case
1588 the client program should expect the connection to be immediately broken.
1589
1590
1591  SCDN   (Schedule or Cancel a shutDowN)
1592
1593  SCDN sets or clears the "scheduled shutdown" flag.  Pass this command a 1 or
1594 0 to respectively set or clear the flag.  When the "scheduled shutdown" flag is
1595 set, the server will be shut down when there are no longer any users logged in.
1596 Any value other than 0 or 1 will not change the flag, only report its state.
1597 No users will be kicked off the system, and in fact the server is still
1598 available for new connections.  The command returns ERROR if it fails;
1599 otherwise, it returns OK followed by a number representing the current state
1600 of the flag.
1601
1602
1603  EMSG   (Enter a system MeSsaGe)
1604
1605  This is the opposite of the MESG command - it allows the creation and editing
1606 of system messages.  The only argument passed to EMSG is the name of the
1607 file being transmitted.  If the file exists in any system message directory
1608 on the server it will be overwritten, otherwise a new file is created.  EMSG
1609 returns SEND_LISTING on success or ERROR+HIGHER_ACCESS_REQUIRED if the user
1610 is not an Aide.
1611
1612  Typical client software would use MESG to retrieve any existing message into
1613 an edit buffer, then present an editor to the user and run EMSG if the changes
1614 are to be saved.
1615
1616
1617  UIMG   (Upload an IMaGe file)
1618
1619  UIMG is complemenary to OIMG; it is used to upload an image to the server.
1620 The first parameter supplied to UIMG should be 0 if the client is only checking
1621 for permission to upload, or 1 if the client is actually attempting to begin
1622 the upload operation.  The second argument is the name of the file to be
1623 transmitted.  In Citadel, the filename is converted to all lower case,
1624 appended with the characters ".gif", and stored in the "images" directory.
1625
1626  UIMG returns OK if the client has permission to perform the requested upload,
1627 or ERROR+HIGHER_ACCESS_REQUIRED otherwise.  If the client requested to begin
1628 the operation (first parameter set to 1), an upload file is opened, and the
1629 client should begin writing to it with WRIT commands, then close it with a
1630 UCLS command.
1631
1632  The supplied filename should be one of:
1633
1634  ->  _userpic_   (Server will attempt to write to the user's online photo)
1635  ->  Any of the "well known" filenames described in the writeup for the
1636      OIMG command.
1637
1638
1639  HCHG   (Hostname CHanGe)
1640
1641  HCHG is a command, usable by any user, that allows a user to change their RWHO
1642 host value.  This will mask a client's originating hostname from normal
1643 users; access level 6 and higher can see, in an extended wholist, the actual
1644 hostname the user originates from.
1645
1646  The format of an HCHG command is:
1647
1648  HCHG <name>
1649
1650  If a HCHG command is successful, the value OK (200) is returned.
1651
1652
1653  RCHG   (Roomname CHanGe)
1654
1655  RCHG is a command, usable by any user, that allows a user to change their RWHO
1656 room value.  This will mask a client's roomname from normal users; access
1657 level 6 and higher can see, in an extended wholist, the actual room the user
1658 is in.
1659
1660  The format of an RCHG command is:
1661
1662  RCHG <name>
1663
1664  If a RCHG command is successful, the value OK (200) is returned.
1665
1666
1667  UCHG   (Username CHanGe)
1668
1669  UCHG is an aide-level command which allows an aide to effectively change their
1670 username.  If this value is blank, the user goes into stealth mode (see
1671 STEL).  Posts
1672 will show up as being from the real username in this mode, however.  In
1673 addition, the RWHO listing will include both the spoofed and real usernames.
1674
1675  The format of an UCHG command is:
1676
1677  UCHG <name>
1678
1679  If a UCHG command is successful, the value OK (200) is returned.
1680
1681
1682  TIME   (get server local TIME)
1683
1684  TIME returns OK followed by the current time measured in seconds since
1685 00:00:00 GMT, Jan 1, 1970 (standard Unix format).
1686
1687  This is used in allowing a client to calculate idle times.
1688
1689
1690  AGUP   (Administrative Get User Parameters)
1691  ASUP   (Administrative Set User Parameters)
1692
1693  These commands are only executable by Aides and by server extensions running
1694 at system-level.  They are used to get/set any and all parameters relating to
1695 a user account.  AGUP requires only one argument: the name of the user in
1696 question.  SGUP requires all of the parameters to be set.  The parameters are
1697 as follows, and are common to both commands:
1698
1699  0 - User name
1700  1 - Password
1701  2 - Flags (see citadel.h)
1702  3 - Times called
1703  4 - Messages posted
1704  5 - Access level
1705  6 - User number
1706  7 - Timestamp of last call
1707  8 - Purge time (in days) for this user (or 0 to use system default)
1708
1709  Upon success, AGUP returns OK followed by all these parameters, and ASUP
1710 simply returns OK.  If the client has insufficient access to perform the
1711 requested operation, ERROR+HIGHER_ACCESS_REQUIRED is returned.  If the
1712 requested user does not exist, ERROR+NO_SUCH_USER is returned.
1713
1714
1715
1716  GPEX   (Get Policy for message EXpiration)
1717
1718  Returns the policy of the current room, floor, or site regarding the automatic
1719 purging (expiration) of messages.  The following policies are available:
1720    0  -  Fall back to the policy of the next higher level.  If this is a room,
1721          use the floor's default policy.  If this is a floor, use the system
1722          default policy.  This is an invalid value for the system policy.
1723    1  -  Do not purge messages automatically.
1724    2  -  Purge by message count.  (Requires a value: number of messages)
1725    3  -  Purge by message age.  (Requires a value: number of days)
1726
1727  The format of this command is:  GPEX <which>
1728  The value of <which> must be one of: "room" "floor" "site" "mailboxes"
1729
1730  If successful, GPEX returns OK followed by <policy>|<value>.
1731
1732
1733
1734  SPEX   (Set Policy for message EXpiration)
1735
1736  Sets the policy of the current room, floor, or site regarding the automatic
1737 purging (expiration) of messages.  See the writeup for the GPEX command for
1738 the list of available policies.
1739
1740  The format of this command is:  SPEX <which>|<policy>|<value>
1741  The value of <which> must be one of: "room" "floor" "site" "mailboxes"
1742
1743  If successful, GPEX returns OK; otherwise, an ERROR code is returned.
1744
1745
1746
1747  CONF   (get or set global CONFiguration options)
1748
1749  Retrieves or sets various system-wide configuration and policy options.  This
1750 command is only available to Aides.  The sole parameter accepted is a command,
1751 which should be either GET or SET.  If the GET command succeeds, CONF will
1752 return LISTING_FOLLOWS followed by the fields described below, one line at a
1753 time.  If the SET command succeeds, CONF will return SEND_LISTING and expect
1754 the fields described below, one line at a time (don't worry about other fields
1755 being added in the future; if a 'short' configuration list is sent, the missing
1756 values at the end will be left unchanged on the system).  If either command
1757 fails for any reason, ERROR is returned.
1758
1759  The configuration lines are as follows:
1760
1761  1. Node name
1762  2. Fully qualified domain name
1763  3. Human-readable node name
1764  4. Landline telephone number of this system
1765  5. Flag (0 or 1) - creator of private room automatically becomes room aide
1766  6. Server connection idle timeout (in seconds)
1767  7. Initial access level for new users
1768  8. Flag (0 or 1) - require registration for new users
1769  9. Flag (0 or 1) - automatically move Problem User messages to twit room
1770  10. Name of twit room
1771  11. Text of <more> prompt
1772  12. Flag (0 or 1) - restrict access to Internet mail
1773  13. Geographic location of this system
1774  14. Name of the system administrator
1775  15. Number of maximum concurrent sessions allowed on the server
1776  16. (placeholder -- this field is no longer in use)
1777  17. Default purge time (in days) for users
1778  18. Default purge time (in days) for rooms
1779  19. Name of room to log instant messages to (or a zero-length name for none)
1780  20. Access level required to create rooms
1781  21. Maximum message length which may be entered into the system
1782  22. Minimum number of worker threads
1783  23. Maximum number of worker threads
1784  24. Port number for POP3 service
1785  25. Port number for SMTP service
1786  26. Flag (0 or 1) - strict RFC822 adherence - don't correct From: forgeries
1787  27. Flag (0 or 1) - allow Aides to zap (forget) rooms
1788  28. Port number for IMAP service
1789  29. How often (in seconds) to run the networker
1790  30. Flag (0 or 1) - disable self-service new user registration
1791  31. (placeholder -- this field is no longer in use)
1792  32. Hour (0 through 23) during which database auto-purge jobs are run
1793  33. Name of host where an LDAP service may be found
1794  34. Port number of LDAP service on above host
1795  35. LDAP Base DN
1796  36. LDAP Bind DN
1797  37. Password for LDAP Bind DN
1798  38. Server IP address to listen on (or "0.0.0.0" for all addresses)
1799
1800  CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
1801 arbitrary MIME type (such as application/x-citadel-internet-config) which
1802 provides a means of storing generic configuration data in the Global System
1803 Configuration room without the need to add extra get/set commands to the
1804 server.
1805  
1806  Please note that the LDAP-specific configs have no effect on Citadel servers
1807 in which LDAP support is not enabled.
1808
1809
1810
1811  MSG4   (read MeSsaGe, mode 4 -- output in preferred MIME format)
1812
1813  This is the equivalent of MSG0, except it's a bit smarter about messages in
1814 rich text formats.  Immediately following the "text" directive, the server
1815 will output RFC822-like MIME part headers such as "Content-type:" and
1816 "Content-length:".  MIME formats are chosen and/or converted based on the
1817 client's preferred format settings, which are set using the MSGP command,
1818 described below.
1819
1820
1821
1822  MSGP   (set MeSsaGe Preferred MIME format)
1823
1824  Client tells the server what MIME content types it knows how to handle, and
1825 the order in which it prefers them.  This is similar to an HTTP "Accept:"
1826 header.
1827
1828  The parameters to a MSGP command are the client's acceptable MIME content
1829 types, in the order it prefers them (from most preferred to least preferred).
1830 For example:  MSGP text/html|text/plain
1831
1832  The MSGP command always returns OK.
1833
1834
1835
1836  OPNA   (OPeN Attachment)
1837
1838  Opens, as a download file, a component of a MIME-encoded message.  The two
1839 parameters which must be passed to this command are the message number and the
1840 name of the desired section.  If the message or section does not exist, an
1841 appropriate ERROR code will be returned; otherwise, if the open is successful,
1842 this command will succeed returning the same information as an OPEN command.
1843
1844
1845  GEXP   (Get instant messages)
1846
1847  This is a more sophisticated way of retrieving instant messages than the old
1848 PEXP method.  If there are no instant messages waiting, PEXP returns ERROR;
1849 otherwise, it returns LISTING_FOLLOWS and the following arguments:
1850
1851  0 - a boolean value telling the client whether there are any additional
1852      instant messages waiting following this one
1853  1 - a Unix-style timestamp
1854  2 - flags (see server.h for more info)
1855  3 - the name of the sender
1856  4 - the node this message originated on (for future support of PIP, ICQ, etc.)
1857
1858  The text sent to the client will be the body of the instant message.
1859
1860  So how does the client know there are instant messages waiting?  It could
1861 execute a random GEXP every now and then.  Or, it can check the byte in
1862 server return code messages, between the return code and the parameters.  In
1863 much the same way as FTP uses "-" to signify a continuation, Citadel uses
1864 an "*" in this position to signify the presence of waiting instant messages.
1865
1866
1867  FSCK   (check message base reference counts)
1868
1869  Verify, via the long way, that all message referenmce counts are correct.  If
1870 the user has permission to do this then LISTING_FOLLOWS is returned, followed
1871 by a transcript of the run.  Otherwise ERROR is returned.
1872
1873
1874  DEXP   (Disable receiving instant messages)
1875
1876  DEXP sets or clears the "disable instant messages" flag.  Pass this command a
1877 1 or 0 to respectively set or clear the flag.  When the "disable instant
1878 messages" flag is set, no one except Aides may send the user instant messages.
1879 Any value other than 0 or 1 will not change the flag, only report its state.
1880 The command returns ERROR if it fails; otherwise, it returns OK followed by a
1881 number representing the current state of the flag.
1882
1883
1884  REQT   (REQuest client Termination)
1885
1886  Request that the specified client (or all clients) log off.  Aide level
1887 access is required to run this command, otherwise ERROR+HIGHER_ACCESS_REQUIRED
1888 is returned.
1889
1890  The REQT command accepts one parameter: the session ID of the client which
1891 should be terminated, or 0 for all clients.  When successful, the REQT command
1892 returns OK.
1893
1894  It should be noted that REQT simply transmits an instant message to the
1895 specified client(s) with the EM_GO_AWAY flag set.  Older clients do not honor
1896 this flag, and it is certainly possible for users to re-program their client
1897 software to ignore it.  Therefore the effects of the REQT command should be
1898 considered advisory only.  The recommended implementation practice is to first
1899 issue a REQT command, then wait a little while (from 30 seconds up to a few
1900 minutes) for well-behaved clients to voluntarily terminate, and then issue a
1901 TERM command to forcibly disconnect the client (or perhaps a DOWN command, if
1902 you are logging off users for the purpose of shutting down the server).
1903
1904
1905  SEEN   (set or clear the SEEN flag for a message)
1906
1907  Beginning with version 5.80, Citadel supports the concept of setting or
1908 clearing the "seen" flag for each individual message, instead of only allowing
1909 a "last seen" pointer.  In fact, the old semantics are implemented in terms
1910 of the new semantics.  This command requires two arguments: the number of the
1911 message to be set, and a 1 or 0 to set or clear the "seen" bit.
1912
1913  This command returns OK, unless the user is not logged in or a usage error
1914 occurred, in which case it returns ERROR.  Please note that no checking is
1915 done on the supplied data; if the requested message does not exist, the SEEN
1916 command simply returns OK without doing anything.
1917
1918
1919  GTSN   (GeT the list of SeeN messages)
1920
1921  This command retrieves the list of "seen" (as opposed to unread) messages for
1922 the current room.  It returns OK followed by an IMAP-format message list.
1923
1924
1925  SMTP   (utility commands for the SMTP gateway)
1926
1927  This command, accessible only by Aides, supports several utility operations
1928 which examine or manipulate Citadel's SMTP support.  The first command argument
1929 is a subcommand telling the server what to do.  The following subcommands are
1930 supported:
1931
1932       SMTP mx|hostname             (display all MX hosts for 'hostname')
1933       SMTP runqueue                (attempt immediate delivery of all messages
1934                                     in the outbound SMTP queue, ignoring any
1935                                     retry times stored there)
1936
1937
1938  STLS   (Start Transport Layer Security)
1939
1940  This command starts TLS on the current connection.  The current
1941 implementation uses OpenSSL on both the client and server end.  For future
1942 compatibility all clients must support at least TLSv1, and servers are
1943 guaranteed to support TLSv1.  During TLS negotiation (see below) the server
1944 and client may agree to use a different protocol.
1945
1946  The server returns ERROR if it does not support SSL or SSL initialization
1947 failed on the server; otherwise it returns OK.  Once the server returns OK and
1948 the client has read the response, the server and client immediately negotiate
1949 TLS (in OpenSSL, using SSL_connect() on the client and SSL_accept() on the
1950 server).  If negotiation fails, the server and client should attempt to resume
1951 the session unencrypted.  If either end is unable to resume the session, the
1952 connection should be closed.
1953
1954  This command may be run at any time.
1955
1956
1957  GTLS   (Get Transport Layer Security Status)
1958
1959  This command returns information about the current connection.  The server
1960 returns OK plus several parameters if the connection is encrypted, and ERROR
1961 if the connection is not encrypted.  It is primarily used for debugging.  The
1962 command may be run at any time.
1963
1964  0 - Protocol name, e.g. "SSLv3"
1965  1 - Cipher suite name, e.g. "ADH-RC4-MD5"
1966  2 - Cipher strength bits, e.g. 128
1967  3 - Cipher strength bits actually in use, e.g. 128
1968
1969
1970  IGAB   (Initialize Global Address Book)
1971
1972  This command creates, or re-creates, a database of Internet e-mail addresses
1973 using the vCard information in the Global Address Book room.  This procedure
1974 is normally run internally when the server determines it necessary, but is
1975 also provided as a server command to be used as a troubleshooting/maintenenance
1976 tool.  Only a system Aide can run the command.  It returns OK on success or
1977 ERROR on failure.
1978
1979
1980  QDIR   (Query global DIRectory)
1981
1982  Look up an internet address in the global directory.  Any logged-in user may
1983 call QDIR with one parameter, the Internet e-mail address to look up.  QDIR
1984 returns OK followed by a Citadel address if there is a match, otherwise it
1985 returns ERROR+NOT_LOGGED_IN.
1986
1987
1988  ISME   (find out if an e-mail address IS ME)
1989
1990  This is a quickie shortcut command to find out if a given e-mail address
1991 belongs to the user currently logged in.  Its sole argument is an address to
1992 parse.  The supplied address may be in any format (local, IGnet, or Internet).
1993 The command returns OK if the address belongs to the user, ERROR otherwise.
1994
1995
1996  VIEW   (set the VIEW for a room)
1997
1998  Set the preferred view for the current user in the current room.  Please see
1999 views.txt for more information on views.  The sole parameter for this command
2000 is the type of view requested.  VIEW returns OK on success or ERROR on failure.
2001
2002
2003  QNOP   (Quiet No OPeration)
2004
2005  This command does nothing, similar to the NOOP command.  However, unlike the
2006 NOOP command, it returns *absolutely no response* at all.  The client has no
2007 way of knowing that the command executed.  It is intended for sending
2008 "keepalives" in situations where a full NOOP would cause the client protocol
2009 to get out of sync.
2010
2011  Naturally, sending this command to a server that doesn't support it is an
2012 easy way to mess things up.  Therefore, client software should first check
2013 the output of an INFO command to ensure that the server supports quiet noops.
2014
2015
2016
2017  ICAL   (Internet CALendaring commands)
2018
2019  This command supports a number of subcommands which are used to process the
2020 calendaring/scheduling support in Citadel.  Here are the subcommands which
2021 may be issued:
2022
2023  ICAL test
2024   Test server for calendaring support.  Always returns OK unless the server
2025   does not have the calendar module enabled.
2026
2027  ICAL respond|msgnum|partnum|action
2028   Respond to a meeting request.  'msgnum' and 'partnum' refer to a MIME-encoded
2029   meeting invitation in the current room.  'action' must be set to either
2030   "accept" or "decline" to determine the action to take.  This subcommand will
2031   return either OK or ERROR.
2032
2033  ICAL conflicts|msgnum|partnum
2034   Determine whether an incoming VEVENT will fit in the user's calendar by
2035   checking it against the existing VEVENTs.  'msgnum' and 'partnum' refer to
2036   a MIME-encoded meeting invitation in the current room (usually the inbox).
2037   This command may return ERROR if something went wrong, but usually it will
2038   return LISTING_FOLLOWS followed by a list of zero or more conflicting
2039   events.  A zero-length list means that there were no conflicts.
2040  
2041  ICAL handle_rsvp|msgnum|partnum
2042   Handle an incoming "reply" (or RSVP) to a meeting request you sent out.
2043   'msgnum' and 'partnum' refer to a MIME-encoded reply in the current room.
2044   'action' must be set to either "update" or "ignore" to determine the action
2045   to take.  If the action is "update" then the server will hunt for the meeting
2046   in the user's Calendar> room, and update the status for this attendee.  Either
2047   way, the reply message is deleted from the current room.  This subcommand will
2048   return either OK or ERROR.
2049  
2050  ICAL freebusy|username
2051   Output the free/busy times for the requested user.  If the user specified
2052   has a calendar available, this command will return LISTING_FOLLOWS and a
2053   compound VCALENDAR object.  That object, in turn, will contain VEVENT
2054   objects that have been stripped of all properties except for the bare
2055   minimum needed to learn free/busy times (such as DTSTART, DTEND, and
2056   TRANSP).  If there is no such user, or no calendar available, the usual
2057   ERROR codes will be returned.
2058  
2059  ICAL sgi|<bool>
2060  
2061  Readers who are paying attention will notice that there is no subcommand to
2062 send out meeting invitations.  This is because that task can be handled
2063 automatically by the Citadel server.  Issue this command with <bool> set to 1
2064 to enable Server Generated Invitations.  In this mode, when an event is saved
2065 to the user's Calendar> room and it contains attendees, Citadel will
2066 automatically turn the event into vCalendar REQUEST messages and mail them
2067 out to all listed attendees.  If for some reason the client needs to disable
2068 Server Generated Invitations, the command may be sent again with <bool> = 0.
2069
2070
2071
2072  MRTG   (Multi Router Traffic Grapher)
2073
2074  Multi Router Traffic Grapher (please see http://www.mrtg.org for more info) is
2075 a tool which creates pretty graphs of network activity, usually collected from
2076 routers using SNMP.  However, its ability to call external scripts has spawned
2077 a small community of people using it to graph anything which can be graphed.
2078 The MRTG command can output Citadel server activity in the format MRTG expects.
2079
2080  This format is as follows:
2081
2082  LISTING_FOLLOWS
2083  Line 1: variable #1
2084  Line 2: variable #2
2085  Line 3: uptime of system
2086  Line 4: name of system
2087  000
2088
2089  MRTG accepts two different keywords.  "MRTG users" will return two variables,
2090 the number of connected users and the number of active users.  "MRTG messages"
2091 will return one variable (and a zero in the second field), showing the current
2092 highest message number on the system.  Any other keyword, or a missing keyword,
2093 will cause the MRTG command to return an ERROR code.
2094
2095  Please get in touch with the Citadel developers if you wish to experiment with
2096 this.
2097
2098
2099
2100  GNET   (Get NETwork configuration for this room)
2101  SNET   (Set NETwork configuration for this room)
2102  
2103  These commands get/set the network configuration for the current room.  Aide
2104 or Room Aide privileges are required, otherwise an ERROR code is returned.
2105 If the command succeeds, LISTING_FOLLOWS or SEND_LISTING is returned.  The
2106 network configuration for a specific room includes neighbor nodes with whom
2107 the room is shared, and mailing list recipients.  The format of the network
2108 configuration is described in the file "netconfigs.txt".
2109
2110
2111
2112  ASYN   (ASYNchronous message support)
2113
2114  Negotiate the use of asynchronous, or unsolicited, protocol messages.  The
2115 only parameter specified should be 1 or 0 to indicate that the client can or
2116 cannot handle this type of messages.  The server will reply OK followed by a
2117 1 or 0 to tell the client which mode it is now operating in.
2118
2119  If the command is not available on the server (i.e. it returns ERROR), or
2120 if the command has not been executed by the client, it should be assumed that
2121 this mode of operation is NOT in effect.
2122
2123  The client may also send any value other than 0 or 1 to simply cause the
2124 server to output its current state without changing it.
2125
2126  When asynchronous protocol mode is in effect, the client MUST handle any
2127 asynchronous messages as they arrive, before doing anything else.
2128
2129
2130
2131
2132  ASYNCHRONOUS MESSAGES
2133  ---------------------
2134
2135  When the client protocol is operating in asynchronous mode (please refer to
2136 the writeup of the ASYN command above), the following messages may arrive at
2137 any time:
2138
2139
2140  902  (instant message arriving)
2141
2142  One or more instant messages have arrived for this client.