1 The totally incomplete guide to Citadel internals
2 -----------------------------------------------------
4 Citadel has evolved quite a bit since its early days, and the data structures
5 have evolved with it. This document provides a rough overview of how the
6 system works internally. For details you're going to have to dig through the
7 code, but this'll get you started.
12 As you probably already know by now, Citadel uses a group of tables stored
13 with a record manager (usually Berkeley DB). Since we're using a record
14 manager rather than a relational database, all record structures are managed
15 by Citadel. Here are some of the tables we keep on disk:
20 This table contains all user records. It's indexed by
21 user name (translated to lower case for indexing purposes). The records in
22 this file look something like this:
24 struct ctdluser { // User record
25 int version; // Citadel version. which created this record
26 uid_t uid; // Associate with a unix account?
27 char password[32]; // Account password (unless using external authentication)
28 unsigned flags; // See US_ flags below
29 CIT_UBYTE axlevel; // Access level
30 long usernum; // User number (never recycled)
31 time_t lastcall; // Last time the user called
32 int USuserpurge; // Purge time (in days) for user
33 char fullname[64]; // Name for Citadel messages & mail
36 Most fields here should be fairly self-explanatory. The ones that might
37 deserve some attention are:
39 - `uid` -- if uid is not the same as the *unix uid* Citadel is running as, then the
40 account is assumed to belong to the user on the underlying Unix system with
41 that uid. This allows us to require the user's OS password instead of having
42 a separate Citadel password.
44 - `usernum` -- these are assigned sequentially, and **NEVER REUSED**. This is
45 important because it allows us to use this number in other data structures
46 without having to worry about users being added/removed later on, as you'll
47 see later in this document.
52 These are room records. There is a room record for every room on the
53 system, public or private or mailbox. It's indexed by room name (also in
54 lower case for easy indexing) and it contains records which look like this:
57 char QRname[ROOMNAMELEN]; /* Name of room */
58 char QRpasswd[10]; /* Only valid if it's a private rm */
59 long QRroomaide; /* User number of room aide */
60 long QRhighest; /* Highest message NUMBER in room */
61 time_t QRgen; /* Generation number of room */
62 unsigned QRflags; /* See flag values below */
63 char QRdirname[15]; /* Directory name, if applicable */
64 long QRinfo; /* Info file update relative to msgs*/
65 char QRfloor; /* Which floor this room is on */
66 time_t QRmtime; /* Date/time of last post */
67 struct ExpirePolicy QRep; /* Message expiration policy */
68 long QRnumber; /* Globally unique room number */
69 char QRorder; /* Sort key for room listing order */
70 unsigned QRflags2; /* Additional flags */
71 int QRdefaultview; /* How to display the contents */
74 Again, mostly self-explanatory. Here are the interesting ones:
76 `QRnumber` is a globally unique room ID, while `QRgen` is the "generation number"
77 of the room (it's actually a timestamp). The two combined produce a unique
78 value which identifies the room. The reason for two separate fields will be
79 explained below when we discuss the visit table. For now just remember that
80 `QRnumber` remains the same for the duration of the room's existence, and `QRgen`
81 is timestamped once during room creation but may be restamped later on when
82 certain circumstances exist.
86 Floors. This is so simplistic it's not worth going into detail about, except
87 to note that we keep a reference count of the number of rooms on each floor.
91 Each record in this table consists of a bunch of message numbers
92 which represent the contents of a room. A message can exist in more than one
93 room (for example, a mail message with multiple recipients -- 'single instance
94 store'). This table is never, ever traversed in its entirety. When you do
95 any type of read operation, it fetches the msglist for the room you're in
96 (using the room's ID as the index key) and then you can go ahead and read
97 those messages one by one.
99 Each room is basically just a list of message numbers. Each time
100 we enter a new message in a room, its message number is appended to the end
101 of the list. If an old message is to be expired, we must delete it from the
102 message base. Reading a room is just a matter of looking up the messages
103 one by one and sending them to the client for display, printing, or whatever.
108 This is the tough one. Put on your thinking cap and grab a fresh cup of
109 coffee before attempting to grok the visit table.
111 This table contains records which establish the relationship between users
112 and rooms. Its index is a hash of the user and room combination in question.
113 When looking for such a relationship, the record in this table can tell the
114 server things like "this user has zapped this room," "this user has access to
115 this private room," etc. It's also where we keep track of which messages
116 the user has marked as "old" and which are "new" (which are not necessarily
117 contiguous; contrast with older Citadel implementations which simply kept a
118 "last read" pointer).
121 Here's what the records look like:
128 unsigned int v_flags;
133 #define V_FORGET 1 /* User has zapped this room */
134 #define V_LOCKOUT 2 /* User is locked out of this room */
135 #define V_ACCESS 4 /* Access is granted to this room */
137 This table is indexed by a concatenation of the first three fields. Whenever
138 we want to learn the relationship between a user and a room, we feed that
139 data to a function which looks up the corresponding record. The record is
140 designed in such a way that an "all zeroes" record (which is what you get if
141 the record isn't found) represents the default relationship.
143 With this data, we now know which private rooms we're allowed to visit: if
144 the `V_ACCESS` bit is set, the room is one which the user knows, and it may
145 appear in his/her known rooms list. Conversely, we also know which rooms the
146 user has zapped: if the `V_FORGET` flag is set, we relegate the room to the
147 zapped list and don't bring it up during new message searches. It's also
148 worth noting that the `V_LOCKOUT` flag works in a similar way to administratively
149 lock users out of rooms.
151 Implementing the "cause all users to forget room" command, then, becomes very
152 simple: we simply change the generation number of the room by putting a new
153 timestamp in the `QRgen` field. This causes all relevant visit records to
154 become irrelevant, because they appear to point to a different room. At the
155 same time, we don't lose the messages in the room, because the msglists table
156 is indexed by the room number (`QRnumber`), which never changes.
158 `v_seen` contains a string which represents the set of messages in this room
159 which the user has read (marked as 'seen' or 'old'). It follows the same
160 syntax used by IMAP and NNTP. When we search for new messages, we simply
161 return any messages that are in the room that are **not** represented by this
162 set. Naturally, when we do want to mark more messages as seen (or unmark
163 them), we change this string. Citadel BBS client implementations are naive
164 and think linearly in terms of "everything is old up to this point," but IMAP
165 clients want to have more granularity.
170 This table simply maps Internet e-mail addresses to Citadel network addresses
171 for quick lookup. It is generated from data in the Global Address Book room.
175 This table keeps track of message ID's of messages arriving over a network,
176 to prevent duplicates from being posted if someone misconfigures the network
177 and a loop is created. This table goes unused on a non-networked Citadel.
181 This is where all message text is stored. It's indexed by message number:
182 give it a number, get back a message. Messages are numbered sequentially, and
183 the message numbers are never reused.
185 We also keep a "metadata" record for each message. This record is also stored
186 in the msgmain table, using the index (0 - msgnum). We keep in the metadata
187 record, among other things, a reference count for each message. Since a
188 message may exist in more than one room, it's important to keep this reference
189 count up to date, and to delete the message from disk when the reference count
192 # Here's the format for the message itself:
194 - Each message begins with an 0xFF 'start of message' byte.
196 - The next byte denotes whether this is an anonymous message. The codes
197 available are `MES_NORMAL`, `MES_ANON`, or `MES_AN2` (defined in `citadel.h`).
199 - The third byte is a "message type" code. The following codes are defined:
200 - 0 - "Traditional" Citadel format. Message is to be displayed "formatted."
201 - 1 - Plain pre-formatted ASCII text (otherwise known as text/plain)
202 - 4 - MIME formatted message. The text of the message which follows is
203 expected to begin with a "Content-type:" header.
205 - After these three opening bytes, the remainder of
206 the message consists of a sequence of character strings. Each string
207 begins with a type byte indicating the meaning of the string and is
208 ended with a null. All strings are printable ASCII: in particular,
209 all numbers are in ASCII rather than binary. This is for simplicity,
210 both in implementing the system and in implementing other code to
211 work with the system. For instance, a database driven off Citadel archives
212 can do wildcard matching without worrying about unpacking binary data such
213 as message ID's first. To provide later downward compatability
214 all software should be written to IGNORE fields not currently defined.
217 # The type bytes currently defined are:
220 | BYTE | Enum | NW | Mnemonic | Enum / Comments
221 |-------|-------------------|------|----------------|---------------------------------------------------------
222 | A | eAuthor | from | Author | The display name of the Author of the message.
223 | B | eBig_message | | Big message | This is a flag which indicates that the message is
224 | | | | | big, and Citadel is storing the body in a separate
225 | | | | | record. You will never see this field because the
226 | | | | | internal API handles it.
227 | E | eExclusiveID | exti | Exclusive ID | A persistent alphanumeric Message ID used for
228 | | | | | replication control. When a message arrives that
229 | | | | | contains an Exclusive ID, any existing messages which
230 | | | | | contain the same Exclusive ID and are *older* than this
231 | | | | | message should be deleted. If there exist any messages
232 | | | | | with the same Exclusive ID that are *newer*, then this
233 | | | | | message should be dropped.
234 | F | erFc822Addr | rfca | rFc822 address | email address or user principal name of the message
236 | I | emessageId | msgn | Message ID | An RFC822-compatible message ID for this message.
238 | J | eJournal | jrnl | Journal | The presence of this field indicates that the message
239 | | | | | is disqualified from being journaled, perhaps because
240 | | | | | it is itself a journalized message and we wish to
241 | | | | | avoid double journaling.
242 | K | eReplyTo | rep2 | Reply-To | the Reply-To header for mailinglist outbound messages
243 | L | eListID | list | List-ID | Mailing list identification, as per RFC 2919
244 | M | eMesageText | text | Message Text | Normal ASCII, newlines seperated by CR's or LF's,
245 | | | | | null terminated as always.
246 | O | eOriginalRoom | room | Room | Room of origin.
247 | P | eMessagePath | path | Path | Complete path of message, as in the UseNet news
248 | | | | | standard. A user should be able to send Internet mail
249 | | | | | to this path. (Note that your system name will not be
250 | | | | | tacked onto this until you're sending the message to
251 | | | | | someone else)
252 | R | eRecipient | rcpt | Recipient | Only present in Mail messages.
253 | T | eTimestamp | time | date/Time | Unix timestamp containing the creation date/time of
254 | | | | | the message.
255 | U | eMsgSubject | subj | sUbject | Message subject. Optional.
256 | | | | | Developers may choose whether they wish to
257 | | | | | generate or display subject fields.
258 | V | eenVelopeTo | nvto | enVelope-to | The recipient specified in incoming SMTP messages.
259 | W | eWeferences | wefw | Wefewences | Previous message ID's for conversation threading. When
260 | | | | | converting from RFC822 we use References: if present, or
261 | | | | | In-Reply-To: otherwise.
262 | | | | | (Who in extnotify spool messages which don't need to know
263 | | | | | other message ids)
264 | Y | eCarbonCopY | cccc | carbon copY | Carbon copy (CC) recipients.
265 | | | | | Optional, and only in Mail messages.
266 | % | eHeaderOnly | nhdr | oNlyHeader | we will just be sending headers. for the Wire protocol only.
267 | % | eFormatType | type | type | type of citadel message: (Wire protocol only)
268 | | | | | FMT\_CITADEL 0 Citadel vari-format (proprietary)
269 | | | | | FMT\_FIXED 1 Fixed format (proprietary)
270 | | | | | FMT\_RFC822 4 Standard (headers are in M field)
271 | % | eMessagePart | part | emessagePart | eMessagePart is the id of this part in the mime hierachy
272 | % | eSubFolder | suff | eSubFolder | descend into a mime sub container
273 | % | ePevious | pref | ePevious | exit a mime sub container
274 | 0 | eErrorMsg | | Error | This field is typically never found in a message on
275 | | | | | disk or in transit. Message scanning modules are
276 | | | | | expected to fill in this field when rejecting a message
277 | | | | | with an explanation as to what happened (virus found,
278 | | | | | message looks like spam, etc.)
279 | 1 | eSuppressIdx | | suppress index | The presence of this field indicates that the message is
280 | | | | | disqualified from being added to the full text index.
281 | 2 | eExtnotify | | extnotify | Used internally by the serv_extnotify module.
282 | 3 | eVltMsgNum | | msgnum | Used internally to pass the local message number in the
283 | | | | | database to after-save hooks. Discarded afterwards.
284 | | | locl | | The presence of this field indicates that the message
285 | | | | | is believed to have originated on the local Citadel node,
286 | | | | | not as an inbound email or some other outside source.
290 Let `<FF>` be a `0xFF` byte, and `<0>` be a null `(0x00)` byte. Then a message
293 Apr 12, 1988 23:16 From Test User In Network Test> @lifesys (Life Central)
296 might be stored as...
298 <FF><40><0>I12345<0>Pneighbor!lifesys!test_user<0>T576918988<0> (continued)
299 -----------|Mesg ID#|--Message Path---------------|--Date------
301 AThe Test User<0>ONetwork Test<0>Nlifesys<0>HLife Central<0>MHave a nice day!<0>
302 |-----Author-----|-Room name-----|-nodename-|Human Name-|--Message text-----
304 Weird things can happen if fields are missing, especially if you use the
305 networker. But basically, the date, author, room, and nodename may be in any
306 order. But the leading fields and the message text must remain in the same
307 place. The H field looks better when it is placed immediately after the N
311 EUID (EXCLUSIVE MESSAGE ID'S)
312 -----------------------------
313 This is where the groupware magic happens. Any message in any room may have
314 a field called the Exclusive message *ID*, or *EUID*. We keep an index in the
315 table `CDB_EUIDINDEX` which knows the message number of any item that has an
316 *EUID*. This allows us to do two things:
318 - If a subsequent message arrives with the same *EUID*, it automatically
319 *deletes* the existing one, because the new one is considered a replacement
320 for the existing one.
321 - If we know the *EUID* of the item we're looking for, we can fetch it by *EUID*
322 and get the most up-to-date version, even if it's been updated several times.
324 This functionality is made more useful by server-side hooks. For example,
325 when we save a vCard to an address book room, or an iCalendar item to a
326 calendar room, our server modules detect this condition, and automatically set
327 the *EUID* of the message to the *UUID* of the *vCard* or *iCalendar* item.
328 Therefore when you save an updated version of an address book entry or
329 a calendar item, the old one is automatically deleted.
331 NETWORKING (REPLICATION)
332 ------------------------
333 Citadel nodes network by sharing one or more rooms. Any Citadel node
334 can choose to share messages with any other Citadel node, through the sending
335 of spool files. The sending system takes all messages it hasn't sent yet, and
336 spools them to the recieving system, which posts them in the rooms.
338 The *EUID* discussion above is extremely relevant, because *EUID* is carried over
339 the network as well, and the replacement rules are followed over the network
340 as well. Therefore, when a message containing an *EUID* is saved in a networked
341 room, it replaces any existing message with the same *EUID* *on every node in
344 Complexities arise primarily from the possibility of densely connected
345 networks: one does not wish to accumulate multiple copies of a given
346 message, which can easily happen. Nor does one want to see old messages
347 percolating indefinitely through the system.
349 This problem is handled by keeping track of the path a message has taken over
350 the network, like the UseNet news system does. When a system sends out a
351 message, it adds its own name to the bang-path in the *<P>* field of the
352 message. If no path field is present, it generates one.
354 With the path present, all the networker has to do to assure that it doesn't
355 send another system a message it's already received is check the <P>ath field
356 for that system's name somewhere in the bang path. If it's present, the system
357 has already seen the message, so we don't send it.
359 We also keep a small database, called the "use table," containing the ID's of
360 all messages we've seen recently. If the same message arrives a second or
361 subsequent time, we will find its ID in the use table, indicating that we
362 already have a copy of that message. It will therefore be discarded.
364 The above discussion should make the function of the fields reasonably clear:
366 o Travelling messages need to carry original message-id, system of origin,
367 date of origin, author, and path with them, to keep reproduction and
368 cycling under control.
370 (Uncoincidentally) the format used to transmit messages for networking
371 purposes is precisely that used on disk, serialized. The current
372 distribution includes serv_network.c, which is basically a database replicator;
373 please see network.txt on its operation and functionality (if any).
377 Citadel is 32/64 bit clean and architecture-independent. The software is
378 developed and primarily run on the Linux operating system (which uses the
379 Linux kernel) but it should compile and run on any reasonably POSIX
382 On the client side, it's also POSIX compliant. The client even seems to
383 build ok on non-POSIX systems with porting libraries (such as Cygwin and
386 SUPPORTING PRIVATE MAIL
387 -----------------------
388 Can one have an elegant kludge? This must come pretty close.
390 Private mail is sent and recieved in the `Mail>` room, which otherwise
391 behaves pretty much as any other room. To make this work, we have a
392 separate Mail> room for each user behind the scenes. The actual room name
393 in the database looks like `0000001234.Mail` (where `1234` is the user
394 number) and it's flagged with the `QR_MAILBOX` flag. The user number is
395 stripped off by the server before the name is presented to the client. This
396 provides the ability to give each user a separate namespace for mailboxes
399 This requires a little fiddling to get things just right. For example,
400 `make_message()` has to be kludged to ask for the name of the recipient
401 of the message whenever a message is entered in `Mail>`. But basically
402 it works pretty well, keeping the code and user interface simple and
405 PASSWORDS AND NAME VALIDATION
406 -----------------------------
407 This has changed a couple of times over the course of Citadel's history. At
408 this point it's very simple, again due to the fact that record managers are
409 used for everything. The user file (user) is indexed using the user's
410 name, converted to all lower-case. Searching for a user, then, is easy. We
411 just lowercase the name we're looking for and query the database. If no
412 match is found, it is assumed that the user does not exist.
414 This makes it difficult to forge messages from an existing user. (Fine
415 point: nonprinting characters are converted to printing characters, and
416 leading, trailing, and double blanks are deleted.)