Home Download News FAQ / Knowledge Base Screenshots Documentation Support Site map
philosophical imaginary

This is an old revision of the document!


Table of Contents

General Commands

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

Misc

Commands that Don't fit into special sections

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 aides can still see unlisted userlog entries.

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

mainmenu Main menu (when in idiot mode).
aideopt .A?
readopt .R?
entopt .E?
dotopt .?
saveopt Options to save a message, abort, etc.
entermsg Displayed just before a message is entered, when in idiot mode.

Several values are replaced into these helpfiles:

TokenValue
^nodename The node name of your system on a Citadel network
^humannode Human-readable node name (also your node name on C86Net)
^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

MRTG (Multi Router Traffic Grapher)

Multi Router Traffic Grapher (please see http://www.mrtg.org for more info) is a tool which creates pretty graphs of network activity, usually collected from routers using SNMP. However, its ability to call external scripts has spawned a small community of people using it to graph anything which can be graphed. The MRTG command can output Citadel server activity in the format MRTG expects.

This format is as follows:

MRTG accepts two different keywords. “MRTG users” will return two variables, the number of connected users and the number of active users. “MRTG messages” will return one variable (and a zero in the second field), showing the current highest message number on the system. Any other keyword, or a missing keyword, will cause the MRTG command to return an ERROR code.

Please get in touch with the Citadel developers if you wish to experiment with this.

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.

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 (in case the client wants the right upper/lower casing)
1 The user's current access level
2 Times called
3 Messages posted
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:

developer ID number (same as the server developer ID numbers in the INFO command – please obtain one if you are a new developer)
client ID number (which does not have to be globally unique - only unique within the domain of the developer number)
version number the Version of your Client
Client IDString afree-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.

IPGM (identify as an Internal ProGraM)

IPGM is a low-level command that should not be used by normal user clients. It is used for various utilities to communicate with the server on the same host. For example, the “sendcommand” utility logs onto the server as an internal program in order to run arbitrary server commands. Since user clients do not utilize this command (or any of its companion commands), developers writing Citadel-compatible servers need not implement it.

The sole argument to IPGM is the system's internal program password. This password is generated by the setup program and stored in the config file. Since internal programs have access to the config file, they know the correct password to use.

IPGM returns OK for a correct authentication or ERROR otherwise.

QUIT (QUIT)

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

Email Related

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 (server v4.03 and above) The name of the host the client is connecting from, or “localhost” if the client is local.
4 (server v4.04 and above) 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: + (spoofed address), - (STEALTH mode), * (posting) and . (idle).
8 Actual user name, if user name is masqueraded and viewer is an Aide.
9 Actual room name, if room name is masqueraded and viewer is an Aide.
10 Actual host name, if host name is masqueraded and viewer is an Aide.
11 Nonzero if the session is a logged-in user, zero otherwise.

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.

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:

line Content
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) * 100
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 (blank - 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 LoadAverage; Average Load calculation inside of citadel. *1
18 WorkerAverage; average count of workerthreads *1
19 ThreadCount; Actual number of worker threads *1
20 Nonzero if the server supports filtering of incoming mail using the Sieve language.
21 Nonzero if the server's full text index is enabled.
22 The servers SVN repository revision code.
23 Version of OpenID supported by the server for authentication. 0 if no support.
24 Nonzero if the server supports anonymous guest logins

*1 → actual development version.
NOTE! The “server type” code is intended to promote global compatibility in a scenario in which developers have added local features to their servers or clients. We are attempting to avoid a future situation in which users need to keep different client software around for each Citadel they use. Please, if you are a developer and plan to add local features:

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.

Please refer to “developers.txt” for information on what codes belong to whom.

Connection Related

TERM (TERMinate another session)

In a multithreaded environment, it sometimes becomes necessary to terminate a session that is unusable for whatever reason. The TERM command performs this task. Naturally, only Aides 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 the session it is currently running on.

See also: REQT

REQT (REQuest client Termination)

Request that the specified client (or all clients) log off. Aide level access is required to run this command, otherwise ERROR+HIGHER_ACCESS_REQUIRED is returned.

The REQT command accepts one parameter: the session ID of the client which should be terminated, or 0 for all clients. When successful, the REQT command returns OK.

It should be noted that REQT simply transmits an instant message to the specified client(s) with the EM_GO_AWAY flag set. Older clients do not honor this flag, and it is certainly possible for users to re-program their client software to ignore it. Therefore the effects of the REQT command should be 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
Copyright © 1987-2014 Uncensored Communications Group. All rights reserved.     Login (site admin)