This is an old revision of the document!
This is a listing of all the commands that a Citadel server can execute.
Commands that Don't fit into special sections
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.
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.
This command also does nothing. It simply returns OK followed by whatever its arguments are.
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.
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).|
|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:
|^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|
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:
- Line 1: variable #1
- Line 2: variable #2
- Line 3: uptime of system
- Line 4: name of system
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.
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.
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 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|
|4||Various flags (see citadel.h)|
|6||Time of last call (UNIX timestamp)|
Log out the user without closing the server connection. It always returns OK even if no user is logged in.
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 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.
Terminate the server connection. This command takes no arguments. It returns OK and closes the connection immediately.
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.|
|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.
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.
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.
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.
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) * 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:
- 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.
Please refer to “developers.txt” for information on what codes belong to whom.
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
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).
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.
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|