Documents Project
The Documents Project, formerly known as Doco-Com, is responsible for creating and maintaining useful resource documentation for the Undernet community. Both new and experienced IRC users will find information here on everything from downloading an IRC client to explanation of the various protocols.
Posted on 16th Nov 2020 14:45:40 in Channel Services
Undernet X commands [English]
Introduction
In this section we will be teaching you about the Undernet Channel Services bot, X. X can usually be found in most registered channels, and is the service which Undernet provides to registered channels to assist them in maintaining stability. Some of X's core functions are: the ability to set bans for a set period of time, maintaining an access list from which X can voice or op users with the appropriate access level, and preventing channel take-overs during a netsplit.
Before we get started, let's take some time to provide some information about the things you'll see in this document. It's recommended that you read this, as it contains important information on how to properly read this document.
About TOTP
TOTP or Time-based One Time Passwords - is a security algorithm designed to help keep you safe against trial and error attacks (also known as bruteforce attacks) against your account. This is a form of Two Factor Authentication or 2FA. It works like this:
- Your account is secured by a password. (This is the factor you know.)
- It's also secured by a time-based password, generated by an app on your phone or tablet - like Google Authenticator. (This is the factor you have.)
- During the login process, you submit both factors - which ensures that only you can access your account.
TOTP codes expire every 30 seconds, so they can't be reused later on. Your app will continously generate new codes every 30 seconds. This helps improve the security of your account, since a malicious user can't "save" your TOTP code to gain access to your account later on.
You can enable TOTP from the CService website. Just follow these instructions:
- First you're going to need a smartphone or a tablet.
- You'll then need a TOTP generator app. We recommend Google Authenticator, as this app is available on both Android and the iOS App Store.
- Go to the CService website
- Login with your username and password.
- After logging in, you will be presented with a reminder. CService Staff will never ask for your passsword. Click on the "proceed normally your login sequence." link.
- On your user page, under the User information section, You will see a Two Step Verification option. It should say: > Disabled - Click here to enable it (read more about two-step verification here).
- Click on the word "here" to start the process.
- You will then be asked if you wish to enable two-step verification. Click on the YES button.
- Check your e-mail. There will be a link for you to click to enable TOTP.
- Once you've clicked on the link, you'll be taken to a CService webpage with a QR Code displayed. This QR code contains your secret key. Use the Google Authenticator app on your smartphone or tablet to scan the code and add it to your device.
- After you've scanned the code into your authenticator app, you will see a new entry followed by a six-digit code and a timer. Every 30 seconds, this code will change. On the page, enter the code into the box and click on the submit button.
- If all went well, TOTP should be enabled on your account.
- From now on, you will need to login to X with your TOTP code. Your TOTP code is always added at the end of your login command:
/msg x@channels.undernet.org LOGIN username password totpcode - You should also consider Login on Connect or LoC to help simplify your login process. See the LoC help document for further information.
About Login on Connect (LoC)
Login on Connect is a new security feature which allows users to be logged into their CService username as they connect to the network. When properly configured, this feature ensures that your IP address is never visible to users on the network.
This setup varies by client, but the general idea of it is to use a specially crafted LoC command to login immediately on connect. For most clients, you can use the following command:
/server irc.undernet.org
For mode, use a corresponding mode that determines how your login process will be handled.
| Mode | Description | Example |
| +x! | Only connect me when X is online and hide my IP address | /server irc.undernet.org 6667 +x! username password |
| -x! | Let me connect anytime, even if X is offline. Don't hide my IP address | /server irc.undernet.org 6667 -x! username password |
| -!+x | Let me connect anytime, even if X is offline. Hide my IP address if X is online | /server irc.undernet.org 6667 -!+x username password |
If you'd like to have this saved in your client, most clients allow you to specify a server password. Simply use the mode and credential portion of an LoC command as your server password. For example: +x! username password would be entered into the server password field of your client.
Some IRC clients offer a separate password field for NickServ or SASL. It's important that you DO NOT enter your LoC command into those fields, as it will not work.
About the command syntaxes and parameters
X follows a standard syntax scheme for IRC bots. You do not need a special client, or any scripts loaded to use X. Now keep in mind that X has three types of commands. Channel commands, which can only be used in channels. User commands which can only be used on users. There are also Shared commands, which can be used in a channel or on a user. We'll give you an example of a shared command below.
| /msg x info #target_channel |
| /msg x info target_username |
| X's INFO command is a shared command. It can be used on either a channel OR a user, provided that you have sufficient access. |
Throughout this documentation, you may see things such as <> and []. They are identifiers for the type of information the command requests.
| Identifier | Description |
| <> | This is a required piece of information. You can't use the command without it. |
| [] | This is an optional piece of information. You don't need to use it to use the command. |
| x|y | This is a decision. You need to pick one of the options given for this command to work. |
| x-y | This is a range. You can pick anything between the given ranges. |
| * | This is a documentation identifier. Commands with this in front of them are part of the MODINFO or SET command. The commands with these identifiers are always underneath the command that owns it. |
The identifiers are usually coupled together with a placeholder to tell you what to enter for a particular command to work.
| Placeholder | Description |
| <nick> | The user's nick is required. |
| <username> | The user's username is required. If you're not sure of it, you can always substitute a username with = in place of their actual nickname, but this will only work if they are logged into X. You can also use the VERIFY command to get a user's username and determine if they're logged in. |
| <pattern> | Any search string that makes use of wildcards (* and ?). A *!*ident@host string is an example of a pattern. |
Commands list
This is a list of all available commands in X. It's been divided up by access level. So we'll start with the highest access level and go down to to the lowest. Please keepin mind, users with higher access levels can perform all commands lower than their access level. So for example, if you had 450 access in channel #Test, you could use commands that need access 0 all the way up to access 450. You can never use commands that are greater than your access level.
The Channel Manager is the owner of the channel and the ultimate authority for its administration. Channel managers may appoint and dismiss subordinate channel administrators and operators at will, modify any setting in X for the channel, and channel-specific settings for users in the channel.
| Command | Example | Description |
| PART | /msg X part <#channel> |
This will tell X to leave your channel. Usually, this is a bad idea. |
| SET | /msg X set <#channel> <feature> <value> |
Turns a feature on or off for your channel. Setting subcommands:
|
| AUTOJOIN | /msg X set <#channel> autojoin <on|off> |
If this feature is turned on, X will join your channel automatically when it reconnects to the network. |
| MASSDEOPPRO | /msg X set <#channel> massdeoppro <0-7> |
This feature tells X the maximum number of deops X will allow a user to place within 15 seconds. If any user deops more than the number specified in this setting, X will ban the user at access 25, and suspend them for 5 minutes. Note: This feature only works with the /mode #channel –o command. X's deop command is exempt from this feature. If this is set to 0, this feature will be disabled. |
| NOOP | /msg X set <#channel> noop <on|off> |
If this is turned on, X will not allow any users to be opped in the channel. Even if they're logged into X. Users with 100 access or higher will still be able to use X to kick, ban, etc. Using this feature may leave your channel opless if X goes down for maintenance. |
| NOTAKE | /msg X set <#channel> notake <on|off> |
NoTake prevents ops in your channel from taking it over through a massban. Note: The channel manager may always takeover their own channel. |
| OPLOG | /msg X set <#channel> oplog <on|off> |
When enabled, the following commands will result in OpNotices being sent: MODE, OP, DEOP, VOICE, DEVOICE, UNBAN, CLEARMODE. This will provide an audit trail for anyone abusing X access on a channel which previously had no accountability. |
| STRICTOP | /msg X set <#channel> strictop <on|off> |
If this is turned on, X will only allow users who are logged in and have access 100 or higher to be opped in the channel. |
| TAKEREVENGE | /msg X set <#channel> takerevenge <none|ban|suspend> |
This feature makes X react to an op attempting to takeover the channel. If it's set to NONE, X will just stop the takeover attempt. If it's set to BAN, X will ban the op attempting to takeover. If it's set to SUSPEND, X will ban the op attempting to take over and suspend their access. |
Trusted Channel Administrators are appointed by the Channel Manager. Generally, a Trusted Channel Administrator is well known by the manager. These administrators can control security settings for the channel on behalf of it's manager. Like the manager, they may also add and remove subordinate administrators and channel operators.
| Command | Example | Description |
| JOIN | /msg X join <#channel> |
This will tell X to join your channel. |
| SET | /msg X set <#channel> <feature> <value> |
Sets a feature in your channel. |
| AUTOTOPIC | /msg X set <#channel> autotopic <on|off> |
If this is turned on, X will set the topic to the channel description and URL every 30 minutes. |
| DESCRIPTION or DESC | /msg X set <#channel> description [text] or /msg X set <#channel> desc [text] |
This will set the channel description (up to 380 characters long) for your channel in X. It will be visible in the CHANINFO reply. If no description text is provided, the current description will be removed. |
| FLOATLIM | /msg X set <#channel> floatlim <on|off> |
If this is turned on, X will set a channel limit with a margin above the number of users in your channel. This can help prevent large botnets from joining and flooding your channel. Configuration subcommands:
|
| FLOATGRACE | /msg X set <#channel> floatgrace <0-19> |
This allows you to set the grace value for the floating limit feature. If the difference between the channel limit, and what the new limit would be is less than the grace value, X will not change the limit. This will cut down on the noise that X makes with each mode change. Setting this to 0 will turn off this feature. The default value for this is 1. Part of the FLOATLIM command. |
| FLOATMARGIN | /msg X set <#channel> floatmargin <2-20> |
This sets the margin for the channel limit. The channel limit will always be set to the number of users in your channel plus the FLOATMARGIN value. The default value for this is 3. Part of the FLOATLIM command. |
| FLOATMAX | /msg X set <#channel> floatmax <0-65536> |
When this is turned on, X will not set a limit higher than the value of FLOATMAX. The default value for this is 0. Part of the FLOATLIM command. |
| FLOATPERIOD | /msg X set <#channel> floatperiod <20-200> |
This is the amount of time in seconds, X will wait before resetting the channel limit. The default value for this is 20 seconds. Part of the FLOATLIM command. |
| FLOODPRO | /msg X set <#channel> floodpro <defaults|kick|ban|off> |
This command turns on X's flood protection for your channel. Configuration subcommands:
|
| CTCPFLOOD | /msg X set <#channel> ctcpflood <0|2-15> |
This is the maximum number of CTCP commands that a user can send in your channel at once within the time you set for floodperiod, before being punished by X. Setting this to 0 will disable flood protection. Part of the FLOODPRO command. |
| FLOODPERIOD | /msg X set <#channel> floodperiod <0-15> |
This command will set the amount of time before one of the flood protection counters must be met before X takes action against a user. Setting this to 0 will turn off flood protection. Part of the FLOODPRO command. |
| MSGFLOOD | /msg X set <#channel> msgflood <0|2-220> |
This is the maximum number of message a user can send in your channel at once within the time you set for floodperiod, before being punished by X. Setting this to 0 will disable flood protection. Part of the FLOODPRO command. |
| NOTICEFLOOD | /msg X set <#channel> noticeflood <0|2-15> |
This is the maximum number of notices a user can send in your channel at once within the time you set for floodperiod, before being punished by X. Setting this to 0 will disable flood protection. Part of the FLOODPRO command. |
| REPEATFLOOD | /msg X set <#channel> repeatflood <0|2-15> |
If a user repeats an action more than the value you have set here, X will punish the user according to what you have set for floodpro. Part of the FLOODPRO command. |
| KEYWORDS | /msg X set <#channel> keywords [keywords] |
This will set the keywords for the channel. Each keyword will need to be separated by a space. The maximum size for this is 300 characters. |
| MODE | /msg X set <#channel> mode |
This will save the current modes in your channel as the default. When X rejoins your channel, it will reset these modes. |
| URL | /msg X set <#channel> url [url(s)] |
This will set the url for your channel. The URL can be viewed in the CHANINFO command, or on the CService website for your channel. If no url is given, this setting will be cleared. The maximum size of this is 128 characters. |
| USERFLAGS | /msg X set <#channel> userflags <0-2|none|op|voice> |
This setting will set the default automode for all new users who are added to the channel's access list.
The default value for this is 0. |
| JOINLIM | /msg X set <#channel> joinlim <on|off> |
Used to manage chanel join floods from clients that are not running identd (with ~ in ident) and who are not authenticated to X. Configuration subcommands:
If JOINLIM is enabled without manually changing JOINMAX, JOINMODE, and JOINPERIOD, the below defaults will be used: |
| JOINMAX | /msg X set <#channel> joinmax |
Defines the threshold for when JOINLIM (if activated) shall be triggered. |
| JOINMODE | /msg X set <#channel> joinmode [parameters] |
The mode to be set by X in your channel if JOINLIM is triggered. |
| JOINPERIOD | /msg X set <#channel> joinperiod <1-600> |
The period after JOINLIM has been triggered (and JOINMODE set) that X will remove the set JOINMODE. |
Userlist Administrators do as their title implies. They administrate the userlist. These administrators may add and remove subordinate channel operators. They may also modify the access of an existing operator or user, configure a user's automode and if necessary, clear all modes from the channel.
| Command | Example | Description |
| ADDUSER | /msg X adduser <#channel> <username> <access> |
This will add a new user to your channel. You won't be able to add a user to your channel with access equal to or greater than your own. |
| CLEARMODE | /msg X clearmode <#channel> |
You can use this to clear all modes in a channel when it's locked. It will remove channel modes +i, +l, and +k. This may not be the best way to regain entry to your channel if you've been locked out. |
| MODINFO | /msg X modinfo <#channel> <access|automode> <username> <value> |
This command allows you to make changes to your channel's access list. |
| ACCESS | /msg X modinfo <#channel> access <username> <level> |
Using this command, you can modify the access level of a user who is already added to your channel. The access level you set here cannot be greater than or equal to your own access level. So if you had access 400, the highest you'd be able to give to another user is 399. Keep in mind, you can't modify your own access, and you can't modify a user with access higher than your own. |
| AUTOMODE | /msg X modinfo <#channel> automode <username> <op|voice|none> |
This command will allow you to set a user's automode to op or voice, or remove it altogether. |
| REMUSER | /msg X remuser <#channel> <username> |
Removes a user from your channel. You need to have access higher than the user you want to remove. You can remove yourself from any channel as long as you are not the manager (Access 500). Channel managers wishing to remove themselves must purge their channel or transfer it to another user. |
Userlist Operators are similar to channel operators, just with the additional power to kick users by host. They may also see the status of the channel, which reveals all authenticated users added to the channel.
| Command | Example | Description |
| KICK | /msg X kick <#channel> <*!userid@host> [reason] |
This version of the kick command will kick all users who match the provided hostmask. If you match the provided hostmask, you won't be kicked. This is useful for cases of extreme channel flooding. If you're considering using this, you may want to set your channel to mode +i before issuing the kick(s) so the affected users don't rejoin. Your username will be inserted into the kick message in paranthesis. |
| STATUS | /msg X status <#channel> |
This command will display all channel flags and settings, channels modes, the number of users and ops in the channel, currently authenticated users for the channel, and whether X is on the channel or not. Currently authenticated users are shown in a "username/nickname [level]" format. A user's nickname will only be shown if that user is currently on the channel, otherwise only their username and level are displayed. If a key is set in the channel, this command will reveal the key. |
Channel Operators are given access to op-commands. This allows them to perform actions like bans and kicks. They may also suspend and unsuspend the access of subordinate users.
| Command | Example | Description |
| OP | /msg X op <#channel> <nick1> [nick2|nick3] |
This command will make X op a user in your channel. You can op multiple users by giving multiple nicks separated by a space. |
| DEOP | /msg X deop <#channel> <nick1> [nick2|nick3] |
This command will make X deop a user in your channel. Much like the op command, you can deop multiple users by giving multiple nicks separated by a space. |
| INVITE | /msg X invite <#channel> |
This will make X invite you to your channel. This is useful if your channel is set to mode +i (Invite Only), +k (Key Required) or there is a +b (ban) on your nick, ident or host. |
| MODINFO | /msg X modinfo <#channel> <invite> <on|off> |
Since this modinfo command only has one option, it'll be explained here. You can use this command to set your autoinvite in a channel by setting invite to ON. Only you can set this option. |
| MODE | /msg X mode <#channel> |
Sets channel modes in your channel. All modes except those which op, deop, voice, or devoice are accepted. If the channel setting OPLOG is enabled, an opnotice will also be sent to the channel. |
| SUSPEND | /msg X suspend <#channel> <username> <duration> <access> [reason] |
This will make X suspend a user's access in your channel for a set duration. The suspension access level cannot be greater than your own. You cannot suspend users who have access greater than or equal to your own. The reason is optional. |
| UNSUSPEND | /msg X unsuspend <#channel> <username> |
This will make X remove a suspension on a user's access in your channel. You cannot unsuspend users who are suspended with an access level greater than or equal to your own. |
New Operators are given access to the Ban and Unban commands. While they cannot op up through X, they can set and remove bans in the channel through X.
| Command | Example | Description |
| BAN | /msg X ban <#channel> <nick!ident@host> <duration> <access> [reason] |
This will make X ban user(s) from your channel for the set duration. If the ban access level is 74 or lower, the user will be deopped and cannot be opped. If the access level is 75 or higher the user will be kick banned from the channel. The ban access level cannot be greater than your own. The ban duration cannot be shorter than 5 minutes, and cannot be longer than 365 days. If you wish to set a permanent ban, use 0d as the duration. You may ban users by their nick, or using a pattern. Multiple nicks and/or banmasks can be specified by comma delimiting a list. The reason is optional, but will be used in the ban comment. Your ban reason cannot be longer than 300 characters. Your channel may not have more than 500 bans set in X. |
| UNBAN | /msg X unban <#channel> <nick!ident@host> |
This will make X remove a ban from your channel. You cannot unban users who are banned with an access level greater than or equal to your own. |
Half Ops may kick users from the channel or change the topic.
| Command | Example | Description |
| KICK | /msg X kick <#channel> <nick!ident@host> [reason] |
This will make X kick a user from the channel. Multiple nicks can be specified by comma delimiting a list. The reason is optional. |
| TOPIC | /msg X topic <#channel> <text> |
This will make X set the channel topic. It can be 145 characters long, and your username will be prepended to the topic you set. |
Trusted Channel Users are granted the ability to voice and devoice others.
| Command | Example | Description |
| VOICE | /msg X voice <#channel> <nick1> [nick2|nick3] |
This will make X voice a user. You can voice multiple users by giving multiple nicks separated by spaces. If you do not specify any nicknames X will perform the mode in the channel specified for yourself. |
| DEVOICE | /msg X devoice <#channel> <nick1> [nick2|nick3] |
This will make X devoice a user. You can devoice multiple users by giving multiple nicks separated by spaces. If you do not specify any nicknames X will perform the mode in the channel specified for yourself. |
Channel Users can view the banlist of the channel and see status information.
| Command | Example | Description |
| BANLIST | /msg X banlist <#channel> |
Using this command will make X show you the banlist for the channel. |
| REMUSER | /msg X remuser <#channel> <username> |
If there's a channel that you have access and you no longer wish to be added to, you can use the REMUSER command to remove yourself from that channel. |
| STATUS | /msg X status <#channel> |
Using this command will show you the status information for a channel, except for the set modes. |
A Registered User is a user who is merely logged into X. These commands are always available to any logged in user, as long as their username hasn't been suspended.
| Command | Example | Description |
| ACCESS | /msg X access <#channel> <username> |
This command will show you a user's access in a channel. See the below chart to learn how to search for specific users by access level. |
| CHANINFO | /msg X chaninfo <#channel> |
This command will show you if a channel is registered, and if it is, who is registered to, as well as its description and url. |
| INFO | /msg X info <username> |
This command will display information about a user if they don't have the invisible flag set. If you use it on yourself, it will show you all channels you have access too. (Only you and CService staff can see that) |
| HELP | /msg X help <command> |
Using this command will help you learn about other commands. Use it wisely! |
| LBANLIST | /msg X lbanlist <#channel> <pattern> |
You can use this command to search through a channel's ban list in X. You can use * as a pattern to display all bans, or you can give a nick!ident@host pattern to search for a specific ban. If there are more than 10 bans, you will need to login to the CService website to see all of them. |
| LOGIN | /msg X@channels.undernet.org login <username> <password> [TOTP Code] |
This command logs you into X! TOTP is a time-based, one-time password designed to improve your account's security. If it's enabled, you'll need to enter the TOTP code after your password. To enable this, visit the CService website. LoC or Login on Connect is a method used to login to X as you connect to the network. When used, your actual IP won't be shown on the network. See the LoC documentation for more information. Note: You must message x@channels.undernet.org. You cannot do /msg X login. |
| MOTD | /msg X motd |
This command will show you X's message of the day. |
| NEWPASS | - Command Disabled - |
This command has been disabled for security reasons. To change your password, please go to the CService website. |
| SET | /msg X set <option> <flag> |
You can use this to set options and flags on your account. |
| INVISIBLE | /msg X set invisible <on|off> |
If this is turned on, users won't be able to get information about your account, like your online status, via the INFO command. This is turned on by default for all accounts registered after November 1st, 2016. |
| LANG | /msg X set lang <language_option> |
You can change this setting to make X reply to you in a different language if English isn't what you speak. The available language options are:
When setting a language, use the abbreviated language code. |
| NOADDUSER | /msg X set noadduser <on|off> |
If this is turned on, X will not allow other users to add you to their channels. |
| SHOWCOMMANDS | /msg X showcommands [#channel] |
This command will show you all commands available to your current access level in the specified channel. If you don't specify a channel, X will only show you the commands available to Access 0. |
| SHOWIGNORE | /msg X showignore |
Is X ignoring one of your friends? If so, use this command. It'll show you X's ignore list, and tell you how long each user has to wait before the ignore expires. |
| SUPPORT | /msg X support <#channel> <yes|no> |
If you use this command and say YES, you will support a channel's registration application. If you say NO, you will object to this channel being registered. This command can only be used in channels with a valid registration application. |
| SUSPENDME | /msg X suspendme <password> |
If you use this command, your account will be immediately suspended. You will not be able to use your account once it's suspended and you will need to /join #usernames to begin the unsuspension process. Use this command with extreme caution. It is only meant to be used if you believe your account has been compromised and can demonstrate or otherwise prove such claim. |
| VERIFY | /msg X verify <nick> |
If you're uncertain about a user's status on the network, this command can be used to tell if they're logged into X. It'll also tell you if they're an official CService member, or an IRC Operator. |
Access searching
You can search for access by username, nickname or for multiple users via a wildcard pattern. This is done through the ACCESS command. When a search is performed, the information displayed includes:
- The access level of the user
- Their automode (if one is set)
- Their suspension status and the level at which they were suspended (if they've been suspended)
- The last time were last seen by X.
If there's more than 15 results, you'll have to login to the CService Website and use the "Channel Information" link to search for the channel and see the complete access list.
You can also combine the available options to get specific results.
/msg X access <#channel> <*|pattern|username|=nickname> [-min ] [-max ] [-modif] [-none|-voice|-op]
| Option | Description | Syntax |
| * |
Shows the entire access list |
/msg X access <#channel> * |
| !@* pattern |
Shows the access level of all usernames matching the wildcard pattern. |
/msg X access <#channel> <pattern> |
| username |
Shows the access level of a single user. |
/msg X access <#channel> <username> |
| =nickname |
Shows the access level of a single user by nickname. |
/msg X access <#channel> <=nickname> |
| -min |
Shows only users with access greater than the specified level. |
/msg X access <#channel> -min |
| -max |
Shows only users with access less than the specified level. |
/msg X access <#channel> -max |
| -op |
Shows only users with the AUTOMODE OP flag. |
/msg X access <#channel> -op |
| -voice |
Shows only users with the AUTOMODE VOICE flag. |
/msg X access <#channel> -voice |
| -none |
Shows only users with the AUTOMODE NONE flag. |
/msg X access <#channel> -none |
| -modif |
Shows who last modified the access listing. |
/msg X access <#channel> -modif |
Durations
The BAN and SUSPEND commands both require a duration in order to be set. To simplify the process, X will accept human readable time formats as a valid duation. See the below chart of durations to understand what is accepted by X.
| Duration | Example | Description |
| m | 5m |
This duration lasts for 5 minutes |
| h | 1h |
This duration lasts for 1 hour. |
| d | 30d |
This duration lasts for 30 days. |
| 0 | 0 |
This duration is permanent. |
This document was last updated on August 31st, 2020
This file is maintained by the CService Documents Team
E-mail cservice@undernet.org with any suggestions or comments
CService URL: https://cservice.undernet.org/live/
Undernet URL: https://www.undernet.org/
Undernet Sponsors
We would like to thank the following organisations for helping to sponsor the Undernet and for providing the many different aspects used for the network's structure and other services.
