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

Commands that change the behavior of this Citadel System

Overall Configuration

IGAB (Initialize Global Address Book)

This command creates, or re-creates, a database of Internet e-mail addresses using the vCard information in the Global Address Book room. 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 Aide can run the command. It returns OK on success or ERROR on failure.

CONF (get or set global CONFiguration options)

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

The six forms of this command are:

CONF SETVAL|name|value

There are two ways to read and change the system configuration. In the legacy mode (the sole parameter is GET or SET), an entire portion of the system configuration is transferred, with each field indicated by its position in the listing. In the new mode (first parameter is GETVAL or SETVAL), a single configuration variable may be read or set by name.

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:

No. 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 aide
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 <more> prompt
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 reserved1 (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 Aides to zap (forget) rooms
27 c_imap_port Port number for IMAP service
28 c_net_freq How often (in seconds) to run the networker
29 c_disable_newu Flag (0 or 1) - disable self-service new user registration
30 reserved2 (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 “” 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 c_mgesve_port Port number for managesieve service
52 c_auth_mode Authentication mode (0 for native, 1 for host (PAM) auth, 2 LDAP, 3 LDAP with MS AD scheme); (Please note that users are bound to authmodes, and are only visible for the mode they were created with)
53 c_funambol_host Host name of Funambol server with Citadel connector
54 c_funambol_port Port number of Funambol server with Citadel connector
55 c_funambol_source funambol source
56 c_funambol_auth funambol auth
57 c_rbl_at_greeting Flag (0 or 1) - perform RBL checks before SMTP greeting instead of after RCPT command
58 c_master_user Master user name (if in use)
59 c_master_pass Master user password (if 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)

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.

Please note that the LDAP-specific configs have no effect on Citadel servers in which LDAP support is not enabled.

Autopurger Related

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 this article on How deferred processing works in Citadel.

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:

No. Name Value
0 EXPIRE_NEXTLEVEL Fall back to 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 Aide. 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.

More details:

Server Maintainance Commands

RSEN Retrieve Seen Status

Administrative command to debug seen stati. Hint: enable seen database debug logs.


fetches the timestamp (if) whether a message of this identity is in the database


Sets the timestamp for this message ID in the database


Removes this entry from the database (if)

SMTP (utility commands for the SMTP gateway)

This command, accessible only by Aides, 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 Aide, immediately shuts down the server. It is only implemented on servers on which such an operation is possible, such as a multithreaded Citadel engine. It takes one optional integer Parameter, that tells the server to try to come up again with the aid of his watcher process, Though it will do a full shutdown, and do allmost everything except for reparsing its commandline. If the parameter is set to 0 or is ommited the server does not restart. DOWN returns OK if the user is allowed to shut down the server, in which case the client program should expect the connection to be immediately broken. If the server isn't running deamonized and is ordered to restart he will answer with an apropriate error, so the client can tell the user he should pay attenion to this.

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. 2 and 3 will do the same, but make the watcher fire up the server again instead of shutting down. 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, 1, 2 or 3 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.

LOGP (LOGging configuration Print)

(available > 8.10) ERROR+HIGHER_ACCESS_REQUIRED if a non-aide user calls this. Else LISTING_FOLLOWS and a listing of the available debug logging facilities

  1. name of the facility
  2. 0/1 whether its turned on or of

LOGS (LOGging configuration Set)

(available > 8.10) ERROR+HIGHER_ACCESS_REQUIRED if a non-aide user calls this. Parameters are the facility to change (see LOGP output for the available list) plus 0 for enable, 1 for disable.

MIGR (Migration & system repair)

These facilities are used by the ctdlmigrate utility which you can use to transfer the contents from an old to a new host.


Outputs a list of directories, which should be transfered outside of the scope of the protocol


Outputs xml containing all floor, room, messages and configurations


Facility that imports the output of export


This utility is not directly related to migration. It analyses internal datastructures, tries to find inconsistencies and fix them.

  1. messages linked in rooms which aren't present in the system anymore are removed
  2. message metadata is reconstructed from the core message data itself. Therefore the whole message database is crawled, all messages loaded, parsed and analysed.
Copyright © 1987-2015 Uncensored Communications Group. All rights reserved.     Login (site admin)