Commands that change the behavior of this Citadel System

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.

Retrieves or sets various system-wide configuration and policy options. This command is only available to Aides. The sole parameter accepted is a command, which should be either GET or SET. 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:

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.

These commands are only executable by Aides and by server extensions running at system-level. They are used to get/set any and all parameters relating to a user account. AGUP requires only one argument: the name of the user in question. SGUP requires all of the parameters to be set. The parameters are as follows, and are common to both commands:

Upon success, AGUP returns OK followed by all these parameters, and ASUP simply returns OK. If the client has insufficient access to perform the requested operation, ERROR+HIGHER_ACCESS_REQUIRED is returned. If the requested user does not exist, ERROR+NO_SUCH_USER is returned.

Because the Citadel system uses the display name of a user as the primary database key for the account, changing the display name requires a separate operation. RENU renames a user. It must be supplied with two parameters: the old (existing) and new (desired) user account names.

RENU will return one of the following codes:

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.

Returns the policy of the current room, floor, or site regarding the automatic purging (expiration) of messages. The following policies are available:

The format of this command is:

GPEX <which>

The value of <which> must be one of: “room” “floor” “site” “mailboxes”

If successful, GPEX returns OK followed by <policy>|<value>.

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.

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.

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:

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 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.

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.