citadel.org

APPLICATION LAYER PROTOCOL FOR THE CITADEL SYSTEM
-------------------------------------------------

(c) 1995-2025 by the citadel.org development team. All Rights Reserved.
This document is provided to you under the terms of the GNU General Public
License.

INTRODUCTION
------------

This is a specification of the application layer protocol used by Citadel
client software to connect to Citadel servers. It is intended as a resource
for programmers who intend to develop their own Citadel clients, but it may
have other uses as well.

Developers will find this protocol refreshingly simple to implement. Unlike
over-enginnered XML and IMAP technologies, there is no need to write a
language parser in order to speak the Citadel protocol. Data is transmitted
back and forth in a delimited format that is easy to load into your program's
own data structures using little more than a string tokenizer.

IMPORTANT NOTES TO DEVELOPERS
-----------------------------

Developers who wish to extend this protocol are strongly encouraged to get in
touch with the Citadel developers to bring useful changes upstream in a
standard and published way.

CONNECTING TO A SERVER
----------------------

The protocols used below the application layer are beyond the scope of this
document, but we will briefly cover the methodology employed by Citadel.

Citadel offers its client protocol 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 via citadel.socket.

The port number officially assigned to Citadel by the IANA is 504 / TCP. Since
our application layer assumes a clean, reliable, sequenced connection, the use
of UDP would render the server unstable and unusable, so we stick with TCP.

CHARACTER SET
-------------

The native character set for the Citadel system is UTF-8. Unless otherwise
specified, all data elements are expected to be in the UTF-8 character set.
Specifically, all non-MIME messages should be assumed to be in UTF-8. MIME
messages may be in whatever character set is specified by the MIME header, of
course; however, some clients (such as WebCit) will automatically convert
messages from other character sets before displaying them.

GENERAL INFORMATION ABOUT THE SERVER
------------------------------------

The server is connection-oriented and stateful: each client requires its own
connection to a server process, and when a command is sent, the client must
read the response, and then transfer data or change modes if necessary.

The application layer is very much like other Internet protocols such as SMTP
or NNTP. A client program sends one-line commands to the server, and the server
responds with a three-digit numeric result code followed by a message
describing what happened. This cycle continues until the end of the session.

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.) 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
------------

The server will respond to all commands with a 3-digit result code, which will
be the first three characters on the line. The rest of the line may contain a
human-readable string explaining what happened. (Some client software will
display some of these strings to the user.)

The first digit is the most important. The following codes are defined for this position:

