pbot/doc/Admin.md

Administrative

• Logging in and out
  • login
  • logout
• User management commands
  • useradd
  • userdel
  • userset
  • userunset
    • User metadata list
  • Listing users
• User capabilities
  • Introduction
  • cap
    • Listing capabilities
    • Grouping capabilities
      • Creating a new group or adding to an existing group
      • Removing capabilites from a group or deleting a group
    • Giving capabilities to users
    • Checking user capabilities
    • Listing users who have a capability
    • User capabilities list
• Channel management commands
  • join
  • part
  • chanadd
  • chanrem
  • chanset
  • chanunset
  • chanlist
    • Channel metadata list
  • ignore
  • unignore
  • blacklist
  • op
  • deop
  • voice
  • devoice
  • mode
  • ban/mute
  • unban/unmute
  • invite
  • kick
• Module management commands
  • load
  • unload
  • Listing modules
• Plugin management commands
  • plug
  • unplug
  • replug
  • pluglist
• Command metadata commands
  • cmdset
  • cmdunset
  • Command metadata list
• Event queue management
  • eventqueue
• Process management commands
  • ps
  • kill
• Miscellaneous commands
  • export
  • refresh
  • reload
  • sl
  • die

Logging in and out

You cannot use any of the admin commands unless you login. Note that the login command requires that your currently connected IRC hostmask matches the hostmask configured for the user account.

You can keep your user account permanently logged in by setting a couple of user metadata values. See the user metadata list for more information.

login

Logs into PBot.

Usage: login [channel] <password>

logout

Logs out of PBot.

Usage: logout

User management commands

useradd

Adds a new user to PBot.

Usage: useradd <username> <hostmasks> [channels [capabilities [password]]]

Parameter	Description
username	A unique name to identify this account (usually the nick of the user, but it can be any identifier).
hostmasks	The hostmasks from which this user is recognized/allowed to login from (e.g., somenick!*@*.somedomain.com or *!*@unaffiliated/someuser). Can be a comma-separated list of values.
channels	The channels this user belongs to; use global for all channels. Can be a comma-separated list of values.
capabilities	A comma-separated list of user-capabilities for this user.
password	The password the user will use to login (from /msg, obviously). Generates a random password if omitted. Users may view and set their password by using the my command.

userdel

Removes a user from PBot.

Usage: userdel <username>

userset

Sets metadata or user-capabilities for a user account. See also: user metadata list.

If key is omitted, it will list all the keys and values that are set. If value is omitted, it will show the value for key.

Usage: userset <username> [<key> [value]]

userunset

Deletes a metadata or user-capability from a user account.

Usage: userunset <username> <key>

User metadata list

This is a list of recognized metadata keys for user accounts.

Name	Description
autologin	Automatically log the user in when they join the channel. Note: make sure the user account’s hostmask wildcards are as restrictive as possible.
autoop	Give the user operator status when they join the channel. Note: make sure the user account’s hostmask wildcards are as restrictive as possible.
autovoice	Give the user voiced status when they join the channel. Note: make sure the user account’s hostmask wildcards are as restrictive as possible.
capabilities	User-capabilities are managed as user metadata.
channels	A comma-separated list of channels this user belongs to.
hostmasks	A comma-separated list of hostmasks this user is recognized by.
location	Sets your location for using the weather command without any arguments.
loggedin	Whether the user is logged in or not.
notyposub	Disallows s/// typo substitutions.
password	The password for the user account.
stayloggedin	Do not log the user out when they part/quit.
timezone	Sets your timezone for using the date command without any arguments.
units	Sets the unit for Wolfram|Alpha answers (imperial or metric)

Listing users

To list user accounts, use the users command. This is not an admin command, but it is included here for completeness. Users with a plus (+) sign next their name have user-capabilities set on their account.

Usage: users [channel]

When the optional [channel] argument is provided, only users for that channel will be listed; no global users will be listed.

When [channel] is omitted and the command is used in a channel, it will list the users for that channel, plus all global users.

When [channel] is omitted and the command is used from private message, it will list all users from all channels, including global users.

User capabilities

PBot uses a user-capability system to control what users can and cannot do. User-capabilities provides fine-grained permissions over various PBot functionality.

