Skip to content

IRCv3

Relay negotiates and uses the following IRCv3 capabilities, client tags, and related ISUPPORT extensions when the connected IRC server advertises them. Availability can vary by network. See the IRCv3 specifications for protocol details. WHOX is used when the server supports it, with ordinary WHO as a fallback.

Supported extensions

Relay also processes the STS capability when a server advertises a strict transport security policy. STS is an advertised policy rather than a capability Relay requests during normal negotiation; Relay stores secure policies and upgrades insecure connections when a secure port is provided.

History and read markers

When a network advertises draft/chathistory, Relay requests older channel messages as you load more history and merges them into the current conversation without duplicating messages already present. When draft/read-marker is available, Relay reports the messages you have read so compatible servers or bouncers can share that position with your other clients.

Multiline messages

When a network advertises draft/multiline, Relay sends line-broken or overlong PRIVMSG and NOTICE content as a single IRCv3 batch and combines incoming multiline batches into one message. Relay follows the server's advertised byte and line limits; networks without the extension use ordinary IRC line splitting.

Compatibility extensions

Relay supports several non-standard bouncer extensions when they are available:

  • znc.in/playback for replaying history from compatible ZNC bouncers.
  • znc.in/self-message as a legacy self-echo fallback when echo-message is unavailable.
  • znc.in/server-time and znc.in/server-time-iso as server-time compatibility aliases.

User metadata

The metadata fields are user-facing profile settings in Settings > Account for authenticated users. Users can choose a display name shown instead of their IRC nickname, add a homepage link, choose a nickname or identity color, set a custom status, and manage their avatar through the existing upload UI when avatars are enabled.

On IRC servers advertising draft/metadata-2, Relay synchronizes these profile values with IRC users. On servers without that capability, Relay still saves and displays the values locally, but does not share them over IRC. A custom status is separate from Relay's online and away presence indicators.

WebIRC

Relay supports the IRCv3 WebIRC specification as a trusted gateway. WebIRC is a command, not a capability: Relay sends WEBIRC as the first upstream command, before capability negotiation, only for IRC hosts configured in Relay's webirc map.

Relay configuration

Add a per-network entry to Relay's config.yaml and use a long, unique secret shared with InspIRCd:

webirc:
  irc.ouch.chat:
    password: "replace-with-a-long-random-secret"

The shorthand form is also accepted:

webirc:
  irc.ouch.chat: "replace-with-a-long-random-secret"

Relay forwards the authenticated browser's client IP. If Relay has no verified reverse-DNS hostname, it sends that IP in both WebIRC hostname and IP fields, as required by the specification. When the Relay browser connection is HTTPS, it also sends the secure option; InspIRCd should only treat that as secure when Relay's IRC connection uses TLS too.

hostnamePrefix remains available for compatibility with existing Relay/The Lounge configurations, but it is an advanced network-specific override. Leave it unset for the normal spec-conformant behavior.

Set reverseProxy: true only when Relay is actually behind a trusted reverse proxy that overwrites X-Forwarded-For and X-Forwarded-Proto. Otherwise a client could influence the address and secure state that Relay forwards.

InspIRCd 4 / OUCH.Chat

The IRCv3 specification requires both the gateway and IRC server to be configured. InspIRCd's gateway module provides the WebIRC command. Enable the module and configure a WebIRC gateway entry in the active InspIRCd configuration. The password is shown as a bcrypt hash below; use the password-hashing method documented for the installed InspIRCd version rather than committing a plaintext secret:

<module name="gateway">

<gateway type="webirc"
         password="$2a$10$REPLACE_WITH_AN_INSPIRCD_COMPATIBLE_BCRYPT_HASH"
         hash="bcrypt"
         mask="RELAY_PUBLIC_EGRESS_IP"
         trustedflags="secure" />

The mask must allow only the public source IP (or tightly controlled source range) from which Relay connects to InspIRCd. Configure the same plaintext secret in Relay's webirc entry; InspIRCd compares it with the configured hash. Relay identifies its gateway name as relay, so a connect class restricted to this gateway should use webirc="relay". Use TLS for Relay's connection to InspIRCd, and reload or restart InspIRCd after changing its configuration.

If a connect class should accept WebIRC only from this gateway, InspIRCd can associate the gateway name with the connect class using its webirc setting. Consult the InspIRCd gateway module documentation for the exact connect-class configuration and authentication alternatives.

Do not expose the WebIRC password to browser code or ordinary IRC users. WebIRC is safe only when the server uses a strong secret and allowlists the Relay gateway's source IP. See the IRCv3 WebIRC security considerations.

The websocket module is separate: it is for IRC clients connecting directly to InspIRCd over WebSocket. Relay does not need it for Relay-to-InspIRCd WebIRC forwarding.

UTF8ONLY

Relay supports the IRCv3 UTF8ONLY specification as an 005 ISUPPORT token. It is not an IRC capability and must not be added to Relay's requested CAP list. When a server advertises UTF8ONLY, Relay records the server option and ensures outbound IRC lines do not contain malformed UTF-8.

InspIRCd 4 / OUCH.Chat

InspIRCd 4 provides this feature through the built-in ircv3_utf8only module. Add the following to the active InspIRCd configuration, usually inspircd.conf or an included module configuration file:

<module name="ircv3_utf8only">

The module requires no additional configuration. Reload or restart InspIRCd after changing the configuration. Verify the change by connecting and checking that the server's 005 output contains UTF8ONLY.

The current irc.ouch.chat server identifies as InspIRCd 4, but it does not currently advertise UTF8ONLY; the module therefore still needs to be enabled in the server's active configuration. See the InspIRCd ircv3_utf8only module documentation and the IRCv3 specification for the protocol details.