InspIRCd

InspIRCd is a modular Internet Relay Chat (IRC) server written in C++ for Linux, BSD, Windows and Mac OS X systems which was created from scratch to be stable, modern and lightweight.

InspIRCd is one of only a few IRC servers to provide a tunable number of features through the use of an advanced but well-documented module system. By keeping core functionality to a minimum we hope to increase the stability, security, and speed of InspIRCd while also making it customizable to the needs of many different users.

Bootstrapping

The easiest way to run this image is using our bootstrap script.

To use it run the following statement:

wget -qO- https://raw.githubusercontent.com/inspircd/docker/master/bootstrap.sh | sh

The bootstrap script takes care of the fact that docker is installed and runs the image.

If port 6697 or 6667 are already in use another random port is used. Otherwise, those ports are allocated by the container.

How to use this image

First, a simple run command:

$ docker run --name ircd -p 6667:6667 inspircd/inspircd-docker

This will start an InspIRCd instance listening on the default IRC port 6667 on the container.

You should then be able to connect using your favourite client.

To include your configuration into the container use:

$ docker run --name inspircd -p 6667:6667 -v /path/to/your/config:/inspircd/conf/ inspircd/inspircd-docker

Notice: In case you provide an empty directory make sure it's owned by UID 10000. Use chown 10000 directory to correct permissions

Default ports of this container image:

|Port|Configuration | |----|------------------| |6667|clients, plaintext| |6697|clients, TLS | |7000|server, plaintext | |7001|server, TLS |

Generated configuration

Instead of including your own configuration files, this container allows you to manipulate a few options of the default configuration by environment variables.

Use the following environment variables to configure your container:

|Available variables |Default value |Description | |-------------------------|--------------------------------|----------------------------------------------| |INSP_NET_SUFFIX |.example.com |Suffix used behind the server name | |INSP_NET_NAME |ExampleNet |Name advertised as network name | |INSP_SERVER_NAME |Container ID + INSP_NET_SUFFIX|Full container name. Has to be an FQDN | |INSP_ADMIN_NAME |Adam Inistrator |Name showed by the /admin command | |INSP_ADMIN_DESC |Supreme Overlord |Description showed by the /admin command | |INSP_ADMIN_EMAIL |noreply@${INSP_SERVER_NAME} |E-mail shown by the /admin command | |INSP_ENABLE_DNSBL |yes |Set to no to disable DNSBLs | |INSP_CONNECT_PASSWORD |no default |Password either as plaintext, or hash value | |INSP_CONNECT_HASH |no default |Hashing algorithm for INSP_CONNECT_PASSWORD |

A quick example how to use the environment variables:

$ docker run --name inspircd -p 6667:6667 -e "INSP_NET_NAME=MyExampleNet" inspircd/inspircd-docker

Initial setup issues

If you have issues with registration timeouts when connecting to a fresh installation, you may have DNS issues. By default, when a user connects to the IRC server, the user's IP is checked against DNS blacklists. In some cases this check can fail.

To see if you're affected by this particular issue, try disabling DNS Blacklists, e.g.

$ docker run --name inspircd -p 6667:6667 -e "INSP_ENABLE_DNSBL=no" inspircd/inspircd-docker

If you can connect with INSP_ENABLE_DNSBL=no, try adding a DNS configuration to your inspircd.conf file to point to a DNS server you trust. See the DNS docs for details.

Password authentication

You can either set a plaintext password or a hashed password. If you leave INSP_CONNECT_HASH unset, the password will be used as a plaintext password.

To use connect password s3cret stored in plaintext:

$ docker run --name inspircd -p 6667:6667 -e "INSP_CONNECT_PASSWORD=s3cret" inspircd/inspircd-docker

To use connect password s3cret stored with bcrypt:

$ docker run --name inspircd -p 6667:6667 -e "INSP_CONNECT_HASH=bcrypt" -e "INSP_CONNECT_PASSWORD=\$2a\$12\$vqVao8w4cUbtE02dh0sqyu6OGnEZEw452SPyWQBE5QGg3ePJbtusm" inspircd/inspircd-docker