5 (ERROR) means the command did not complete.
2 (OK) means the command executed successfully.
3 (MORE_DATA) means the command executed partially. Usually this means that
another command needs to be executed to complete the operation. For
example, sending the USER command to log in a user usually results in a
MORE_DATA result code, because the client needs to execute a PASS command
to send the password and complete the login.
1 (LISTING_FOLLOWS) means that after the server response, the server will
output a listing of some sort. The client **must** read the listing,
whether it wants to or not. The end of the listing is signified by the
string "000" on a line by itself.
4 (SEND_LISTING) is the opposite of LISTING_FOLLOWS. It means that the
client 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.
6 (BINARY_FOLLOWS) means that the client must immediately receive a block of
binary data. The first parameter will be the number of bytes to expect.
7 (SEND_BINARY) means that the client must immediately send a block of
binary data. The first parameter will always be the number of bytes.
9 (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.

Some of the values which may be returned in the second and third digits are:

02 ASYNC_GEXP An instant message is waiting to be retrieved.
10 INTERNAL_ERROR An internal error occurred.
11 TOO_BIG The supplied data will not fit in the allocated
space.
12 ILLEGAL_VALUE One or more parameters supplied to a command are not
within the permitted ranges.
20 NOT_LOGGED_IN The client attempted to perform an operation which is only
permitted when a user is logged in.
30 CMD_NOT_SUPPORTED The client attempted to perform an operation which is
defined in the protocol, but not supported by this server instance.
31 SERVER_SHUTTING_DOWN A command failed because the server is in the process of shutting down.
40 PASSWORD_REQUIRED A command failed because a password is required.
41 ALREADY_LOGGED_IN Authentication failed because a user is already logged in.
42 USERNAME_REQUIRED The client attempted to perform an operation which requires the
specification of a user name.
50 HIGHER_ACCESS_REQUIRED The client attempted to perform an operation which requires
administrator privileges.
51 MAX_SESSIONS_EXCEEDED A login attempt failed because the server is operating at its
maximum number of connected sessions.
52 RESOURCE_BUSY The client attempted to perform an operation on a locked resource.
53 RESOURCE_NOT_OPEN The client attempted to access an object which is not locked yet.
60 NOT_HERE The specified command is valid, but is not permitted in the current
room.
61 INVALID_FLOOR_OPERATION The client attempted to manipulate rooms and/or floors in a way that
would break the data model.
70 NO_SUCH_USER The user name specified in a command does not exist.
71 FILE_NOT_FOUND The file name specified in a command does not exist.
72 ROOM_NOT_FOUND The room name specified in a command does not exist.
73 NO_SUCH_SYSTEM The network node specified in a command does not exist.
74 ALREADY_EXISTS The client attempted to create an object with a name that already
refers to an existing object on the system.
75 MESSAGE_NOT_FOUND The requested message does not exist in the current room.

PARAMETERIZATION
----------------

Zero or more parameters may be passed to a command. When more than one
parameter is passed to a command, they should be separated by the "|" symbol
like this:
SETU 80|24|260
In this example, we're using the "SETU" command and passing three parameters.

When the server spits out data that has parameters, if more than one parameter
is returned, they will be separated by the "|" symbol like this:
200 80|24|260
In this example, we just executed the "GETU" command, and it returned us an OK
result code (the '2' in the 200) and three parameters: 80, 24, and 260.

Citadel's data model, and how it influences the protocol
--------------------------------------------------------

Citadel orders data into containers called Rooms. Its top level folders are
called Floors, and they may just contain rooms. Rooms may have a Description
Text, and an Image file. Users may invite other Users to view or view and
create Messages in their Rooms. Citadel supports sharing of rooms between
different nodes. A user always is known to be 'inside' a room, which is an
implicit Parameter to most of the commands of the citadel protocol.

COMMANDS
--------

This is a listing of all the commands that a Citadel server can execute.

NOOP (NO OPeration)

This command does nothing. It takes no arguments and always returns OK. It
is intended primarily for testing and development, but it might also be used
as a "keep alive" command to prevent the server from timing out, if it's
running over a transport that needs this type of thing.

QNOP (Quiet No OPeration)

This command does nothing, similar to the NOOP command. However, unlike the
NOOP command, it returns **absolutely no response** at all. The client has no
way of knowing that the command executed. It is intended for sending
"keepalives" in situations where a full NOOP would cause the client protocol
to get out of sync.

Naturally, sending this command to a server that doesn't support it is an easy
way to mess things up. Therefore, client software should first check the
output of an INFO command to ensure that the server supports quiet NOOPs.

ECHO (ECHO something)

This command also does nothing. It simply returns OK followed by whatever its
arguments are.

TIME (get server local TIME)

TIME returns OK followed by four parameters:

* The current time measured in seconds since 00:00:00 GMT, Jan 1, 1970
(standard Unix format).

* The server's time zone offset from UTC

* 1 or 0 to indicate whether Daylight Savings Time is in effect in the
server's time zone

* The date/time (again in Unix timestamp format) when the server was started.

This is used in allowing a client to calculate idle times, server uptime, etc.

MESG (read system 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 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 to
the file being displayed. Then the message is printed, in format type 0 (see
MSG0 command for more information on this). If the file is not found, ERROR
is returned.

There are some "well known" names of system messages which client software may
expect most servers to carry:

hello | Welcome message, to be displayed before the user logs in.
changepw | To be displayed whenever the user is prompted for a new
password. Warns about picking guessable passwords and such.
register | Should be displayed prior to the user entering registration.
Warnings about not getting access if not registered, etc.
help | Main system help file.
goodbye | System logoff banner; display when user logs off.
roomaccess | Information about how public rooms and different types of
private rooms function with regards to access.
unlisted | Tells users not to choose to be unlisted unless they're really
paranoid, and warns that administrators can still see unlisted
user list entries.

Citadel provides these for the Citadel Unix text client. They are probably
not very useful for other clients:

Several values are replaced into these helpfiles:

Token | Value
^nodename | The node name of your system on a Citadel network
^humannode | Human-readable node name
^fqdn | Your system's fully-qualified domain name
^username | The name of the user reading the help file
^usernum | The user number of the user reading the help file
^sysadm | The name of the system administraor (i.e., you)
^variantname | The name of the software you're running
^bbsdir | The directory on the host system in which you have installed
the Citadel system.
^maxsessions | The mamximum number of allowed simultaneous sessions

SESSION AUTHENTICATION
----------------------

Citadel knows several states of a connection. There can be an authenticated
user, (which will involve a user being the base of rights to list for example
folders) or being authenticated as an internal programm, which will give the
full access to all Rooms on the Server.

USER (send USER name)

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+NO_SUCH_USER is returned.

The USER command will also accept a user's Internet e-mail address as the
login name.

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,
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
** Note: client software should always set the display name of the user
to this value, instead of what the user entered. Citadel tolerates a
number of variants of the user's name when logging in, but this function
will tell the client software how it *should* look.
1 The user's current access level
2 (empty field)
3 (empty field)
4 Various flags (see citadel.h)
5 User number
6 Time of last call (UNIX timestamp)

LOUT (LogOUT)

Log out the user without closing the server connection. It always returns OK
even if no user is logged in.

IDEN (IDENtify the client software)

The client software has the option to identify itself to the server.
Currently, the server does nothing with this information except to write it
to the syslog to satisfy the system administrator's curiosity. Other uses
might become apparent in the future.

The IDEN command should contain five fields (and the first three are unused)

0|0|0|IDstring|Hostname

Client IDString - a free-form text string describing the client
Remote Hostname - the name of the host the user is located at.

It is up to the server to determine whether to accept the host name or to
use the host name it has detected itself. Generally, if the client is
running on a trusted host (either localhost or a well-known publically
accessible client) it should use the host name transmitted by IDEN,
otherwise it should use the host name it has detected itself.

IDEN always returns OK, but since that's the only way it ever returns there's
no point in checking the result code.

QUIT (QUIT)

Terminate the server connection. This command takes no arguments. It
returns OK and closes the connection immediately.

BIFF (check for new mail)

This command returns the number of new messages which have arrived in the current
user's inbox while they were logged in. This count will begin at zero when the user
initially logs in, even if they have new mail. It also resets to zero when this
command is called. This makes the BIFF command useful only for delivering real-time
alerts.

RWHO (Read WHO's online)

Displays a list of all users connected to the server. No error codes are ever
returned. LISTING_FOLLOWS will be returned, followed by zero or more lines
containing the following three fields:

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
contain other information (such as the name of a file the user is
downloading).
3 | The name of the host the client is connecting from, or "localhost" if the
client is local.
4 | Description of the client software being used
5 | The last time, locally to the server, that a command was received from
this client (Note: NOOP's don't count)
6 | The last command received from a client. (NOOP's don't count)
7 | Session flags. These are:
- (STEALTH mode)
* (posting)
. (idle)
8 | (no longer used)
9 | (no longer used)
10 | (no longer used)
11 | Nonzero if the session is a logged-in user, zero otherwise.
12 | Session state (idle, bound, executing, etc.)

The listing is terminated, as always, with the string "000" on a line by
itself.

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.

RBDI (ReBuild Directory Index)

This command creates, or re-creates, the index of Internet email addresses using
information from all user records. 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/maintenance tool. Only a system
administrator can run the command. It returns OK on success or ERROR on failure.

AUTO (AUTOcompletion of email addresses)

The AUTO command is used by clients which want to request a list of email
recipients whose names or email addresses match a partial string supplied by
the client. This string is the only parameter passed to this command. The
command will return ERROR if no user is logged in or if no address book could
be found; otherwise, it returns LISTING_FOLLOWS followed by zero or more
candidate recipients.

ISME (find out if an e-mail address IS ME)

This is a quickie shortcut command to find out if a given e-mail address
belongs to the user currently logged in. Its sole argument is an address to
parse. The supplied address may be in any format (local, IGnet, or Internet).
The command returns OK if the address belongs to the user, ERROR otherwise.

INFO (get server INFO)

This command will **always** return LISTING_FOLLOWS and then print out a
listing of zero or more strings. Client software should be written to expect
anywhere from a null listing to an infinite number of lines, to allow later
backward compatibility. The current implementation defines the following
parts of the listing:

0 | Your unique session ID on the server
1 | The node name of the Citadel server
2 | Human-readable node name of the Citadel server
3 | The fully-qualified domain name (FQDN) of the server
4 | The name of the server software, i.e. "Citadel 4.00"
5 | The revision level of the server code
6 | The geographical location of the site (city and state if in the US)
7 | The name of the system administrator
8 | A number identifying the server type (see below)
9 | The text of the system's paginator prompt
10 | Floor Flag. 1 if the system supports floors, 0 otherwise.
11 | Paging level. 0 if the system only supports inline paging, 1 if the
system supports "extended" paging (check-only and multiline modes).
See the SEXP command for further information.
12 | (empty field - no longer in use)
13 | Set to nonzero if this server supports the QNOP command.
14 | Set to nonzero if this server is capable of connecting to a directory
service using LDAP.
15 | Set to nonzero if this server does **not** allow self-service creation
of new user accounts.
16 | The default timezone for calendar items which do not have any timezone
specified and are not flagged as UTC. This will be a zone name from
the Olsen database.
17 | (empty field - no longer in use)
18 | (empty field - no longer in use)
19 | (empty field - no longer in use)
20 | (empty field - no longer in use)
21 | Nonzero if the server's full text index is enabled.
22 | Build ID of this version of Citadel Server.
23 | OpenID version supported by the server (always 0 because support for OpenID has ended)
24 | Nonzero if the server supports anonymous guest logins

Notes for anyone developing third party client software:
* Your client programs should still be able to utilize servers other than
your own.
* Clients other than your own should still be able to utilize your server,
even if your extensions aren't supported.
* Please contact the citadel.org project 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 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 of
confusion about which client program works with which server, etc. Client
software can simply check the server type (and perhaps the revision level) to
determine ahead of time what commands may be utilized.

TERM (TERMinate another session)

This command administratively terminates another running Citadel Server
session. The TERM command performs this task. Naturally, only administrators
can execute TERM. The command should be called with a single argument: the
session ID (obtained from an RWHO command) of the session to be terminated.

TERM returns OK if the session was terminated, or ERROR otherwise. Note that a
client program is prohibited from terminating its own session.

See also: REQT

REQT (REQuest client Termination)

Request that the specified client (or all clients) log off. Admin 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 the REQT command simply transmits an instant message
to the specified client(s) with the EM_GO_AWAY flag set. It is the client's
responsibility to honor this flag and log off. Clients which do not honor
this flag, and clients running other protocols, will not respond. 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).

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

ICAL (Internet CALendaring commands)

This command supports a number of subcommands which are used to process the
calendaring/scheduling support in Citadel. Here are the subcommands which may
be issued:

ICAL test

Test server for calendaring support. Always returns OK unless the server has
disabled the calendar functions.

ICAL respond|msgnum|partnum|action

Respond to a meeting request. 'msgnum' and 'partnum' refer to a MIME-encoded
meeting invitation in the current room. 'action' must be set to either
"accept" or "decline" to determine the action to take. This subcommand will
return either OK or ERROR.

ICAL conflicts|msgnum|partnum

Determine whether an incoming VEVENT will fit in the user's calendar by
checking it against the existing VEVENTs. 'msgnum' and 'partnum' refer to a
MIME-encoded meeting invitation in the current room (usually the inbox). This
command may return ERROR if something went wrong, but usually it will return
LISTING_FOLLOWS followed by a list of zero or more conflicting events. A
zero-length list means that there were no conflicts.

ICAL handle_rsvp|msgnum|partnum

Handle an incoming "reply" (or RSVP) to a meeting request you sent out.
'msgnum' and 'partnum' refer to a MIME-encoded reply in the current room.
'action' must be set to either "update" or "ignore" to determine the action to
take. If the action is "update" then the server will hunt for the meeting in
the user's Calendar> room, and update the status for this attendee. Either
way, the reply message is deleted from the current room. This subcommand will
return either OK or ERROR.

ICAL freebusy|username

Output the free/busy times for the requested user. If the user specified has a
calendar available, this command will return LISTING_FOLLOWS and a compound
VCALENDAR object. That object, in turn, will contain VEVENT objects that have
been stripped of all properties except for the bare minimum needed to learn
free/busy times (such as DTSTART, DTEND, and 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 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 calendar 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.

ICAL getics

Output the contents of the entire calendar (assuming we are in a calendar room)
as one big data stream. All of the events (or tasks, etc.) in the room are
combined into a single VCALENDAR object, which is then serialized and
transmitted to the client. This is suitable for subscribing to a calendar in
third-party software. This command will output LISTING_FOLLOWS followed by the
calendar data stream, or ERROR if the requested operation is not permitted.

ICAL putics

Delete the entire contents of a calendar room and replace it with the calendar
supplied by a client-input data stream. This is suitable for publishing a
calendar from third-party software. This command will output SEND_LISTING and
then expect the client to transmit the calendar data stream. Alternatively,
it will return ERROR if the requested operation is not permitted.

SEXP (Send instant message)

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
message to, and the text of the message. If the message is successfully
transmitted, OK is returned. If the target user is not logged in or if
anything else goes wrong, ERROR is returned.

If the server supports extended paging, sending a zero-length message merely
checks for the presence of the requested user without actually sending a
message. Sending a message consisting solely of a "-" (hyphen) will cause the
server to return SEND_LISTING if the requested user is logged in, and the
client can then transmit a multi-line page.

The reserved name "broadcast" may be used instead of a user name, to broadcast
an instant message to all users currently connected to the server.

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 to sessions running a
protocol which does not support them, such as SMTP, POP3, and IMAP.

GEXP (Get instant messages)

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 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 (deprecated, do not use)
5 - the email address or XMPP JID of the sender

The text sent to the client will be the body of the instant message.

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 instant messages.

DEXP (Disable receiving instant 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 administrators 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.

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:

902 (instant message arriving)

One or more instant messages have arrived for this client.

Room and Message Commands
-------------------------

Manipulate data in the current room
-----------------------------------

As previously noted, many commands implicitly reference the room the user is
in. Here is how to move to another room:

GOTO (GOTO a room)

This command is used to goto a new room. When the user first logs in (login is
completed after execution of the PASS command) this command is automatically
and silently executed to take the user to the first room in the system (usually
called the Lobby).

This command can be passed one or two parameters. The first parameter is, of
course, the name of the room. Although it is not case sensitive, the full name
of the room must be used. Wildcard matching or unique string matching of room
names should be the responsibility of the client.

Note that the reserved room name "_BASEROOM_" can be passed to the server to
cause the goto command to take the user to the first room in the system,
traditionally known as the Lobby. As long as a user is logged in, a GOTO
command to _BASEROOM_ is guaranteed to succeed. This is useful to allow client
software to return to the base room when it doesn't know where else to go.

There are also several additional reserved room names:

_MAIL_ goes to the user's inbox (i.e. the Mail> room).
_TRASH_ goes to the user's personal trashcan room (trash folder).
_BITBUCKET_ goes to a room that has been chosen for messages without a home.
_CALENDAR_ goes to the user's primary personal calendar.
_CONTACTS_ goes to the user's primary personal address book.
_NOTES_ goes to the user's primary personal notes room.
_TASKS_ goes to the user's primary personal task list.

The second (and optional) parameter is a password, if one is required for
access to the room. This allows for all types of rooms to be accessed via this
command: for public rooms, invitation-only rooms to which the user has access,
and preferred users only rooms to which the user has access, the room will
appear in a room listing. For guess-name rooms, this command will work
transparently, adding the room to the user's known room list when it completes.
For passworded rooms, access will be denied if the password is not supplied or
is incorrect, or the command will complete successfully if the password is
correct.

The third (and also) optional parameter is a "transient" flag. Normally, when a
user enters a private and/or zapped room, the room is added to the user's known
rooms list. If the transient flag is set to non-zero, this is called a
"transient goto" which causes the user to enter the room without adding the
room to the known rooms list.

The possible result codes are:

OK The command completed successfully. User is now in the room.
(See the list of returned parameters below)
ERROR The command did not complete successfully. Check the second
and third positions of the result code to find out what
happened:
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.
ROOM_NOT_FOUND The requested room does not exist.

The typical procedure for entering a passworded room would be:

- Execute a GOTO command without supplying any password.
- ERROR+PASSWORD_REQUIRED will be returned. The client now knows that the
room is passworded, and prompts the user for a password.
- Execute a GOTO command, supplying both the room name and the password.
- If OK is returned, the command is complete. If, however,
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.

When the command succeeds, these parameters are returned:
0 | The name of the room
1 | Number of unread messages in this room
2 | Total number of messages in this room
3 | Info flag: set to nonzero if the user needs to read this room's info
file (see RINF command below)
4 | Various flags associated with this room. (See LKRN cmd above)
5 | The highest message number present in this room
6 | The highest message number the user has read in this room
7 | Boolean flag: 1 if this is a Mail> room, 0 otherwise
8 | Administrator flag: 1 if the user has admin rights to either the current
room or the entire site.
9 | (this position is no longer used)
10 | The floor number this room resides on
11 | The **current**"view" for this room (see views.txt for more info)
12 | The **default**"view" for this room
13 | Boolean flag: 1 if this is the user's Trash folder, 0 otherwise.
14 | More flags associated with this room
15 | Timestamp of the last write activity in this room (addition or deletion
of messages, reconfiguration of room, etc)

The default view gives the client a hint as to what views the user should be
allowed to select. For example, it would be confusing to allow messages in a
room intended for calendar items. The server does not enforce these
restrictions, though.

STAT (retrieve name and modification time of current room)

This is a lightweight command which may be used by a client to quickly determine
whether there has been any activity in the current room (added or deleted
messages, modification of the room's configuration, etc). It is called with no
parameters, and returns OK followed by two parameters: the name of the room, and
the modification timestamp.

Commands manipulating Message Index Lists
-----------------------------------------

MSGS (get pointers to MeSsaGeS in this room)

This command obtains a listing of all the messages in the current room which the
client may request. This command may be passed a single parameter: either "all",
"old", or "new" to request all messages, only old messages, or new messages. Or
it may be passed two parameters: "last" plus a number, in which case that many
message pointers will be returned; "first" plus a number, for the corresponding
effect; or "gt" plus a number, to list all messages in the current room with a
message number greater than the one specified; or "lt" plus a number, to list
all messages in the current room with a message number less than the one
specified. If no parameters are specified, "all" is assumed.

In addition, the first parameter may be set to "search", in which case the third
parameter must be a search string. This will request all messages in the
current room whose text contains the search string.

The third argument, 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 message type values listed below
in the writeup for the "MSG0" command.

The optional fourth argument may also be either 0 or 9. If it is 9, the output
of this command will include not only a list of message numbers, but a simple
header summary of each message as well. This is somewhat resource intensive so
you shouldn't do this unless you absolutely need all the headers immediately.
The fields which are output (in the usual delimited fashion, of course) are:
message number, timestamp, display name, node name, Internet email address
(if present), subject (if present), hash of message-id (if present),
comma-separated hashes of message thread references (if present).

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:

Example 1: Read all new messages

Client: MSGS NEW
Server: 100 Message list...
523218
523293
523295
000

Example 2: Read the last five messages

Client: MSGS LAST|5
Server: 100 Message list...
523190
523211
523218
523293
523295
000

Example 3: Read all messages written by "IGnatius T Foobar"

Client: MSGS ALL|0|1
Server: 800 Send template then receive message list
Client: from|IGnatius T Foobar
000
Server: 518604
519366
519801
520201
520268
520805
520852
521579
521720
522571
000

Note that in "search mode" the client may specify any number of search criteria.
These criteria are applied with an AND logic.

Another note: anyone reading through the code may observe that there are other
undocumented parameters which may be supplied to this command. These are
deprecated and should not be used.

SEEN (set or clear the SEEN flag for a message)

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.

GTSN (GeT the list of SeeN messages)

This command retrieves the list of "seen" (as opposed to unread) messages for
the current room. It returns OK followed by an IMAP-format message list.

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.

SRCH (SeaRCH the message base)

Please do not use this command. It is not intended to remain in the protocol
in its current form. If you want to perform a full text search, use the MSGS
command with the 'search' subcommand instead.

The current implementation accepts a search string as its sole argument, and
will respond with LISTING_FOLLOWS followed by a list of messages (globally, not
just in the current room) which contain ALL of the words in the search string.
If the client desires an "exact phrase" match, it must then slow-search the text
of each returned message for the exact string. The client should also compare
the returned message numbers against those which actually exist in the room or
rooms being searched. In particular, clients should avoid telling the user
about messages which exist only in rooms to which the user does not have access.

EUID (get message number using an EUID)

Returns the message number, if present, of the message in the current room which
is indexed using the supplied EUID (exclusive message ID). There can be only
one message in a room with any given EUID; if another message arrives with the
same EUID, the existing one is replaced. This makes it possible to reference
things like calendar items using an immutable URL that does not change even when
the message number changes due to an update.

The format of this command is: EUID (euid)

If successful, EUID returns OK followed by a message number.
If no message exists in the current room with the supplied EUID, the command
returns ERROR+MESSAGE_NOT_FOUND.

Commands manipulating One Message
---------------------------------

DELE (DELEte a message)

Delete one or more messages from the current room. The one argument that should
be passed to this command is a message number, or a list of message numbers
separated by commas, to be deleted.

The return value will be OK if one or more messages were deleted, or an ERROR code.

Please note that is operation only deletes the message pointer from the room.
The actual "delete from disk" operation will take place during the next database
purge, provided that the message is not also present in one or more additional
rooms.

MOVE (MOVE or copy a message to a different room)

Move or copy a message to a different room. This command expects to be passed
three arguments:

0 the message number(s) 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.

You can move/copy multiple messages with a single command by separating the
message numbers with commas; for example:
MOVE 112,113,114|Trash|0

EMSG (Enter a system MeSsaGe)

This is the opposite of the MESG command - it allows the creation and editing
of system messages. The only argument passed to EMSG is the name of the file
being transmitted. If the file exists in any system message directory on the
server it will be overwritten, otherwise a new file is created. EMSG returns
SEND_LISTING on success or ERROR+HIGHER_ACCESS_REQUIRED if the user is not an
administrator.

Typical client software would use MESG to retrieve any existing message into an
edit buffer, then present an editor to the user and run EMSG if the changes are
to be saved.

ENT0 (ENTer message, mode 0)

This command is used to enter messages into the system. It accepts the
following parameters:

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. Client software should, in fact, perform
this operation at the beginning of an "enter message" command **before**
starting up its editor, so the user does not end up typing a message in
vain that will not be permitted to be saved.
1 Recipient (To: field). This argument is utilized only for private mail.
It is ignored for public messages. It contains, of course, the name of
the recipient(s) of the message.
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 format type may be used (this will typically
be 0; see the MSG0 command below).
4 Subject. If present, this argument will be used as the subject of the
message.
5 Post name. This is the 'display name' or 'screen name' to be used as the
author of the message. It is permissible to leave this field blank to
allow the server to select a suitable default. The supplied name must
be one of the names returned by a GVSN command, unless the user is an
administrator.
6 Do Confirmation. NOTE: this changes the protocol semantics! When you set
this to nonzero, ENT0 will reply with a confirmation message after you
submit the message text. The reply code for the ENT0 command will be
START_CHAT_MODE instead of SEND_LISTING.
7 Recipient (Cc: field). This argument is utilized only for private mail. It
is ignored for public messages. It contains, of course, the name(s) of the
recipient(s) of the message.
8 Recipient (Bcc: field). This argument is utilized only for private mail.
It is ignored for public messages. It contains, of course, the name(s) of
the recipient(s) of the message.
9 Exclusive message ID. When a message is submitted with an Exclusive message
ID, any existing messages with the same ID will automatically be deleted.
This is only applicable for Wiki rooms; other types of rooms either
ignore the supplied ID (such as message boards and mailboxes) or derive
the ID from a UUID native to the objects stored in them (such as
calendars and address books).
10 Email address. This is the Internet email address to be used as the author
of the message. It is permissible to leave this field blank to allow
the server to select a suitable default. The supplied name must be one
of the names returned by a GVEA command.
11 If this is a reply to another message, supply a delimiter-separated list of
message ID's for the thread, starting with the message being replied to,
and ending with the thread root. Note that the delimiter is "!"
(exclamation point) rather than the vertical bar, because we are already
using the vertical bar delimiter here.

Possible result codes:

OK The request is valid. (Client did not set the "post" flag, so the server
will not read in message text.) If the message is an e-mail with a
recipient, the text that follows the OK code will contain the exact name
to which mail is being sent. The client can display this to the user.
The implication here is that the name that the server returns will contain
the correct upper and lower case characters. In addition, if the
recipient is having his/her mail forwarded, the forwarding address will be
returned. In newer Citadel versions its followed by a "|0" or "|1"
that indicates whether the client should force the user to set a message
subject.
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).
START_CHAT_MODE The request is valid. The client should now transmit the text of
the message, ending with a 000 on a line by itself. After
transmitting the 000 terminator, the client MUST read in the
confirmation from the server, which will also end with 000 on a
line by itself. The format of the confirmation appears below.
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.
ERROR+NO_SUCH_USER One or more specified recipients do not exist.

The format of the confirmation message, if requested, is as follows:

Line 1: The new message number on the server for the message. It will be
positive for a real message number, or negative to denote that an
error occurred. If an error occurred, the message was not saved.
Line 2: A human-readable confirmation or error message.
Line 3: The resulting Exclusive UID of the message, if present. (More may
be added to this in the future, so do not assume that there will
only be these lines output. Keep reading until 000 is received.)

GVSN (Get Valid Screen Names)

Returns LISTING_FOLLOWS followed by a list of one or more "screen names" which
the user may use to post messages (argument 5 to an ENT0 command). The user
must be logged in or the command will return ERROR+NOT_LOGGED_IN.

GVEA (Get Valid Email Addresses)

Returns LISTING_FOLLOWS followed by a list of one or more Internet email
addresses which the user may use to post messages (argument 10 to an ENT0
command). The user must be logged in or the command will return
ERROR+NOT_LOGGED_IN.

DVCA (Dump VCard Addresses)

Returns LISTING_FOLLOWS followed by a list of zero or more contacts (display
name plus email address in RFC822 format) found in any vCards in the current
room. This command is used to rapidly output the list of contacts in an
address book room. The user must be logged in or the command will return
ERROR+NOT_LOGGED_IN.

Reading a single message
------------------------

Due to the several needs of clients to get preformated messages, citadel offers
several modes to clients to display a message (or parts of it)

MSG0 (read MeSsaGe, mode 0)

This is a command used to read the text of a message. "Mode 0" implies that
other MSG commands (MSG1, MSG2, etc.) exist to read messages in more robust
formats. This command should be passed two arguments. The first is the message
number of the message being requested. The second argument specifies whether
the client wants headers and/or message body:

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 the
contents of the message. The following fields may be sent:
Field Value
type= Formatting type. see the next table for the currently defined types
msgn= The message ID of this message on the system it originated on.
path= An e-mailable path back to the user who wrote the message.
time= The date and time of the message, in Unix format (the number of seconds
since midnight on January 1, 1970, GMT).
from= The name of the author of the message.
rcpt= If the message is a private e-mail, this is the recipient.
room= The name of the room the message originated in.
node= The short node name of the system this message originated on.
hnod= The long node name of the system this message originated on.
zaps= The id/node of a message which this one zaps (supersedes).
part= Information about a MIME part embedded in this message.
pref= formation about a multipart MIME prefix such as "multipart/mixed" or
"multipart/alternative". This will be output immediately prior to the
various "part=" lines which make up the multipart section.
suff= Information about a multipart MIME suffix. This will be output
immediately following the various "part=" lines which make up the
multipart section.
text Note that there is no "=" after the word "text". This string signifies
that the message text begins on the next line.

Message Type Values

0 (FMT_CITADEL) - "traditional" Citadel formatting. This means that newlines
should be treated as spaces UNLESS the first character on the next
line is a space. In other words, only indented lines should generate
a newline on the user's screen when the message is being displayed.
This allows a message to be formatted to the reader's screen width.
It also allows the use of proportional fonts.
1 (FMT_FIXED) - a simple fixed-format message. The message should be displayed
to the user's screen as is, preferably in a fixed-width font that will
fit 80 columns on a screen.
4 (FMT_RFC822) - MIME format message. The message text is expected to contain a
header with the "Content-type:" directive (and possibly others).

MSG2 (read MeSsaGe, mode 2)

MSG2 follows the same calling convention as MSG0.

This command will output the raw RFC822 message source. If the message on disk
is not in RFC822 format, it will be converted into RFC822 format. MSG2 may be
used by clients which prefer to perform the full RFC822/MIME decode on the
client side.

MSG4 (read MeSsaGe, mode 4 -- output in preferred MIME format)

This is the equivalent of MSG0, except it's a bit smarter about messages in
rich text formats. Immediately following the "text" directive, the server
will output RFC822-like MIME part headers such as "Content-type:" and
"Content-length:". MIME formats are chosen and/or converted based on the
client's preferred format settings, which are set using the MSGP command,
described below.

The MSG4 command also accepts an optional second argument, which may be the
MIME part specifier of an encapsulated message/rfc822 message. This is useful
for fetching the encapsulated message instead of the top-level message, for
example, when someone has forwarded a message as an attachment. Note that the
only way for the client to know the part specifier is to fetch the top-level
message and then look for attachments of type message/rfc822, and then call
MSG4 again with that part specifier.

MIME RELATED COMMANDS
---------------------

These commands manipulate parts of messages, available in Multipart-MIME Format
as specified in RFC822.

MSGP (set MeSsaGe Preferred MIME format)

Client tells the server what MIME content types it knows how to handle, and the
order in which it prefers them. This is similar to an HTTP "Accept:" header.

The parameters to a MSGP command are the client's acceptable MIME content types,
in the order it prefers them (from most preferred to least preferred). For
example:

MSGP text/html|text/plain

There is also a special form of this command, which may be used for the client
to indicate to the server that it prefers to decode Base64 and quoted-printable
on the client side. If this command is issued, these encodings will **not** be
decoded prior to transmitting messages to the client. This is done with the
following form:

MSGP dont_decode

The MSGP command always returns OK.

OPNA (OPeN Attachment)

(Note: this command is deprecated. Use DLAT instead.)

Opens, as a download file, a component of a MIME-encoded message. The two
parameters which must be passed to this command are the message number and the
name of the desired section. If the message or section does not exist, an
appropriate ERROR code will be returned; otherwise, if the open is successful,
this command will succeed returning the same information as an OPEN command.

The desired section may be specified using either its part number or its
content-id.

DLAT (DownLoad ATtachment)

Similar to OPNA, and with the same calling syntax. The difference is that
instead of opening a download file for block transfer, this command outputs the
entire decoded MIME section at once, using a BINARY_FOLLOWS response. This is
useful for outputting small objects such as calendar items.

The desired section may be specified using either its part number or its
content-id.

Wiki room commands
------------------

These commands are usable in Citadel Wiki rooms only.

WIKI (perform operations on WIKI pages)

WIKI history|(pagename)

Displays the edit history for the specified page. Returns LISTING_FOLLOWS and
a delimited list of edits. The fields of each line are:

position 0: The UUID of the edit
position 1: Timestamp of the edit
position 2: Name of the user who performed the edit
position 3: The node on which that user resides

WIKI rev|(pagename)|(rev_uuid)|(operation)

Performs an operation on a specific revision (whose UUID has been learned from
a "history" command) of a specific page. The valid operations are "fetch" and
"revert". "fetch" will simply retrieve the specified revision of the page,
while "revert" will actually make that revision the current one. In either
case, this command will return OK followed by a message number.

In the case of a "fetch" operation, the client will probably want to then fetch
the message with that number in order to display the desired revision of the
page. The message has been saved in a hidden room in an invalid namespace,
and will therefore be deleted from disk the next time the auto-purger runs.

Rooms and Floor Directory Commands
----------------------------------

Floor Commands
--------------

Floors are a loosely organized way to organize rooms into groups or categories.

LFLR (List all known FLooRs)

On systems supporting floors, this command lists all known floors. The command
accepts no parameters. It will return ERROR+NOT_LOGGED_IN if no user is logged
in. Otherwise it returns LISTING_FOLLOWS and a list of the available floors,
each line consisting of three fields:

* The floor number associated with the floor
* The name of the floor
* Reference count (number of rooms on this floor)

CFLR (Create a new FLooR)

This command is used to create a new floor. It should be passed two arguments:
the name of the new floor to be created, and a 1 or 0 depending on whether the
client is actually creating a floor or merely checking to see if it has
permission to create the floor. The user must be logged in and have
administrator privileges to create a floor.

If the command succeeds, it will return OK followed by the floor number
associated with the new floor. Otherwise, it will return ERROR (plus perhaps
HIGHER_ACCESS_REQUIRED, ALREADY_EXISTS, or INVALID_FLOOR_OPERATION) followed by
a description of why the command failed.

KFLR (Kill a FLooR)

This command deletes a floor. It should be passed two argument: the **number**
of the floor to be deleted, and a 1 or 0 depending on whether the client is
actually deleting the floor or merely checking to see if it has permission to
delete the floor. The user must be logged in and have administrator privileges
to delete a floor.

Floors that contain rooms may not be deleted. If there are rooms on a floor,
they must be either deleted or moved to different floors first. This implies
that the Main Floor (floor 0) can never be deleted, since Lobby>, Mail>, and
Aide> all reside on the Main Floor and cannot be deleted.

If the command succeeds, it will return OK. Otherwise it will return ERROR
(plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION) followed by a
description of why the command failed.

EFLR (Edit a FLooR)

Edit the parameters of a floor. The client may pass one or more parameters to
this command:

* The number of the floor to be edited
* The desired new name

More parameters may be added in the future. Any parameters not passed to the
server will remain unchanged. A minimal command would be EFLR and a floor
number -- which would do nothing. EFLR plus the floor number plus a floor name
would change the floor's name.

If the command succeeds, it will return OK. Otherwise it will return ERROR
(plus perhaps HIGHER_ACCESS_REQUIRED or INVALID_FLOOR_OPERATION).

ROOM LIST COMMANDS
------------------

The various "list rooms" commands all return lists of rooms in the same format.
The fields in the delimited list are as follows:

0 NAME Actual name of this room; may include '\' to separate trese
1 FLAG Flags for this room (one per bit, from the QR_ flags listed below)
2 FLOOR The number of the floor on which this room resides.
3 LISTORDER Listing order (the client can voluntarily sort the list this way)
4 ACL Flags for this room (one per bit, from the QR2_ flags listed below)
5 CURVIEW the currently configured "view" for this room
6 DEFVIEW the default "view" for this room
7 LASTCHANGE date/time stamp of the last write to this room

LKRN (List Known Rooms with New messages)
-------------------------------------------

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:

Flag Name integer value Description
-------------- -------------- -------------------------------------
QR_PERMANENT 1 Room is protected from auto-deletion
QR_PRIVATE 4 Set for any type of private room
QR_PASSWORDED 8 Set if there's a password too
QR_GUESSNAME 16 Set if this room can be accessed to anyone who knows its name
QR_DIRECTORY 32 Directory room
QR_UPLOAD 64 Allowed to upload
QR_DOWNLOAD 128 Allowed to download
QR_VISDIR 256 Visible directory
QR_ANONONLY 512 Anonymous-Only room
QR_ANONOPT 1024 Anonymous-Option room
QR_NETWORK 2048 Shared network room
QR_PREFONLY 4096 Preferred status needed to enter
QR_READONLY 8192 administrator status required to post
QR_MAILBOX 16384 Is this room a private mailbox

Then it returns another '|' symbol, followed by a second set of bits comprised
of the following:

Flag Name integer Value Description
-------------- -------------- -------------------------------------
QR2_SYSTEM 1 System room; hide by default
QR2_SELFLIST 2 Self-service mailing list mgmt

Other bits may be defined in the future. The listing terminates, as with all
listings, with "000" on a line by itself.

The caller can request the listing to be filtered by floor. The first argument
to LKRN should be the number of the floor to list rooms from. Only rooms from
this floor will be listed. If no arguments are passed to LKRN, or if the floor
number requested is (-1), rooms on all floors will be listed.

The third field displayed on each line is the number of the floor the room is
on. The LFLR command should be used to associate floor numbers with floor names.

The fourth field displayed on each line is a "room listing order." Unless there
is a compelling reason not to, clients should sort any received room listings
by this value.

The fifth field is a special bit bucket containing fields which pertain to room
access controls:

Flag Name Value Description
UA_KNOWN 2 Known room
UA_GOTOALLOWED 4 Access will be granted to this room if the user calls it up by name
UA_HASNEWMSGS 8 Unread messages exist in room
UA_ZAPPED 16 Zapped from known rooms list

The sixth field is the user's current view for the room. (See VIEW command).

The seventh field is the **default** view for the room. (See VIEW command).

The eigth field is a unix timestamp which reflects the last time the room was
modified (created, edited, posted in, deleted from, etc.)

LKRO (List Known Rooms with Old [no new] messages)

This follows the same usage and format as LKRN.

LZRM (List Zapped RooMs)

This follows the same usage and format as LKRN and LKRO.

LKRA (List All Known Rooms)

Same format. Lists all known rooms, with or without new messages.

LRMS (List all accessible RooMS)

Again, same format. This command lists all accessible rooms, known and
forgotten, with and without new messages. It does not, however, list
inaccessible private rooms.

LPRM (List all Public RooMs)

Again, same format. This command lists all public rooms, and nothing else.
Unlike the other list rooms commands, this one can be executed without logging
in.

COMMANDS WHICH MANIPULATE ONE ROOM
----------------------------------

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, ERROR+HIGHER_ACCESS_REQUIRED
will be returned if the room's directory is not visible and the user does not
have administrator or Room administrator 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:

filez.tgz|2345678|application/x-tar|Hey all, have a look at that cool stuff

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).

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.

GETR (GET Room attributes)

This command is used for editing the various attributes associated with a room.
A typical "edit room" command would work like this:

* Use the GETR command to get the current attributes
* Change some of them around
* Use SETR (see below) to save the changes
* Possibly also change the room administrator using the GETA and SETA commands

GETR takes no arguments. It will only return OK if the SETR command will also
return OK. This allows client software to tell the user that he/she can't edit
the room **before** going through the trouble of actually doing the editing.
Possible return codes are:

ERROR+NOT_LOGGED_IN No user is logged in.
ERROR+HIGHER_ACCESS_REQUIRED Not enough access. Typically, only administrators and the
room administrator associated with the current room, can
access this command.
OK Command succeeded. Parameters are returned.

If OK is returned, the following parameters will be returned as well:

- The name of the room
- The room's password (if it's a passworded room)
- The name of the room's directory (if it's a directory room)
- Various flags (bits) associated with the room (see LKRN cmd above)
- The floor number on which the room resides
- The room listing order
- The default view for the room (see views.txt)
- A second set of flags (bits) associated with the room

SETR (SET Room attributes)

This command sets various attributes associated with the current room. It
should be passed the following arguments:

- The name of the room
- The room's password (if it's a passworded room)
- The name of the room's directory (if it's a directory room)
- Various flags (bits) associated with the room (see LKRN cmd above)
- "Bump" flag (see below)
- The floor number on which the room should reside
- The room listing order
- The default view for the room (see views.txt)
- 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
all back. This is particularly important with respect to the flags: if a
particular bit is set, and you don't know what it means, LEAVE IT ALONE and
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.

