Listen block

The listen block defines the TCP/IP ports and/or UNIX socket that the IRCd will listen on.

Syntax

listen {
        /* For IPv4 or IPv6: */
        ip <ip>;
        port <port>;
        /* For UNIX sockets: */
        file <full path>;
        mode <mode>;
        spoof-ip <fake-ip>;

        /* Options: */
	options {
		<option>;
		<option>;
		...
	}

        /* Specific SSL/TLS configuration to this listen block */
	tls-options {
		...
	}
}

ip

Simply set ip to * (an asterisk) to bind to all available IP's on the machine, OR specify an IP to only bind to that IP address (this latter is usually required at shell providers).

port

This is the port you want to listen on, like 6667. You can also specify a port range, like 6667-6669.

file

This is the full path (filename) to a UNIX socket that will be created on the machine. This feature is rarely used, so if you don't what this is then don't use and don't set it. If you have a file item then you cannot have an ip or port in the same listen block.

mode

Optionally, if the listener is a file, then you can specify permissions mode here. Valid choices are: 0700 (user only, rwx------, the default), 0770 (user and group, rwxrwx---), and 0777 (world writable, rwxrwxrwx, not recommended). This can be useful if you have a webserver on the same machine which needs to access the *NIX socket, for example. This option only exists in UnrealIRCd 6.0.6 or later.

spoof-ip

If the socket is a file, then connections over this UNIX domain socket are spoofed to come from 127.0.0.1 by default. You can override this by setting spoof-ip to a different IP address. This can be useful for Running Tor hidden service with UnrealIRCd. This requires UnrealIRCd 6.1.0 or higher

options block (optional)

You can specify options for the port. Valid options are:

• tls: SSL/TLS encrypted port
• clientsonly: port is only for clients
• serversonly: port is only for servers
• rpc: for remote control via JSON-RPC
• websocket: port is for WebSocket, and within that block:
  • You must specify a websocket type. Either text or binary, with text being the usual choice.
    options { websocket { type text; } }
  • You can optionally restrict from which websites websockets can be used by web browsers, via allow-origin.
    In this context websites means the site(s) hosting the HTML/JS page that makes the websocket, e.g. if the chat page is https://kiwiirc.com/nextclient/ then you would use { kiwiirc.com; }.
    Please don't confuse allow-origin with the Proxy block, the proxy block is about reverse proxies.
    The allow-origin directive does not restrict any NON-browsers from using websockets to connect to your server, as they could can just spoof the Origin header. It is only a browser restriction for regular users.
    The allow-origin contains of a list, like options { websocket { type text; allow-origin { kiwiirc.com; } } }
    And the default is to allow all: options { websocket { allow-origin { *; } } }
  • See #Websocket_port for a full example.

tls-options block (optional)

Valid options are all the SSL/TLS settings that also exist in set::tls. For example you may want to use an Lets Encrypt certificate/key on all normal client ports (via set::tls::certificate). But for this port you want to use another SSL certificate/key:

listen {
        ...
        tls-options {
                certificate "ssl/server.cert.pem";
                key "ssl/server.key.pem";
        }
}

Examples

Standard port 6667, insecure plaintext

listen {
        ip *;
        port 6667;
}

Standard SSL/TLS port 6697

listen {
        ip *;
        port 6697;
	options {
		tls;
	}
}

Or, with a Let's Encrypt certificate:

listen {
        ip *;
        port 6697;
        options { tls; }
        tls-options {
                certificate "/etc/letsencrypt/live/irc.example.org/fullchain.pem";
                key "/etc/letsencrypt/live/irc.example.org/privkey.pem";
        }
}

Websocket port

Example of Websockets on port 8000 with Let's Encrypt certificate:

listen {
    ip *;
    port 8000;
    options {
        tls;
        websocket {
            type text;  // type must be either 'text' or 'binary'
            // In 6.1.3+ you can optionally restrict origins, see websocket options
            // https://www.unrealircd.org/docs/Listen_block#options_block
            //allow-origin { *; }
        }
    }
    tls-options {
        certificate "/etc/letsencrypt/live/irc.example.org/fullchain.pem";
        key "/etc/letsencrypt/live/irc.example.org/privkey.pem";
        options {
            no-client-certificate;
        }
    }
}

If you wish to use a reverse proxy in front of websockets, then see the Proxy block. This is rare, but possible.

JSON-RPC port

A JSON-RPC port:

listen {
        ip *;
        port 8600;
        options { rpc; }
}

NOTE: this requires including rpc.modules.default.conf, see JSON-RPC.