Introduction

For example, imagine a user named alice. alice has no capabilities granted yet. She tries to use the ban command:

<alice> !ban somebody
 <PBot> The ban command requires the can-ban capability, which your user account does not have.

Suppose alice tries to grant herself the can-ban capability:

<alice> !my can-ban 1
 <PBot> The can-ban metadata requires the can-modify-capabilities capability, which your user account does not have.

To grant her the can-ban capability, a user with the can-userset and can-modifiy-capabilities capabilities can use the userset command:

<bob> !userset alice can-ban 1

Now alice can use the ban command.

Let’s consider the mode command. Channel operators can use their IRC client’s /mode command to set any channel modes, including any undesirable modes (such as +k). Suppose you’d prefer to limit their modes to just a specific subset of all modes. You can do this with user-capabilities. To do so, instead of making them channel operators you can make them PBot users and grant them specific PBot user-capabilities.

First grant the user the can-mode capability so they can use the PBot mode command. Then grant them the specific can-mode-<flag> capabilities. To allow them to set any modes without restriction, grant them the can-mode-any capability.

See this demonstration:

<alice> !mode +b test
 <PBot> The mode command requires the can-mode capability, which your user account does not have.
  <bob> !userset alice can-mode 1
<alice> !mode +b test
 <PBot> Your user account does not have the can-mode-b capability required to set this mode.
  <bob> !userset alice can-mode-b 1
<alice> !mode +b test
      * PBot sets mode +b test!*@*
<alice> !mode +k lol
 <PBot> Your user account does not have the can-mode-k capability required to set this mode.

As you can see, user-capabilities can be very flexible and very powerful in configuring your channel users. Check out grouping capabilities in the upcoming section of this document, as well. Read on!

cap

Use the cap command to list capabilities, to manage capability groups and to see what capabilities a user has.

Usage:

cap list [capability] |
cap group <existing or new capability group> <existing capabilities...> |
cap ungroup <existing capability group> <grouped capability> |
cap userhas <user> [capability] |
cap whohas <capability>

Listing capabilities

Use cap list [capability] to list user-capabilities.

If [capability] is omitted, the command will list all available capabilities.

<pragma-> cap list
   <PBot> Capabilities: admin (25 caps), botowner (71 caps), can-ban (1 cap), can-deop (1 cap),
          can-devoice (1 cap), can-mode-any (53 caps), can-mute (1 cap), can-op (1 cap), can-unban (1 cap),
          can-unmute (1 cap), can-voice (1 cap), chanmod (4 caps), chanop (10 caps), moderator (4 caps),
          can-actiontrigger, can-akalink, can-akaunlink, can-antispam, can-blacklist, ...

Grouping capabilities

Capabilities can be grouped together into a collection, which can then be applied to a user. Capability groups can contain nested groups.

In the listing capabilities example, the admin capability is a group containing several capabilities, including other grouped capabilites such as the chanop capability group which itself can contain more groups and capabilities.

Observe.

<pragma-> cap list admin
   <PBot> Grouped capabilities for admin: can-mode-any (53 caps), chanop (10 caps),
          can-actiontrigger, can-akalink, can-akaunlink, can-antispam, can-blacklist,
          can-chanlist, can-clear-bans, can-clear-mutes, can-countertrigger, can-ignore,
          can-in, can-join, can-kick-wildcard, can-mode, can-op-wildcard, can-part,
          can-unignore, can-useradd, can-userdel, can-userset, can-userunset, can-voice-wildcard

<pragma-> cap list chanop
   <PBot> Grouped capabilities for chanop: can-ban (1 cap), can-deop (1 cap), can-devoice (1 cap),
          can-mute (1 cap), can-op (1 cap), can-unban (1 cap), can-unmute (1 cap), can-voice (1 cap),
          can-invite, can-kick

<pragma-> cap list can-ban
   <PBot> Grouped capabilities for can-ban: can-mode-b

Creating a new group or adding to an existing group

To create a new capability group or to add capabilities to an existing group, use the cap group command.

Usage: cap group <existing or new capability group> <existing capabilities...>