RINF (read Room INFormation file)

Each room has associated with it a text file containing a description of the
room, perhaps containing its intended purpose or other important information.
The info file for the Lobby> (the system's base room) is often used as a
repository for system bulletins and the like.

This command, which accepts no arguments, is simply used to read the info file
for the current room. It will return LISTING_FOLLOWS followed by the text of
the message (always in format type 0) if the request can be honored, or ERROR
if no info file exists for the current room (which is often the case). Other
error description codes may accompany this result.

When should this command be used? This is, of course, up to the discretion of
client software authors, but in Citadel it is executed in two situations: the
first time the user ever enters a room; and whenever the contents of the file
change. The latter can be determined from the result of a GOTO command, which
will tell the client whether the file needs to be read (see GOTO above).

GETA

This command is used to get the name of the Room administrator for the current
room. 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 administrator. A conforming server must guarantee that the
user is always in some room.

SETA

The opposite of GETA, used to set the Room administrator for the current room.
One parameter should be passed, which is the name of the user who is to be the
new room administrator. Under Citadel, this command may only be executed by
administrators and by the **current** Room administrator for the room. Return
codes possible are:

ERROR+NOT_LOGGED_IN Not logged in.
ERROR+HIGHER_ACCESS_REQUIRED Higher access required.
ERROR+NOT_HERE Room cannot be edited.
OK Command succeeded.

KILL (KILL current room)

This command deletes the current room. It accepts a single argument, which
should be nonzero to actually delete the room, or zero to merely check whether
the room can be deleted.

Once the room is deleted, the current room is undefined. It is suggested that
client software immediately GOTO another room (usually _BASEROOM_) after this
command completes.

Possible return codes:

CRE8 (CRE[ate] a new room)

This command is used to create a new room. Like some of the other commands, it
provides a mechanism to first check to see if a room can be created before
actually executing the command. CRE8 accepts the following arguments:

0 Create flag. Set this to 1 to actually create the room. If it is set to 0,
the server merely checks that there is a free slot in which to create a new
room, and that the user has enough access to create a room. It returns OK
if the client should go ahead and prompt the user for more info, or ERROR or
ERROR+HIGHER_ACCESS_REQUIRED if the command will not succeed.
1 Name for new room.
2 Access type for new room:
0 Public
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.
6 The default "view" for the room.

If the create flag is set to 1, the room is created (unless something went wrong
and an ERROR return is sent), and the server returns OK, but the session is
**not** automatically sent to that room. The client still must perform a GOTO
command to go to the new rooml must perform a GOTO command to go to the new room.

FORG (FORGet the current room)

This command is used to forget (zap) the current room. For those not familiar
with Citadel, this terminology refers to removing the room from a user's own
known rooms list, **not** removing the room itself. After a room is forgotten,
it no longer shows up in the user's known room list, but it will exist in the
user's forgotten room list, and will return to the known room list if the user
explicity requests the room by its exact name.

The command takes no arguments. If the command cannot execute for any reason,
ERROR will be returned. ERROR+NOT_LOGGED_IN or ERROR+NOT_HERE may be returned
as they apply.

If the command succeeds, OK will be returned. At this point, the current room
is **undefined**, and the client software is responsible for taking the user to
another room before executing any other room commands (usually this will be
_BASEROOM_ since it is always there).

EINF (Enter INFo file for room)

Transmit the info file for the current room with this command. EINF uses a
boolean flag (1 or 0 as the first and only argument to the command) to determine
whether the client actually wishes to transmit a new info file, or is merely
checking to see if it has permission to do so.

If the command cannot succeed, it returns ERROR.

If the client is only checking for permission, and permission will be granted,
OK is returned.

If the client wishes to transmit the new info file, SEND_LISTING is returned,
and the client should transmit the text of the info file, ended by the usual
000 on a line by itself.

INVT (INViTe a user to a room)

This command may only be executed by administrators, or by the room
administrator for the current room. It is used primarily to add users to
invitation-only rooms, 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. 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.

WHOK (WHO Knows room)

This command is available only to administrators.
ERROR+HIGHER_ACCESS_REQUIRED will be returned if the user is not an
administrator. Otherwise, it returns LISTING_FOLLOWS and then lists, one user
per line, every user who has access to the current room.

KICK (KICK a user out of a room)

This is the opposite of INVT: it is used to kick a user out of a private room.
It can also be used to kick a user out of a public room, but the effect will
only be the same as if the user [Z]apped the room - a non-stupid user can
simply un-zap the room to get back in.

Commands related to a room's file directory
-------------------------------------------

DELF (DELete a File)

This command deletes a file from the room's directory, if there is one. The
name of the file to delete is the only parameter to be supplied. Wildcards are
not acceptable, and any slashes in the filename will be converted to
underscores, to prevent unauthorized access to neighboring directories. The
possible return codes are:

OK Command succeeded. The file was deleted.
ERROR+NOT_LOGGED_IN Not logged in.
ERROR+HIGHER_ACCESS_REQUIRED Not an administrator or Room administrator.
ERROR+NOT_HERE There is no directory in this room.
ERROR+FILE_NOT_FOUND Requested file was not found.

MOVF (MOVe a File)

This command is similar to DELF, except that it moves a file (and its associated
file description) to another room. It should be passed two parameters: the name
of the file to move, and the name of the room to move the file to. All of the
same return codes as DELF may be returned, and also one additional one:
ERROR+NO_SUCH_ROOM, which means that the target room does not exist.
ERROR+NOT_HERE could also mean that the target room does not have a directory.

OPEN (OPEN a file for download)

This command is used to open a file for downloading. Only one download file may
be open at a time. The only argument to this command is the name of the file to
be opened. The user should already be in the room where the file resides.
Possible return codes are:

ERROR+NOT_LOGGED_IN
ERROR+NOT_HERE no directory in this room
ERROR+FILE_NOT_FOUND could not open the file
ERROR misc errors
OK file is open

If the file is successfully opened, OK will be returned, along with the size (in
bytes) of the file, the time of last modification (if applicable), the filename
(if known), and the MIME type of the file (if known).

CLOS (CLOSe the download file)

This command is used to close the download file. It returns OK if the file was
successfully closed, or ERROR if there wasn't any file open in the first place.

READ (READ from the download file)

Two arguments are passed to this command. The first is the starting position in
the download file, and the second is the total number of bytes to be read. If
the operation can be performed, BINARY_FOLLOWS will be returned, along with the
number of bytes to follow. Then, immediately following the newline, will be
that many bytes of binary data. The client **must** read exactly that number of
bytes, otherwise the client and server will get out of sync.

If the operation cannot be performed, any of the usual error codes will be returned.

UOPN (OPeN a file for Uploading)

This command is similar to OPEN, except that this one is used when the client
wishes to upload a file to the server. The first argument is the name of the
file to create, the second argument is the MimmeType of the file and the third
argument is a one-line comment describing the contents of the file. Only one
upload file may be open at a time. Possible return codes are:

If OK is returned, the command has succeeded and writes may be performed.

UCLS (CLoSe the Upload file)

Close the file opened with UOPN. An argument of "1" should be passed to this
command to close and save the file; otherwise, the transfer will be considered
aborted and the file will be deleted. This command returns OK if the operation
succeeded or ERROR if it did not.

WRIT (WRITe to the upload file)

If an upload file is open, this command may be used to write to it. The
argument passed to this command is the number of bytes the client wishes to
transmit. An ERROR code will be returned if the operation cannot be performed.

If the operation can be performed, SEND_BINARY will be returned, followed by the
number of bytes the server is expecting. The client must then transmit exactly
that number of bytes. Note that in the current implementation, the number of
bytes the server is expecting will always be the number of bytes the client
requested to transmit, but the client software should never assume this.

UIMG (Upload an IMaGe file)

UIMG is complemenary to OIMG; it is used to upload an image to the server. 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 should specify the MIME type of the
image. The third argument is the name of the file to be transmitted. The
filename is converted to all lower case and stored in the "images" directory.

UIMG returns OK if the client has permission to perform the requested upload, or
ERROR+HIGHER_ACCESS_REQUIRED otherwise. If the client requested to begin the
operation (first parameter set to 1), an upload file is opened, and the client
should begin writing to it with WRIT commands, then close it with a UCLS command.

The supplied filename should be one of the "well known" filenames described in
the writeup for the OIMG command.

OIMG (Open an IMaGe file)

Open an image (graphics) file for downloading. Once opened, the file can be
read as if it were a download file. This implies that an image and a download
cannot be opened at the same time. OIMG returns the same result codes as OPEN.

In the case of Citadel, the server will convert the supplied filename to all
lower case 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:

hello "Welcome" graphics to be displayed alongside MESG "hello"
goodbye Logoff banner graphics to be displayed alongside MESG "goodbye"
background Background image (usually tiled) for graphical clients

DLRI (DownLoad Room Image)

Download the image (photo, icon, etc.) associated with the current room. If
successful, DLRI returns data in the same format as the DLAT (DownLoad
ATtachment) command: a BINARY_FOLLOWS code followed by three parameters - the
number of bytes in the data, a filename (always empty), the MIME type of the
image (such as image/gif), and the character set (always empty).

ULRI (UpLoad Room Image)

Upload the image (photo, icon, etc.) associated with the current room. This
command should be passed two parameters:

0 Data length to be transmitted (in bytes)
1 MIME Content-Type of the data to be transmitted

An error will occur if a user without administrative privileges attempts to
change a room image.

If successful, a SEND_BINARY response will be delivered, along with the number
of bytes expected. The client MUST then transmit a binary blob containing that
number of bytes.

Commands that change the behavior of this Citadel System
--------------------------------------------------------

Overall Configuration
---------------------

CONF (get or set global CONFiguration options)

Retrieves or sets various system-wide configuration and policy options. This
command is only available to Admins.

Each configuration variable has a name (see below) which can be read or set.
CONF GETVAL will read the value of a configuration variable by name.
CONF PUTVAL will set the value of a configuration variable by name.
CONF LISTVAL will list all configuration variable names and values.

There is also a legacy mode (CONF GET and CONF SET) available. These
subcommands are deprecated and should not be used in new implementations.
If the GET command succeeds, CONF will return LISTING_FOLLOWS followed by the
fields described below, one line at a time. If the SET command succeeds, CONF
will return SEND_LISTING and expect the fields described below, one line at a
time (don't worry about other fields being added in the future; if a 'short'
configuration list is sent, the missing values at the end will be left unchanged
on the system). If either command fails for any reason, ERROR is returned.

The configuration lines are as follows:
Line Variable name Value
------ -------------------- -----------------------------------------------
0 c_nodename Node name
1 c_fqdn Fully qualified domain name
2 c_humannode Human-readable node name
3 c_phonenum Land line telephone number of this system
4 c_creataide Flag (0 or 1) - creator of private room
automatically becomes room administrator
5 c_sleeping Server connection idle timeout (in seconds)
6 c_initax Initial access level for new users
7 c_regiscall Flag (0 or 1) - require registration for new users
8 c_twitdetect Flag (0 or 1) - automatically move Problem User messages to twit room
9 c_twitroom Name of twit room
10 c_moreprompt Text of paginator prompt for console-based clients (for example, "[more]")
11 c_restrict Flag (0 or 1) - restrict access to Internet mail
12 c_bbs_city Geographic location of this system
13 c_sysadm Name of the system administrator
14 c_maxsessions Number of maximum concurrent sessions allowed on the server
15 (placeholder -- this field is no longer in use)
16 c_userpurge Default purge time (in days) for users
17 c_roompurge Default purge time (in days) for rooms
18 c_logpages Name of room to log instant messages to (or a zero-length name for none)
19 c_createax Access level required to create rooms
20 c_maxmsglen Maximum message length which may be entered into the system
21 c_min_workers Minimum number of worker threads
22 c_max_workers Maximum number of worker threads
23 c_pop3_port Port number for POP3 service
24 c_smtp_port Port number for SMTP service
25 c_rfc822_strict_from Flag (0-3) - strict RFC822 adherence
0: no from: headers altered
1: only if not a valid email alias of the user
2: always the users primary email address
3: Reject the mail if its not a valid alias
26 c_aide_zap Flag (0 or 1) - allow administrators to zap (forget) rooms
27 c_imap_port Port number for IMAP service
28 c_net_freq How often (in seconds) to run network processing jobs
29 c_disable_newu Flag (0 or 1) - disable self-service new user registration
30 (placeholder -- this field is no longer in use)
31 c_purge_hour Hour (0 through 23) during which database auto-purge jobs are run
32 c_ldap_host Name of host where an LDAP service may be found
33 c_ldap_port Port number of LDAP service on above host
34 c_ldap_base_dn LDAP Base DN
35 c_ldap_bind_dn LDAP Bind DN
36 c_ldap_bind_pw Password for LDAP Bind DN
37 c_ip_addr Server IP address to listen on (or "0.0.0.0" for all addresses)
38 c_msa_port Port number for SMTP MSA service
39 c_imaps_port Port number for IMAPS (SSL-encrypted IMAP)
40 c_pop3s_port Port number for POP3S (SSL-encrypted POP3)
41 c_smtps_port Port number for SMTPS (SSL-encrypted SMTP)
42 c_enable_fulltext Flag (0 or 1) - enable full text search index
43 c_auto_cull Flag (0 or 1) - automatically cull database log files
44 c_instant_expunge Flag (0 or 1) - enable IMAP"instant expunge" of deleted messages
45 c_allow_spoofing Flag (0 or 1) - allow unauthenticated SMTP clients to spoof my domains
46 c_journal_email Flag (0 or 1) - perform journaling of email messages
47 c_journal_pubmsgs Flag (0 or 1) - perform journaling of non-email messages
48 c_journal_dest Address to which journalized messages are to be sent
49 c_default_cal_zone Default time zone (Olsen database name) for unzoned calendar items
50 c_pftcpdict_port Port number for Postfix TCP Dict
51 (placeholder - no longer in use)
52 c_auth_mode Authentication mode:
0 for native, 1 for host (PAM) auth,
2 LDAP with POSIX schema, 3 LDAP with MS AD schema
53 (placeholder -- this field is no longer in use)
54 (placeholder -- this field is no longer in use)
55 (placeholder -- this field is no longer in use)
56 (placeholder -- this field is no longer in use)
57 c_rbl_at_greeting Flag (0 or 1) - perform RBL checks before SMTP greeting
instead of after RCPT command
58 (placeholder - no longer in use)
59 (placeholder - no longer in use)
60 c_pager_program External pager command
61 c_imap_keep_from IMAP keep original from header in msgs
62 c_xmpp_c2s_port XMPP client-to-server port (usually 5222)
63 c_xmpp_s2s_port XMPP server-to-server port (usually 5269)
64 c_pop3_fetch POP3 Aggregator System Default Frequency
65 c_pop3_fastest POP3 Aggregator minimum poll Frequency
66 c_spam_flag_only set to 1 to flag spam instead of rejecting it
67 c_guest_logins set to 1 to allow anonymous guest logins
68 c_port_number Listening port number for Citadel client protocol
69 c_ctdluid User id (uid) under which Citadel server will run
70 c_nntp_port Port number for NNTP service
71 c_nntps_port Port number for NNTPS (SSL-encrypted NNTP)
72 smtp_advertise_starttls Set to 1 to offer STARTTLS in the SMTP server

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.

Some of these configuration variables will have no effect depending on how the server
is configured. For example, the LDAP-specific configs have no effect on Citadel
servers in which LDAP support is not enabled.

Commands related to the auto-purger
-----------------------------------

The citadel system is designed to let messages vanish once they've been a
certain time on the system, and are no longer of interest to user. These
commands configure the global configuration. This is available on a per room
basis too. For a technical discussion of how this works internally, read the
documentation article on deferred processing.

GPEX (Get Policy for message EXpiration)

Returns the policy of the current room, floor, or site regarding the automatic
purging (expiration) of messages. The following policies are available:

0 EXPIRE_NEXTLEVEL Inherit the policy of the next higher
level. If this is a room, use the floor's default
policy. If this is a floor, use the system
default policy. This is an invalid value for the
system policy.
1 EXPIRE_MANUAL Do not purge messages automatically.
2 EXPIRE_NUMMSGS Purge by message count.
(Requires a value: number of messages)
3 EXPIRE_AGE 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:
"roompolicy" "floorpolicy" "sitepolicy" "mailboxespolicy"

If successful, GPEX returns OK followed by [policy]|[value].

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 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" "mailboxes"

If successful, GPEX returns OK; otherwise, an ERROR code is returned.

TDAP (manually initate The Dreaded Auto Purger)

Nearly all database maintenance involving the removal of deleted or expired
items from the database is deferred until off-hours in order to improve the
interactive performance of the system. This nightly job is affectionately
known as The Dreaded Auto-Purger, and it runs at an hour which is specified in
the global system configuration.

If for some reason you want to manually initiate a run of the purger, the TDAP
command can be issued. This command will ignore any parameters passed to it,
and of course it will fail if the user is not an administrator. If the command
is accepted, OK is returned, and the purger will begin running within one minute.
If the command is not accepted, ERROR is returned.

Server Maintenance Commands
---------------------------

SMTP (utility commands for the SMTP gateway)

This command, accessible only by administrators, 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)

