1 SESSION LAYER PROTOCOL FOR CITADEL/UX
2 (c) 1995-2003 by Art Cancro et. al. All Rights Reserved
8 This is an attempt to document the session layer protocol used by the
9 Citadel/UX 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
15 IMPORTANT NOTE TO DEVELOPERS!
16 -----------------------------
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.
26 The coordinator of the Citadel/UX project is Art Cancro
27 <ajc@uncensored.citadel.org>.
30 CONNECTING TO A SERVER
31 ----------------------
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/UX.
36 Citadel/UX offers Citadel BBS service using TCP/IP. It does so via a
37 multithreaded server listening on a TCP port. Older (4.xx) versions employed
38 an inetd-based server.
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.
45 GENERAL INFORMATION ABOUT THE SERVER
46 ------------------------------------
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.
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
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.
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.)
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.
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.
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
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
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
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 "|"
112 In this example, we're using the "SETU" command and passing three
113 parameters: 80, 24, and 260.
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
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
127 This is a listing of all the commands that a Citadel/UX server can execute.
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.
138 ECHO (ECHO something)
140 This command also does nothing. It simply returns OK followed by whatever
146 Terminate the server connection. This command takes no arguments. It
147 returns OK and closes the connection immediately.
152 Log out the user without closing the server connection. It always returns
153 OK even if no user is logged in.
156 USER (send USER name)
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 is returned.
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 or if a USER command has not been executed yet, ERROR is returned. If the
170 password is correct, OK is returned and the user is now logged in... and
171 most of the other server commands can now be executed. Along with OK, the
172 following parameters are returned:
174 0 - The user's name (in case the client wants the right upper/lower casing)
175 1 - The user's current access level
178 4 - Various flags (see citadel.h)
180 6 - Time of last call (UNIX timestamp)
183 NEWU (create NEW User account)
185 This command creates a new user account AND LOGS IT IN. The argument to
186 this command will be the name of the account. No case conversion is done
187 on the name. Note that the new account is installed with a default
188 configuration, and no password, so the client should immediately prompt the
189 user for a password and install it with the SETP command as soon as this
190 command completes. This command returns OK if the account was created and
191 logged in, or ERROR if another user already exists with this name. If OK,
192 it will also return the same parameters that PASS returns.
194 Please note that the NEWU command should only be used for self-service user account
195 creation. For administratively creating user accounts, please use the CREU command.
198 SETP (SET new Password)
200 This command sets a new password for the currently logged in user. The
201 argument to this command will be the new password. The command always
202 returns OK, unless the client is not logged in, in which case it will return
206 CREU (CREate new User account)
208 This command creates a new user account AND DOES NOT LOG IT IN. The argument to
209 this command will be the name of the account. No case conversion is done
210 on the name. Note that the new account is installed with a default
211 configuration, and no password. This command returns OK if the account was created,
212 or ERROR if another user already exists with this name.
214 Please note that CREU is intended to be used for activities in which a system
215 administrator is creating user accounts. For self-service user account creation,
216 use the NEWU command.
220 LKRN (List Known Rooms with New messages)
222 List known rooms with new messages. If the client is not logged in, ERROR
223 is returned. Otherwise, LISTING_FOLLOWS is returned, followed by the room
224 listing. Each line in the listing contains the full name of a room, followed
225 by the '|' symbol, and then a number that may contain the following bits:
228 #define QR_PERMANENT 1 /* Room does not purge */
229 #define QR_PRIVATE 4 /* Set for any type of private room */
230 #define QR_PASSWORDED 8 /* Set if there's a password too */
231 #define QR_GUESSNAME 16 /* Set if it's a guessname room */
232 #define QR_DIRECTORY 32 /* Directory room */
233 #define QR_UPLOAD 64 /* Allowed to upload */
234 #define QR_DOWNLOAD 128 /* Allowed to download */
235 #define QR_VISDIR 256 /* Visible directory */
236 #define QR_ANONONLY 512 /* Anonymous-Only room */
237 #define QR_ANON2 1024 /* Anonymous-Option room */
238 #define QR_NETWORK 2048 /* Shared network room */
239 #define QR_PREFONLY 4096 /* Preferred status needed to enter */
240 #define QR_READONLY 8192 /* Aide status required to post */
242 Then it returns another '|' symbol, followed by a second set of bits comprised
244 #define QR2_SYSTEM 1 /* System room; hide by default */
245 #define QR2_SELFLIST 2 /* Self-service mailing list mgmt */
247 Other bits may be defined in the future. The listing terminates, as with
248 all listings, with "000" on a line by itself.
250 Starting with version 4.01 and above, floors are supported. The first
251 argument to LKRN should be the number of the floor to list rooms from. Only
252 rooms from this floor will be listed. If no arguments are passed to LKRN, or
253 if the floor number requested is (-1), rooms on all floors will be listed.
255 The third field displayed on each line is the number of the floor the room
256 is on. The LFLR command should be used to associate floor numbers with
259 The fourth field displayed on each line is a "room listing order." Unless
260 there is a compelling reason not to, clients should sort any received room
261 listings by this value.
265 LKRO (List Known Rooms with Old [no new] messages)
267 This follows the same usage and format as LKRN.
270 LZRM (List Zapped RooMs)
272 This follows the same usage and format as LKRN and LKRO.
275 LKRA (List All Known Rooms)
277 Same format. Lists all known rooms, with or without new messages.
280 LRMS (List all accessible RooMS)
282 Again, same format. This command lists all accessible rooms, known and
283 forgotten, with and without new messages. It does not, however, list
284 inaccessible private rooms.
287 LPRM (List all Public RooMs)
289 Again, same format. This command lists all public rooms, and nothing else.
290 Unlike the other list rooms commands, this one can be executed without logging
294 GETU (GET User configuration)
296 This command retrieves the screen dimensions and user options for the
297 currently logged in account. ERROR will be returned if no user is logged
298 in, of course. Otherwise, OK will be returned, followed by four parameters.
299 The first parameter is the user's screen width, the second parameter is the
300 user's screen height, and the third parameter is a bag of bits with the
303 #define US_LASTOLD 16 /* Print last old message with new */
304 #define US_EXPERT 32 /* Experienced user */
305 #define US_UNLISTED 64 /* Unlisted userlog entry */
306 #define US_NOPROMPT 128 /* Don't prompt after each message */
307 #define US_DISAPPEAR 512 /* Use "disappearing msg prompts" */
308 #define US_PAGINATOR 2048 /* Pause after each screen of text */
310 There are other bits, too, but they can't be changed by the user (see below).
313 SETU (SET User configuration)
315 This command does the opposite of SETU: it takes the screen dimensions and
316 user options (which were probably obtained with a GETU command, and perhaps
317 modified by the user) and writes them to the user account. This command
318 should be passed three parameters: the screen width, the screen height, and
319 the option bits (see above).
321 Note that there exist bits here which are not listed in this document. Some
322 are flags that can only be set by Aides or the system administrator. SETU
323 will ignore attempts to toggle these bits. There also may be more user
324 settable bits added at a later date. To maintain later downward compatibility,
325 the following procedure is suggested:
327 1. Execute GETU to read the current flags
328 2. Toggle the bits that we know we can toggle
329 3. Execute SETU to write the flags
331 If we are passed a bit whose meaning we don't know, it's best to leave it
332 alone, and pass it right back to the server. That way we can use an old
333 client on a server that uses an unknown bit without accidentally clearing
334 it every time we set the user's configuration.
339 This command is used to goto a new room. When the user first logs in (login
340 is completed after execution of the PASS command) this command is
341 automatically and silently executed to take the user to the first room in the
342 system (usually called the Lobby).
344 This command can be passed one or two parameters. The first parameter is,
345 of course, the name of the room. Although it is not case sensitive, the
346 full name of the room must be used. Wildcard matching or unique string
347 matching of room names should be the responsibility of the client.
349 Note that the reserved room name "_BASEROOM_" can be passed to the server
350 to cause the goto command to take the user to the first room in the system,
351 traditionally known as the Lobby>. As long as a user is logged in, a
352 GOTO command to _BASEROOM_ is guaranteed to succeed. This is useful to
353 allow client software to return to the base room when it doesn't know
356 There are also two additional reserved room names:
357 "_MAIL_" translates to the system's designated room for e-mail messages.
358 "_BITBUCKET_" goes to whatever room has been chosen for messages
361 The second (and optional) parameter is a password, if one is required for
362 access to the room. This allows for all types of rooms to be accessed via
363 this command: for public rooms, invitation-only rooms to which the user
364 has access, and preferred users only rooms to which the user has access, the
365 room will appear in a room listing. For guess-name rooms, this command
366 will work transparently, adding the room to the user's known room list when
367 it completes. For passworded rooms, access will be denied if the password
368 is not supplied or is incorrect, or the command will complete successfully
369 if the password is correct.
371 The third (and also) optional parameter is a "transient" flag. Normally,
372 when a user enters a private and/or zapped room, the room is added to the
373 user's known rooms list. If the transient flag is set to non-zero, this is
374 called a "transient goto" which causes the user to enter the room without
375 adding the room to the known rooms list.
377 The possible result codes are:
379 OK - The command completed successfully. User is now in the room.
380 (See the list of returned parameters below)
382 ERROR - The command did not complete successfully. Check the second and
383 third positions of the result code to find out what happened:
385 NOT_LOGGED_IN - Of course you can't go there. You didn't log in.
386 PASSWORD_REQUIRED - Either a password was not supplied, or the supplied
387 password was incorrect.
388 NO_SUCH_ROOM - The requested room does not exist.
390 The typical procedure for entering a passworded room would be:
392 1. Execute a GOTO command without supplying any password.
393 2. ERROR+PASSWORD_REQUIRED will be returned. The client now knows that
394 the room is passworded, and prompts the user for a password.
395 3. Execute a GOTO command, supplying both the room name and the password.
396 4. If OK is returned, the command is complete. If, however,
397 ERROR+PASSWORD_REQUIRED is still returned, tell the user that the supplied
398 password was incorrect. The user remains in the room he/she was previously
401 When the command succeeds, these parameters are returned:
402 0. The name of the room
403 1. Number of unread messages in this room
404 2. Total number of messages in this room
405 3. Info flag: set to nonzero if the user needs to read this room's info
406 file (see RINF command below)
407 4. Various flags associated with this room. (See LKRN cmd above)
408 5. The highest message number present in this room
409 6. The highest message number the user has read in this room
410 7. Boolean flag: 1 if this is a Mail> room, 0 otherwise.
411 8. Aide flag: 1 if the user is either the Room Aide for this room, *or* is
412 a regular Aide (this makes access checks easy).
413 9. The number of new Mail messages the user has (useful for alerting the
414 user to the arrival of new mail during a session)
415 10. The floor number this room resides on
416 11. The *current* "view" for this room (see views.txt for more info)
417 12. The *default* "view" for this room
419 The default view gives the client a hint as to what views the user should
420 be allowed to select. For example, it would be confusing to allow messages
421 in a room intended for calendar items. The server does not enforce these
422 restrictions, though.
425 MSGS (get pointers to MeSsaGeS in this room)
427 This command obtains a listing of all the messages in the current room
428 which the client may request. This command may be passed a single parameter:
429 either "all", "old", or "new" to request all messages, only old messages, or
430 new messages. Or it may be passed two parameters: "last" plus a number, in
431 which case that many message pointers will be returned, or "first" plus a
432 number, for the corresponding effect. If no parameters are specified, "all"
435 In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number,
436 to list all messages in the current room with a message number greater than
439 The third argument, valid only in Citadel/UX 5.60 and above, may be either
440 0 or 1. If it is 1, this command behaves differently: before a listing is
441 returned, the client must transmit a list of fields to search for. The field
442 headers are listed below in the writeup for the "MSG0" command.
444 This command can return three possible results. An ERROR code may be returned
445 if no user is currently logged in or if something else went wrong. Otherwise,
446 LISTING_FOLLOWS will be returned, and the listing will consist of zero or
447 more message numbers, one per line. The listing ends, as always, with the
448 string "000" alone on a line by itself. The listed message numbers can be used
449 to request messages from the system. If "search mode" is being used, the
450 server will return START_CHAT_MODE, and the client is expected to transmit
451 the search criteria, and then read the message list.
453 Since this is somewhat complex, here are some examples:
455 Example 1: Read all new messages
458 Server: 100 Message list...
464 Example 2: Read the last five messages
467 Server: 100 Message list...
475 Example 3: Read all messages written by "IGnatius T Foobar"
478 Server: 800 Send template then receive message list
479 Client: from|IGnatius T Foobar
493 Note that in "search mode" the client may specify any number of search
494 criteria. These criteria are applied with an AND logic.
498 MSG0 (read MeSsaGe, mode 0)
500 This is a command used to read the text of a message. "Mode 0" implies that
501 other MSG commands (MSG1, MSG2, etc.) will probably be added later on to read
502 messages in more robust formats. This command should be passed two arguments.
503 The first is the message number of the message being requested. The second
504 argument specifies whether the client wants headers and/or message body:
509 If the request is denied, an ERROR code will be returned. Otherwise, the
510 LISTING_FOLLOWS code will be returned, followed by the contents of the message.
511 The following fields may be sent:
513 type= Formatting type. The currently defined types are:
514 0 = "traditional" Citadel formatting. This means that newlines should be
515 treated as spaces UNLESS the first character on the next line is a space. In
516 other words, only indented lines should generate a newline on the user's screen
517 when the message is being displayed. This allows a message to be formatted to
518 the reader's screen width. It also allows the use of proportional fonts.
519 1 = a simple fixed-format message. The message should be displayed to
520 the user's screen as is, preferably in a fixed-width font that will fit 80
522 4 = MIME format message. The message text is expected to contain a header
523 with the "Content-type:" directive (and possibly others).
525 msgn= The message ID of this message on the system it originated on.
526 path= An e-mailable path back to the user who wrote the message.
528 time= The date and time of the message, in Unix format (the number of
529 seconds since midnight on January 1, 1970, GMT).
531 from= The name of the author of the message.
532 rcpt= If the message is a private e-mail, this is the recipient.
533 room= The name of the room the message originated in.
534 node= The short node name of the system this message originated on.
535 hnod= The long node name of the system this message originated on.
536 zaps= The id/node of a message which this one zaps (supersedes).
538 part= Information about a MIME part embedded in this message.
539 pref= Information about a multipart MIME prefix such as "multipart/mixed"
540 or "multipart/alternative". This will be output immediately prior
541 to the various "part=" lines which make up the multipart section.
542 suff= Information about a multipart MIME suffix. This will be output
543 immediately following the various "part=" lines which make up the
546 text Note that there is no "=" after the word "text". This string
547 signifies that the message text begins on the next line.
550 WHOK (WHO Knows room)
552 This command is available only to Aides. ERROR+HIGHER_ACCESS_REQUIRED will
553 be returned if the user is not an Aide. Otherwise, it returns
554 LISTING_FOLLOWS and then lists, one user per line, every user who has
555 access to the current room.
558 INFO (get server INFO)
560 This command will *always* return LISTING_FOLLOWS and then print out a
561 listing of zero or more strings. Client software should be written to expect
562 anywhere from a null listing to an infinite number of lines, to allow later
563 backward compatibility. The current implementation defines the following
564 parts of the listing:
566 Line 1 - Your unique session ID on the server
567 Line 2 - The node name of the server BBS
568 Line 3 - Human-readable node name of the server BBS
569 Line 4 - The fully-qualified domain name (FQDN) of the server
570 Line 5 - The name of the server software, i.e. "Citadel/UX 4.00"
571 Line 6 - (The revision level of the server code) * 100
572 Line 7 - The geographical location of the BBS (city and state if in the US)
573 Line 8 - The name of the system administrator
574 Line 9 - A number identifying the server type (see below)
575 Line 10 - The text of the system's paginator prompt
576 Line 11 - Floor Flag. 1 if the system supports floors, 0 otherwise.
577 Line 12 - Paging level. 0 if the system only supports inline paging,
578 1 if the system supports "extended" paging (check-only and
579 multiline modes). See the SEXP command for further information.
580 Line 13 - The "nonce" for this session, for support of APOP-style
581 authentication. If this field is present, clients may authenticate
583 Line 14 - Set to nonzero if this server supports the QNOP command.
585 *** NOTE! *** The "server type" code is intended to promote global
586 compatibility in a scenario in which developers have added proprietary
587 features to their servers or clients. We are attempting to avoid a future
588 situation in which users need to keep different client software around for
589 each BBS they use. *Please*, if you are a developer and plan to add
590 proprietary features:
592 -> Your client programs should still be able to utilize servers other than
594 -> Clients other than your own should still be able to utilize your server,
595 even if your proprietary extensions aren't supported.
596 -> Please contact Art Cancro <ajc@uncensored.citadel.org> and obtain a unique
597 server type code, which can be assigned to your server program.
598 -> If you document what you did in detail, perhaps it can be added to a
599 future release of the Citadel/UX program, so everyone can enjoy it. Better
600 yet, just work with the Citadel development team on the main source tree.
602 If everyone follows this scheme, we can avoid a chaotic situation with lots
603 of confusion about which client program works with which server, etc. Client
604 software can simply check the server type (and perhaps the revision level)
605 to determine ahead of time what commands may be utilized.
607 Please refer to "developers.txt" for information on what codes belong to whom.
611 RDIR (Read room DIRectory)
613 Use this command to read the directory of a directory room. ERROR+NOT_HERE
614 will be returned if the room has no directory, or some other error; ERROR +
615 HIGHER_ACCESS_REQUIRED will be returned if the room's directory is not
616 visible and the user does not have Aide or Room Aide privileges; otherwise
617 LISTING_FOLLOWS will be returned, followed by the room's directory. Each
618 line of the directory listing will contain three fields: a filename, the
619 length of the file, and a description.
621 The server message contained on the same line with LISTING_FOLLOWS will
622 contain the name of the system and the name of the directory, such as:
623 uncensored.citadel.org|/usr/bbs/files/my_room_directory
626 SLRP (Set Last-message-Read Pointer)
628 This command marks all messages in the current room as read (seen) up to and
629 including the specified number. Its sole parameter
630 is the number of the last message that has been read. This allows the pointer
631 to be set at any arbitrary point in the room. Optionally, the parameter
632 "highest" may be used instead of a message number, to set the pointer to the
633 number of the highest message in the room, effectively marking all messages
634 in the room as having been read (ala the Citadel <G>oto command).
636 The command will return OK if the pointer was set, or ERROR if something
637 went wrong. If OK is returned, it will be followed by a single argument
638 containing the message number the last-read-pointer was set to.
641 INVT (INViTe a user to a room)
643 This command may only be executed by Aides, or by the room aide for the
644 current room. It is used primarily to add users to invitation-only rooms,
645 but it may also be used in other types of private rooms as well. Its sole
646 parameter is the name of the user to invite.
648 The command will return OK if the operation succeeded, or ERROR if it did
649 not. ERROR+HIGHER_ACCESS_REQUIRED may also be returned if the operation
650 would have been possible if the user had higher access, and ERROR+NOT_HERE
651 may be returned if the room is not a private room.
654 KICK (KICK a user out of a room)
656 This is the opposite of INVT: it is used to kick a user out of a private
657 room. It can also be used to kick a user out of a public room, but the
658 effect will only be the same as if the user <Z>apped the room - a non-stupid
659 user can simply un-zap the room to get back in.
662 GETR (GET Room attributes)
664 This command is used for editing the various attributes associated with a
665 room. A typical "edit room" command would work like this:
666 1. Use the GETR command to get the current attributes
667 2. Change some of them around
668 3. Use SETR (see below) to save the changes
669 4. Possibly also change the room aide using the GETA and SETA commands
671 GETR takes no arguments. It will only return OK if the SETR command will
672 also return OK. This allows client software to tell the user that he/she
673 can't edit the room *before* going through the trouble of actually doing the
674 editing. Possible return codes are:
676 ERROR+NOT_LOGGED_IN - No user is logged in.
677 ERROR+HIGHER_ACCESS_REQUIRED - Not enough access. Typically, only aides
678 and the room aide associated with the current room, can access this command.
679 ERROR+NOT_HERE - Lobby>, Mail>, and Aide> cannot be edited.
680 OK - Command succeeded. Parameters are returned.
682 If OK is returned, the following parameters will be returned as well:
684 0. The name of the room
685 1. The room's password (if it's a passworded room)
686 2. The name of the room's directory (if it's a directory room)
687 3. Various flags (bits) associated with the room (see LKRN cmd above)
688 4. The floor number on which the room resides
689 5. The room listing order
690 6. The default view for the room (see views.txt)
691 7. A second set of flags (bits) associated with the room
694 SETR (SET Room attributes)
696 This command sets various attributes associated with the current room. It
697 should be passed the following arguments:
699 0. The name of the room
700 1. The room's password (if it's a passworded room)
701 2. The name of the room's directory (if it's a directory room)
702 3. Various flags (bits) associated with the room (see LKRN cmd above)
703 4. "Bump" flag (see below)
704 5. The floor number on which the room should reside
705 6. The room listing order
706 7. The default view for the room (see views.txt)
707 8. A second set of flags (buts) associated with the room
709 *Important: You should always use GETR to retrieve the current attributes of
710 the room, then change what you want to change, and then use SETR to write it
711 all back. This is particularly important with respect to the flags: if a
712 particular bit is set, and you don't know what it means, LEAVE IT ALONE and
713 only toggle the bits you want to toggle. This will allow for upward
716 If the room is a private room, you have the option of causing all users who
717 currently have access, to forget the room. If you want to do this, set the
718 "bump" flag to 1, otherwise set it to 0.
723 This command is used to get the name of the Room Aide for the current room.
724 It will return ERROR+NOT_LOGGED_IN if no user is logged in, ERROR if there
725 is no current room, or OK if the command succeeded. Along with OK there will
726 be returned one parameter: the name of the Room Aide.
731 The opposite of GETA, used to set the Room Aide for the current room. One
732 parameter should be passed, which is the name of the user who is to be the
733 new Room Aide. Under Citadel/UX, this command may only be executed by Aides
734 and by the *current* Room Aide for the room. Return codes possible are:
735 ERROR+NOT_LOGGED_IN (Not logged in.)
736 ERROR+HIGHER_ACCESS_REQUIRED (Higher access required.)
737 ERROR+NOT_HERE (No current room, or room cannot be edited.
738 Under Citadel/UX, the Lobby> Mail> and Aide> rooms are non-editable.)
739 OK (Command succeeded.)
742 ENT0 (ENTer message, mode 0)
744 This command is used to enter messages into the system. It accepts four
747 0 - Post flag. This should be set to 1 to post a message. If it is
748 set to 0, the server only returns OK or ERROR (plus any flags describing
749 the error) without reading in a message. Client software should, in fact,
750 perform this operation at the beginning of an "enter message" command
751 *before* starting up its editor, so the user does not end up typing a message
752 in vain that will not be permitted to be saved. If it is set to 2, the
753 server will accept an "apparent" post name if the user is privileged enough.
754 This post name is arg 5.
755 1 - Recipient. This argument is utilized only for private mail messages.
756 It is ignored for public messages. It contains, of course, the name of the
757 recipient of the message.
758 2 - Anonymous flag. This argument is ignored unless the room allows
759 anonymous messages. In such rooms, this flag may be set to 1 to flag a
760 message as anonymous, otherwise 0 for a normal message.
761 3 - Format type. Any valid Citadel/UX format type may be used (this will
762 typically be 0; see the MSG0 command above).
763 4 - Subject. If present, this argument will be used as the subject of
765 5 - Post name. When postflag is 2, this is the name you are posting as.
766 This is an Aide only command.
768 Possible result codes:
769 OK - The request is valid. (Client did not set the "post" flag, so the
770 server will not read in message text.) If the message is an e-mail with
771 a recipient, the text that follows the OK code will contain the exact name
772 to which mail is being sent. The client can display this to the user. The
773 implication here is that the name that the server returns will contain the
774 correct upper and lower case characters. In addition, if the recipient is
775 having his/her mail forwarded, the forwarding address will be returned.
776 SEND_LISTING - The request is valid. The client should now transmit
777 the text of the message (ending with a 000 on a line by itself, as usual).
778 ERROR - Miscellaneous error. (Explanation probably follows.)
779 ERROR + NOT_LOGGED_IN - Not logged in.
780 ERROR + HIGHER_ACCESS_REQUIRED - Higher access is required. An
781 explanation follows, worded in a form that can be displayed to the user.
782 ERROR + NO_SUCH_USER - The specified recipient does not exist.
785 RINF (read Room INFormation file)
787 Each room has associated with it a text file containing a description of
788 the room, perhaps containing its intended purpose or other important
789 information. The info file for the Lobby> (the system's base room) is
790 often used as a repository for system bulletins and the like.
792 This command, which accepts no arguments, is simply used to read the info
793 file for the current room. It will return LISTING_FOLLOWS followed by
794 the text of the message (always in format type 0) if the request can be
795 honored, or ERROR if no info file exists for the current room (which is
796 often the case). Other error description codes may accompany this result.
798 When should this command be used? This is, of course, up to the discretion
799 of client software authors, but in Citadel it is executed in two situations:
800 the first time the user ever enters a room; and whenever the contents of the
801 file change. The latter can be determined from the result of a GOTO command,
802 which will tell the client whether the file needs to be read (see GOTO above).
805 DELE (DELEte a message)
807 Delete a message from the current room. The one argument that should be
808 passed to this command is the message number of the message to be deleted.
809 The return value will be OK if the message was deleted, or an ERROR code.
810 If the delete is successful, the message's reference count is decremented, and
811 if the reference count reaches zero, the message is removed from the message
815 MOVE (MOVE or copy a message to a different room)
817 Move a message to a different room. The two arguments that should be passed
818 to this command are the message number of the message to be deleted, and the
819 name of the target room. If the operation succeeds, the message will be
820 deleted from the current room and moved to the target room. An ERROR code
821 usually means that either the user does not have permission to perform this
822 operation, or that the target room does not exist.
824 In Citadel/UX 5.55 and above, a third argument may be specified: 0 or 1 to
825 designate whether the message should be moved (0) or copied (1) to the target
826 room. In the case of a "copy" operation, the message's reference count is
827 incremented, and a pointer to the message will exist in both the source *and*
828 target rooms. In the case of a "move" operation, the message pointer is
829 deleted from the source room and the reference count remains the same.
832 KILL (KILL current room)
834 This command deletes the current room. It accepts a single argument, which
835 should be nonzero to actually delete the room, or zero to merely check
836 whether the room can be deleted.
838 Once the room is deleted, the current room is undefined. It is suggested
839 that client software immediately GOTO another room (usually _BASEROOM_)
840 after this command completes.
842 Possible return codes:
844 OK - room has been deleted (or, if checking only, request is valid).
845 ERROR+NOT_LOGGED_IN - no user is logged in.
846 ERROR+HIGHER_ACCESS_REQUIRED - not enough access to delete rooms.
847 ERROR+NOT_HERE - this room can not be deleted.
850 CRE8 (CRE[ate] a new room)
852 This command is used to create a new room. Like some of the other
853 commands, it provides a mechanism to first check to see if a room can be
854 created before actually executing the command. CRE8 accepts the following
857 0 - Create flag. Set this to 1 to actually create the room. If it is
858 set to 0, the server merely checks that there is a free slot in which to
859 create a new room, and that the user has enough access to create a room. It
860 returns OK if the client should go ahead and prompt the user for more info,
861 or ERROR or ERROR+HIGHER_ACCESS_REQUIRED if the command will not succeed.
862 1 - Name for new room.
863 2 - Access type for new room:
865 1 - Private; can be entered by guessing the room's name
866 2 - Private; can be entered by knowing the name *and* password
867 3 - Private; invitation only (sometimes called "exclusive")
868 3 - Password for new room (if it is a type 2 room)
869 4 - Floor number on which the room should reside (optional)
870 5 - Set to 1 to avoid automatically gaining access to the created room.
872 If the create flag is set to 1, the room is created (unless something
873 went wrong and an ERROR return is sent), and the server returns OK, but
874 the session is **not** automatically sent to that room. The client still
875 must perform a GOTO command to go to the new room.
878 FORG (FORGet the current room)
880 This command is used to forget (zap) the current room. For those not
881 familiar with Citadel, this terminology refers to removing the room from
882 a user's own known rooms list, *not* removing the room itself. After a
883 room is forgotten, it no longer shows up in the user's known room list,
884 but it will exist in the user's forgotten room list, and will return to the
885 known room list if the user goes to the room (in Citadel, this is
886 accomplished by explicitly typing the room's name in a <.G>oto command).
888 The command takes no arguments. If the command cannot execute for any
889 reason, ERROR will be returned. ERROR+NOT_LOGGED_IN or ERROR+NOT_HERE may
890 be returned as they apply.
892 If the command succeeds, OK will be returned. At this point, the current
893 room is **undefined**, and the client software is responsible for taking
894 the user to another room before executing any other room commands (usually
895 this will be _BASEROOM_ since it is always there).
898 MESG (read system MESsaGe)
900 This command is used to display system messages and/or help files. The
901 single argument it accepts is the name of the file to display. IT IS CASE
902 SENSITIVE. Citadel/UX looks for these files first in the "messages"
903 subdirectory and then in the "help" subdirectory.
905 If the file is found, LISTING_FOLLOWS is returned, followed by a pathname
906 to the file being displayed. Then the message is printed, in format type 0
907 (see MSG0 command for more information on this). If the file is not found,
910 There are some "well known" names of system messages which client software
911 may expect most servers to carry:
913 hello - Welcome message, to be displayed before the user logs in.
914 changepw - To be displayed whenever the user is prompted for a new
915 password. Warns about picking guessable passwords and such.
916 register - Should be displayed prior to the user entering registration.
917 Warnings about not getting access if not registered, etc.
918 help - Main system help file.
919 goodbye - System logoff banner; display when user logs off.
920 roomaccess - Information about how public rooms and different types of
921 private rooms function with regards to access.
922 unlisted - Tells users not to choose to be unlisted unless they're
923 really paranoid, and warns that aides can still see
924 unlisted userlog entries.
926 Citadel/UX provides these for the Citadel/UX Unix text client. They are
927 probably not very useful for other clients:
929 mainmenu - Main menu (when in idiot mode).
934 saveopt - Options to save a message, abort, etc.
935 entermsg - Displayed just before a message is entered, when in
939 GNUR (Get Next Unvalidated User)
941 This command shows the name of a user that needs to be validated. If there
942 are no unvalidated users, OK is returned. Otherwise, MORE_DATA is returned
943 along with the name of the first unvalidated user the server finds. All of
944 the usual ERROR codes may be returned as well (for example, if the user is
945 not an Aide and cannot validate users).
947 A typical "Validate New Users" command would keep executing this command,
948 and then validating each user it returns, until it returns OK when all new
949 users have been validated.
952 GREG (Get REGistration for user)
954 This command retrieves the registration info for a user, whose name is the
955 command's sole argument. All the usual error messages can be returned. If
956 the command succeeds, LISTING_FOLLOWS is returned, followed by the user's name
957 (retrieved from the userlog, with the right upper and lower case etc.) The
958 contents of the listing contains one field per line, followed by the usual
959 000 on the last line.
961 The following lines are defined. Others WILL be added in the futre, so all
962 software should be written to read the lines it knows about and then ignore
968 Line 4: Street address or PO Box
969 Line 5: City/town/village/etc.
970 Line 6: State/province/etc.
972 Line 8: Telephone number
974 Line 10: Internet e-mail address
977 Users without Aide privileges may retrieve their own registration using
978 this command. This can be accomplished either by passing the user's own
979 name as the argument, or the string "_SELF_". The command will always
980 succeed when used in this manner, unless no user is logged in.
985 This command is used to validate users. Obviously, it can only be executed
986 by users with Aide level access. It should be passed two parameters: the
987 name of the user to validate, and the desired access level
989 If the command succeeds, OK is returned. The user's access level is changed
990 and the "need validation" bit is cleared. If the command fails for any
991 reason, ERROR, ERROR+NO_SUCH_USER, or ERROR+HIGHER_ACCESS_REQUIRED will be
995 EINF (Enter INFo file for room)
997 Transmit the info file for the current room with this command. EINF uses
998 a boolean flag (1 or 0 as the first and only argument to the command) to
999 determine whether the client actually wishes to transmit a new info file, or
1000 is merely checking to see if it has permission to do so.
1002 If the command cannot succeed, it returns ERROR.
1003 If the client is only checking for permission, and permission will be
1004 granted, OK is returned.
1005 If the client wishes to transmit the new info file, SEND_LISTING is
1006 returned, and the client should transmit the text of the info file, ended
1007 by the usual 000 on a line by itself.
1012 This is a simple user listing. It always succeeds, returning
1013 LISTING_FOLLOWS followed by zero or more user records, 000 terminated. The
1014 fields on each line are as follows:
1019 4. Date/time of last login (Unix format)
1022 7. Password (listed only if the user requesting the list is an Aide)
1024 Unlisted entries will also be listed to Aides logged into the server, but
1025 not to ordinary users.
1028 REGI (send REGIstration)
1030 Clients will use this command to transmit a user's registration info. If
1031 no user is logged in, ERROR+NOT_LOGGED_IN is returned. Otherwise,
1032 SEND_LISTING is returned, and the server will expect the following information
1033 (terminated by 000 on a line by itself):
1036 Line 2: Street address or PO Box
1037 Line 3: City/town/village/etc.
1038 Line 4: State/province/etc.
1040 Line 6: Telephone number
1041 Line 7: e-mail address
1045 CHEK (CHEcK various things)
1047 When logging in, there are various things that need to be checked. This
1048 command will return ERROR+NOT_LOGGED_IN if no user is logged in. Otherwise
1049 it returns OK and the following parameters:
1051 0: Number of new private messages in Mail>
1052 1: Nonzero if the user needs to register
1053 2: (Relevant to Aides only) Nonzero if new users require validation
1054 3: The user's preferred Internet e-mail address
1057 DELF (DELete a File)
1059 This command deletes a file from the room's directory, if there is one. The
1060 name of the file to delete is the only parameter to be supplied. Wildcards
1061 are not acceptable, and any slashes in the filename will be converted to
1062 underscores, to prevent unauthorized access to neighboring directories. The
1063 possible return codes are:
1065 OK - Command succeeded. The file was deleted.
1066 ERROR+NOT_LOGGED_IN - Not logged in.
1067 ERROR+HIGHER_ACCESS_REQUIRED - Not an Aide or Room Aide.
1068 ERROR+NOT_HERE - There is no directory in this room.
1069 ERROR+FILE_NOT_FOUND - Requested file was not found.
1074 This command is similar to DELF, except that it moves a file (and its
1075 associated file description) to another room. It should be passed two
1076 parameters: the name of the file to move, and the name of the room to move
1077 the file to. All of the same return codes as DELF may be returned, and also
1078 one additional one: ERROR+NO_SUCH_ROOM, which means that the target room
1079 does not exist. ERROR+NOT_HERE could also mean that the target room does
1080 not have a directory.
1083 NETF (NETwork send a File)
1085 This command is similar to MOVF, except that it attempts to send a file over
1086 the network to another system. It should be passed two parameters: the name
1087 of the file to send, and the node name of the system to send it to. All of
1088 the same return codes as MOVF may be returned, except for ERROR+NO_SUCH_ROOM.
1089 Instead, ERROR+NO_SUCH_SYSTEM may be returned if the name of the target
1092 The name of the originating room will be sent along with the file. Most
1093 implementations will look for a room with the same name at the receiving end
1094 and attempt to place the file there, otherwise it goes into a bit bucket room
1095 for miscellaneous files. This is, however, beyond the scope of this document;
1096 see elsewhere for more details.
1099 RWHO (Read WHO's online)
1101 Displays a list of all users connected to the server. No error codes are
1102 ever returned. LISTING_FOLLOWS will be returned, followed by zero or more
1103 lines containing the following three fields:
1105 0 - Session ID. Citadel/UX fills this with the pid of a server program.
1107 2 - The name of the room the user is currently in. This field might not
1108 be displayed (for example, if the user is in a private room) or it might
1109 contain other information (such as the name of a file the user is
1111 3 - (server v4.03 and above) The name of the host the client is connecting
1112 from, or "localhost" if the client is local.
1113 4 - (server v4.04 and above) Description of the client software being used
1114 5 - The last time, locally to the server, that a command was received from
1115 this client (Note: NOOP's don't count)
1116 6 - The last command received from a client. (NOOP's don't count)
1117 7 - Session flags. These are: + (spoofed address), - (STEALTH mode), *
1118 (posting) and . (idle).
1119 8 - Actual user name, if user name is masqueraded and viewer is an Aide.
1120 9 - Actual room name, if room name is masqueraded and viewer is an Aide.
1121 10 - Actual host name, if host name is masqueraded and viewer is an Aide.
1122 11 - Nonzero if the session is a logged-in user, zero otherwise.
1124 The listing is terminated, as always, with the string "000" on a line by
1128 OPEN (OPEN a file for download)
1130 This command is used to open a file for downloading. Only one download
1131 file may be open at a time. The only argument to this command is the name
1132 of the file to be opened. The user should already be in the room where the
1133 file resides. Possible return codes are:
1136 ERROR+NOT_HERE (no directory in this room)
1137 ERROR+FILE_NOT_FOUND (could not open the file)
1141 If the file is successfully opened, OK will be returned, along with the
1142 size (in bytes) of the file, the time of last modification (if applicable),
1143 the filename (if known), and the MIME type of the file (if known).
1146 CLOS (CLOSe the download file)
1148 This command is used to close the download file. It returns OK if the
1149 file was successfully closed, or ERROR if there wasn't any file open in the
1153 READ (READ from the download file)
1155 Two arguments are passed to this command. The first is the starting position
1156 in the download file, and the second is the total number of bytes to be
1157 read. If the operation can be performed, BINARY_FOLLOWS will be returned,
1158 along with the number of bytes to follow. Then, immediately following the
1159 newline, will be that many bytes of binary data. The client *must* read
1160 exactly that number of bytes, otherwise the client and server will get out
1163 If the operation cannot be performed, any of the usual error codes will be
1167 UOPN (OPeN a file for Uploading)
1169 This command is similar to OPEN, except that this one is used when the
1170 client wishes to upload a file to the server. The first argument is the name
1171 of the file to create, and the second argument is a one-line comment
1172 describing the contents of the file. Only one upload file may be open at a
1173 time. Possible return codes are:
1176 ERROR+NOT_HERE (no directory in this room)
1177 ERROR+FILE_NOT_FOUND (a name must be specified)
1178 ERROR (miscellaneous errors)
1179 ERROR+ALREADY_EXISTS (a file with the same name already exists)
1182 If OK is returned, the command has succeeded and writes may be performed.
1185 UCLS (CLoSe the Upload file)
1187 Close the file opened with UOPN. An argument of "1" should be passed to
1188 this command to close and save the file; otherwise, the transfer will be
1189 considered aborted and the file will be deleted. This command returns OK
1190 if the operation succeeded or ERROR if it did not.
1193 WRIT (WRITe to the upload file)
1195 If an upload file is open, this command may be used to write to it. The
1196 argument passed to this command is the number of bytes the client wishes to
1197 transmit. An ERROR code will be returned if the operation cannot be
1200 If the operation can be performed, SEND_BINARY will be returned, followed
1201 by the number of bytes the server is expecting. The client must then transmit
1202 exactly that number of bytes. Note that in the current implementation, the
1203 number of bytes the server is expecting will always be the number of bytes
1204 the client requested to transmit, but the client software should never assume
1205 that this will always happen, in case changes are made later.
1208 QUSR (Query for a USeR)
1210 This command is used to check to see if a particular user exists. The only
1211 argument to this command is the name of the user being searched for. If
1212 the user exists, OK is returned, along with the name of the user in the userlog
1213 (so the client software can learn the correct upper/lower casing of the name
1214 if necessary). If the user does not exist, ERROR+NO_SUCH_USER is returned.
1215 No login or current room is required to utilize this command.
1218 OIMG (Open an IMaGe file)
1220 Open an image (graphics) file for downloading. Once opened, the file can be
1221 read as if it were a download file. This implies that an image and a download
1222 cannot be opened at the same time. OIMG returns the same result codes as OPEN.
1224 All images will be in GIF (Graphics Interchange Format). In the case of
1225 Citadel/UX, the server will convert the supplied filename to all lower case,
1226 append the characters ".gif" to the filename, and look for it in the "images"
1227 subdirectory. As with the MESG command, there are several "well known"
1228 images which are likely to exist on most servers:
1230 hello - "Welcome" graphics to be displayed alongside MESG "hello"
1231 goodbye - Logoff banner graphics to be displayed alongside MESG "goodbye"
1232 background - Background image (usually tiled) for graphical clients
1234 The following "special" image names are defined in Citadel/UX server version
1237 _userpic_ - Picture of a user (send the username as the second argument)
1238 _floorpic_ - A graphical floor label (send the floor number as the second
1239 argument). Clients which request a floor picture will display
1240 the picture *instead* of the floor name.
1241 _roompic_ - A graphic associated with the *current* room. Clients which
1242 request a room picture will display the picture in *addition*
1243 to the room name (i.e. it's used for a room banner, as
1244 opposed to the floor picture's use in a floor listing).
1247 NETP (authenticate as network session with system NET Password)
1249 This command is used by client software to identify itself as a transport
1250 session for IGnet/Open BBS to BBS networking. It should be called with
1251 two arguments: the node name of the calling system, and the system net
1252 password for the server. If the authentication succeeds, NETP will return
1253 OK, otherwise, it returns ERROR.
1256 NUOP (Network Upload OPen file)
1258 Open a network spool file for uploading. The client must have already
1259 identified itself as a network session using the NETP command. If the command
1260 returns OK, the client may begin transmitting IGnet/Open spool data using
1261 a series of WRIT commands. When a UCLS command is issued, the spooled data
1262 is entered into the BBS if the argument to UCLS is 1 or discarded if the
1263 argument to UCLS is 0. If the client has not authenticated itself with a
1264 NETP command, ERROR+HIGHER_ACCESS_REQUIRED will be returned.
1267 NDOP (Network Download OPen file)
1269 Open a network spool file for downloading. The client must have already
1270 identified itself as a network session using the NETP command. If the command
1271 returns OK, the client may begin receiving IGnet/Open spool data using
1272 a series of READ commands. When a CLOS command is issued, the spooled data
1273 is deleted from the server and may not be read again. If the client has not
1274 authenticated itself with a NETP command, ERROR+HIGHER_ACCESS_REQUIRED will
1278 LFLR (List all known FLooRs)
1280 On systems supporting floors, this command lists all known floors. The
1281 command accepts no parameters. It will return ERROR+NOT_LOGGED_IN if no
1282 user is logged in. Otherwise it returns LISTING_FOLLOWS and a list of
1283 the available floors, each line consisting of three fields:
1285 1. The floor number associated with the floor
1286 2. The name of the floor
1287 3. Reference count (number of rooms on this floor)
1290 CFLR (Create a new FLooR)
1292 This command is used to create a new floor. It should be passed two
1293 arguments: the name of the new floor to be created, and a 1 or 0 depending
1294 on whether the client is actually creating a floor or merely checking to
1295 see if it has permission to create the floor. The user must be logged in
1296 and have Aide privileges to create a floor.
1298 If the command succeeds, it will return OK followed by the floor number
1299 associated with the new floor. Otherwise, it will return ERROR (plus perhaps
1300 HIGHER_ACCESS_REQUIRED, ALREADY_EXISTS, or INVALID_FLOOR_OPERATION)
1301 followed by a description of why the command failed.
1306 This command is used to delete a floor. It should be passed two
1307 argument: the *number* of the floor to be deleted, and a 1 or 0 depending
1308 on whether the client is actually deleting the floor or merely checking to
1309 see if it has permission to delete the floor. The user must be logged in
1310 and have Aide privileges to delete a floor.
1312 Floors that contain rooms may not be deleted. If there are rooms on a floor,
1313 they must be either deleted or moved to different floors first. This implies
1314 that the Main Floor (floor 0) can never be deleted, since Lobby>, Mail>, and
1315 Aide> all reside on the Main Floor and cannot be deleted.
1317 If the command succeeds, it will return OK. Otherwise it will return
1318 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1319 followed by a description of why the command failed.
1324 Edit the parameters of a floor. The client may pass one or more parameters
1327 1. The number of the floor to be edited
1328 2. The desired new name
1330 More parameters may be added in the future. Any parameters not passed to
1331 the server will remain unchanged. A minimal command would be EFLR and a
1332 floor number -- which would do nothing. EFLR plus the floor number plus a
1333 floor name would change the floor's name.
1335 If the command succeeds, it will return OK. Otherwise it will return
1336 ERROR (plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION)
1339 IDEN (IDENtify the client software)
1341 The client software has the option to identify itself to the server.
1342 Currently, the server does nothing with this information except to write
1343 it to the syslog to satisfy the system administrator's curiosity. Other
1344 uses might become apparent in the future.
1346 The IDEN command should contain five fields: a developer ID number (same as
1347 the server developer ID numbers in the INFO command -- please obtain one if
1348 you are a new developer), a client ID number (which does not have to be
1349 globally unique - only unique within the domain of the developer number),
1350 a version number, a free-form text string describing the client, and the name
1351 of the host the user is located at.
1353 It is up to the server to determine whether to accept the host name or to
1354 use the host name it has detected itself. Generally, if the client is
1355 running on a trusted host (either localhost or a well-known publically
1356 accessible client) it should use the host name transmitted by IDEN,
1357 otherwise it should use the host name it has detected itself.
1359 IDEN always returns OK, but since that's the only way it ever returns
1360 there's no point in checking the result code.
1363 IPGM (identify as an Internal ProGraM)
1365 IPGM is a low-level command that should not be used by normal user clients.
1366 It is used for various utilities to communicate with the server on the same
1367 host. For example, the "sendcommand" utility logs onto the server as an
1368 internal program in order to run arbitrary server commands. Since user clients
1369 do not utilize this command (or any of its companion commands), developers
1370 writing Citadel-compatible servers need not implement it.
1372 The sole argument to IPGM is the system's internal program password. This
1373 password is generated by the setup program and stored in the config file.
1374 Since internal programs have access to the config file, they know the correct
1377 IPGM returns OK for a correct authentication or ERROR otherwise.
1380 CHAT (enter CHAT mode)
1382 This command functions differently from every other command in the system. It
1383 is used to implement multi-user chat. For this to function, a new transfer
1384 mode, called START_CHAT_MODE, is implemented. If a client does not support
1385 chat mode, it should never send a CHAT command!
1387 In chat mode, messages may arrive asynchronously from the server at any
1388 time. The client may send messages at any time. This allows the arrival of
1389 messages without the client having to poll for them. Arriving messages will
1390 be of the form "user|message", where the "user" portion is, of course, the
1391 name of the user sending the message, and "message" is the message text.
1393 Chat mode ends when the server says it ends. The server will signal the end
1394 of chat mode by transmitting "000" on a line by itself. When the client reads
1395 this line, it must immediately exit from chat mode without sending any
1396 further traffic to the server. The next transmission sent to the server
1397 will be a regular server command.
1399 The Citadel/UX server understands the following commands:
1400 /quit - Exit from chat mode (causes the server to do an 000 end)
1401 /who - List users currently in chat
1402 /whobbs - List users currently in chat and on the bbs
1403 /me - Do an irc-style action.
1404 /join - Join a new "room" in which all messages are only heard by
1405 people in that room.
1406 /msg - /msg <user> <msg> will send the msg to <user> only.
1407 /help - Print help information
1408 NOOP - Do nothing (silently)
1410 Any other non-empty string is treated as message text and will be broadcast
1411 to other users currently in chat.
1414 SEXP (Send EXPress messages)
1416 This is one of two commands which implement "express messages" (also known
1417 as "paging"). An express message is a near-real-time message sent from one
1418 logged in user to another. When an express message is sent, it will be
1419 displayed the next time the target user executes a PEXP or GEXP command.
1421 The SEXP command accepts two arguments: the name of the user to send the
1422 message to, and the text of the message. If the message is successfully
1423 transmitted, OK is returned. If the target user is not logged in or if
1424 anything else goes wrong, ERROR is returned.
1426 If the server supports extended paging, sending a zero-length message
1427 merely checks for the presence of the requested user without actually sending
1428 a message. Sending a message consisting solely of a "-" (hyphen) will cause
1429 the server to return SEND_LISTING if the requested user is logged in, and the
1430 client can then transmit a multi-line page.
1432 The reserved name "broadcast" may be used instead of a user name, to
1433 broadcast an express message to all users currently connected to the server.
1435 Do be aware that if an express message is transmitted to a user who is logged
1436 in using a client that does not check for express messages, the message will
1440 PEXP (Print EXPress messages) ***DEPRECATED***
1442 This command is deprecated; it will eventually disappear from the protocol and
1443 its use is not recommended. Please use the GEXP command instead.
1445 Called without any arguments, PEXP simply dumps out the contents
1446 of any waiting express messages. It returns ERROR if there is a problem,
1447 otherwise it returns LISTING_FOLLOWS followed by all messages.
1449 So how does the client know there are express messages waiting? It could
1450 execute a random PEXP every now and then. Or, it can check the byte in
1451 server return code messages, between the return code and the parameters. In
1452 much the same way as FTP uses "-" to signify a continuation, Citadel uses
1453 an "*" in this position to signify the presence of waiting express messages.
1456 EBIO (Enter BIOgraphy)
1458 Transmit to the server a free-form text file containing a little bit of
1459 information about the user for other users to browse. This is typically
1460 referred to as a 'bio' online. EBIO returns SEND_LISTING if it succeeds,
1461 after which the client is expected to transmit the file, or any of the usual
1462 ERROR codes if it fails.
1465 RBIO (Read BIOgraphy)
1467 Receive from the server a named user's bio. This command should be passed
1468 a single argument - the name of the user whose bio is requested. RBIO returns
1469 LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file.
1470 The return has the following parameters: the user name, user number, access
1471 level, date of last call, times called, and messages posted. This command
1472 returns ERROR+NO_SUCH_USER if the named user does not exist.
1474 RBIO no longer considers a user with no bio on file to be an error condition.
1475 It now returns a message saying the user has no bio on file as the text of the
1476 bio. This allows newer servers to operate with older clients.
1479 STEL (enter STEaLth mode)
1481 When in "stealth mode," a user will not show up in the "Who is online"
1482 listing (the RWHO server command). Only Aides may use stealth mode. The
1483 STEL command accepts one argument: a 1 indicating that the user wishes to
1484 enter stealth mode, or a 0 indicating that the user wishes to exit stealth
1485 mode. STEL returns OK if the command succeeded, ERROR+NOT_LOGGED_IN if no
1486 user is logged in, or ERROR+HIGHER_ACCESS_REQUIRED if the user is not an Aide;
1487 followed by a 1 or 0 indicating the new state.
1489 If any value other than 1 or 0 is sent by the client, the server simply
1490 replies with 1 or 0 to indicate the current state without changing it.
1492 The STEL command also makes it so a user does not show up in the chat room
1496 LBIO (List users who have BIOs on file)
1498 This command is self-explanatory. Any user who has used EBIO to place a bio
1499 on file is listed. LBIO almost always returns LISTING_FOLLOWS followed by
1500 this listing, unless it experiences an internal error in which case ERROR
1504 MSG2 (read MeSsaGe, mode 2)
1506 MSG2 follows the same calling convention as MSG0. The difference between
1507 the two commands is that MSG2 outputs messages in standard RFC822 format
1508 rather than in Citadel/UX proprietary format.
1510 This command was implemented in order to make various gateway programs
1511 easier to implement, and to provide some sort of multimedia support in the
1512 future. Keep in mind that when this command is used, all messages will be
1513 output in fixed 80-column format.
1516 MSG3 (read MeSsaGe, mode 3 -- internal command)
1518 MSG3 is for use by internal programs only and should not be utilized by
1519 user-mode clients. It does require IPGM authentication. MSG3 follows the
1520 same calling convention as the other MSG commands, but upon success returns
1521 BINARY_FOLLOWS followed by a data block containing the _raw_ message format
1525 TERM (TERMinate another session)
1527 In a multithreaded environment, it sometimes becomes necessary to terminate
1528 a session that is unusable for whatever reason. The TERM command performs
1529 this task. Naturally, only Aides can execute TERM. The command should be
1530 called with a single argument: the session ID (obtained from an RWHO command)
1531 of the session to be terminated.
1533 TERM returns OK if the session was terminated, or ERROR otherwise. Note that
1534 a client program is prohibited from terminating the session it is currently
1540 DOWN (shut DOWN the server)
1542 This command, which may only be executed by an Aide, immediately shuts down
1543 the server. It is only implemented on servers on which such an operation is
1544 possible, such as a multithreaded Citadel engine. The server does not restart.
1545 DOWN returns OK if the user is allowed to shut down the server, in which case
1546 the client program should expect the connection to be immediately broken.
1549 SCDN (Schedule or Cancel a shutDowN)
1551 SCDN sets or clears the "scheduled shutdown" flag. Pass this command a 1 or
1552 0 to respectively set or clear the flag. When the "scheduled shutdown" flag is
1553 set, the server will be shut down when there are no longer any users logged in.
1554 Any value other than 0 or 1 will not change the flag, only report its state.
1555 No users will be kicked off the system, and in fact the server is still
1556 available for new connections. The command returns ERROR if it fails;
1557 otherwise, it returns OK followed by a number representing the current state
1561 EMSG (Enter a system MeSsaGe)
1563 This is the opposite of the MESG command - it allows the creation and editing
1564 of system messages. The only argument passed to EMSG is the name of the
1565 file being transmitted. If the file exists in any system message directory
1566 on the server it will be overwritten, otherwise a new file is created. EMSG
1567 returns SEND_LISTING on success or ERROR+HIGHER_ACCESS_REQUIRED if the user
1570 Typical client software would use MESG to retrieve any existing message into
1571 an edit buffer, then present an editor to the user and run EMSG if the changes
1575 UIMG (Upload an IMaGe file)
1577 UIMG is complemenary to OIMG; it is used to upload an image to the server.
1578 The first parameter supplied to UIMG should be 0 if the client is only checking
1579 for permission to upload, or 1 if the client is actually attempting to begin
1580 the upload operation. The second argument is the name of the file to be
1581 transmitted. In Citadel/UX, the filename is converted to all lower case,
1582 appended with the characters ".gif", and stored in the "images" directory.
1584 UIMG returns OK if the client has permission to perform the requested upload,
1585 or ERROR+HIGHER_ACCESS_REQUIRED otherwise. If the client requested to begin
1586 the operation (first parameter set to 1), an upload file is opened, and the
1587 client should begin writing to it with WRIT commands, then close it with a
1590 The supplied filename should be one of:
1592 -> _userpic_ (Server will attempt to write to the user's online photo)
1593 -> Any of the "well known" filenames described in the writeup for the
1597 HCHG (Hostname CHanGe)
1599 HCHG is a command, usable by any user, that allows a user to change their RWHO
1600 host value. This will mask a client's originating hostname from normal
1601 users; access level 6 and higher can see, in an extended wholist, the actual
1602 hostname the user originates from.
1604 The format of an HCHG command is:
1608 If a HCHG command is successful, the value OK (200) is returned.
1611 RCHG (Roomname CHanGe)
1613 RCHG is a command, usable by any user, that allows a user to change their RWHO
1614 room value. This will mask a client's roomname from normal users; access
1615 level 6 and higher can see, in an extended wholist, the actual room the user
1618 The format of an RCHG command is:
1622 If a RCHG command is successful, the value OK (200) is returned.
1625 UCHG (Username CHanGe)
1627 UCHG is an aide-level command which allows an aide to effectively change their
1628 username. If this value is blank, the user goes into stealth mode (see
1630 will show up as being from the real username in this mode, however. In
1631 addition, the RWHO listing will include both the spoofed and real usernames.
1633 The format of an UCHG command is:
1637 If a UCHG command is successful, the value OK (200) is returned.
1640 TIME (get server local TIME)
1642 TIME returns OK followed by the current time measured in seconds since
1643 00:00:00 GMT, Jan 1, 1970 (standard Unix format).
1645 This is used in allowing a client to calculate idle times.
1648 AGUP (Administrative Get User Parameters)
1649 ASUP (Administrative Set User Parameters)
1651 These commands are only executable by Aides and by server extensions running
1652 at system-level. They are used to get/set any and all parameters relating to
1653 a user account. AGUP requires only one argument: the name of the user in
1654 question. SGUP requires all of the parameters to be set. The parameters are
1655 as follows, and are common to both commands:
1659 2 - Flags (see citadel.h)
1664 7 - Timestamp of last call
1665 8 - Purge time (in days) for this user (or 0 to use system default)
1667 Upon success, AGUP returns OK followed by all these parameters, and ASUP
1668 simply returns OK. If the client has insufficient access to perform the
1669 requested operation, ERROR+HIGHER_ACCESS_REQUIRED is returned. If the
1670 requested user does not exist, ERROR+NO_SUCH_USER is returned.
1674 GPEX (Get Policy for message EXpiration)
1676 Returns the policy of the current room, floor, or site regarding the automatic
1677 purging (expiration) of messages. The following policies are available:
1678 0 - Fall back to the policy of the next higher level. If this is a room,
1679 use the floor's default policy. If this is a floor, use the system
1680 default policy. This is an invalid value for the system policy.
1681 1 - Do not purge messages automatically.
1682 2 - Purge by message count. (Requires a value: number of messages)
1683 3 - Purge by message age. (Requires a value: number of days)
1685 The format of this command is: GPEX <which>
1686 The value of <which> must be one of: "room" "floor" "site"
1688 If successful, GPEX returns OK followed by <policy>|<value>.
1692 SPEX (Set Policy for message EXpiration)
1694 Sets the policy of the current room, floor, or site regarding the automatic
1695 purging (expiration) of messages. See the writeup for the GPEX command for
1696 the list of available policies.
1698 The format of this command is: SPEX <which>|<policy>|<value>
1699 The value of <which> must be one of: "room" "floor" "site"
1701 If successful, GPEX returns OK; otherwise, an ERROR code is returned.
1705 CONF (get or set global CONFiguration options)
1707 Retrieves or sets various system-wide configuration and policy options. This
1708 command is only available to Aides. The sole parameter accepted is a command,
1709 which should be either GET or SET. If the GET command succeeds, CONF will
1710 return LISTING_FOLLOWS followed by the fields described below, one line at a
1711 time. If the SET command succeeds, CONF will return SEND_LISTING and expect
1712 the fields described below, one line at a time (don't worry about other fields
1713 being added in the future; if a 'short' configuration list is sent, the missing
1714 values at the end will be left unchanged on the system). If either command
1715 fails for any reason, ERROR is returned.
1717 The configuration lines are as follows:
1720 2. Fully qualified domain name
1721 3. Human-readable node name
1722 4. Landline telephone number of this system
1723 5. Flag (0 or 1) - creator of private room automatically becomes room aide
1724 6. Server connection idle timeout (in seconds)
1725 7. Initial access level for new users
1726 8. Flag (0 or 1) - require registration for new users
1727 9. Flag (0 or 1) - automatically move Problem User messages to twit room
1728 10. Name of twit room
1729 11. Text of <more> prompt
1730 12. Flag (0 or 1) - restrict access to Internet mail
1731 13. Geographic location of this system
1732 14. Name of the system administrator
1733 15. Number of maximum concurrent sessions allowed on the server
1734 16. Password for server-to-server networking
1735 17. Default purge time (in days) for users
1736 18. Default purge time (in days) for rooms
1737 19. Name of room to log express messages to (or a zero-length name for none)
1738 20. Access level required to create rooms
1739 21. Maximum message length which may be entered into the system
1740 22. Minimum number of worker threads
1741 23. Maximum number of worker threads
1742 24. Port number for POP3 service
1743 25. Port number for SMTP service
1745 27. Flag (0 or 1) - allow Aides to zap (forget) rooms
1746 28. Port number for IMAP service
1747 29. How often (in seconds) to run the networker
1749 CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
1750 arbitrary MIME type (such as application/x-citadel-internet-config) which
1751 provides a means of storing generic configuration data in the Global System
1752 Configuration room without the need to add extra get/set commands to the
1756 EXPI (EXPIre system objects)
1758 Begins purge operations for objects which, according to site policy, are
1759 "old" and should be removed. EXPI should be called with one argument, one of:
1761 "messages" (purge old messages out of each room)
1762 "users" (purge old users from the userlog)
1763 "rooms" (remove rooms which have not been posted in for some time)
1764 "visits" (purge dereferenced user/room relationship records)
1766 EXPI returns OK (probably after a long delay while it does its work) if it
1767 succeeds; otherwise it returns an ERROR code.
1769 This command is probably temporary, until we can work some sort of scheduler
1770 into the system. It is implemented in the serv_expire module.
1774 MSG4 (read MeSsaGe, mode 4 -- output in preferred MIME format)
1776 This is the equivalent of MSG0, except it's a bit smarter about messages in
1777 rich text formats. Immediately following the "text" directive, the server
1778 will output RFC822-like MIME part headers such as "Content-type:" and
1779 "Content-length:". MIME formats are chosen and/or converted based on the
1780 client's preferred format settings, which are set using the MSGP command,
1785 MSGP (set MeSsaGe Preferred MIME format)
1787 Client tells the server what MIME content types it knows how to handle, and
1788 the order in which it prefers them. This is similar to an HTTP "Accept:"
1791 The parameters to a MSGP command are the client's acceptable MIME content
1792 types, in the order it prefers them (from most preferred to least preferred).
1793 For example: MSGP text/html|text/plain
1795 The MSGP command always returns OK.
1799 OPNA (OPeN Attachment)
1801 Opens, as a download file, a component of a MIME-encoded message. The two
1802 parameters which must be passed to this command are the message number and the
1803 name of the desired section. If the message or section does not exist, an
1804 appropriate ERROR code will be returned; otherwise, if the open is successful,
1805 this command will succeed returning the same information as an OPEN command.
1808 GEXP (Get EXPress messages)
1810 This is a more sophisticated way of retrieving express messages than the old
1811 PEXP method. If there are no express messages waiting, PEXP returns ERROR;
1812 otherwise, it returns LISTING_FOLLOWS and the following arguments:
1814 0 - a boolean value telling the client whether there are any additional
1815 express messages waiting following this one
1816 1 - a Unix-style timestamp
1817 2 - flags (see server.h for more info)
1818 3 - the name of the sender
1819 4 - the node this message originated on (for future support of PIP, ICQ, etc.)
1821 The text sent to the client will be the body of the express message.
1823 So how does the client know there are express messages waiting? It could
1824 execute a random GEXP every now and then. Or, it can check the byte in
1825 server return code messages, between the return code and the parameters. In
1826 much the same way as FTP uses "-" to signify a continuation, Citadel uses
1827 an "*" in this position to signify the presence of waiting express messages.
1830 FSCK (check message base reference counts)
1832 Verify, via the long way, that all message referenmce counts are correct. If
1833 the user has permission to do this then LISTING_FOLLOWS is returned, followed
1834 by a transcript of the run. Otherwise ERROR is returned.
1837 DEXP (Disable EXPress messages)
1839 DEXP sets or clears the "disable express messages" flag. Pass this command a
1840 1 or 0 to respectively set or clear the flag. When the "disable express
1841 messages" flag is set, no one except Aides may send the user express messages.
1842 Any value other than 0 or 1 will not change the flag, only report its state.
1843 The command returns ERROR if it fails; otherwise, it returns OK followed by a
1844 number representing the current state of the flag.
1847 REQT (REQuest client Termination)
1849 Request that the specified client (or all clients) log off. Aide level
1850 access is required to run this command, otherwise ERROR+HIGHER_ACCESS_REQUIRED
1853 The REQT command accepts one parameter: the session ID of the client which
1854 should be terminated, or 0 for all clients. When successful, the REQT command
1857 It should be noted that REQT simply transmits an express message to the
1858 specified client(s) with the EM_GO_AWAY flag set. Older clients do not honor
1859 this flag, and it is certainly possible for users to re-program their client
1860 software to ignore it. Therefore the effects of the REQT command should be
1861 considered advisory only. The recommended implementation practice is to first
1862 issue a REQT command, then wait a little while (from 30 seconds up to a few
1863 minutes) for well-behaved clients to voluntarily terminate, and then issue a
1864 TERM command to forcibly disconnect the client (or perhaps a DOWN command, if
1865 you are logging off users for the purpose of shutting down the server).
1868 SEEN (set or clear the SEEN flag for a message)
1870 Beginning with version 5.80, Citadel supports the concept of setting or
1871 clearing the "seen" flag for each individual message, instead of only allowing
1872 a "last seen" pointer. In fact, the old semantics are implemented in terms
1873 of the new semantics. This command requires two arguments: the number of the
1874 message to be set, and a 1 or 0 to set or clear the "seen" bit.
1876 This command returns OK, unless the user is not logged in or a usage error
1877 occurred, in which case it returns ERROR. Please note that no checking is
1878 done on the supplied data; if the requested message does not exist, the SEEN
1879 command simply returns OK without doing anything.
1882 GTSN (GeT the list of SeeN messages)
1884 This command retrieves the list of "seen" (as opposed to unread) messages for
1885 the current room. It returns OK followed by an IMAP-format message list.
1888 SMTP (utility commands for the SMTP gateway)
1890 This command, accessible only by Aides, supports several utility operations
1891 which examine or manipulate Citadel's SMTP support. The first command argument
1892 is a subcommand telling the server what to do. The following subcommands are
1895 SMTP mx|hostname (display all MX hosts for 'hostname')
1896 SMTP runqueue (attempt immediate delivery of all messages
1897 in the outbound SMTP queue, ignoring any
1898 retry times stored there)
1901 STLS (Start Transport Layer Security)
1903 This command starts TLS on the current connection. The current
1904 implementation uses OpenSSL on both the client and server end. For future
1905 compatibility all clients must support at least TLSv1, and servers are
1906 guaranteed to support TLSv1. During TLS negotiation (see below) the server
1907 and client may agree to use a different protocol.
1909 The server returns ERROR if it does not support SSL or SSL initialization
1910 failed on the server; otherwise it returns OK. Once the server returns OK and
1911 the client has read the response, the server and client immediately negotiate
1912 TLS (in OpenSSL, using SSL_connect() on the client and SSL_accept() on the
1913 server). If negotiation fails, the server and client should attempt to resume
1914 the session unencrypted. If either end is unable to resume the session, the
1915 connection should be closed.
1917 This command may be run at any time.
1920 GTLS (Get Transport Layer Security Status)
1922 This command returns information about the current connection. The server
1923 returns OK plus several parameters if the connection is encrypted, and ERROR
1924 if the connection is not encrypted. It is primarily used for debugging. The
1925 command may be run at any time.
1927 0 - Protocol name, e.g. "SSLv3"
1928 1 - Cipher suite name, e.g. "ADH-RC4-MD5"
1929 2 - Cipher strength bits, e.g. 128
1930 3 - Cipher strength bits actually in use, e.g. 128
1933 IGAB (Initialize Global Address Book)
1935 This command creates, or re-creates, a database of Internet e-mail addresses
1936 using the vCard information in the Global Address Book room. This procedure
1937 is normally run internally when the server determines it necessary, but is
1938 also provided as a server command to be used as a troubleshooting/maintenenance
1939 tool. Only a system Aide can run the command. It returns OK on success or
1943 QDIR (Query global DIRectory)
1945 Look up an internet address in the global directory. Any logged-in user may
1946 call QDIR with one parameter, the Internet e-mail address to look up. QDIR
1947 returns OK followed by a Citadel address if there is a match, otherwise it
1948 returns ERROR+NOT_LOGGED_IN.
1951 ISME (find out if an e-mail address IS ME)
1953 This is a quickie shortcut command to find out if a given e-mail address
1954 belongs to the user currently logged in. Its sole argument is an address to
1955 parse. The supplied address may be in any format (local, IGnet, or Internet).
1956 The command returns OK if the address belongs to the user, ERROR otherwise.
1959 VIEW (set the VIEW for a room)
1961 Set the preferred view for the current user in the current room. Please see
1962 views.txt for more information on views. The sole parameter for this command
1963 is the type of view requested. VIEW returns OK on success or ERROR on failure.
1966 QNOP (Quiet No OPeration)
1968 This command does nothing, similar to the NOOP command. However, unlike the
1969 NOOP command, it returns *absolutely no response* at all. The client has no
1970 way of knowing that the command executed. It is intended for sending
1971 "keepalives" in situations where a full NOOP would cause the client protocol
1974 Naturally, sending this command to a server that doesn't support it is an
1975 easy way to mess things up. Therefore, client software should first check
1976 the output of an INFO command to ensure that the server supports quiet noops.
1980 ICAL (Internet CALendaring commands)
1982 This command supports a number of subcommands which are used to process the
1983 calendaring/scheduling support in Citadel. Here are the subcommands which
1987 Test server for calendaring support. Always returns OK unless the server
1988 does not have the calendar module enabled.
1990 ICAL respond|msgnum|partnum|action
1991 Respond to a meeting request. 'msgnum' and 'partnum' refer to a MIME-encoded
1992 meeting invitation in the current room. 'action' must be set to either
1993 "accept" or "decline" to determine the action to take. This subcommand will
1994 return either OK or ERROR.
1996 ICAL conflicts|msgnum|partnum
1997 Determine whether an incoming VEVENT will fit in the user's calendar by
1998 checking it against the existing VEVENTs. 'msgnum' and 'partnum' refer to
1999 a MIME-encoded meeting invitation in the current room (usually the inbox).
2000 This command may return ERROR if something went wrong, but usually it will
2001 return LISTING_FOLLOWS followed by a list of zero or more conflicting
2002 events. A zero-length list means that there were no conflicts.
2004 ICAL handle_rsvp|msgnum|partnum
2005 Handle an incoming "reply" (or RSVP) to a meeting request you sent out.
2006 'msgnum' and 'partnum' refer to a MIME-encoded reply in the current room.
2007 'action' must be set to either "update" or "ignore" to determine the action
2008 to take. If the action is "update" then the server will hunt for the meeting
2009 in the user's Calendar> room, and update the status for this attendee. Either
2010 way, the reply message is deleted from the current room. This subcommand will
2011 return either OK or ERROR.
2013 ICAL freebusy|username
2014 Output the free/busy times for the requested user. If the user specified
2015 has a calendar available, this command will return LISTING_FOLLOWS and a
2016 compound VCALENDAR object. That object, in turn, will contain VEVENT
2017 objects that have been stripped of all properties except for the bare
2018 minimum needed to learn free/busy times (such as DTSTART, DTEND, and
2019 TRANSP). If there is no such user, or no calendar available, the usual
2020 ERROR codes will be returned.
2022 Readers who are paying attention will notice that there is no subcommand to
2023 send out meeting invitations. This is because that task is handled
2024 automatically by the Citadel server. When an event is saved to the user's
2025 Calendar> room and it contains attendees, Citadel will automatically turn
2026 the event into vCalendar REQUEST messages and mail them out to all listed
2031 MRTG (Multi Router Traffic Grapher)
2033 Multi Router Traffic Grapher (please see http://www.mrtg.org for more info) is
2034 a tool which creates pretty graphs of network activity, usually collected from
2035 routers using SNMP. However, its ability to call external scripts has spawned
2036 a small community of people using it to graph anything which can be graphed.
2037 The MRTG command can output Citadel server activity in the format MRTG expects.
2039 This format is as follows:
2044 Line 3: uptime of system
2045 Line 4: name of system
2048 MRTG accepts two different keywords. "MRTG users" will return two variables,
2049 the number of connected users and the number of active users. "MRTG messages"
2050 will return one variable (and a zero in the second field), showing the current
2051 highest message number on the system. Any other keyword, or a missing keyword,
2052 will cause the MRTG command to return an ERROR code.
2054 Please get in touch with the Citadel developers if you wish to experiment with
2059 ASYN (ASYNchronous message support)
2061 Negotiate the use of asynchronous, or unsolicited, protocol messages. The
2062 only parameter specified should be 1 or 0 to indicate that the client can or
2063 cannot handle this type of messages. The server will reply OK followed by a
2064 1 or 0 to tell the client which mode it is now operating in.
2066 If the command is not available on the server (i.e. it returns ERROR), or
2067 if the command has not been executed by the client, it should be assumed that
2068 this mode of operation is NOT in effect.
2070 The client may also send any value other than 0 or 1 to simply cause the
2071 server to output its current state without changing it.
2073 When asynchronous protocol mode is in effect, the client MUST handle any
2074 asynchronous messages as they arrive, before doing anything else.
2079 ASYNCHRONOUS MESSAGES
2080 ---------------------
2082 When the client protocol is operating in asynchronous mode (please refer to
2083 the writeup of the ASYN command above), the following messages may arrive at
2087 901 (express message arriving)
2089 There is an express message intended for this client. When the client
2090 receives this message, it MUST act as if it just sent a GEXP command (the data
2091 following the 901 message WILL be a LISTING_FOLLOWS data transfer; in fact,
2092 the current implementation simply executes a GEXP command internally).