- SESSION LAYER PROTOCOL FOR CITADEL/UX
- (c) 1995-2003 by Art Cancro et. al. All Rights Reserved
+ SESSION LAYER PROTOCOL FOR THE CITADEL SYSTEM
+ (c) 1995-2004 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
------------
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)
The first step in logging in a user. This command takes one argument: the
name of the user to be logged in. If the user exists, a MORE_DATA return
code will be sent, which means the client should execute PASS as the next
-command. If the user does not exist, ERROR is returned.
+command. If the user does not exist, ERROR + NO_SUCH_USER is returned.
PASS (send PASSword)
The second step in logging in a user. This command takes one argument: the
password for the user we are attempting to log in. If the password doesn't
match the correct password for the user we specified for the USER command,
-or if a USER command has not been executed yet, ERROR is returned. If the
-password is correct, OK is returned and the user is now logged in... and
-most of the other server commands can now be executed. Along with OK, the
-following parameters are returned:
+ERROR + PASSWORD_REQUIRED is returned. If a USER command has not been
+executed yet, ERROR + USERNAME_REQUIRED is returned. If a user is already
+logged in, ERROR + ALREADY_LOGGED_IN is returned. If the password is
+correct, OK is returned and the user is now logged in... and most of the
+other server commands can now be executed. Along with OK, the following
+parameters are returned:
0 - The user's name (in case the client wants the right upper/lower casing)
1 - The user's current access level
configuration, and no password, so the client should immediately prompt the
user for a password and install it with the SETP command as soon as this
command completes. This command returns OK if the account was created and
-logged in, or ERROR if another user already exists with this name. If OK,
-it will also return the same parameters that PASS returns.
+logged in, ERROR + ALREADY_EXISTS if another user already exists with this
+name, ERROR + NOT_HERE if self-service account creation is disabled,
+ERROR + MAX_SESSIONS_EXCEEDED if too many users are logged in, ERROR +
+USERNAME_REQUIRED if a username was not provided, or ERROR + ILELGAL_VALUE
+if the username provided is invalid. If OK, it will also return the same
+parameters that PASS returns.
- Please note that the NEWU command should only be used for self-service user account
-creation. For administratively creating user accounts, please use the CREU command.
+ Please note that the NEWU command should only be used for self-service
+user account creation. For administratively creating user accounts, please
+use the CREU command.
SETP (SET new Password)
This command sets a new password for the currently logged in user. The
argument to this command will be the new password. The command always
returns OK, unless the client is not logged in, in which case it will return
-ERROR.
+ERROR + NOT_LOGGED_IN, or if the user is an auto-login user, in which case
+it will return ERROR + NOT_HERE.
CREU (CREate new User account)
- This command creates a new user account AND DOES NOT LOG IT IN. The argument to
-this command will be the name of the account. No case conversion is done
-on the name. Note that the new account is installed with a default
-configuration, and no password. This command returns OK if the account was created,
-or ERROR if another user already exists with this name.
-
- Please note that CREU is intended to be used for activities in which a system
-administrator is creating user accounts. For self-service user account creation,
-use the NEWU command.
+ This command creates a new user account AND DOES NOT LOG IT IN. The first
+argument to this command will be the name of the account. No case conversion
+is done on the name. Note that the new account is installed with a default
+configuration, and no password. The second argument is optional, and will be
+an initial password for the user. This command returns OK if the account was
+created, ERROR + HIGHER_ACCESS_REQUIRED if the user is not an Aide, ERROR +
+USERNAME_REQUIRED if no username was specified, or ERROR + ALREADY_EXISTS if
+another user already exists with this name.
+ Please note that CREU is intended to be used for activities in which a
+system administrator is creating user accounts. For self-service user
+account creation, use the NEWU command.
LKRN (List Known Rooms with New messages)
- List known rooms with new messages. If the client is not logged in, ERROR
-is returned. Otherwise, LISTING_FOLLOWS is returned, followed by the room
-listing. Each line in the listing contains the full name of a room, followed
-by the '|' symbol, and then a number that may contain the following bits:
-
+ List known rooms with new messages. If the client is not logged in, ERROR +
+NOT_LOGGED_IN is returned. Otherwise, LISTING_FOLLOWS is returned, followed
+by the room listing. Each line in the listing contains the full name of a
+room, followed by the '|' symbol, and then a number that may contain the
+following bits:
#define QR_PERMANENT 1 /* Room does not purge */
#define QR_PRIVATE 4 /* Set for any type of private room */
Then it returns another '|' symbol, followed by a second set of bits comprised
of the following:
+
#define QR2_SYSTEM 1 /* System room; hide by default */
#define QR2_SELFLIST 2 /* Self-service mailing list mgmt */
GETU (GET User configuration)
This command retrieves the screen dimensions and user options for the
-currently logged in account. ERROR will be returned if no user is logged
-in, of course. Otherwise, OK will be returned, followed by four parameters.
-The first parameter is the user's screen width, the second parameter is the
-user's screen height, and the third parameter is a bag of bits with the
-following meanings:
+currently logged in account. ERROR + NOT_LOGGED_IN will be returned if no
+user is logged in, of course. Otherwise, OK will be returned, followed by
+four parameters. The first parameter is the user's screen width, the second
+parameter is the user's screen height, and the third parameter is a bag of
+bits with the following meanings:
#define US_LASTOLD 16 /* Print last old message with new */
#define US_EXPERT 32 /* Experienced user */
user options (which were probably obtained with a GETU command, and perhaps
modified by the user) and writes them to the user account. This command
should be passed three parameters: the screen width, the screen height, and
-the option bits (see above).
+the option bits (see above). It returns ERROR + NOT_LOGGED_IN if no user is
+logged in, and ERROR + ILLEGAL_VALUE if the parameters are incorrect.
Note that there exist bits here which are not listed in this document. Some
are flags that can only be set by Aides or the system administrator. SETU
NOT_LOGGED_IN - Of course you can't go there. You didn't log in.
PASSWORD_REQUIRED - Either a password was not supplied, or the supplied
password was incorrect.
- NO_SUCH_ROOM - The requested room does not exist.
+ ROOM_NOT_FOUND - The requested room does not exist.
The typical procedure for entering a passworded room would be:
1. Execute a GOTO command without supplying any password.
- 2. ERROR+PASSWORD_REQUIRED will be returned. The client now knows that
+ 2. ERROR + PASSWORD_REQUIRED will be returned. The client now knows that
the room is passworded, and prompts the user for a password.
3. Execute a GOTO command, supplying both the room name and the password.
4. If OK is returned, the command is complete. If, however,
-ERROR+PASSWORD_REQUIRED is still returned, tell the user that the supplied
+ERROR + PASSWORD_REQUIRED is still returned, tell the user that the supplied
password was incorrect. The user remains in the room he/she was previously
in.
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.
- This command can return three possible results. An ERROR code may be returned
-if no user is currently logged in or if something else went wrong. Otherwise,
-LISTING_FOLLOWS will be returned, and the listing will consist of zero or
-more message numbers, one per line. The listing ends, as always, with the
-string "000" alone on a line by itself. The listed message numbers can be used
-to request messages from the system. If "search mode" is being used, the
-server will return START_CHAT_MODE, and the client is expected to transmit
-the search criteria, and then read the message list.
+ This command can return three possible results. ERROR + NOT_LOGGED_IN will
+be returned if no user is currently logged in. Otherwise, LISTING_FOLLOWS
+will be returned, and the listing will consist of zero or more message
+numbers, one per line. The listing ends, as always, with the string "000"
+alone on a line by itself. The listed message numbers can be used to request
+messages from the system. If "search mode" is being used, the server will
+return START_CHAT_MODE, and the client is expected to transmit the search
+criteria, and then read the message list.
Since this is somewhat complex, here are some examples:
criteria. These criteria are applied with an AND logic.
-
MSG0 (read MeSsaGe, mode 0)
This is a command used to read the text of a message. "Mode 0" implies that
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, an ERROR code will be returned. Otherwise, the
-LISTING_FOLLOWS code will be returned, followed by the contents of the message.
-The following fields may be sent:
+ 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
+the contents of the message. The following fields may be sent:
type= Formatting type. The currently defined types are:
0 = "traditional" Citadel formatting. This means that newlines should be
WHOK (WHO Knows room)
- This command is available only to Aides. ERROR+HIGHER_ACCESS_REQUIRED will
-be returned if the user is not an Aide. Otherwise, it returns
+ This command is available only to Aides. ERROR + HIGHER_ACCESS_REQUIRED
+will be returned if the user is not an Aide. Otherwise, it returns
LISTING_FOLLOWS and then lists, one user per line, every user who has
access to the current room.
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
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
+ directory service using LDAP.
*** NOTE! *** The "server type" code is intended to promote global
compatibility in a scenario in which developers have added proprietary
-> 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
RDIR (Read room DIRectory)
- Use this command to read the directory of a directory room. ERROR+NOT_HERE
-will be returned if the room has no directory, or some other error; ERROR +
-HIGHER_ACCESS_REQUIRED will be returned if the room's directory is not
-visible and the user does not have Aide or Room Aide privileges; otherwise
-LISTING_FOLLOWS will be returned, followed by the room's directory. Each
-line of the directory listing will contain three fields: a filename, the
-length of the file, and a description.
+ Use this command to read the directory of a directory room. ERROR + NOT_HERE
+will be returned if the room has no directory, ERROR + HIGHER_ACCESS_REQUIRED
+will be returned if the room's directory is not visible and the user does not
+have Aide or Room Aide privileges, ERROR + NOT_LOGGED_IN will be returned if
+the user is not logged in; otherwise LISTING_FOLLOWS will be returned,
+followed by the room's directory. Each line of the directory listing will
+contain three fields: a filename, the length of the file, and a description.
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
SLRP (Set Last-message-Read Pointer)
This command marks all messages in the current room as read (seen) up to and
-including the specified number. Its sole parameter
-is the number of the last message that has been read. This allows the pointer
-to be set at any arbitrary point in the room. Optionally, the parameter
-"highest" may be used instead of a message number, to set the pointer to the
-number of the highest message in the room, effectively marking all messages
-in the room as having been read (ala the Citadel <G>oto command).
+including the specified number. Its sole parameter is the number of the last
+message that has been read. This allows the pointer to be set at any
+arbitrary point in the room. Optionally, the parameter "highest" may be used
+instead of a message number, to set the pointer to the number of the highest
+message in the room, effectively marking all messages in the room as having
+been read (ala the Citadel <G>oto command).
- The command will return OK if the pointer was set, or ERROR if something
-went wrong. If OK is returned, it will be followed by a single argument
-containing the message number the last-read-pointer was set to.
+ The command will return OK if the pointer was set, or ERROR + NOT_LOGGED_IN
+if the user is not logged in. If OK is returned, it will be followed by a
+single argument containing the message number the last-read-pointer was set to.
INVT (INViTe a user to a room)
but it may also be used in other types of private rooms as well. Its sole
parameter is the name of the user to invite.
- The command will return OK if the operation succeeded, or ERROR if it did
-not. ERROR+HIGHER_ACCESS_REQUIRED may also be returned if the operation
-would have been possible if the user had higher access, and ERROR+NOT_HERE
-may be returned if the room is not a private room.
+ The command will return OK if the operation succeeded. ERROR + NO_SUCH_USER
+will be returned if the user does not exist, ERROR + HIGHER_ACCESS_REQUIRED
+will be returned if the operation would have been possible if the user had
+higher access, and ERROR + NOT_HERE may be returned if the room is not a
+private room.
KICK (KICK a user out of a room)
ERROR+NOT_LOGGED_IN - No user is logged in.
ERROR+HIGHER_ACCESS_REQUIRED - Not enough access. Typically, only aides
and the room aide associated with the current room, can access this command.
- ERROR+NOT_HERE - Lobby>, Mail>, and Aide> cannot be edited.
OK - Command succeeded. Parameters are returned.
If OK is returned, the following parameters will be returned as well:
5. The floor number on which the room should reside
6. The room listing order
7. The default view for the room (see views.txt)
- 8. A second set of flags (buts) associated with the room
+ 8. A second set of flags (bits) associated with the room
*Important: You should always use GETR to retrieve the current attributes of
the room, then change what you want to change, and then use SETR to write it
only toggle the bits you want to toggle. This will allow for upward
compatibility.
+ The _BASEROOM_, user's Mail> and Aide> rooms can only be partially edited.
+Any changes which cannot be made will be silently ignored.
+
If the room is a private room, you have the option of causing all users who
currently have access, to forget the room. If you want to do this, set the
"bump" flag to 1, otherwise set it to 0.
GETA
This command is used to get the name of the Room Aide for the current room.
-It will return ERROR+NOT_LOGGED_IN if no user is logged in, ERROR if there
-is no current room, or OK if the command succeeded. Along with OK there will
-be returned one parameter: the name of the Room Aide.
+It will return ERROR + NOT_LOGGED_IN if no user is logged in, or OK if the
+command succeeded. Along with OK there will be returned one parameter: the
+name of the Room Aide. A conforming server must guarantee that the user is
+always in some room.
SETA
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.)
- ERROR+NOT_HERE (No current room, or room cannot be edited.
-Under Citadel/UX, the Lobby> Mail> and Aide> rooms are non-editable.)
+ ERROR + NOT_LOGGED_IN (Not logged in.)
+ ERROR + HIGHER_ACCESS_REQUIRED (Higher access required.)
+ ERROR + NOT_HERE (Room cannot be edited.)
OK (Command succeeded.)
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.
having his/her mail forwarded, the forwarding address will be returned.
SEND_LISTING - The request is valid. The client should now transmit
the text of the message (ending with a 000 on a line by itself, as usual).
- ERROR - Miscellaneous error. (Explanation probably follows.)
ERROR + NOT_LOGGED_IN - Not logged in.
ERROR + HIGHER_ACCESS_REQUIRED - Higher access is required. An
explanation follows, worded in a form that can be displayed to the user.
MOVE (MOVE or copy a message to a different room)
- Move a message to a different room. The two arguments that should be passed
-to this command are the message number of the message to be deleted, and the
-name of the target room. If the operation succeeds, the message will be
-deleted from the current room and moved to the target room. An ERROR code
-usually means that either the user does not have permission to perform this
-operation, or that the target room does not exist.
-
- In Citadel/UX 5.55 and above, a third argument may be specified: 0 or 1 to
-designate whether the message should be moved (0) or copied (1) to the target
-room. In the case of a "copy" operation, the message's reference count is
-incremented, and a pointer to the message will exist in both the source *and*
-target rooms. In the case of a "move" operation, the message pointer is
-deleted from the source room and the reference count remains the same.
+ 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.
+ 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.
KILL (KILL current room)
1 - Private; can be entered by guessing the room's name
2 - Private; can be entered by knowing the name *and* password
3 - Private; invitation only (sometimes called "exclusive")
+ 4 - Personal (mailbox for this user only)
3 - Password for new room (if it is a type 2 room)
4 - Floor number on which the room should reside (optional)
5 - Set to 1 to avoid automatically gaining access to the created room.
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)
opposed to the floor picture's use in a floor listing).
- NETP (authenticate as network session with system NET Password)
+ 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
-two arguments: the node name of the calling system, and the system net
-password for the server. If the authentication succeeds, NETP will return
-OK, otherwise, it returns ERROR.
-
+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.
+
+ NSYN (Network SYNchronize room)
+
+ This command can be used to synchronize the contents of a room on the
+network. It is only usable by Aides. It accepts one argument: the name of
+a network node (which must be a valid one).
+
+ When NSYN is run, the *entire* contents of the current room will be spooled
+to the specified node, without regard to whether any of the messages have
+already undergone network processing. It is up to the receiving node to
+check for duplicates (the Citadel networker does handle this) and avoid
+posting them twice.
+
+ The command returns OK upon success or ERROR if the user is not an Aide.
+
+
NUOP (Network Upload OPen file)
Open a network spool file for uploading. The client must have already
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.
+ 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,
3 - Purge by message age. (Requires a value: number of days)
The format of this command is: GPEX <which>
- The value of <which> must be one of: "room" "floor" "site"
+ The value of <which> must be one of: "room" "floor" "site" "mailboxes"
If successful, GPEX returns OK followed by <policy>|<value>.
the list of available policies.
The format of this command is: SPEX <which>|<policy>|<value>
- The value of <which> must be one of: "room" "floor" "site"
+ The value of <which> must be one of: "room" "floor" "site" "mailboxes"
If successful, GPEX returns OK; otherwise, an ERROR code is returned.
13. Geographic location of this system
14. Name of the system administrator
15. Number of maximum concurrent sessions allowed on the server
- 16. Password for server-to-server networking
+ 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
23. Maximum number of worker threads
24. Port number for POP3 service
25. Port number for SMTP service
- 26. (unused)
+ 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)
CONF also accepts two additional commands: GETSYS and PUTSYS followed by an
arbitrary MIME type (such as application/x-citadel-internet-config) which
provides a means of storing generic configuration data in the Global System
Configuration room without the need to add extra get/set commands to the
server.
-
-
- EXPI (EXPIre system objects)
-
- Begins purge operations for objects which, according to site policy, are
-"old" and should be removed. EXPI should be called with one argument, one of:
-
- "messages" (purge old messages out of each room)
- "users" (purge old users from the userlog)
- "rooms" (remove rooms which have not been posted in for some time)
- "visits" (purge dereferenced user/room relationship records)
-
- EXPI returns OK (probably after a long delay while it does its work) if it
-succeeds; otherwise it returns an ERROR code.
-
- This command is probably temporary, until we can work some sort of scheduler
-into the system. It is implemented in the serv_expire module.
+
+ Please note that the LDAP-specific configs have no effect on Citadel servers
+in which LDAP support is not enabled.
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
TRANSP). If there is no such user, or no calendar available, the usual
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 is handled
-automatically by the Citadel server. 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.
+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.
+ GNET (Get NETwork configuration for this room)
+ SNET (Set NETwork configuration for this room)
+
+ These commands get/set the network configuration for the current room. Aide
+or Room Aide privileges are required, otherwise an ERROR code is returned.
+If the command succeeds, LISTING_FOLLOWS or SEND_LISTING is returned. The
+network configuration for a specific room includes neighbor nodes with whom
+the room is shared, and mailing list recipients. The format of the network
+configuration is described in the file "netconfigs.txt".
+
+
+
ASYN (ASYNchronous message support)
Negotiate the use of asynchronous, or unsolicited, protocol messages. The
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