Tip of the day: You can exempt users dynamically from server bans, spamfilter, maxperip and other restrictions with the ELINE command on IRC.

JSON-RPC:User

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

JSON Methods

JSON Basics

The user.* JSON RPC calls can list and retrieve information about users.

IMPORTANT: many user.set_* calls require all servers on the network to be using UnrealIRCd 6.0.6 or later, otherwise the commands don't work or you get desynchs. Also, set::limit-svscmds should be set to servers (which is the default). The same is (partially) true for user.join and user.part.

Structure of a client object

A "Client object" is used in responses. In case of user.* API calls the result in response will always be a user (never a server).

This can be a user, a server or a freshly accepted connection that is still in the handshake and we don't know yet what it will be.

Detail level Variable Description Example value
0+ name The name of the client (nick name, server name, ..) Syzop
0+ id The unique client ID 001F9RV02
1+ hostname Resolved hostname (or IP) xyz.example.org
1+ ip IP address of the user (empty for services) 198.51.100.1
1+ details Detailed description of the client.
The output depends on the type of client and what information we have. 		nick!user@host

[email protected]
[198.51.100.1]

1+ geoip GeoIP information regarding the IP address of the user (not always available) (see next)
1+ geoip.country_code The ISO 3166-1 alpha-2 country code NL
2+ server_port Server TCP port (unrealircd side) 6697
2+ client_port Client TCP port (client side) 37030
2+ connected_since Date/time when the client connected (only available for local clients) 2022-05-23T11:02:06.000Z
2+ idle_since Last time the client said anything in PM or channel (only available for local clients) 2022-05-23T11:02:06.000Z
2+ tls If the client is using SSL/TLS then this contains a tls object which has two members (see next)
2+ tls.cipher The TLS cipher negotiated with the client TLSv1.3-TLS_CHACHA20_POLY1305_SHA256
2+ tls.certfp The client Certificate fingerprint (if any) aafe66a7d808e1fca077805c54b1274a92d30c3023e35ec130f358d238218296
2+ user If the client is a user (a person) then additional information is available in this object. See client.user object
2+ server If the client is a server then additional information is available in this object. See client.server object

See also below for the user and server objects.

client.user object

If the client is a user then there is a user object within the client object:

Detail level Variable Description Example value
2+ user.username The user name / ident ~xyz
2+ user.realname The real name / GECOS IRC User
2+ user.vhost If the user is +x or +t this contains the vhost/cloakedhost oper/netadmin.test.net
2+ user.cloakedhost The calculated cloaked host, even if the user is not +x Mask-8608861.example.net
2+ user.servername The server to which the user is connected irc.example.net
2+ user.account The account name, if the user is logged in to Services. SomeAccount
2+ user.reputation The reputation score. 10000
2+ user.security-groups The security groups that the user is in. ["known-users","tls-and-known-users"]
2+ user.modes The user modes of the user. "iwx"
2+ user.snomasks The snomasks of the user, if they are IRCOp. "iwx"
2+ user.operlogin The name of the oper { } block, if they are IRCOp. "iwx"
2+ user.snomasks The oper::operclass, if they are IRCOp. "iwx"
3 user.channels The channels the user is in.
Minimized and capped at 384 bytes total length. 		["#a","#b","#c"]
4 user.channels The channels the user is in with the level [{"name": "#a", "level": "o"}, {"name": "#b", "level": "o"}, {"name": "#c", "level": "o"}]

client.server object

If the client is a server then there is a server object within the client object:

Detail level Description Example value
2+ server.info The server description Primary IRC server of example.net
2+ server.num_users Number of currently connected users 123
2+ server.boot_time Date/time the server was started 2022-05-23T11:02:06.000Z
2+ server.synced Set to 1 if the server is synced, 0 if the server is currently linking in and syncing users/channels/etc. 1
2+ server.features.software Server software version in use UnrealIRCd 6.0.0
2+ server.features.protocol UnrealIRCd protocol version 6000
2+ server.features.usermodes User modes supported by this server abcd
2+ server.features.chanmodes Channel modes supported by this server.
This is an array of 4 strings, the same format as IRC numeric 005 CHANMODES=. 		['abc','def','ghi','jkl']
2+ server.features.nick_character_sets Nick Character Sets supported by this server. Comma separated string.

NOTE: The client.server object is never returned with the user.* API calls, because the user.* API calls only deal with users. In the future there will be server.* API calls for handling servers.

The detail level depends on the API call:

  • user.list has a default level of 2
  • user.get has a default level of 4

The detail level can be overridden by use of object_detail_level, see the documentation of the API calls.

API Calls

user.list

List users.

Request arguments

There are no mandatory arguments.

Optional arguments:

  • object_detail_level: set the detail of the response object, see the Detail level column in Structure of a client object. In this RPC call it defaults to 2 if this parameter is not specified.

Example

{"jsonrpc": "2.0", "method": "user.list", "params": {}, "id": 123}

user.get

Retrieve all details of a single user.

Request arguments

Mandatory argument:

  • nick: the nick name or the UID

Optional arguments:

  • object_detail_level: set the detail of the response object, see the Detail level column in Structure of a client object. In this RPC call it defaults to 4 if this parameter is not specified.

Example

Simply by nick name: 

{"jsonrpc": "2.0", "method": "user.get", "params": {"nick":"XYZ"}, "id": 123}

Or by NICK ID, which is safer if you already know the ID, because the ID will not change between nick changes: 

{"jsonrpc": "2.0", "method": "user.get", "params": {"nick":"0017A04PU"}, "id": 123}

user.set_nick

Sets the nick name of a user (changes the nick).

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • newnick: the new nick name

