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

User Related Commands

Session authentication

Become / Create this user

USER (send USER name)

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.

PASS (send PASSword)

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:

No. Value
0 The user's name (in case the client wants the right upper/lower casing)
1 The user's current access level
2 Times called
3 Messages posted
4 Various flags (see libcitadel.h; US_*)
5 User number
6 Time of last call (UNIX timestamp)

NEWU (create NEW User account)

This command creates a new user account AND LOGS IT IN. The argument to this command will be the name of the account. No case conversion is done on the name. Note that the new account is installed with a default configuration, and no password, so the client should immediately prompt the user for a password and install it with the SETP command as soon as this command completes. This command returns OK if the account was created and logged in, ERROR + ALREADY_EXISTS if another user already exists with this name, ERROR + NOT_HERE if self-service account creation is disabled, ERROR + MAX_SESSIONS_EXCEEDED if too many users are logged in, ERROR + USERNAME_REQUIRED if a username was not provided, or ERROR + ILELGAL_VALUE if the username provided is invalid. If OK, it will also return the same parameters that PASS returns.

Please note that the NEWU command should only be used for self-service user account creation. For administratively creating user accounts, please use the CREU command.

CREU (CREate new User account)

This command creates a new user account AND DOES NOT LOG IT IN. The first argument to this command will be the name of the account. No case conversion is done on the name. Note that the new account is installed with a default configuration, and no password. The second argument is optional, and will be an initial password for the user. This command returns OK if the account was created, ERROR + HIGHER_ACCESS_REQUIRED if the user is not an Aide, ERROR + USERNAME_REQUIRED if no username was specified, or ERROR + ALREADY_EXISTS if another user already exists with this name.

Please note that CREU is intended to be used for activities in which a system administrator is creating user accounts. For self-service user account creation, use the NEWU command.

VALI (VALIdate user)

This command is used to validate users. Obviously, it can only be executed by users with Aide level access. It should be passed two parameters: the name of the user to validate, and the desired access level

If the command succeeds, OK is returned. The user's access level is changed and the “need validation” bit is cleared. If the command fails for any reason, ERROR, ERROR+NO_SUCH_USER, or ERROR+HIGHER_ACCESS_REQUIRED will be returned.

QUSR (Query for a USeR)

This command is used to check to see if a particular user exists. The only argument to this command is the name of the user being searched for. If the user exists, OK is returned, along with the name of the user in the userlog (so the client software can learn the correct upper/lower casing of the name if necessary). If the user does not exist, ERROR+NO_SUCH_USER is returned. No login or current room is required to utilize this command.

LIST (user LISTing)

This is a simple user listing. It always succeeds, returning LISTING_FOLLOWS followed by zero or more user records, 000 terminated. The fields on each line are as follows:

  1. User display name
  2. Access level
  3. User number
  4. Date/time of last login (Unix timestamp format)
  5. Total number of logins
  6. Total number of messages posted
  7. Password (listed only if the user requesting the list is an Aide)

Unlisted entries will also be listed to Aides logged into the server, but not to ordinary users.

The LIST command accepts an optional single argument, which is a simple, case-insensitive search string. If this argument is present, only usernames in which the search string is present will be returned. It is a simple substring search, not a regular expression search. If this string is empty or not present, all users will be returned.

Manipulate existing users

SETP (SET new Password)

This command sets a new password for the currently logged in user. The argument to this command will be the new password. The command always returns OK, unless the client is not logged in, in which case it will return ERROR + NOT_LOGGED_IN, or if the user is an auto-login user, in which case it will return ERROR + NOT_HERE.

If the specified password is the string “GENERATE_RANDOM_PASSWORD”, then a random password will be generated, and returned to the client immediately after the OK success code. This might be useful for hosting systems which provide a way for a user to administratively reset a password via email, for example.

GETU (GET User configuration)

This command retrieves the screen dimensions and user options for the currently logged in account. ERROR + NOT_LOGGED_IN will be returned if no user is logged in, of course. Otherwise, OK will be returned, followed by four parameters.

The first two parameters in the past conveyed the stored screen dimensions for the user, but since modern displays are able to communicate their screen dimensions back to the system this is no longer needed, so the server always returns 80×24 as a placeholder.

The third parameter is a bag of bits with the following meanings:

