JSON-RPC:Server ban exception

JSON Methods

• rpc: set_issuer, info, add_timer, del_timer
• stats: get
• log: send, 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
• message: send_privmsg, send_notice, send_numeric, send_standard_reply
• connthrottle: status, set, reset,
• security_group: list, get

JSON Basics

• JSON-RPC Technical documentation

The server_ban_exception.* JSON RPC calls can add, remove and list server ban exceptions (ELINEs).

Structure of a server ban exception

The following object is used in responses. This is a server ban, such as a GLINE or Spamfilter. It is also used for ban exceptions (ELINE).

Variable	Description	Example value
type	Type of the server ban. One of: gline, kline, gzline, zline, spamfilter, qline, except, shun, local-qline, local-exception, local-spamfilter.	gline
type_string	Type of the server ban in a more friendly user printable string. Possibly prefixed with "Soft" eg "Soft G-Line".	G-Line
id	Unique ID for this TKL entry. (UnrealIRCd 6.2.6 and later)	G7K2MP9WQX3
name	The target of the ban or except. For Spamfilter this is the regex/matcher.	*@*.badisp.example.net
match	Target of the ban or except, a Match item object. This is only present for server bans and server ban exceptions if a mask/match is used in the config file. Only in that case match is present and name will be absent.	{ certfp "aabbccdd.."; }
set_by	Name of the person or server who set the ban	Syzop
set_at	Date/Time when the server ban was added	2022-05-23T11:02:06.000Z
set_at_string	Date/Time when the server ban was added in a more human printable string.	Mon May 23 11:02:06 2022
expire_at	Date/Time when the server ban will expire. NULL means: never.	2023-05-23T10:00:00.000Z
expire_at_string	Date/Time when the server ban will expire in a more human printable string. Uses "Never" for never.	Tue May 23 10:00:00 2023
duration_string	How long the ban will last from this point in time (human printable). Uses "permanent" for forever.	permanent
set_at_delta	How many seconds ago the ban was placed.	1800
reason	The reason of the ban	Lots of abuse from this ISP
spamfilter_id	If a server ban was placed by a spamfilter, this shows the TKL ID of the Spamfilter entry. Not to be confused with id which is OUR tkl id. (UnrealIRCd 6.2.6 and later)	SPAM5P9WQX3
exception_types	Only for ban exceptions! Specifies the exception types (letters). See HELPOP ELINE for a list of those letters.	kGzZsF
match_type	Only for spamfilters! The matching type. One of: simple, regex	regex
ban_action	Only for spamfilters! The action to take on spamfilter hit.	gline
spamfilter_targets	Only for spamfilters! Which targets the spamfilter must filter on.	cpnN
except	An exception to which this particular spamfilter does not apply, a Match item object. Rarely used. Only for spamfilters.	{ reputation-score 25; }
hits	For Spamfilters and server bans: the number of hits this entry had on this server (not network wide). For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2
last_hit_at	For Spamfilters and server bans: the timestamp of the last hit of this entry on this server (not network wide). For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2026-06-10T12:34:56.000Z
hits_except	For Spamfilters only: the number of hits by exempted users (which were unaffected) of this particular entry on this server (not network wide). This allows you to get an idea of "false positives" for this spamfilter. For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2
last_hit_except_at	For Spamfilters only: the timestamp of the last hit by an exempted user (which was unaffected) of this particular entry on this server (not network wide). This allows you to get an idea of "false positives" for this spamfilter. For config-based spamfilters/bans this is reset after a server restart, for non-config-bans this is preserved via tkldb. (UnrealIRCd 6.2.6 and later)	2026-06-10T12:34:56.000Z

NOTE: Only server ban exceptions are handled through server_ban_exception.*. See the other API calls for handling spamfilter, server bans and name bans.

API Calls

server_ban_exception.list

List server ban exceptions (ELINEs).

Request arguments

No mandatory arguments

Example

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

server_ban_exception.get

Retrieve all details of a single server ban exception (ELINE).

Request arguments

Mandatory arguments (see structure of a server ban for an explanation of the fields):

• name

Example

{"jsonrpc": "2.0", "method": "server_ban_exception.get", "params": {"name":"*@127.0.0.0/8"}, "id": 123}

server_ban_exception.add

Add a server ban exception (ELINE).

Request arguments

Mandatory arguments (see structure of a server ban for an explanation of the fields):

• name: user@host mask or extended server ban
• exception_types: eg k for a kline exception
• reason: reason for the ban

Optional arguments:

• set_by: who set the entry
• the duration (this is rarely used, as usually exceptions are permanent!), either:
  • expire_at, OR
  • duration_string

Example request

{"jsonrpc": "2.0", "method": "server_ban_exception.add", "params": {"name":"*@192.168.0.0/16", "exception_types":"kGzZ","reason":"this is a test"}, "id": 123}

server_ban_exception.del

Delete a server ban exception (ELINE).

Request arguments

Mandatory arguments (see structure of a server ban for an explanation of the fields):

• name

Optional arguments:

• set_by: who unset the entry

Example

{"jsonrpc": "2.0", "method": "server_ban_exception.del", "params": {"name":"*@192.168.0.0/16"}, "id": 123}