Home Download News FAQ / Knowledge Base Screenshots Documentation Support
philosophical imaginary
Table of Contents

Application Layer Protocol for the Citadel system

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


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!

Anyone who wants to add commands or other functionality to this protocol, please get in touch so that these efforts can be coordinated. New commands added by other developers can be added to this document, so we don't end up with new server commands from multiple developers which have the same name but perform different functions. If you don't coordinate new developments ahead of time, please at least send in an e-mail documenting what you did, so that your new commands can be added to this document.

You can get in touch with a coordinator via the Citadel Support forum.

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 Sets

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: ERROR, OK, MORE_DATA, LISTING_FOLLOWS, and SEND_LISTING.

The second and third digits may provide a reason as to why a command succeeded or failed. See ipcdef.h for the available codes.


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: 80, 24, and 260.

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.

The following Sections are available:

Copyright © 1987-2020 Uncensored Communications Group. All rights reserved.     Login (site admin)