- SESSION LAYER PROTOCOL FOR CITADEL/UX
+ SESSION LAYER PROTOCOL FOR THE CITADEL SYSTEM
(c) 1995-2004 by Art Cancro et. al. All Rights Reserved
------------
This is an attempt to document the session layer protocol used by the
-Citadel/UX system, beginning with version 4.00, which is the first version
+Citadel system, beginning with version 4.00, which is the first version
to implement a client/server paradigm. It is intended as a resource for
programmers who intend to develop their own Citadel clients, but it may have
other uses as well.
developments ahead of time, please at least send in an e-mail documenting
what you did, so that your new commands can be added to this document.
- The coordinator of the Citadel/UX project is Art Cancro
+ The coordinator of the Citadel project is Art Cancro
<ajc@uncensored.citadel.org>.
----------------------
The protocols used below the session layer are beyond the scope of this
-document, but we will briefly cover the methodology employed by Citadel/UX.
+document, but we will briefly cover the methodology employed by Citadel.
- Citadel/UX offers Citadel BBS service using TCP/IP. It does so via a
-multithreaded server listening on a TCP port. Older (4.xx) versions employed
-an inetd-based server.
+ Citadel offers Citadel BBS service 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.
The port number officially assigned to Citadel by the IANA is 504/tcp. Since
our session layer assumes a clean, reliable, sequenced connection, the use
COMMANDS
--------
- This is a listing of all the commands that a Citadel/UX server can execute.
+ This is a listing of all the commands that a Citadel server can execute.
NOOP (NO OPeration)
number, for the corresponding effect. If no parameters are specified, "all"
is assumed.
- In Citadel/UX 5.00 and above, the client may also specify "gt" plus a number,
+ 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/UX 5.60 and above, may be either
+ 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.
0 = Headers and body
1 = Headers only
2 = Body only
+ 3 = Headers only, with MIME information suppressed (this runs faster)
If the request is denied, ERROR + NOT_LOGGED_IN or ERROR + MESSAGE_NOT_FOUND
will be returned. Otherwise, LISTING_FOLLOWS will be returned, followed by
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/UX 4.00"
+ 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
-> Please contact Art Cancro <ajc@uncensored.citadel.org> and obtain a unique
server type code, which can be assigned to your server program.
-> If you document what you did in detail, perhaps it can be added to a
-future release of the Citadel/UX program, so everyone can enjoy it. Better
+future release of the Citadel program, so everyone can enjoy it. Better
yet, just work with the Citadel development team on the main source tree.
If everyone follows this scheme, we can avoid a chaotic situation with lots
The opposite of GETA, used to set the Room Aide for the current room. One
parameter should be passed, which is the name of the user who is to be the
-new Room Aide. Under Citadel/UX, this command may only be executed by Aides
+new Room Aide. Under Citadel, this command may only be executed by Aides
and by the *current* Room Aide for the room. Return codes possible are:
ERROR + NOT_LOGGED_IN (Not logged in.)
ERROR + HIGHER_ACCESS_REQUIRED (Higher access required.)
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.
- 3 - Format type. Any valid Citadel/UX format type may be used (this will
+ 3 - Format type. Any valid Citadel format type may be used (this will
typically be 0; see the MSG0 command above).
4 - Subject. If present, this argument will be used as the subject of
the message.
This command is used to display system messages and/or help files. The
single argument it accepts is the name of the file to display. IT IS CASE
-SENSITIVE. Citadel/UX looks for these files first in the "messages"
+SENSITIVE. Citadel looks for these files first in the "messages"
subdirectory and then in the "help" subdirectory.
If the file is found, LISTING_FOLLOWS is returned, followed by a pathname
really paranoid, and warns that aides can still see
unlisted userlog entries.
- Citadel/UX provides these for the Citadel/UX Unix text client. They are
+ Citadel provides these for the Citadel Unix text client. They are
probably not very useful for other clients:
mainmenu - Main menu (when in idiot mode).
ever returned. LISTING_FOLLOWS will be returned, followed by zero or more
lines containing the following three fields:
- 0 - Session ID. Citadel/UX fills this with the pid of a server program.
+ 0 - Session ID. Citadel fills this with the pid of a server program.
1 - User name.
2 - The name of the room the user is currently in. This field might not
be displayed (for example, if the user is in a private room) or it might
cannot be opened at the same time. OIMG returns the same result codes as OPEN.
All images will be in GIF (Graphics Interchange Format). In the case of
-Citadel/UX, the server will convert the supplied filename to all lower case,
+Citadel, the server will convert the supplied filename to all lower case,
append the characters ".gif" to the filename, and look for it in the "images"
subdirectory. As with the MESG command, there are several "well known"
images which are likely to exist on most servers:
goodbye - Logoff banner graphics to be displayed alongside MESG "goodbye"
background - Background image (usually tiled) for graphical clients
- The following "special" image names are defined in Citadel/UX server version
+ The following "special" image names are defined in Citadel server version
5.00 and above:
_userpic_ - Picture of a user (send the username as the second argument)
further traffic to the server. The next transmission sent to the server
will be a regular server command.
- The Citadel/UX server understands the following commands:
+ 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
to other users currently in chat.
- SEXP (Send EXPress messages)
+ SEXP (Send instant message)
- This is one of two commands which implement "express messages" (also known
-as "paging"). An express message is a near-real-time message sent from one
-logged in user to another. When an express message is sent, it will be
+ This is one of two commands which implement instant messages (also known
+as "paging"). Commands ending in "...EXP" are so-named because we called
+them "express messages" before the industry standardized on the term
+"instant messages." When an instant message is sent, it will be
+logged in user to another. When an instant message is sent, it will be
displayed the next time the target user executes a PEXP or GEXP command.
The SEXP command accepts two arguments: the name of the user to send the
client can then transmit a multi-line page.
The reserved name "broadcast" may be used instead of a user name, to
-broadcast an express message to all users currently connected to the server.
+broadcast an instant message to all users currently connected to the server.
- Do be aware that if an express message is transmitted to a user who is logged
-in using a client that does not check for express messages, the message will
-never be received. Also, express messages are NOT sent via the following
+ Do be aware that if an instant message is transmitted to a user who is logged
+in using a client that does not check for instant messages, the message will
+never be received. Also, instant messages are NOT sent via the following
transports: SMTP, POP3.
- PEXP (Print EXPress messages) ***DEPRECATED***
+ PEXP (Print instant messages) ***DEPRECATED***
This command is deprecated; it will eventually disappear from the protocol and
its use is not recommended. Please use the GEXP command instead.
Called without any arguments, PEXP simply dumps out the contents
-of any waiting express messages. It returns ERROR if there is a problem,
+of any waiting instant messages. It returns ERROR if there is a problem,
otherwise it returns LISTING_FOLLOWS followed by all messages.
- So how does the client know there are express messages waiting? It could
+ So how does the client know there are instant messages waiting? It could
execute a random PEXP every now and then. Or, it can check the byte in
server return code messages, between the return code and the parameters. In
much the same way as FTP uses "-" to signify a continuation, Citadel uses
-an "*" in this position to signify the presence of waiting express messages.
+an "*" in this position to signify the presence of waiting instant messages.
EBIO (Enter BIOgraphy)
MSG2 follows the same calling convention as MSG0. The difference between
the two commands is that MSG2 outputs messages in standard RFC822 format
-rather than in Citadel/UX proprietary format.
+rather than in Citadel proprietary format.
This command was implemented in order to make various gateway programs
easier to implement, and to provide some sort of multimedia support in the
The first parameter supplied to UIMG should be 0 if the client is only checking
for permission to upload, or 1 if the client is actually attempting to begin
the upload operation. The second argument is the name of the file to be
-transmitted. In Citadel/UX, the filename is converted to all lower case,
+transmitted. In Citadel, the filename is converted to all lower case,
appended with the characters ".gif", and stored in the "images" directory.
UIMG returns OK if the client has permission to perform the requested upload,
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 express messages to (or a zero-length name for none)
+ 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
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. Flag (0 or 1) - Aides are allowed access to all mailboxes
+ 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
+ 37. Password for LDAP Bind DN
+ 38. Server IP address to listen on (or "0.0.0.0" for all addresses)
CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
arbitrary MIME type (such as application/x-citadel-internet-config) which
this command will succeed returning the same information as an OPEN command.
- GEXP (Get EXPress messages)
+ GEXP (Get instant messages)
- This is a more sophisticated way of retrieving express messages than the old
-PEXP method. If there are no express messages waiting, PEXP returns ERROR;
+ This is a more sophisticated way of retrieving instant messages than the old
+PEXP method. If there are no instant messages waiting, PEXP returns ERROR;
otherwise, it returns LISTING_FOLLOWS and the following arguments:
0 - a boolean value telling the client whether there are any additional
- express messages waiting following this one
+ instant messages waiting following this one
1 - a Unix-style timestamp
2 - flags (see server.h for more info)
3 - the name of the sender
4 - the node this message originated on (for future support of PIP, ICQ, etc.)
- The text sent to the client will be the body of the express message.
+ The text sent to the client will be the body of the instant message.
- So how does the client know there are express messages waiting? It could
+ So how does the client know there are instant messages waiting? It could
execute a random GEXP every now and then. Or, it can check the byte in
server return code messages, between the return code and the parameters. In
much the same way as FTP uses "-" to signify a continuation, Citadel uses
-an "*" in this position to signify the presence of waiting express messages.
+an "*" in this position to signify the presence of waiting instant messages.
FSCK (check message base reference counts)
by a transcript of the run. Otherwise ERROR is returned.
- DEXP (Disable EXPress messages)
+ DEXP (Disable receiving instant messages)
- DEXP sets or clears the "disable express messages" flag. Pass this command a
-1 or 0 to respectively set or clear the flag. When the "disable express
-messages" flag is set, no one except Aides may send the user express messages.
+ DEXP sets or clears the "disable instant messages" flag. Pass this command a
+1 or 0 to respectively set or clear the flag. When the "disable instant
+messages" flag is set, no one except Aides may send the user instant messages.
Any value other than 0 or 1 will not change the flag, only report its state.
The command returns ERROR if it fails; otherwise, it returns OK followed by a
number representing the current state of the flag.
should be terminated, or 0 for all clients. When successful, the REQT command
returns OK.
- It should be noted that REQT simply transmits an express message to the
+ It should be noted that REQT simply transmits an instant message to the
specified client(s) with the EM_GO_AWAY flag set. Older clients do not honor
this flag, and it is certainly possible for users to re-program their client
software to ignore it. Therefore the effects of the REQT command should be
any time:
- 901 (express message arriving)
+ 902 (instant message arriving)
- There is an express message intended for this client. When the client
-receives this message, it MUST act as if it just sent a GEXP command (the data
-following the 901 message WILL be a LISTING_FOLLOWS data transfer; in fact,
-the current implementation simply executes a GEXP command internally).
+ One or more instant messages have arrived for this client.
projects / citadel.git / blobdiff