DOWN (shut DOWN the server)

This command, which may only be executed by an administrator, immediately shuts
down the server. The server will disconnect all active client sessions and
closes its databases as quickly as possible. It then exits with exit code 0.

OK is returned if the user is allowed to shut down the server, in which case the
client program should expect the connection to be immediately broken.

SCDN (Schedule or Cancel a shutDowN)

SCDN sets or clears the "scheduled shutdown" flag. Pass this command a 1 or 0
to respectively set or clear the flag. When the "scheduled
shutdown" flag is set, the server will be shut down when there are no longer any
users logged in. Any value other than 0 or 1 will not change the flag,
only report its state. No users will be kicked off the system, and in fact the
server is still available for new connections. The command returns ERROR if it
fails; otherwise, it returns OK followed by a number representing the current state of the flag.

HALT (HALT the server without shutting it down)

Identical to the DOWN command, except instead of exiting, the server process
cleans up and then suspends indefinitely. This could potentially be useful for
shutdown scripts that don't want init to automatically respawn another citserver
process.

User Related Commands
---------------------

Session authentication
----------------------

NEWU (create NEW User account)

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 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, 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+ILLEGAL_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.

CREU (CREate new User account)

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 administrator,
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.

VALI (VALIdate user)

This command is used to validate users. Obviously, it can only be executed by
users with administrator level access. It should be passed two parameters: the
name of the user to validate, and the desired access level