For example, to create a new capability group called moderator who can strictly only set mode +m or mode -m and use the voice and devoice commands:

<pragma-> cap group moderator can-voice can-devoice can-mode can-mode-m

<pragma-> cap list moderator
   <PBot> Grouped capabilities for moderator: can-devoice (1 cap), can-voice (1 cap),
          can-mode, can-mode-m

Then you can set this capability group on users with the userset command.

Removing capabilites from a group or deleting a group

To remove capabilities from a group or to delete a group, use the cap ungroup command.

Usage: cap ungroup <existing capability group> <grouped capability>

When the last capability is removed from a group, the group itself will be deleted.

Giving capabilities to users

To give capabilities to a user, use the useradd or the userset commands.

<pragma-> useradd alice global alice!*@* moderator

or

<pragma-> userset alice moderator 1

Checking user capabilities

To see what capabilities a user account has, use the cap userhas command.

Usage: cap userhas <user> [capability]

If the [capability] argument is omitted, the command will list all capability groups and capabilities the user account has.

If the [capability] argument is provided, the command will determine if the capability is granted to the user account.

<pragma-> cap userhas alice
   <PBot> User alice has capabilities: moderator (4 caps)

<pragma-> cap userhas alice can-voice
   <PBot> Yes. User alice has capability can-voice.

<pragma-> cap userhas alice can-op
   <PBot> No. User alice does not have capability can-op.

Listing users who have a capability

To list all the users that have a capability, use the cap whohas command.

Usage: cap whohas <capability>

<pragma-> cap whohas moderator
   <PBot> Users with capability moderator: alice

<pragma-> cap whohas can-voice
   <PBot> Users with capability can-voice: alice

User capabilities list

This is a list of built-in capability groups and capabilities. You can create new custom capability groups with the cap group command.

Please note that PBot is sometimes updated more frequently than this list is updated. To see the most current list of capabilities, use the cap list command or see the data/capabilities file.

Name	Description	Belongs to group
botowner	The most powerful capability group. Contains all capabilities.	none
admin	The admin capability group. Contains the basic administrative capabilities.	botowner
chanop	Channel operator capability group. Contains the basic channel management capabilities.	botowner, admin
chanmod	Channel moderator capability group. Grants can-voice, can-devoice and the use of the mod command without being voiced.	botowner
can-<command name>	If a command <command name> has the cap-required command metadata then the user’s account must have the can-<command name> capability to invoke it. For example, the op command requires users to have the can-op capability.	botowner, various groups
can-mode-<flag>	Allows the mode command to set mode <flag>. For example, to allow a user to set mode +m give them the can-mode and can-mode-m capabilities. <flag> is one mode character.	botowner, can-mode-any
can-mode-any	Allows the mode command to set any mode flag.	botowner
can-modify-admins	Allows the user to modify user accounts that have the admin capability	botowner
can-modify-capabilities	Allows the user to use the useradd or userset commands to add or remove capabilities from users.	botowner
can-group-capabilities	Allows the user to use the cap group and cap ungroup commands to modify capability groups.	botowner
can-clear-bans	Allows the user to use unban * to clear a channel’s bans.	botowner, admin
can-clear-mutes	Allows the user to use unmute * to clear a channel’s mutes.	botowner, admin
can-kick-wildcard	Allows the user to use wildcards with the kick command.	botowner, admin
can-op-wildcard	Allows the user to use wildcards with the op command.	botowner, admin
can-voice-wildcard	Allows the user to use wildcards with the voice command.	botowner, admin, chanop, chanmod
is-whitelisted	The user is exempt from anti-flood, ban-evasion checks, wild-card kicking, etc.	botowner, admin, chanop

Channel management commands

join

To temporarily join a channel, use the join command. The channels may be a comma- separated list.

Usage: join <channel(s)>

part

To temporarily leave a channel (that is, without removing it from PBot’s list of channels), use the part command. The channels may be a comma-separated list.

Usage part <channel(s)>

chanadd

chanadd permanently adds a channel to PBot’s list of channels to auto-join and manage.

Usage: chanadd <channel>

chanrem

chanrem removes a channel from PBot’s list of channels to auto-join and manage.

