IRCv3 WebIRC extension

Copyright © 2017 Evan Magaliff <>

Copyright © 2017 Darren Whitlen <>

Unlimited redistribution and modification of this document is allowed provided that the above copyright notice and this permission notice remains intact.


This specification is intended to document the existing WEBIRC command that is already in use by multiple IRC servers and WebIRC gateways to provide a standard specification for implementation. This specification does not add any new features or changes, although new features, such as use of public-key cryptography instead of password authentication, can be submitted as extensions.


When a user connects through an indirect connection to the IRC server, the user’s actual IP address and hostname are not visible. The WEBIRC command allows the WebIRC gateway to pass on the user’s actual IP address and hostname to the IRC server. This information can be used by the network as if the user was connecting directly.


The WEBIRC command MUST be the first command sent from the WebIRC gateway to the IRC server and MUST be sent before capability negotiation.

The WEBIRC command takes four parameters: password, gateway, hostname, and ip.

If forward and reverse DNS do not match, the IP address SHOULD be sent as the hostname and the unverified hostname SHOULD NOT be sent (see Security Considerations). If the connection fails to the IRC server, the WebIRC gateway MUST return an ERROR with an appropriate message and terminate the connection.

Note: Previous implementations referred to the gateway field as user. This change is for documentation clarity only and maintains compatibility with all existing implementations.


Generic format.

WEBIRC password gateway hostname ip

IP address resolves to hostname.

WEBIRC hunter2 ExampleGateway

IP address does not resolve to hostname.

WEBIRC hunter2 ExampleGateway

Error from invalid password.

ERROR :Invalid WebIRC password

Use Cases

Webchat applications that proxy the connection to the IRC server are the primary intended use case. WebIRC allows network and channel operators to use available moderation and security tools to their full extent by exposing user IP addresses and hosts.

Other use cases include bouncer services that wish to pass user information to the IRC server.


WebIRC requires that the both WebIRC gateway and IRC server be configured to accept the connection in advance. Specific recommendations are outlined below in the Security Considerations section.

Security Considerations

WebIRC allows anyone with a valid password to successfully connect to the IRC server and spoof any desired hostname. IRC servers SHOULD use secure passwords and SHOULD whitelist the IP addresses for the allowed WebIRC gateway servers. If the WEBIRC command does not originate from a whitelisted IP address or uses an incorrect password, the gateway SHOULD close any connections with an ERROR command.

Because the possibility for hostname spoofing exists, IRC servers MAY attempt to further validate or resolve hostnames and match them to an IP address. It is the responsibility of IRC servers to verify the authenticity of connecting users and perform additional security checks as they see fit. To assist network operators and prevent abuse, IRC servers SHOULD show when a WebIRC connection is in use and SHOULD provide the original host when possible. This behavior is non-normative and implementation defined.