SESSION LAYER PROTOCOL FOR CITADEL/UX
- (c) 1995-2001 by Art Cancro et. al. All Rights Reserved
+ (c) 1995-2002 by Art Cancro et. al. All Rights Reserved
INTRODUCTION
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
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
9. The number of new Mail messages the user has (useful for alerting the
user to the arrival of new mail during a session)
10. The floor number this room resides on
+ 11. The current "view" for this room (see views.txt for more info)
MSGS (get pointers to MeSsaGeS in this room)
3. Various flags (bits) associated with the room (see LKRN cmd above)
4. The floor number on which the room resides
5. The room listing order
+ 6. The default view for the room (see views.txt)
SETR (SET Room attributes)
4. "Bump" flag (see below)
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)
*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
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.
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
See also: REQT
- 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.
-
-
DOWN (shut DOWN the server)
This command, which may only be executed by an Aide, immediately shuts down
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
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)
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.
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.
+
+
+ VIEW (set the VIEW for a room)
+
+ Set the preferred view for the current user in the current room. Please see
+views.txt for more information on views. The sole parameter for this command
+is the type of view requested. VIEW returns OK on success or ERROR on failure.
+
+
ASYN (ASYNchronous message support)
Negotiate the use of asynchronous, or unsolicited, protocol messages. The
projects / citadel.git / blobdiff