Configure PolarBot
PolarBot is configured in two places:
- on the server, by the operator: the config file and the credentials. They apply to the whole bot. Changes need a restart.
- in Discord, per server, by its staff: slash commands. Changes apply at once and are stored in the database.
On the server
The config file
sudoedit /etc/polarbot/config.toml
sudo systemctl restart polarbot
sudo journalctl -u polarbot -n 20 --no-pager
The file is TOML; every key is optional and documented in Configuration file. Common changes:
| You want to | Set |
|---|---|
| Use your own host name for the OAuth callback | [web] public_url = "https://bot.example.org" |
| More detail in the journal while debugging | [log] level = "polarbot=debug,info" (and back to "info" afterwards) |
| Logs for a log collector | [log] json = true |
| Your own or extra threat lists | [[scanner.threatlists]] entries (they replace the defaults, so list the defaults too if you want to keep them) |
| No adult-site category | [scanner] adultlists = [] |
| Test commands in one server instantly | [discord] dev_guild_id = <server ID> (development only) |
A typo or an unknown key stops the bot at startup with a message such as
polarbot: invalid config: line 3: unknown field …; systemctl status polarbot shows it.
Credentials
To replace a credential (for example after resetting the bot token in the Developer Portal), encrypt the new value over the old file and restart:
sudo -v
read -rsp "Bot token: " TOKEN; echo
printf '%s' "$TOKEN" | sudo systemd-creds encrypt --name=discord_token - /etc/polarbot/discord_token.cred
unset TOKEN
sudo systemctl restart polarbot
The same works for discord_client_secret. sudo ./deploy/install.sh --token and
sudo ./deploy/install.sh --secrets do the same from the repository (--secrets also
generates a new oauth_key, which makes every server run /perms authorize again).
In Discord
Every command, option and required level is listed in Commands;
/help command:<name> explains one inside Discord.
First steps in a new server
| Step | Command | Who |
|---|---|---|
| Choose the log channel for cards and logs | /setup log_channel:#mod-log | Admin |
| Give staff roles their levels | /perms set role:@Mods level:Moderator, /perms set role:@Admins level:Admin | Owner |
| Let each role see only its commands | /perms authorize (needs OAuth) | Owner |
| Ping a role on scanner punishments | /scanner mod-role role:@Mods | Admin |
| Check everything | /config view, /scanner status, /perms list | Admin |
Logging
/config log-level level:<0–10> chooses how much is posted in the log channel; each level adds
to the ones below it. The default is 2 (scanner punishments and moderation through
PolarBot). See Log levels for exactly what each level adds. Level 1
or higher is needed for scanner cards.
/config announcements-channel chooses where “PolarBot updated to vX.Y.Z” notices go. Without
one, PolarBot uses a channel named like staff-announcements, staff-news,
mod-announcements, staff-updates or bot-updates that it can post in, and otherwise the
log channel.
The scanner
A cautious way to start in an existing community:
/scanner actions enabled:False: log-only mode. The scanner posts cards but deletes and punishes nothing.- Watch the cards for a few days. Press Scam or Not scam on each: this teaches the block list, lifts wrong punishments and collects anonymized training examples.
- Adjust:
/scanner thresholds log:60 delete:90 punish:97,/scanner punishment action:Timeout duration:1h,/scanner allow domain:example.comfor domains your community uses,/scanner channel//scanner exempt-rolefor places and roles to skip. /scanner actions enabled:Truewhen you trust it.
| Setting | Command | Default |
|---|---|---|
| Scanner on/off | /scanner enable, /scanner disable | on |
| Log-only mode | /scanner actions enabled: | actions on (servers that had PolarBot before the scanner: off) |
| Thresholds | /scanner thresholds log: delete: punish: (1–100, log ≤ delete ≤ punish) | 60 / 90 / 97 |
| Punishment at the punish threshold | /scanner punishment action: duration: | Timeout, 1 hour (1 minute to 28 days) |
| Hacked accounts (same link in 3+ channels in 2 min) | /scanner hacked action: | Delete the messages and time out |
| Discord invites | /scanner invites allow: | flagged |
| Which channels | /scanner channel-mode mode: and /scanner channel channel: rule: | all channels |
| Skipped roles | /scanner exempt-role role: exempt: | none (Moderators and above are always skipped) |
| Allow and block lists | /scanner allow, /scanner block, /scanner unlist | empty |
| Adult-site links | /scanner nsfw-links action: | Delete (servers that had PolarBot before 0.3.1: Log) |
/scanner analyze (and right-click a message → Apps → Analyze with PolarBot) shows what the
scanner would do with a text or message under the current settings, without doing anything.
The scanner explains the rules and the score.