Tip of the day: Did you know that users are put in the security-group known-users based on their reputation score or if they are identified to Services?Users in this group receive a number of benefits, such as being able to send more messages per minute. |
JSON-RPC:Server
JSON Methods
- rpc:
set_issuer
,info
,add_timer
,del_timer
- stats:
get
- log:
list
,subscribe
,unsubscribe
- user:
list
,get
,set_nick
,set_username
,set_realname
,set_vhost
,set_mode
,set_snomask
,set_oper
- whowas:
get
- server:
list
,get
,rehash
,connect
,disconnect
- channel:
list
,get
,set_mode
,set_topic
,kick
- server_ban:
list
,get
,add
,del
- server_ban_exception:
list
,get
,add
,del
- spamfilter:
list
,get
,add
,del
- name_ban:
list
,get
,add
,del
JSON Basics
The server.*
JSON RPC calls can list and retrieve information about servers, rehash the server, connect/disconnect servers, etc.
IMPORTANT: server.* API calls require UnrealIRCd 6.0.6 or later
Structure of a server object
A "Server object" is used in responses. In case of server.*
API calls the result in response will always be a server (never a normal user).
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
|
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: Above is the general description. If you want to deal with users, use the user.*
API calls.
API Calls
server.list
List servers.
Request arguments
No mandatory arguments
Example
{"jsonrpc": "2.0", "method": "server.list", "params": {}, "id": 123}
server.get
Retrieve all details of a single server.
Request arguments
Optional argument:
- server: the server name (or the SID). If not specified then the current server is assumed (the one you connect to via the JSON-RPC API).
Example
{"jsonrpc": "2.0", "method": "server.get", "params": {"server":"irc1.example.net"}, "id": 123}
server.rehash
Rehash the server.
IMPORTANT: If all servers on your network have rpc.modules.default.conf
included then this can return an object with full rehash details. Otherwise, for remote rehashes a simple boolean 'true' result is returned.
Request arguments
Optional arguments:
- server: the server name (or SID). If not specified then the current server is assumed (the one you connect to via the JSON-RPC API).
Result
For local servers and remote servers that support RPC, this request may take a few seconds and you will receive a rehash object with the full rehash details:
- rehash_client: the person who initiated the request (normally you, not very useful)
- success: this is
true
if the REHASH succeeded, orfalse
if there was some config error - log: this is the full rehash log as an array of JSON log items.
For remote servers that do not support RPC:
- A simple boolean result
true
Example
{"jsonrpc": "2.0", "method": "server.rehash", "params": {}, "id": 123}
Example response:
{ "jsonrpc": "2.0", "method": "server.rehash", "id": 123, "result": { "rehash_client": { "name": "RPC:local", "id": "001JGJ30G", "hostname": "127.0.0.1", "ip": "127.0.0.1", "server_port": 0, "details": "RPC:[email protected]", "connected_since": "2023-01-11T16:16:15.000Z", "idle_since": "2023-01-11T16:16:15.000Z" }, "log": [ { "timestamp": "2023-01-11T16:16:15.659Z", "level": "info", "subsystem": "config", "event_id": "CONFIG_INFO_GENERIC", "log_source": "maintest.test.net", "msg": "Loading IRCd configuration..", "source": { "file": "conf.c", "line": 1476, "function": "config_status" } }, { "timestamp": "2023-01-11T16:16:16.545Z", "level": "info", "subsystem": "config", "event_id": "CONFIG_INFO_GENERIC", "log_source": "maintest.test.net", "msg": "Testing IRCd configuration..", "source": { "file": "conf.c", "line": 1476, "function": "config_status" } }, { "timestamp": "2023-01-11T16:16:24.727Z", "level": "info", "subsystem": "config", "event_id": "CONFIG_LOADED", "log_source": "maintest.test.net", "msg": "Configuration loaded", "source": { "file": "conf.c", "line": 2142, "function": "config_test" } } ], "success": true } }
server.connect
Make server link (connect) to another server.
Request arguments
Mandatory argument:
- link: the server name to link to
Right now you can only tell to link to servers from the directly connected server (the one you are issuing JSON-RPC calls to), you cannot (yet) tell remote server B to link to server C.
Example
{"jsonrpc": "2.0", "method": "server.connect", "params": {"link":"irc2.example.net"}, "id": 123}
server.disconnect
Terminate a server link (disconnect).
This works for both directly connected servers and remote servers further up the network.
Request arguments
Mandatory argument:
- link: the server name to unlink from
Example
{"jsonrpc": "2.0", "method": "server.disconnect", "params": {"link":"irc2.example.net"}, "id": 123}
server.module_list
Get the module list (list of loaded modules) on a server.
IMPORTANT: This only works with remote servers if all servers on your network have rpc.modules.default.conf
included. This is because then the JSON-RPC request/response is forwarded over the IRC network.
Request arguments
Optional argument:
- server: the server name (or the SID). If not specified then the current server is assumed (the one you connect to via the JSON-RPC API).
Response object
TODO: document
Example
{"jsonrpc": "2.0", "method": "server.module_list", "params": {"server":"irc1.example.net"}, "id": 123}