Optional:

  • force: if set to true then q-lines (banned nick) checks will be bypassed. And also, if the new nick name already exists, the other existing user is killed and we will take that new nick.

Example

{"jsonrpc": "2.0", "method": "user.set_nick", "params": {"nick":"XYZ","newnick":"some_new_nick"}, "id": 123}

user.set_username

Set the username / ident of a user.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • username: the new user name / ident

Example

{"jsonrpc": "2.0", "method": "user.set_username", "params": {"nick":"XYZ","username":"someident"}, "id": 123}

user.set_realname

Set the realname / gecos of a user.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • realname: the new user name / ident

Example

{"jsonrpc": "2.0", "method": "user.set_username", "params": {"nick":"XYZ","realname":"I like apples"}, "id": 123}

user.set_vhost

Set a virtual host (vhost) on the user.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • vhost: the new virtual host

Example

{"jsonrpc": "2.0", "method": "user.set_vhost", "params": {"nick":"XYZ","vhost":"likes.apples"}, "id": 123}

user.set_mode

Change the modes of a user.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • modes: the mode string, eg -i+w

Optional:

  • hidden: if this is set to true then don't show the mode change to the user (generally not recommended)

NOTE: For changing snomask you need to use the user.set_snomask API call!

Example

{"jsonrpc": "2.0", "method": "user.set_mode", "params": {"nick":"XYZ","modes":"-i+w"}, "id": 123}

user.set_snomask

Change the snomask of a user.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • snomask: the snomask string, eg -j+R

Optional:

  • hidden: if this is set to true then don't show the snomask change to the user (generally not recommended)

Example

{"jsonrpc": "2.0", "method": "user.set_mode", "params": {"nick":"XYZ","snomask":"-j+R"}, "id": 123}

user.set_oper

Make user an IRC operator.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • oper_account: the oper account, to be shown in WHOIS to fellow ircops and in logs.
  • oper_class: the operclass. Usually one of the default operclasses like netadmin-with-override

Optional:

  • class: the class to put the user in. If this option is not specified then opers is assumed, since this class exists in most unrealircd.conf's. You can specify "" (empty) if you don't want to put the user in a class.
  • modes: user modes to set on oper. For example: +xws. If this option is not specified then set::modes-on-oper is used. You can specify "" (empty) if you don't want to set any additional modes on the user.
  • snomask: snomask to set on oper. For example: +bBcdfkqsSoO. If this option is not specified then set::snomask-on-oper is used. You can specify "" (empty) if you don't want to set any snomasks on the user.
  • vhost: virtual host to set on oper.

Example

{"jsonrpc": "2.0", "method": "user.set_oper", "params": {"nick":"XYZ","oper_account":"SomeOper","oper_class":"netadmin-with-override","class":"opers","modes":"+ws","snomask":"+bBcdfkqsSoO","vhost":"oper.on.this.net"}, "id": 123}

user.join

Join a user to a channel.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • channel: the channel(s) to join (e.g. #channel or #channel1,#channel2)

Optional arguments:

  • key: the key of the channel(s) (only for channels with +k needed, again separate by colon for multiple channels)
  • force: whether to bypass join restrictions or not

NOTE: If force is set to true then the user will walk through bans, modes and other restrictions (similar to SAJOIN on IRC). If force is not set, or set to false, then it will be a regular JOIN attempt that may fail. If it fails then the user will see an error message on their screen, such as for example Cannot join channel (+k).

Result

This API call will always return boolean true. For technical reasons it is hard for us to check if the join actually succeeded (the join could be done on a remote server, asynchronously, seconds after we return)

Example

Normal join without bypassing any restrictions: 

{"jsonrpc": "2.0", "method": "user.join", "params": {"nick":"XYZ","channel":"#main"}, "id": 123}

Joining through all restrictions, similar to a SAJOIN: 

{"jsonrpc": "2.0", "method": "user.join", "params": {"nick":"XYZ","channel":"#restricted","force":true}, "id": 123}

user.part

Part a user from a channel.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • channel: the channel(s) to part (e.g. #channel or #channel1,#channel2)

Optional arguments:

  • force: show force notification

NOTE: If force is set to true then the user will see a notice that they were forcefully PARTed from the channel(s). If force is not set, or set to false, then there will be no such notice.

Result

This API call will always return boolean true.

Example

{"jsonrpc": "2.0", "method": "user.part", "params": {"nick":"XYZ","channel":"#main"}, "id": 123}

user.kill

Kill a user, showing that the user was forcefully removed.

NOTE: There is also user.quit. The difference is that user.kill will show that the user is forcefully killed, while user.quit pretend the user quit normally. This slight difference may invoke certain client behavior. For example, some clients don't immediately reconnect for a KILL but do so on a QUIT.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • reason: reason for the kill

Example

{"jsonrpc": "2.0", "method": "user.kill", "params": {"nick":"XYZ","reason":"go away"}, "id": 123}

user.quit

Quit a user, pretending it was a normal QUIT.

NOTE: There is also user.kill. The difference is that user.kill will show that the user is forcefully killed, while user.quit pretend the user quit normally. This slight difference may invoke certain client behavior. For example, some clients don't immediately reconnect for a KILL but do so on a QUIT.

Request arguments

Mandatory arguments:

  • nick: the nick name or the UID
  • reason: reason for the quit

Example

{"jsonrpc": "2.0", "method": "user.quit", "params": {"nick":"XYZ","reason":"go away"}, "id": 123}

See also

  • For kicking a user from a channel, see the channel.kick API call
Retrieved from "https://www.unrealircd.org/docwiki/index.php?title=JSON-RPC:User&oldid=12911"