If the command succeeds, OK is returned. The user's access level is changed and
the "need validation" bit is cleared. If the command fails for any reason,
ERROR, ERROR+NO_SUCH_USER, or ERROR+HIGHER_ACCESS_REQUIRED will be returned.

QUSR (Query for a USeR)
This command is used to check to see if a particular user exists. The only
argument to this command is the name of the user being searched for. If the
user exists, OK is returned, along with the name of the user in the userlog (so
the client software can learn the correct upper/lower casing of the name if
necessary). If the user does not exist, ERROR+NO_SUCH_USER is returned. No
login or current room is required to utilize this command.

LIST (user LISTing)

This is a simple user listing. It always succeeds, returning LISTING_FOLLOWS
followed by zero or more user records, 000 terminated. The fields on each line
are as follows:

- User display name
- Access level
- User number
- Date/time of last login (Unix timestamp format)
- (empty field)
- (empty field)
- Password (listed only if the user requesting the list is an administrator)

Unlisted entries will also be listed to administrators logged into the server,
but not to ordinary users.

The LIST command accepts an optional single argument, which is a simple,
case-insensitive search string. If this argument is present, only usernames in
which the search string is present will be returned. It is a simple substring
search, not a regular expression search. If this string is empty
or not present, all users will be returned.

Commands which manipulate user records
--------------------------------------

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+NOT_LOGGED_IN,
or if the user is an auto-login user, in which case it will return
ERROR+NOT_HERE.

