Dancer - An IRC bot: Administration of Users

4. Administration of Users

This section describes what a bot maintainer can do with users. Adding, deleting, changing, fixing so that they are treated correctly by the bot and to the benefit of the channel the bot is visiting.

4.1 Vocabulary

The vocabulary used here is as follows:

Users: Registered users. They're recognized by the bot when they join and they have different status levels, flags and privileges.
Guests: Persons joined in the channel.

4.2 Userdata

Registered users have a set of data stored that is connected to the particular user. That data include:

A list of recognized hostpatterns (possibly including nick)
Nick name (used for i.e off-channel references to the user)
Access level
Comment (changeable by the user itself and the COMMENT command)
Email/real name
Flags (Autoop, Banprotect, Linkbot, Regularbot, etc)
Encrypted password (there is no way to reverse engineer the password)

Some data is automatically taken care of:

Total number of joins
Various dates, such as date of last password change and general change
Information about who added (or raised, or lowered) the user and when

No user is recognized until he or she is added. There is only one single command that adds users: USERADD, and you can only add the user once. If the user is on-channel when you add him/her, the bot will try to inform the newly added user.

The simplest and most commonly used format of this command is

USERADD <nick> <level> [email]

If the guest foobar should get added as a level 20 users, we just enter

USERADD foobar 20

To do the same, but include the user's email address too

USERADD foobar 20 foo@unsigned.int

In some situations, we want to alter details in the data that is about to get stored for the user. Then we can specify a few options that does it for us. For example, if foobar isn't joined when we want to add him, the bot can't possibly know what hostpattern to add for the user and we have to specify that manually. Then we could do it like

USERADD -p foo@*unsigned.int foobar 20

