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
3 - Messages posted
4 - Various flags (see citadel.h)
5 - User number
+ 6 - Time of last call (UNIX timestamp)
NEWU (create NEW User account)
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
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.
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)
+
ASYN (ASYNchronous message support)
projects / citadel.git / blobdiff