If the specified password is the string "GENERATE_RANDOM_PASSWORD", then a
random password will be generated, and returned to the client immediately after
the OK success code. This might be useful for hosting systems which provide a
way for a user to administratively reset a password via email, for example.

GETU (GET User configuration)

This command retrieves the configuration options for the 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 two parameters in the past conveyed the stored screen dimensions for
the user, but since modern displays are able to communicate their screen
dimensions back to the system this is no longer needed, so the server always
returns 80x24 as a placeholder.

The third parameter is a bag of bits with the following meanings:

US_LASTOLD 16 Print last old message with new
US_EXPERT 32 Experienced user (suppress some of the help blurbs)
US_UNLISTED 64 Unlisted userlog entry
US_NOPROMPT 128 Don't prompt after each message
US_DISAPPEAR 512 Use "disappearing msg prompts"
US_PAGINATOR 2048 Pause after each screen of text

There are other bits, too, but they can't be changed by the user (see below).

SETU (SET User configuration)

This command does the opposite of GETU: it takes the screen dimensions and 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). 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 administrators. SETU will ignore attempts to
toggle these bits. There also may be more user settable bits added at a later
date. To maintain later downward compatibility, the following procedure is suggested:

* Execute GETU to read the current flags
* Toggle the bits that we know we can toggle
* Execute SETU to write the flags

