Tip of the day: On IRC you can use the HELPOP command to read about various IRC commands.

JSON-RPC:Server

From UnrealIRCd documentation wiki
Jump to navigation Jump to search

JSON Methods

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

[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
1+ geoip.asn The AS (Autonomous System) number that the user is connecting from 16276
1+ geoip.asname The AS (Autonomous System) name that the user is connecting from OVH SAS
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"]
2+ user.away_reason If the user is away, this field is present and shows the AWAY reason. "On the phone"
2+ user.away_since If the user is away, this shows since when. 2025-09-17T12:50:00.000Z
2+ user.modes The user modes of the user. "iwx"
2+ user.snomasks The snomasks of the user, if they are IRCOp. "bBcdfkqsSoO"
2+ user.operlogin The name of the oper { } block, if they are IRCOp. "Bob"
2+ user.operclass The oper::operclass, if they are IRCOp. "netadmin-with-override"
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, or false 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}
Retrieved from "https://www.unrealircd.org/docwiki/index.php?title=JSON-RPC:Server&oldid=12712"