SESSION LAYER PROTOCOL FOR CITADEL/UX
- (c) 1995-2000 by Art Cancro et. al. All Rights Reserved
+ (c) 1995-2002 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
what you did, so that your new commands can be added to this document.
The coordinator of the Citadel/UX project is Art Cancro
-<ajc@uncnsrd.mt-kisco.ny.us>.
+<ajc@uncensored.citadel.org>.
CONNECTING TO A SERVER
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.
-
- The port number officially assigned to Citadel by the IANA is TCP/504. Since
+
+ 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
of UDP would render the server unstable and unusable, so we stick with TCP.
Unlike protocols such as FTP, all data transfers occur in-band. This means
that the same connection that is used for exchange of client/server
messages, will also be used to transfer data back and forth. (FTP opens a
-separate connection for data transfers.) We do this to allow the server to
-function over transports which can only handle one session at a time (such
-as a dialup connection).
+separate connection for data transfers.) This keeps protocol administration
+straightforward, as it can traverse firewalls without any special protocol
+support on the firewall except for opening the port number.
RESULT CODES
should begin sending a listing of some sort. The client *must* send something,
even if it is an empty listing. Again, the listing ends with "000" on a line
by itself.
-
+ BINARY_FOLLOWS and SEND_BINARY mean that the client must immediately send
+or receive a block of binary data. The first parameter will always be the
+number of bytes.
+ ASYNC_MESSAGE_FOLLOWS means that an asynchronous, or unsolicited, message
+follows. The next line will be one of the above codes, and if a data transfer
+is involved it must be handled immediately. Note that the client will not
+receive this type of response unless it indicates to the server that it is
+capable of handling them; see the writeup of the ASYN command later in this
+document.
PARAMETERIZATION
----------------
3 - Messages posted
4 - Various flags (see citadel.h)
5 - User number
+ 6 - Time of last call (UNIX timestamp)
NEWU (create NEW User account)
- This command creates a new user account and logs it in. The argument to
+ This command creates a new user account AND LOGS 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, so the client should immediately prompt the
logged in, or ERROR if another user already exists with this name. 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.
+
SETP (SET new Password)
ERROR.
+ 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.
+
+
+
LKRN (List Known Rooms with New messages)
List known rooms with new messages. If the client is not logged in, ERROR
your own.
-> Clients other than your own should still be able to utilize your server,
even if your proprietary extensions aren't supported.
- -> Please contact Art Cancro <ajc@uncnsrd.mt-kisco.ny.us> and obtain a unique
+ -> 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
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:
- uncnsrd.mt-kisco.ny.us|/usr/bbs/files/my_room_directory
+ uncensored.citadel.org|/usr/bbs/files/my_room_directory
SLRP (Set Last-message-Read Pointer)
- This command is used to mark messages as having been read. Its sole parameter
+ 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
Line 8: Telephone number
Line 9: Access level
Line 10: Internet e-mail address
+ Line 11: Country
Users without Aide privileges may retrieve their own registration using
this command. This can be accomplished either by passing the user's own
Line 5: ZIP Code
Line 6: Telephone number
Line 7: e-mail address
+ Line 8: Country
CHEK (CHEcK various things)
IPGM is a low-level command that should not be used by normal user clients.
It is used for various utilities to communicate with the server on the same
-host. For example, the networker (netproc.c) logs onto the server as an
-internal program in order to fetch and store messages. Since user clients
+host. For example, the "sendcommand" utility logs onto the server as an
+internal program in order to run arbitrary server commands. Since user clients
do not utilize this command (or any of its companion commands), developers
writing Citadel-compatible servers need not implement it.
Receive from the server a named user's bio. This command should be passed
a single argument - the name of the user whose bio is requested. RBIO returns
-LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file,
-ERROR+NO_SUCH_USER if the named user does not exist, or ERROR+FILE_NOT_FOUND
-if the user exists but has no bio on file.
+LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file.
+The return has the following parameters: the user name, user number, access
+level, date of last call, times called, and messages posted. This command
+returns ERROR+NO_SUCH_USER if the named user does not exist.
+
+ RBIO no longer considers a user with no bio on file to be an error condition.
+It now returns a message saying the user has no bio on file as the text of the
+bio. This allows newer servers to operate with older clients.
STEL (enter STEaLth mode)
on disk.
- ENT3 (ENTer message, mode 3 -- internal command)
-
- ENT3 is for use by internal programs only and should not be utilized by
-user-mode clients. It does require IPGM authentication. This command posts
-a raw message straight into the message base without modification or performing
-any checks. It accepts the following arguments:
-
- 0 - Post flag. This should be set to 1 to post a message. If it is
-set to 0, the server only returns OK or ERROR (plus any flags describing
-the error) without reading in a message. This is used to verify the operation
-before actually transmitting a message.
- 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.
- 2 - The size (in bytes) of the message to be transmitted.
-
- ENT3 returns OK to tell the client that a message can be posted, ERROR if
-there would be a problem with the operation, or SEND_BINARY followed by a byte
-count if it is expecting the message to be transmitted.
-
-
TERM (TERMinate another session)
In a multithreaded environment, it sometimes becomes necessary to terminate
a client program is prohibited from terminating the session it is currently
running on.
-
- NSET (Network SETup commands)
-
- Aides may use this command to configure the networker. This command's
-parameters are passed directly to the 'netsetup' command line utility. If
-netsetup returns a non-zero exit code, ERROR is returned, along with the
-error message (if any). If netsetup returns a zero (success) exit code,
-LISTING_FOLLOWS is returned, followed by zero or more lines of output (since
-netsetup may have information to display, such as a room or node list) and
-the usual '000' listing terminator.
+ See also: REQT
DOWN (shut DOWN the server)
HCHG is a command, usable by any user, that allows a user to change their RWHO
host value. This will mask a client's originating hostname from normal
-users; access level 6 and higher see an entry right underneath the spoofed
-entry listing the actual hostname the user originates from.
+users; access level 6 and higher can see, in an extended wholist, the actual
+hostname the user originates from.
The format of an HCHG command is:
RCHG is a command, usable by any user, that allows a user to change their RWHO
room value. This will mask a client's roomname from normal users; access
-level 6 and higher see an entry right underneath the spoofed entry listing
-the actual room the user is in.
+level 6 and higher can see, in an extended wholist, the actual room the user
+is in.
The format of an RCHG command is:
- SPEX (Set Polict for message EXpiration)
+ SPEX (Set Policy for message EXpiration)
Sets the policy of the current room, floor, or site regarding the automatic
purging (expiration) of messages. See the writeup for the GPEX command for
19. Name of room to log express 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. Default moderation filter level for new users (-63 to +63)
-
-
-
- EXPI (EXPIre system objects)
+ 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. Default moderation filter level for new users (-63 to +63)
+ 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
+
+ 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:
MSG4 (read MeSsaGe, mode 4 -- enumerate MIME parts)
- FIX ... do the writeup for this once it's done.
+ FIXME ... do the writeup for this once it's done.
acceptable limits, ERROR+ILLEGAL_VALUE is returned. This command requires at
least Room Aide access; if the calling user is not an Aide, or a Room Aide for
the current room, ERROR+HIGHER_ACCESS_REQUIRED is returned.
+
+
+ REQT (REQuest client Termination)
+
+ Request that the specified client (or all clients) log off. Aide level
+access is required to run this command, otherwise ERROR+HIGHER_ACCESS_REQUIRED
+is returned.
+
+ The REQT command accepts one parameter: the session ID of the client which
+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
+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
+considered advisory only. The recommended implementation practice is to first
+issue a REQT command, then wait a little while (from 30 seconds up to a few
+minutes) for well-behaved clients to voluntarily terminate, and then issue a
+TERM command to forcibly disconnect the client (or perhaps a DOWN command, if
+you are logging off users for the purpose of shutting down the server).
+
+
+ SEEN (set or clear the SEEN flag for a message)
+
+ Beginning with version 5.80, Citadel supports the concept of setting or
+clearing the "seen" flag for each individual message, instead of only allowing
+a "last seen" pointer. In fact, the old semantics are implemented in terms
+of the new semantics. This command requires two arguments: the number of the
+message to be set, and a 1 or 0 to set or clear the "seen" bit.
+
+ This command returns OK, unless the user is not logged in or a usage error
+occurred, in which case it returns ERROR. Please note that no checking is
+done on the supplied data; if the requested message does not exist, the SEEN
+command simply returns OK without doing anything.
+
+
+ SMTP (utility commands for the SMTP gateway)
+
+ This command, accessible only by Aides, supports several utility operations
+which examine or manipulate Citadel's SMTP support. The first command argument
+is a subcommand telling the server what to do. The following subcommands are
+supported:
+
+ SMTP mx|hostname (display all MX hosts for 'hostname')
+ SMTP runqueue (attempt immediate delivery of all messages
+ in the outbound SMTP queue, ignoring any
+ retry times stored there)
+
+
+ STLS (Start Transport Layer Security)
+
+ This command starts TLS on the current connection. The current
+implementation uses OpenSSL on both the client and server end. For future
+compatibility all clients must support at least TLSv1, and servers are
+guaranteed to support TLSv1. During TLS negotiation (see below) the server
+and client may agree to use a different protocol.
+
+ The server returns ERROR if it does not support SSL or SSL initialization
+failed on the server; otherwise it returns OK. Once the server returns OK and
+the client has read the response, the server and client immediately negotiate
+TLS (in OpenSSL, using SSL_connect() on the client and SSL_accept() on the
+server). If negotiation fails, the server and client should attempt to resume
+the session unencrypted. If either end is unable to resume the session, the
+connection should be closed.
+
+ This command may be run at any time.
+
+
+ GTLS (Get Transport Layer Security Status)
+
+ This command returns information about the current connection. The server
+returns OK plus several parameters if the connection is encrypted, and ERROR
+if the connection is not encrypted. It is primarily used for debugging. The
+command may be run at any time.
+
+ 0 - Protocol name, e.g. "SSLv3"
+ 1 - Cipher suite name, e.g. "ADH-RC4-MD5"
+ 2 - Cipher strength bits, e.g. 128
+ 3 - Cipher strength bits actually in use, e.g. 128
+
+
+ IGAB (Initialize Global Address Book)
+
+ This command creates, or re-creates, a database of Internet e-mail addresses
+using the vCard information in the Global Address Book room. This procedure
+is normally run internally when the server determines it necessary, but is
+also provided as a server command to be used as a troubleshooting/maintenenance
+tool. Only a system Aide can run the command. It returns OK on success or
+ERROR on failure.
+
+
+ QDIR (Query global DIRectory)
+
+ Look up an internet address in the global directory. Any logged-in user may
+call QDIR with one parameter, the Internet e-mail address to look up. QDIR
+returns OK followed by a Citadel address if there is a match, otherwise it
+returns ERROR+NOT_LOGGED_IN.
+
+
+ BMBX (Bump MailBoX generation numbers)
+
+ This is a sooper-seekrit undocumented command.
+
+
+ ASYN (ASYNchronous message support)
+
+ Negotiate the use of asynchronous, or unsolicited, protocol messages. The
+only parameter specified should be 1 or 0 to indicate that the client can or
+cannot handle this type of messages. The server will reply OK followed by a
+1 or 0 to tell the client which mode it is now operating in.
+
+ If the command is not available on the server (i.e. it returns ERROR), or
+if the command has not been executed by the client, it should be assumed that
+this mode of operation is NOT in effect.
+
+ The client may also send any value other than 0 or 1 to simply cause the
+server to output its current state without changing it.
+
+ When asynchronous protocol mode is in effect, the client MUST handle any
+asynchronous messages as they arrive, before doing anything else.
+
+
+
+
+ ASYNCHRONOUS MESSAGES
+ ---------------------
+
+ When the client protocol is operating in asynchronous mode (please refer to
+the writeup of the ASYN command above), the following messages may arrive at
+any time:
+
+
+ 901 (express 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).
projects / citadel.git / blobdiff