Make sure you escape special chars like $ or & if needed. If you are using docker-compose you might need to double escape and use double-dollar signs

Oper

We provide two possibly ways to define a default oper for the server.

If neither INSP_OPER_PASSWORD_HASH, nor INSP_OPER_FINGERPRINT is configured, no oper will be provided to keep your server secure.

Further details see official opers.conf docs.

Password authentication

A normal password authentication uses /oper <opername> <password> (everything case sensitive)

To generate a password hash connect to the network and use /mkpasswd <hash-type> <password>.

|Available variables |Default value |Description | |-------------------------|--------------------------------|----------------------------------------------| |INSP_OPER_NAME |oper |Oper name | |INSP_OPER_PASSWORD_HASH|no default |Hash value for your oper password hash | |INSP_OPER_HOST |*@* |Hosts allowed to oper up | |INSP_OPER_HASH |hmac-sha256 |Hashing algorithm for INSP_OPER_PASSWORD | |INSP_OPER_SSLONLY |yes |Allow oper up only while using TLS | |INSP_OPER_PASSWORD |no default |(deprecated) Alias INSP_OPER_PASSWORD_HASH |

For example to oper up with /oper oper s3cret you would run the following line:

$ docker run --name inspircd -p 6667:6667 -p 6697:6697 -e "INSP_OPER_PASSWORD_HASH=cNkbWRWn\$MhSTITMbrCxp0neoDqL66/MSI2C+oxIa4Ux6DXb5R4Q" inspircd/inspircd-docker

Make sure you escape special chars like $ or & if needed

Client certificate authentication

This way only works using TLS connection and uses a client certificate for authentication.

Provide the SHA256 fingerprint of the certificate as INSP_OPER_FINGERPRINT to configure it.

|Available variables |Default value |Description | |-------------------------|--------------------------------|----------------------------------------------| |INSP_OPER_NAME |oper |Oper name for usage with /oper | |INSP_OPER_FINGERPRINT |no default |Oper TLS fingerprint (SHA256) | |INSP_OPER_AUTOLOGIN |no |Automatic login of with TLS fingerprint |

Linking servers and services

Links

With this container you can link other servers. To do so you have to define a few environment variables.

Currently we allow 3 links per container. Those link variables are INSP_LINK1_*, INSP_LINK2_*, and INSP_LINK3_*.

We only list the possible options once, but they work for INSP_LINK1_*, as well as for INSP_LINK2_* and INSP_LINK3_*.

|Available variables |Default value |Description | |-------------------------|--------------------------------|----------------------------------------------| |INSP_LINK1_NAME |no default |Name of the remote server (INSP_SERVER_NAME)| |INSP_LINK1_IPADDR |no default |IP or hostname of the remote server | |INSP_LINK1_PORT |7001 (TLS) or 7000 |Port used to connect the remote server | |INSP_LINK1_SENDPASS |no default |Password send by this server | |INSP_LINK1_RECVPASS |no default |Password send by remote server | |INSP_LINK1_PASSWORD |no default |Alias for sendpass and recvpass | |INSP_LINK1_ALLOWMASK |first container subnet |CIDR of remote server's IP address | |INSP_LINK1_TLS_ON |yes |Turn on TLS encryption for the link | |INSP_LINK1_FINGERPRINT |no default |TLS Fingerprint of the remote server (SHA256) | |INSP_LINK1_OPTIONS |no default |Allows additional to set options to <link> | |INSP_LINK1_AUTOCONNECT |yes |Enables <autoconnect> for this link |

Services

This image allows you to configure services link blocks by environment variables.

This way you can easily connect Anope or Atheme to your InspIRCd container.

|Available variables |Default value |Description | |-------------------------|--------------------------------|----------------------------------------------| |INSP_SERVICES_NAME |services + INSP_NET_SUFFIX |Name of the services host | |INSP_SERVICES_IPADDR |services |IP or hostname of services | |INSP_SERVICES_ALLOWMASK|first container subnet |CIDR of services source IP | |`INSP_SERVICES_HIDDEN