Usage: chanrem <channel>

chanset

chanset sets a channel’s metadata. See channel metadata list

Usage: chanset <channel> [key [value]]

If both key and value are omitted, chanset will show all the keys and values for that channel. If only value is omitted, chanset will show the value for that key.

chanunset

chanunset deletes a channel’s metadata key.

Usage: chanunset <channel> <key>

chanlist

chanlist lists all added channels and their metadata keys and values.

Channel metadata list

Name	Description
enabled	When set to a true value, PBot will auto-join this channel after identifying to NickServ (unless general.autojoin_wait_for_nickserv is 0, in which case auto-join happens immediately).
chanop	When set to a true value, PBot will perform channel management (anti-flooding, ban-evasion, etc).
permop	When set to a true value, PBot will automatically op itself when joining and remain opped instead of automatically opping and deopping as necessary.

ignore

Ignore a user. If you omit [channel] PBot will ignore the user in all channels, including private messages.

Usage: ignore <hostmask regex> [channel [timeout]]

Timeout can be specified as an relative time in English; for instance, 5 minutes, 1 month and 2 weeks, next thursday, friday after next, forever and such.

unignore

Unignores a user. If you omit [channel] PBot will unignore the user from all channels, including private messages.

Usage: unignore <hostmask regex> [channel]

blacklist

Blacklists a hostmask regex from joining a channel.

Usages:

• blacklist <show/list>
• blacklist add <hostmask regex> [channel]
• blacklist remove <hostmask regex> [channel]

op

deop

voice

devoice

The op, deop, voice and devoice commands all perform their respective named action.

The targets parameter can be a list of multiple nicks, optionally containing wildcards. If targets is omitted, the action will be performed on the caller.

Usages:

In channel:

• op [targets]
• deop [targets]
• voice [targets]
• devoice [targets]

From private message:

• op <channel> [targets]
• deop <channel> [targets]
• voice <channel> [targets]
• devoice <channel> [targets]

mode

Sets or unsets channel or user modes.

Usage: mode [channel] <flags> [targets]

PBot extends the IRC MODE command in useful ways. For instance, the targets parameter may contain wildcards. To op everybody whose nick ends with |dev you can do !mode +o *|dev in a channel.

ban/mute

Bans or mutes a user. If the argument is a nick instead of a hostmask, it will determine an appropriate banmask for that nick. The argument can be a comma-separated list of multiple nicks or masks.

Usages: - ban <nick or hostmask> [channel [timeout]] - mute <nick or hostmask> [channel [timeout]]

If timeout is omitted, PBot will ban the user for 24 hours. Timeout can be specified as an relative time in English; for instance, 5 minutes, 1 month and 2 weeks, next thursday, friday after next, forever and such.

unban/unmute

Unbans or unmutes a user. If the argument is a nick instead of a hostmask, it will find all bans that match any of that nick’s hostmasks or NickServ accounts and unban them. The argument can be a comma-separated list of multiple nicks or masks. If the argument is * then all bans/mutes for the channel will be removed.

Usages: - unban <nick or hostmask> [channel] - unmute <nick or hostmask> [channel]

invite

Invites a user to a channel.

Usage: invite [channel] <nick>

kick

Removes a user from the channel. <nick> can be a comma-separated list of multiple users, optionally containing wildcards. If [reason] is omitted, a random insult will be used.

Usage from channel: kick <nick> [reason] From private message: kick <channel> <nick> [reason]

Module management commands

Note that modules are “reloaded” each time they are executed. There is no need to refresh after editing a module.

load

This command loads a module in $data_dir/modules/ as a PBot command. It is equivalent to factadding a new keyword and then setting its type to module.

Usage: load <keyword> <module>

For example, to load $data_dir/modules/qalc.sh as the qalc command:

<pragma-> !load qalc qalc.sh

unload

This command unloads a module. It is equivalent to deleting the factoid keyword the module was loaded as.

Usage: unload <keyword>

Listing modules

To list the loaded modules, use the list modules command. This is not an admin command, but it is included here for completeness.

Usage: list modules

Plugin management commands

plug

Loads a plugin into PBot.

Usage: plug <plugin>