Flag No. Meaning
US_LASTOLD 16 Print last old message with new
US_EXPERT 32 Experienced user
US_UNLISTED 64 Unlisted userlog entry
US_NOPROMPT 128 Don't prompt after each message
US_DISAPPEAR 512 Use “disappearing msg prompts”
US_PAGINATOR 2048 Pause after each screen of text

SETU (SET User configuration)

This command does the opposite of GETU: it takes the screen dimensions and user options (which were probably obtained with a GETU command, and perhaps modified by the user) and writes them to the user account. This command should be passed three parameters: the screen width, the screen height, and the option bits (see above). It returns ERROR + NOT_LOGGED_IN if no user is logged in, and ERROR + ILLEGAL_VALUE if the parameters are incorrect.

Note that there exist bits here which are not listed in this document. Some are flags that can only be set by Aides or the system administrator. SETU will ignore attempts to toggle these bits. There also may be more user settable bits added at a later date. To maintain later downward compatibility, the following procedure is suggested:

If we are passed a bit whose meaning we don't know, it's best to leave it alone, and pass it right back to the server. That way we can use an old client on a server that uses an unknown bit without accidentally clearing it every time we set the user's configuration.

As noted above, we no longer store per-user screen dimensions, so any value supplied will be ignored.

EBIO (Enter BIOgraphy)

Transmit to the server a free-form text file containing a little bit of information about the user for other users to browse. This is typically referred to as a 'bio' online. EBIO returns SEND_LISTING if it succeeds, after which the client is expected to transmit the file, or any of the usual ERROR codes if it fails.

RBIO (Read BIOgraphy)

Receive from the server a named user's bio. This command should be passed a single argument - the name of the user whose bio is requested. RBIO returns LISTING_FOLLOWS plus the bio file if the user exists and has a bio on file. The return has the following parameters: the user name, user number, access level, date of last call, times called, and messages posted. This command returns ERROR+NO_SUCH_USER if the named user does not exist.

RBIO no longer considers a user with no bio on file to be an error condition. It now returns a message saying the user has no bio on file as the text of the bio. This allows newer servers to operate with older clients.

LBIO (List users who have BIOs on file)

This command is self-explanatory. Any user who has used EBIO to place a bio on file is listed. LBIO almost always returns LISTING_FOLLOWS followed by this listing, unless it experiences an internal error in which case ERROR is returned.

AGUP | ASUP (Administrative Get / Set User Parameters)

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. ASUP requires all of the parameters to be set. The parameters are as follows, and are common to both commands:

No. Value
0 User name
1 Password
2 Flags (see libcitadel.h; US_*)
3 Times called
4 Messages posted
5 Access level
6 User number
7 Timestamp of last call
8 Purge time (in days) for this user (or 0 to use system default)

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.

If 1 to 8 are 0, the user will be scheduled for deletion; he will be unable to log in or send/receive email; His data will be removed on the next run of the Autopurger; Until then, you won't be able to re-create a similar user.

RENU (REName a User)

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:

OKOperation succeeded; the user has been renamed.
ERROR + ALREADY_LOGGED_INThe user cannot be renamed because the account is currently logged in.
ERROR + NO_SUCH_USERThe specified user does not exist.
ERROR + ALREADY_EXISTSAn account with the requested new name already exists.

GETU (GET User configuration)

This command retrieves the screen dimensions and user options for the currently logged in account. ERROR + NOT_LOGGED_IN will be returned if no user is logged in, of course. Otherwise, OK will be returned, followed by four parameters. The first parameter is the user's screen width, the second parameter is the user's screen height, and the third parameter is a bag of bits with the following meanings:

Flag No. Meaning
US_LASTOLD 16 Print last old message with new
US_EXPERT 32 Experienced user
US_UNLISTED 64 Unlisted userlog entry
US_NOPROMPT 128 Don't prompt after each message
US_DISAPPEAR 512 Use “disappearing msg prompts”
US_PAGINATOR 2048 Pause after each screen of text

SETU (SET User configuration)

This command does the opposite of SETU: it takes the screen dimensions and user options (which were probably obtained with a GETU command, and perhaps modified by the user) and writes them to the user account. This command should be passed three parameters: the screen width, the screen height, and the option bits (see above). It returns ERROR + NOT_LOGGED_IN if no user is logged in, and ERROR + ILLEGAL_VALUE if the parameters are incorrect.

Note that there exist bits here which are not listed in this document. Some are flags that can only be set by Aides or the system administrator. SETU will ignore attempts to toggle these bits. There also may be more user settable bits added at a later date. To maintain later downward compatibility, the following procedure is suggested:

If we are passed a bit whose meaning we don't know, it's best to leave it alone, and pass it right back to the server. That way we can use an old client on a server that uses an unknown bit without accidentally clearing it every time we set the user's configuration.

GNUR (Get Next Unvalidated User)

This command shows the name of a user that needs to be validated. If there are no unvalidated users, OK is returned. Otherwise, MORE_DATA is returned along with the name of the first unvalidated user the server finds. All of the usual ERROR codes may be returned as well (for example, if the user is not an Aide and cannot validate users).

A typical “Validate New Users” command would keep executing this command, and then validating each user it returns, until it returns OK when all new users have been validated.

GREG (Get REGistration for user)

This command retrieves the registration info for a user, whose name is the command's sole argument. All the usual error messages can be returned. If the command succeeds, LISTING_FOLLOWS is returned, followed by the user's name (retrieved from the userlog, with the right upper and lower case etc.) The contents of the listing contains one field per line, followed by the usual 000 on the last line.

The following lines are defined. Others WILL be added in the futre, so all software should be written to read the lines it knows about and then ignore all remaining lines:

Line No. Value
1 User number
2 Password
3 Real name
4 Street address or PO Box
5 City/town/village/etc.
6 State/province/etc.
7 ZIP Code
8 Telephone number
9 Access level
10 Internet e-mail address
11 Country

Users without Aide privileges may retrieve their own registration using this command. This can be accomplished either by passing the user's own name as the argument, or the string “_SELF_”. The command will always succeed when used in this manner, unless no user is logged in.

REGI (send REGIstration)

Clients will use this command to transmit a user's registration info. If no user is logged in, ERROR + NOT_LOGGED_IN is returned. Otherwise, SEND_LISTING is returned, and the server will expect the following information (terminated by 000 on a line by itself):

Line No. Value
1 Real name
2 Street address or PO Box
3 City/town/village/etc.
4 State/province/etc.
5 ZIP Code
6 Telephone number
7 e-mail address
8 Country

Please note that this command is deprecated. The preferred way to transmit this information is to submit it as a vCard (with MIME type “text/x-vcard”) to the user's “My Citadel Config” room.

CHEK (CHEcK various things)

When logging in, there are various things that need to be checked. This command will return ERROR + NOT_LOGGED_IN if no user is logged in. Otherwise it returns OK and the following parameters:

No.Value
0 Number of new private messages in Mail>
1 Nonzero if the user needs to register
2 (Relevant to Aides only) Nonzero if new users require validation
3 The user's preferred Internet e-mail address

Runtime Attribute Manipulation

Users can modify the way they are anounced to others using these commands. This data is shown for example in the “who is online” list

HCHG (Hostname CHanGe)

HCHG is a command, usable by any user, that allows a user to change their RWHO host value. This will mask a client's originating hostname from normal users; access level 6 and higher can see, in an extended wholist, the actual hostname the user originates from.

The format of an HCHG command is:

HCHG <name>

If a HCHG command is successful, the value OK is returned.

RCHG (Roomname CHanGe)

RCHG is a command, usable by any user, that allows a user to change their RWHO room value. This will mask a client's roomname from normal users; access level 6 and higher can see, in an extended wholist, the actual room the user is in.

The format of an RCHG command is:

RCHG <name>

If a RCHG command is successful, the value OK is returned.

UCHG (Username CHanGe)

UCHG is an aide-level command which allows an aide to effectively change their username. If this value is blank, the user goes into stealth mode (see STEL). Posts will show up as being from the real username in this mode, however. In addition, the RWHO listing will include both the spoofed and real usernames.

The format of an UCHG command is:

UCHG <name>

If a UCHG command is successful, the value OK is returned.

STEL (enter STEaLth mode)

When in “stealth mode,” a user will not show up in the “Who is online” listing (the RWHO server command). Only Aides may use stealth mode. The STEL command accepts one argument: a 1 indicating that the user wishes to enter stealth mode, or a 0 indicating that the user wishes to exit stealth mode. STEL returns OK if the command succeeded, ERROR + NOT_LOGGED_IN if no user is logged in, or ERROR + HIGHER_ACCESS_REQUIRED if the user is not an Aide; followed by a 1 or 0 indicating the new state.

If any value other than 1 or 0 is sent by the client, the server simply replies with 1 or 0 to indicate the current state without changing it.

The STEL command also makes it so a user does not show up in the chat room /who.

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