APPLICATION LAYER PROTOCOL FOR THE CITADEL SYSTEM
- (c) 1995-2005 by Art Cancro et. al. All Rights Reserved
+ (c) 1995-2006 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
The protocols used below the application layer are beyond the scope of this
document, but we will briefly cover the methodology employed by Citadel.
- Citadel offers Citadel BBS service using TCP/IP. It does so via a
+ Citadel offers its client protocol using TCP/IP. It does so via a
multithreaded server listening on a TCP port. Local connections may also
be made using the same protocol using Unix domain sockets.
of UDP would render the server unstable and unusable, so we stick with TCP.
+ CHARACTER SETS
+ --------------
+
+ The native character set for the Citadel system is UTF-8. Unless otherwise
+specified, all data elements are expected to be in the UTF-8 character set.
+Specifically, all non-MIME messages should be assumed to be in UTF-8. MIME
+messages may be in whatever character set is specified by the MIME header, of
+course; however, some clients (such as WebCit) will automatically convert
+messages from other character sets before displaying them.
+
+
GENERAL INFORMATION ABOUT THE SERVER
------------------------------------
#define UA_ZAPPED 16 /* Zapped from known rooms list */
The sixth field is the user's current view for the room. (See VIEW command)
+ The seventh field is the *default* view for the room. (See VIEW command)
+ The eigth field is a unix timestamp which reflects the last time the room
+ was modified (created, edited, posted in, deleted from, etc.)
LKRO (List Known Rooms with Old [no new] messages)
allow client software to return to the base room when it doesn't know
where else to go.
- There are also two additional reserved room names:
- "_MAIL_" translates to the system's designated room for e-mail messages.
- "_BITBUCKET_" goes to whatever room has been chosen for messages
-without a home.
+ There are also several additional reserved room names:
+ "_MAIL_" goes to the user's inbox (i.e. the Mail> room).
+ "_TRASH_" goes to the user's personal trashcan room (trash folder).
+ "_BITBUCKET_" goes to a room that has been chosen for messages without a home.
+ "_CALENDAR_" goes to the user's primary personal calendar.
+ "_CONTACTS_" goes to the user's primary personal address book.
+ "_NOTES_" goes to the user's primary personal notes room.
+ "_TASKS_" goes to the user's primary personal task list.
+
The second (and optional) parameter is a password, if one is required for
access to the room. This allows for all types of rooms to be accessed via
10. The floor number this room resides on
11. The *current* "view" for this room (see views.txt for more info)
12. The *default* "view" for this room
+ 13. Boolian flag: 1 if this is the user's Trash folder, 0 otherwise.
The default view gives the client a hint as to what views the user should
be allowed to select. For example, it would be confusing to allow messages
which the client may request. This command may be passed a single parameter:
either "all", "old", or "new" to request all messages, only old messages, or
new messages. Or it may be passed two parameters: "last" plus a number, in
-which case that many message pointers will be returned, or "first" plus a
-number, for the corresponding effect. If no parameters are specified, "all"
-is assumed.
-
- In Citadel 5.00 and above, the client may also specify "gt" plus a number,
-to list all messages in the current room with a message number greater than
-the one specified.
-
- The third argument, valid only in Citadel 5.60 and above, may be either
-0 or 1. If it is 1, this command behaves differently: before a listing is
-returned, the client must transmit a list of fields to search for. The field
-headers are listed below in the writeup for the "MSG0" command.
+which case that many message pointers will be returned; "first" plus a
+number, for the corresponding effect; or "gt" plus a number, to list all
+messages in the current room with a message number greater than the one
+specified. If no parameters are specified, "all" is assumed.
+
+ In addition, the first parameter may be set to "search", in which case the
+third parameter must be a search string. This will request all messages
+in the current room whose text contains the search string.
+
+ The third argument, may be either 0 or 1. If it is 1, this command behaves
+differently: before a listing is returned, the client must transmit a list
+of fields to search for. The field headers are listed below in the writeup
+for the "MSG0" command.
+
+ The optional fourth argument may also be either 0 or 1. If it is 1, the
+output of this command will include not only a list of message numbers, but
+a simple header summary of each message as well. This is somewhat resource
+intensive so you shouldn't do this unless you absolutely need all the headers
+immediately. The fields which are output (in the usual delimited fashion, of
+course) are: message number, timestamp, display name, node name, Internet
+email address (if present), subject (if present).
This command can return three possible results. ERROR + NOT_LOGGED_IN will
be returned if no user is currently logged in. Otherwise, LISTING_FOLLOWS
backward compatibility. The current implementation defines the following
parts of the listing:
- Line 1 - Your unique session ID on the server
- Line 2 - The node name of the server BBS
- Line 3 - Human-readable node name of the server BBS
- Line 4 - The fully-qualified domain name (FQDN) of the server
- Line 5 - The name of the server software, i.e. "Citadel 4.00"
- Line 6 - (The revision level of the server code) * 100
- Line 7 - The geographical location of the BBS (city and state if in the US)
- Line 8 - The name of the system administrator
- Line 9 - A number identifying the server type (see below)
- Line 10 - The text of the system's paginator prompt
- Line 11 - Floor Flag. 1 if the system supports floors, 0 otherwise.
- Line 12 - Paging level. 0 if the system only supports inline paging,
+ Line 0 - Your unique session ID on the server
+ Line 1 - The node name of the Citadel server
+ Line 2 - Human-readable node name of the Citadel server
+ Line 3 - The fully-qualified domain name (FQDN) of the server
+ Line 4 - The name of the server software, i.e. "Citadel 4.00"
+ Line 5 - (The revision level of the server code) * 100
+ Line 6 - The geographical location of the site (city and state if in the US)
+ Line 7 - The name of the system administrator
+ Line 8 - A number identifying the server type (see below)
+ Line 9 - The text of the system's paginator prompt
+ Line 10 - Floor Flag. 1 if the system supports floors, 0 otherwise.
+ Line 11 - Paging level. 0 if the system only supports inline paging,
1 if the system supports "extended" paging (check-only and
multiline modes). See the SEXP command for further information.
- Line 13 - The "nonce" for this session, for support of APOP-style
+ Line 12 - The "nonce" for this session, for support of APOP-style
authentication. If this field is present, clients may authenticate
in this manner.
- Line 14 - Set to nonzero if this server supports the QNOP command.
- Line 15 - Set to nonzero if this server is capable of connecting to a
+ Line 13 - Set to nonzero if this server supports the QNOP command.
+ Line 14 - Set to nonzero if this server is capable of connecting to a
directory service using LDAP.
+ Line 15 - Set to nonzero if this server does *not* allow self-service
+ creation of new user accounts.
+ Line 16 - The default timezone for calendar items which do not have any
+ timezone specified and are not flagged as UTC. This will be a
+ zone name from the Olsen database.
*** NOTE! *** The "server type" code is intended to promote global
compatibility in a scenario in which developers have added proprietary
features to their servers or clients. We are attempting to avoid a future
situation in which users need to keep different client software around for
-each BBS they use. *Please*, if you are a developer and plan to add
+each Citadel they use. *Please*, if you are a developer and plan to add
proprietary features:
-> Your client programs should still be able to utilize servers other than
The server message contained on the same line with LISTING_FOLLOWS will
contain the name of the system and the name of the directory, such as:
- uncensored.citadel.org|/usr/bbs/files/my_room_directory
+ uncensored.citadel.org|/usr/local/citadel/files/my_room_directory
SLRP (Set Last-message-Read Pointer)
in vain that will not be permitted to be saved. If it is set to 2, the
server will accept an "apparent" post name if the user is privileged enough.
This post name is arg 5.
- 1 - Recipient. This argument is utilized only for private mail messages.
-It is ignored for public messages. It contains, of course, the name of the
-recipient of the message.
+ 1 - Recipient (To: field). This argument is utilized only for private
+mail. It is ignored for public messages. It contains, of course, the name
+of the recipient(s) of the message.
2 - Anonymous flag. This argument is ignored unless the room allows
anonymous messages. In such rooms, this flag may be set to 1 to flag a
message as anonymous, otherwise 0 for a normal message.
you set this to nonzero, ENT0 will reply with a confirmation message after
you submit the message text. The reply code for the ENT0 command will be
START_CHAT_MODE instead of SEND_LISTING.
+ 7 - Recipient (Cc: field). This argument is utilized only for private
+mail. It is ignored for public messages. It contains, of course, the name
+of the recipient(s) of the message.
+ 8 - Recipient (Bcc: field). This argument is utilized only for private
+mail. It is ignored for public messages. It contains, of course, the name
+of the recipient(s) of the message.
+ 9 - Exclusive message ID. When a message is submitted with an Exclusive
+message ID, any existing messages with the same ID will automatically be
+deleted. This is only applicable for Wiki rooms; other types of rooms either
+ignore the supplied ID (such as message boards and mailboxes) or derive the
+ID from a UUID native to the objects stored in them (such as calendars and
+address books).
Possible result codes:
OK - The request is valid. (Client did not set the "post" flag, so the
DELE (DELEte a message)
- Delete a message from the current room. The one argument that should be
-passed to this command is the message number of the message to be deleted.
-The return value will be OK if the message was deleted, or an ERROR code.
-If the delete is successful, the message's reference count is decremented, and
-if the reference count reaches zero, the message is removed from the message
-base.
+ Delete one or more messages from the current room. The one argument that
+should be passed to this command is a message number, or a list of message
+numbers separated by commas, to be deleted.
+
+ The return value will be OK if one or more messages were deleted, or an ERROR
+code. If the delete is successful, the messages' reference counts are
+decremented, and if the reference count reaches zero, the messages are removed
+from the message base.
MOVE (MOVE or copy a message to a different room)
Move or copy a message to a different room. This command expects to be
passed three arguments:
- 0: the message number of the message to be moved or copied.
+ 0: the message number(s) of the message to be moved or copied.
1: the name of the target room.
2: flag: 0 to move the message, 1 to copy it without deleting from the
source room.
This command never creates or deletes copies of a message; it merely moves
around links. When a message is moved, its reference count remains the same.
When a message is copied, its reference count is incremented.
+
+ You can move/copy multiple messages with a single command by separating the
+message numbers with commas; for example: MOVE 112,113,114|Trash|0
KILL (KILL current room)
Unlisted entries will also be listed to Aides logged into the server, but
not to ordinary users.
+
+ The LIST command accepts an optional single argument, which is a simple,
+case-insensitive search string. If this argument is present, only usernames
+in which the search string is present will be returned. It is a simple
+substring search, not a regular expression search. If this string is empty
+or not present, all users will be returned.
REGI (send REGIstration)
NETP (authenticate as network session with connection NET Password)
This command is used by client software to identify itself as a transport
-session for IGnet/Open BBS to BBS networking. It should be called with
+session for Citadel site-to-site networking. It should be called with
two arguments: the node name of the calling system, and the "shared secret"
password for that connection. If the authentication succeeds, NETP will
return OK, otherwise, it returns ERROR.
identified itself as a network session using the NETP command. If the command
returns OK, the client may begin transmitting IGnet/Open spool data using
a series of WRIT commands. When a UCLS command is issued, the spooled data
-is entered into the BBS if the argument to UCLS is 1 or discarded if the
+is entered into the server if the argument to UCLS is 1 or discarded if the
argument to UCLS is 0. If the client has not authenticated itself with a
NETP command, ERROR+HIGHER_ACCESS_REQUIRED will be returned.
The Citadel server understands the following commands:
/quit - Exit from chat mode (causes the server to do an 000 end)
/who - List users currently in chat
- /whobbs - List users currently in chat and on the bbs
+ /whobbs - List users currently in chat and elsewhere
/me - Do an irc-style action.
/join - Join a new "room" in which all messages are only heard by
people in that room.
of the flag.
+ HALT (HALT the server without shutting it down)
+
+ Identical to the DOWN command, except instead of exiting, the server process
+cleans up and then suspends indefinitely. This could potentially be useful for
+shutdown scripts that don't want init to automatically respawn another citserver
+process.
+
+
EMSG (Enter a system MeSsaGe)
This is the opposite of the MESG command - it allows the creation and editing
The configuration lines are as follows:
- 1. Node name
- 2. Fully qualified domain name
- 3. Human-readable node name
- 4. Landline telephone number of this system
- 5. Flag (0 or 1) - creator of private room automatically becomes room aide
- 6. Server connection idle timeout (in seconds)
- 7. Initial access level for new users
- 8. Flag (0 or 1) - require registration for new users
- 9. Flag (0 or 1) - automatically move Problem User messages to twit room
- 10. Name of twit room
- 11. Text of <more> prompt
- 12. Flag (0 or 1) - restrict access to Internet mail
- 13. Geographic location of this system
- 14. Name of the system administrator
- 15. Number of maximum concurrent sessions allowed on the server
- 16. (placeholder -- this field is no longer in use)
- 17. Default purge time (in days) for users
- 18. Default purge time (in days) for rooms
- 19. Name of room to log instant messages to (or a zero-length name for none)
- 20. Access level required to create rooms
- 21. Maximum message length which may be entered into the system
- 22. Minimum number of worker threads
- 23. Maximum number of worker threads
- 24. Port number for POP3 service
- 25. Port number for SMTP service
- 26. Flag (0 or 1) - strict RFC822 adherence - don't correct From: forgeries
- 27. Flag (0 or 1) - allow Aides to zap (forget) rooms
- 28. Port number for IMAP service
- 29. How often (in seconds) to run the networker
- 30. Flag (0 or 1) - disable self-service new user registration
- 31. (placeholder -- this field is no longer in use)
- 32. Hour (0 through 23) during which database auto-purge jobs are run
- 33. Name of host where an LDAP service may be found
- 34. Port number of LDAP service on above host
- 35. LDAP Base DN
- 36. LDAP Bind DN
- 37. Password for LDAP Bind DN
- 38. Server IP address to listen on (or "0.0.0.0" for all addresses)
+ 0. Node name
+ 1. Fully qualified domain name
+ 2. Human-readable node name
+ 3. Landline telephone number of this system
+ 4. Flag (0 or 1) - creator of private room automatically becomes room aide
+ 5. Server connection idle timeout (in seconds)
+ 6. Initial access level for new users
+ 7. Flag (0 or 1) - require registration for new users
+ 8. Flag (0 or 1) - automatically move Problem User messages to twit room
+ 9. Name of twit room
+ 10. Text of <more> prompt
+ 11. Flag (0 or 1) - restrict access to Internet mail
+ 12. Geographic location of this system
+ 13. Name of the system administrator
+ 14. Number of maximum concurrent sessions allowed on the server
+ 15. (placeholder -- this field is no longer in use)
+ 16. Default purge time (in days) for users
+ 17. Default purge time (in days) for rooms
+ 18. Name of room to log instant messages to (or a zero-length name for none)
+ 19. Access level required to create rooms
+ 20. Maximum message length which may be entered into the system
+ 21. Minimum number of worker threads
+ 22. Maximum number of worker threads
+ 23. Port number for POP3 service
+ 24. Port number for SMTP service
+ 25. Flag (0 or 1) - strict RFC822 adherence - don't correct From: forgeries
+ 26. Flag (0 or 1) - allow Aides to zap (forget) rooms
+ 27. Port number for IMAP service
+ 28. How often (in seconds) to run the networker
+ 29. Flag (0 or 1) - disable self-service new user registration
+ 30. (placeholder -- this field is no longer in use)
+ 31. Hour (0 through 23) during which database auto-purge jobs are run
+ 32. Name of host where an LDAP service may be found
+ 33. Port number of LDAP service on above host
+ 34. LDAP Base DN
+ 35. LDAP Bind DN
+ 36. Password for LDAP Bind DN
+ 37. Server IP address to listen on (or "0.0.0.0" for all addresses)
+ 38. Port number for SMTP MSA service
+ 39. Port number for IMAPS (SSL-encrypted IMAP)
+ 40. Port number for POP3S (SSL-encrypted POP3)
+ 41. Port number for SMTPS (SSL-encrypted SMTP)
+ 42. Flag (0 or 1) - enable full text search index
+ 43. Flag (0 or 1) - automatically cull database log files
+ 44. Flag (0 or 1) - enable IMAP "instant expunge" of deleted messages
+ 45. Flag (0 or 1) - allow unauthenticated SMTP clients to spoof my domains
+ 46. Flag (0 or 1) - perform journaling of email messages
+ 47. Flag (0 or 1) - perform journaling of non-email messages
+ 48. Address to which journalized messages are to be sent
+ 49. Default time zone (Olsen database name) for unzoned calendar items
+ 50. Port number for Postfix TCP Dict (http://www.postfix.org/tcp_table.5.html)
CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
arbitrary MIME type (such as application/x-citadel-internet-config) which
"Content-length:". MIME formats are chosen and/or converted based on the
client's preferred format settings, which are set using the MSGP command,
described below.
+
+ The MSG4 command also accepts an optional second argument, which may be the
+MIME part specifier of an encapsulated message/rfc822 message. This is useful
+for fetching the encapsulated message instead of the top-level message, for
+example, when someone has forwarded a message as an attachment. Note that the
+only way for the client to know the part specifier is to fetch the top-level
+message and then look for attachments of type message/rfc822, and then call
+MSG4 again with that part specifier.
+
this command will succeed returning the same information as an OPEN command.
+ DLAT (DownLoad ATtachment)
+
+ Similar to OPNA, and with the same calling syntax. The difference is that
+instead of opening a download file for block transfer, this command outputs the
+entire decoded MIME section at once, using a BINARY_FOLLOWS response. This is
+useful for outputting small objects such as calendar items.
+
+
GEXP (Get instant messages)
This is a more sophisticated way of retrieving instant messages than the old
ERROR codes will be returned.
ICAL sgi|<bool>
+ Readers who are paying attention will notice that there is no subcommand to
+ send out meeting invitations. This is because that task can be handled
+ automatically by the Citadel server. Issue this command with <bool> set to 1
+ to enable Server Generated Invitations. In this mode, when an event is saved
+ to the user's Calendar> room and it contains attendees, Citadel will
+ automatically turn the event into calendar REQUEST messages and mail them
+ out to all listed attendees. If for some reason the client needs to disable
+ Server Generated Invitations, the command may be sent again with <bool> = 0.
+
+ ICAL getics
+ Output the contents of the entire calendar (assuming we are in a calendar
+ room) as one big data stream. All of the events (or tasks, etc.) in the room
+ are combined into a single VCALENDAR object, which is then serialized and
+ transmitted to the client. This is suitable for subscribing to a calendar
+ in third-party software. This command will output LISTING_FOLLOWS followed
+ by the calendar data stream, or ERROR if the requested operation is not
+ permitted.
- Readers who are paying attention will notice that there is no subcommand to
-send out meeting invitations. This is because that task can be handled
-automatically by the Citadel server. Issue this command with <bool> set to 1
-to enable Server Generated Invitations. In this mode, when an event is saved
-to the user's Calendar> room and it contains attendees, Citadel will
-automatically turn the event into vCalendar REQUEST messages and mail them
-out to all listed attendees. If for some reason the client needs to disable
-Server Generated Invitations, the command may be sent again with <bool> = 0.
+ ICAL putics
+ Delete the entire contents of a calendar room and replace it with the calendar
+ supplied by a client-input data stream. This is suitable for publishing a
+ calendar from third-party software. This command will output SEND_LISTING and
+ then expect the client to transmit the calendar data stream. Alternatively,
+ it will return ERROR if the requested operation is not permitted.
+ AUTO (AUTOcompletion of email addresses)
+
+ The AUTO command is used by clients which want to request a list of email
+recipients whose names or email addresses match a partial string supplied by
+the client. This string is the only parameter passed to this command. The
+command will return ERROR if no user is logged in or if no address book could
+be found; otherwise, it returns LISTING_FOLLOWS followed by zero or more
+candidate recipients.
+
+
+
+ SRCH (SeaRCH the message base)
+
+ This command's implementation is incomplete and will be documented when it
+is finished. The current implementation accepts a search string as its sole
+argument, and will respond with LISTING_FOLLOWS followed by a list of
+messages (globally, not just in the current room) which contain ALL of the
+words in the search string. If the client desires an "exact phrase" match,
+it must then slow-search the text of each returned message for the exact
+string. The client should also compare the returned message numbers against
+those which actually exist in the room or rooms being searched. In
+particular, clients should avoid telling the user about messages which exist
+only in rooms to which the user does not have access.
+
+ Again, keep in mind that this is a temporary implementation and is not
+guaranteed to continue to exist in this form.
+
+
+
+EUID (get message number using an EUID)}
+
+ Returns the message number, if present, of the message in the current room
+which is indexed using the supplied EUID (exclusive message ID). There can be
+only one message in a room with any given EUID; if another message arrives
+with the same EUID, the existing one is replaced. This makes it possible to
+reference things like calendar items using an immutable URL that does not
+change even when the message number changes due to an update.
+
+ The format of this command is: EUID <euid>
+
+ If successful, EUID returns OK followed by a message number.
+ If no message exists in the current room with the supplied EUID, the command
+returns ERROR+MESSAGE_NOT_FOUND.
+
+
+MSIV (Manage SIeVe scripts)
+
+This command is the interface to Citadel's implementation of Sieve, the
+mail filtering and sorting language. Clients may automate the handling
+of incoming messages to their inbox by administering one or more Sieve
+scripts. The available subcommands are:
+
+ MSIV putscript|<scriptname>
+ Add a new script or replace an existing one. Always returns
+SEND_LISTING and expects the client to transmit the script content.
+
+ MSIV listscripts
+
+ List the scripts which are available for this account. Returns
+LISTING_FOLLOWS followed by a list of available scripts. Each line of
+the output contains two parameters: the name of the script, and 0 or 1
+to indicate whether the script is active.
+
+ MSIV setactive|<scriptname>
+
+ Choose which script is to become the active one that handles the
+user's inbox. <scriptname> must be either the name of an existing
+script or an empty string to indicate that the user wishes to disable
+all scripts. Returns OK if successful, or ERROR if the supplied name
+is invalid.
+
+ MSIV getscript|<scriptname>
+
+ Output one of the existing scripts. Returns LISTING_FOLLOWS followed
+by the script, or ERROR if the named script does not exist.
+
+ MSIV deletescript|<scriptname>
+
+ Delete one of the existing scripts. Returns OK if the script was
+deleted, or ERROR if the named script does not exist or cannot be
+deleted because it is active.
+
+
+
+
ASYNCHRONOUS MESSAGES
---------------------
projects / citadel.git / blobdiff