unplug

Unloads a plugin from PBot.

Usage: unplug <plugin>

replug

Reloads a plugin into PBot. The plugin is first unloaded and then it is loaded again.

Usage: replug <plugin>

pluglist

Lists all currently loaded plugins. This isn’t an admin command, but it is included here for completeness.

Usage: pluglist

<pragma-> !pluglist
   <PBot> Loaded plugins: ActionTrigger, AntiAway, AntiKickAutoRejoin, AntiNickSpam,
          AntiRepeat, AntiTwitter, AutoRejoin, Battleship, Connect4, Counter, Date,
          GoogleSearch, Quotegrabs, RemindMe, RestrictedMod, Spinach, TypoSub, UrlTitles,
          Weather, Wolfram, Wttr

Command metadata commands

cmdset

Use cmdset to set various metadata for built-in commands.

Usage: cmdset <command> [key [value]]

Omit <key> and <value> to list all the keys and values for a command. Specify <key>, but omit <value> to see the value for a specific key.

cmdunset

Use cmdunset to delete various metadata from built-in commands.

Usage: cmdunset <command> <key>

Command metadata list

Name	Description
help	The text to display for the help command.
cap-required	When set to a true value then the command requires that users have the can-<command name> capability before they can invoke it.
dont-replace-pronouns	When set to a true value then pronouns such as “my”, “me”, “your”, etc, will not be intuitively replaced with nicks and such.
background-process	When set to a true value then this command will be executed as a background process. Use this for commands that can potentially take a long time to complete.
process-timeout	The timeout, in seconds, before the process is automatically killed. If not set then the processmanager.default_timeout registry value will be used.

Event queue management

eventqueue

PBot uses an event queue to schedule future tasks or commands. The eventqueue command can be used to list or remove upcoming events. It can also be used to schedule a command.

Usage: eventqueue list [filter regex] | add <relative time> <command> [-repeat] | remove <event>

For example, to schedule a command to run 1 hour from now:

<pragma-> eventqueue add "1 hour" echo Ta-da!
   <PBot> Command added to event queue.

<pragma-> eventqueue list
   <PBot> Queued events: 1) in 1h: command #channel echo Ta-da!

... 1 hour later ...

   <PBot> Ta-da!

The remove command’s <event> argument can include wildcards. For example, to remove all command events:

<pragma-> eventqueue remove command *
   <PBot> Removed 1 event.

Or to remove all command events in #channel:

<pragma-> eventqueue remove command #channel *

Process management commands

ps

Lists all currently running background processes.

Usage: Usage: ps [-atu]

Option	Description
-a	show all information
-t	show running time
-u	show user and channel

kill

Sends the interrupt signal to selected running background processes.

Usage: Usage: kill [-a] [-t <seconds>] [-s <signal>] [pids...]

Option	Description
-a	kill all processes
-t <seconds>	kill processes running longer than <seconds>
-s <signal>	send <signal> to processes instead of interrupt signal
pids...	space-delimited list of PIDs to kill

If neither options -a or -t are provided then the pids... option is required.

Miscellaneous commands

These are some of the miscellaneous admin commands that have not been covered above or in the rest of the PBot documentation.

export

Exports specified list to HTML file in $data_dir.

Usage: export <factoids|quotegrabs>

refresh

Refreshes/reloads PBot core modules and plugins (not the command-line modules since those are executed/loaded each time they are invoked).

For example, suppose you edit some PBot source file, be it a core file such as PBot/Factoids.pm or a Plugin such as Plugins/Wttr.pm. Rather than shut the bot down and restart it, you can simply use the refresh command to reload all modified PBot core files and Plugins.

reload

Reloads a data or configuration file from $data_dir. This is useful if you manually edit a data or configuration file and you want PBot to know about the modifications.

Usage reload <admins|bantimeouts|blacklist|channels|factoids|funcs|ignores|mutetimeouts|registry>

sl

Sends a raw IRC command to the server. Use the sl command when PBot does not have a built-in command to do what you need.

Usage: sl <irc command>

<pragma-> sl PRIVMSG #channel :Test message
   <PBot> Test message

die

Tells PBot to disconnect and exit.