(Specifying the hostpattern can be useful even if the user is joined if the bot hasn't picked a perfect pattern as viewed with "SVIEW -A".)

If you want to register the user with a certain nick, which he isn't using when you add him, for example he is using foobar2 instead of foobar, use the -R option like this

USERADD -r foobar foobar2 20

Adding a user that is joined, but preventing the bot to inform him, can be done with -Q like

USERADD -q foobar 20

Of course, all or any of the flags can be combined as in

USERADD -q -n mypasswd -p foo@*unsigned.int -r Newbie foobar 20 foo@unsigned.int

USERADD Error Messages

I need a pattern for off-channel addings

You wanted to add a user that is not currently joined without specifying a hostpattern. The bot cannot possibly know how to match the user without that knowledge.

Another user with nick XXX is already added

The registered nick has to be unique. Most often this error occurs when the user actually already is added properly, just not matching any of the hostpatterns as he is joined now. If that is the case, add the pattern to the userdata instead (see USERMOD -p).

<XXX> is already added

Despite what you think or what the user says, this user is already added. This may be because this user matches a hostpattern of an already registered user. If that is the case, you should make sure that hostpattern gets narrowed.

Illegal pattern (XXX)

The added hostpattern was seriously wrong. A hostpattern should be in one of the two formats

<nick>!<user>@<site><domain>

<user>@<site><domain>

For our imaginary user, normally using the nick foobar, the pattern could be like "foo*!foo@*unsigned.int" or if you don't want the nick to matter, pick a pattern like "foobar@*foobar.com".

4.4 Changing Users

Users are humans (yes, that's true). They change accounts, they disappear, they show up, they behave, they go bananas or they remain the same. To change any(*) of the registered user's data fields, use the USERMOD command.

The basic syntax of this command is USERMOD options <nick> level. The options specifies with properties you want to change and if level is specified, that will become the new level of the user (if it isn't higher or equal to the level of yourself, which will then cause the level to get set to your level -1). Plain and simple change the user 'foobar' to status 50

USERMOD foobar 50

When the user shows up in the channel with a new hostpattern that is not previously added to the user (and thus the user isn't recognized by the bot) you can add a new pattern to the user in a few different ways. Specify the complete new pattern as in

USERMOD -p foo@*short.int foobar

or add the currently used pattern to the registered user with that same nick

USERMOD -p - foobar

(this can be done by the user itself by using the IDENT command as described further down) or you can "steal" the pattern from a user in the channel and add that pattern to the registered user. If the user shows up with a nick different to the one that he is registered as (foobar_ in this example), and you want to add the user's current hostpattern to the user's list of patterns, you can use it like

USERMOD -p foobar_ foobar

If you added a bad pattern to the user, or if the user has hostpatterns he will without doubt not use anymore, you can delete one from a user like

USERMOD -d foo@*.unsigned.int foobar

or if you have done a "SVIEW -A" previously and remember the number of the pattern you want to remove (2 in our example), you can write it like

USERMOD -d 2 foobar

Further, you can change the email field for the user like

USERMOD -e bar@short.int foobar

You can change the registered nick name like

USERMOD -r foobie foobar

To alter the flags of a user, you use the -F option. You should specify the flags to add preceded with a '+' and the flags to remove preceded with a '-'. The existing flags(*2) at this point are

A = Autoop (automatically ops the person on join if AUTOOP is enabled)
B = Banprotect (try to unban bans matching this user)
L = Linkbot (this is a linkbot user. This reserved for future use)
R = Regularbot (this is a regular bot user)

Enable Autoop and disable Banprotect like

USERMOD -f +a-b foobar

Prevent a joined user from getting information about the change by using the -Q option like

USERMOD -q foobar 50

Remember that "SVIEW -A" is a very good command to use to view any user's data.

(*) Exceptions are the comment field which is set by the user itself with the COMMENT command and the password which can be reset to 'pass' for a specified user with the DEFPASS command.

(*2) There is in fact a 'DELETE' flag too, that is not possible to add nor to remove with the USERMOD command. Read further about the USERDEL command for more info.

4.5 Deleting Users

Sometimes a registered user quits visiting IRC or just your channel. Instead of keeping the users entry in the database present forever (which could lead to an extensive amount of never-joining users) there is a USERDEL command. Write a command like

USERDEL foobar

to delete the registered user named foobar. If there is a user joined using the registered nick without actually being the user with that nick registered, you can specify that you want this to affect the registered nick's user with

USERDEL -r foobar

Deleting a user DOES NOT mean that the user will be erased from the userlist immediately. The user will instead get marked with the DELETE flag and if the user isn't changed the following month (meaning that if there is a one month old or older DELETE-flag) the user will no longer get saved in the userfile. Thus, at next restart the user won't exist. This allows the undo option, that can be used in case you change your mind before the user is actually erased

USERDEL -u foobar

Like the other user-commands, this will tell the affected user unless the -Q (quiet) option is used as in

USERDEL -q foobar

4.6 Password

All registered users have passwords. By default, all initial users have 'pass' as password (can be specified with the 'USERADD -n' command though). Passwords are stored encrypted and cannot be reverse engineered. Passwords are never shown in spylinks or in logfiles. Alas, nobody but the user himself knows what sequence of letters that creates his encrypted password.

A user identifies himself with the "PASS <password>" command, or can get the bot to make him chanop at the same time (if the user has sufficient status) by entering "OP <password>". A new password is set with "NEWPASS <password>" but of course the old password has to be entered accordingly first.

All users should set their own passwords as soon as possible. Keeping the default password is considered very insecure! The IDENT command will even reject users that try it with the default password!

DEFPASS is the only command that can change another user's password. It re-installs the default password for the specified user.

NOTE: If the SVIEW output includes the word 'Confirmed', the user has successfully entered his passwords and is considered identified.

4.7 Seen

The seen data has nothing to do with the userdata. They are two completely different systems and stored users may very well not be found by a seen command and vice versa.

4.8 Hostpatterns

User hostpatterns are tricky business. The hostpatterns listed for a single user should preferably match only one single person. A typical bad case where a hostpattern matches an unintended person, is when the guy claims he has lost his password and wants you to reset it for him and voila, he has taken control of that user.

The hostpatterns listed for a user are compared against the user regardless of the ircd-server prefixes (known to this date) like ~, -, + etc. So, adding a pattern like "~foo@*unsigned.int" to a user still matches the user joining as "foo@static.unsigned.int" as well as "+foo@const.unsigned.int" and similar.

The hostpattern can optionally contain a nick match too, like if the previous user always used a nick starting with "foo", the hostpattern could be written like "foo*!foo@*unsigned.int".

A user can (if IDENTPROTECT is off) add it's current userdomain pattern to its list of host patterns by using the IDENT command. It is typically used when the user joins from an account not recognized by the bot. The user then enters the command

IDENT <password>

Userdomain Pattern

Another pattern that should not be confused with the hostpatterns is the userdomain pattern that the bot constructs when a user joins. That pattern is what the bot considers is a good string to match that particular person. The userdomain is used i.e when the bot bans the person or if the person is added to the warnlist. That pattern is also used as default hostpattern in case the user is added (with USERADD) or get its current pattern added (with " USERMOD -p -"). This is the pattern that is viewed on the first line of an sview output.

Some hosts are what we refer to as host-only ISPs (short for Internet Service Providers). When the bot is about to create a userdomain pattern for a user from such a host, the machine name will be kept and the username will be '*' and if the host from the example above was listed as 'hostisp' the userdomain for a user like "+foo@static.unsigned.int" would look like "*@static.unsigned.int". The bot will also do its best to never siteban such a host.

Users that join with a userhost that looks like "user@host.domain" (with only one dot) get a pattern that looks like "user@*ost.domain".

4.9 Bans

When banning a single user with the BAN command (as in "BAN foobar"), the userdomain pattern of the user will be used when creating the banpattern. That pattern will also be used in case the user floods or is abusive in any other sense that makes the bot ban him.