If we are passed a bit whose meaning we don't know, it's best to leave it
alone, and pass it right back to the server. That way we can use an old client
on a server that uses an unknown bit without accidentally clearing it every
time we set the user's configuration.

As noted above, we no longer store per-user screen dimensions, so any value supplied will be ignored.

EBIO (Enter BIOgraphy)

Transmit to the server a free-form text file containing a little bit of
information about the user for other users to browse. This is typically
referred to as a 'bio' online. EBIO returns SEND_LISTING if it succeeds, after
which the client is expected to transmit the file, or any of the usual ERROR
codes if it fails.

RBIO (Read BIOgraphy)

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. The
return has the following parameters: the user name, user number, access level,
date of last call, (empty field), and (empty field). 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.

DLUI (DownLoad User Image)

Download the image (photo, icon, avatar, etc.) associated with a user account.
This command should be passed a single argument - the name of the user whose
photo is requested. If successful, DLUI returns data in the same format as the
DLAT (DownLoad ATtachment) command: a BINARY_FOLLOWS code followed by three
parameters - the number of bytes in the data, a filename (always empty), the
Content-Type (such as image/gif), and the character set (always empty).

ULUI (UpLoad User Image)

Upload the image (photo, icon, avatar, etc.) associated with a user account.
This command may be passed either two or three parameters:

0 Data length to be transmitted (in bytes)
1 MIME Content-Type of the data to be transmitted
2 (Optional) name of the user whose image is being uploaded.
If empty, assumes the currently logged in user.

An error will occur if a user without administrative privileges attempts to
change another user's photo, or if a nonexistent user is specified.

If successful, a SEND_BINARY response will be delivered, along with the number
of bytes expected. The client MUST then transmit a binary blob containing that
number of bytes.

AGUP | ASUP (Administrative Get / Set User Parameters)

These commands are only executable by administrators. They are used to get/set
any and all parameters relating to a user account. AGUP requires only one
argument: the name of the user in question. ASUP requires all of the parameters
to be set. The parameters are as follows, and are common to both commands:

0 User name
1 Password
2 Flags (see libcitadel.h; US_*)
3 (empty field)
4 (empty field)
5 Access level
6 User number
7 Timestamp of last call
8 Purge time (in days) for this user (or 0 to use system default)

Upon success, AGUP returns OK followed by all these parameters, and ASUP simply
returns OK. If the client has insufficient access to perform the requested
operation, ERROR+HIGHER_ACCESS_REQUIRED is returned. If the requested user does
not exist, ERROR+NO_SUCH_USER is returned.

If 1 to 8 are 0, the user will be scheduled for deletion; he will be unable to
log in or send/receive email; His data will be removed on the next run of the
auto-purger; Until then, you won't be able to re-create a similar user.

AGEA (Administrative Get Email Addresses)

This command is only executable by administrators. It is used to retrieve a
list of Internet email addresses associated with a user account. The sole
parameter to be passed is the name of the user being queried.

If the current user is an administrator and the requested user account exists,
AGEA will return OK followed by a delimited list of email addresses; otherwise
an appropriate error code is returned.

ASEA (Administrative Set Email Addresses)

This command is only executable by administrators. It is used to set the list
of Internet email addresses associated with a user account. If the current
user is an administrator and the requested user account exists, ASEA will return
SEND_LISTING, at which time the client is expected to transmit a list of all
Internet email addresses to be associated with the account. This list *replaces*
any existing email addresses associated with the account. Any addresses
that are invalid, or belong to domains not associated with the Citadel server,
or belong to other users, will be silently discarded.

If the current user is not an administrator or if the requested user account
does not exist, an appropriate error code is returned.

RENU (REName a User)

Because the Citadel system uses the display name of a user as the primary
database key for the account, changing the display name requires a separate
operation. RENU renames a user. It must be supplied with two parameters: the
old (existing) and new (desired) user account names.

RENU will return one of the following codes:

OK Operation succeeded; the user has been renamed.
ERROR+ALREADY_LOGGED_IN The user cannot be renamed because the account
is currently logged in.
ERROR+NO_SUCH_USER The specified user does not exist.
ERROR+ALREADY_EXISTS An account with the requested new name already exists.

GNUR (Get Next Unvalidated User)

This command shows the name of a user that needs to be validated. If there are
no unvalidated users, OK is returned. Otherwise, MORE_DATA is returned along
with the name of the first unvalidated user the server finds. All of the usual
ERROR codes may be returned as well (for example, if the user is not an
administrator and cannot validate users).

A typical "Validate New Users" command would keep executing this command, and
then validating each user it returns, until it returns OK when all new users
have been validated.

GREG (Get REGistration for user)

This command retrieves the registration info for a user, whose name is the
command's sole argument. All the usual error messages can be returned. If the
command succeeds, LISTING_FOLLOWS is returned, followed by the user's name
(retrieved from the userlog, with the right upper and lower case etc.) The
contents of the listing contains one field per line, followed by the usual 000
on the last line.

The following lines are defined. Others WILL be added in the futre, so all
software should be written to read the lines it knows about and then ignore all
remaining lines:

1 User number
2 Password
3 Real name
4 Street address or PO Box
5 City/town/village/etc.
6 State/province/etc.
7 ZIP or Postal Code
8 Telephone number
9 Access level
10 Internet e-mail address
11 Country

Users without administrator privileges may retrieve their own registration
using this command. This can be accomplished either by passing the user's own
name as the argument, or the string "_SELF_". The command will always succeed
when used in this manner, unless no user is logged in.

REGI (send REGIstration)

Clients will use this command to transmit a user's registration info. If no
user is logged in, ERROR+NOT_LOGGED_IN is returned. Otherwise, SEND_LISTING is
returned, and the server will expect the following information (terminated by
000 on a line by itself):

1 Real name
2 Street address or PO Box
3 City/town/village/etc.
4 State/province/etc.
5 ZIP or postal code
6 Telephone number
7 email address
8 Country

Please note that this command is deprecated. The preferred way to transmit
this information is to submit it as a vCard (with MIME type "text/x-vcard") to
the user's "My Citadel Config" room.

CHEK (CHEcK various things)

When logging in, there are various things that need to be checked. This
command will return ERROR+NOT_LOGGED_IN if no user is logged in. Otherwise it
returns OK and the following parameters:

0 Number of new private messages in Mail>
1 Nonzero if the user needs to register
2 (Relevant to administrators only) Nonzero if new users require validation
3 The user's preferred Internet e-mail address

Runtime Attribute Manipulation
------------------------------

Users can modify the way they are anounced to others using these commands. This
data is shown for example in the "who is online" list

STEL (enter STEaLth mode)

When in "stealth mode," a user will not show up in the "Who is online" listing
(the RWHO server command). Only administrators may use stealth mode. The STEL
command accepts one argument: a 1 indicating that the user wishes to enter
stealth mode, or a 0 indicating that the user wishes to exit stealth mode.
STEL returns OK if the command succeeded, ERROR+NOT_LOGGED_IN if no user is
logged in, or ERROR+HIGHER_ACCESS_REQUIRED if the user is not an
administrator; followed by a 1 or 0 indicating the new state.

If any value other than 1 or 0 is sent by the client, the server simply replies
with 1 or 0 to indicate the current state without changing it.

The STEL command also hides a user's presence from chat rooms.