Skip to content

Latest commit

 

History

History
363 lines (228 loc) · 18 KB

README.md

File metadata and controls

363 lines (228 loc) · 18 KB
Raw

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 Omega Name advertised as network name
INSP_SERVER_NAME Container ID + INSP_NET_SUFFIX Full container name. Has to be an FQDN
INSP_ADMIN_NAME Jonny English Name showed by the /admin command
INSP_ADMIN_NICK MI5 Nick showed by the /admin command
INSP_ADMIN_EMAIL [email protected] 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 hmac-sha256:

$ docker run --name inspircd -p 6667:6667 -e "INSP_CONNECT_HASH=hmac-sha256" -e "INSP_CONNECT_PASSWORD=mlknZfDb\$C5E0lXKxdoHFxmsJEfSNe8Ct4XG25slv2WiJvUnnWew" 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 yes 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 no Hide services from /MAP and /LINKS
INSP_SERVICES_SENDPASS no default Password send by this server
INSP_SERVICES_RECVPASS no default Password send by the services
INSP_SERVICES_PASSWORD no default Alias for sendpass and recvpass
INSP_SERVICES_TLS_ON no Turn on TLS encryption for the services link
INSP_SERVICES_OPTIONS no default Allows additional to set options to <link>

If you want to link services.example.com for example, you have to specify at least the INSP_SERVICES_PASSWORD:

$ docker run --name inspircd -p 6667:6667 -p 6697:6697 -e "INSP_SERVICES_PASSWORD=somesecretpassword" inspircd/inspircd-docker

Make sure you run the services and InspIRCd container on the same docker network or specify the correct INSP_SERVICES_ALLOWMASK

TLS

Using self-generated certificates

This container image generates a self-signed TLS certificate on start-up as long as none exists. To use this container with TLS enabled:

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

You can customize the self-signed TLS certificate using the following environment variables:

Available variables Default value Description
INSP_TLS_CN irc.example.com Common name of the certificate
INSP_TLS_MAIL [email protected] Mail address represented in the certificate
INSP_TLS_UNIT Server Admins Unit responsible for the service
INSP_TLS_ORG Example IRC Network Organisation name
INSP_TLS_LOC Example City City name
INSP_TLS_STATE Example State State name
INSP_TLS_COUNTRY XZ Country Code by ISO 3166-1
INSP_TLS_DURATION 365 Duration until the certificate expires

This will generate a self-signed certificate for irc.example.org instead of irc.example.com:

$ docker run --name inspircd -p 6667:6667 -p 6697:6697 -e "INSP_TLS_CN=irc.example.org" inspircd/inspircd-docker

Using secrets

We provide the ability to use secrets with this image to place a certificate to your nodes.

Docker version 1.13 is required and secrets are only supported in swarm mode

docker secret create irc.key /path/to/your/ircd.key
docker secret create inspircd.crt /path/to/your/ircd.crt

docker service create --name inspircd --secret source=irc.key,target=inspircd.key,mode=0400 --secret inspircd.crt inspircd/inspircd-docker

Notice the syntax --secret source=irc.key,target=inspircd.key allows you to name a secret in a way you like.

Currently used secrets:

  • inspircd.key
  • inspircd.crt

Generic configuration includes

To extend the default configuration you can use /inspircd/conf.d/.

All .conf-files placed there, by mounting or extending the image, are automatically included.

$ docker run --name inspircd -p 6667:6667 -v /path/to/your/configs:/inspircd/conf.d/ inspircd/inspircd-docker

You have to take care about possible conflicts with the existing configuration. If you want a full custom configuration, copy or mount it to /inspircd/conf/ instead of /inspircd/conf.d/.

Using secrets

Additional to the conf.d/ directory we offer a automated includes for all .conf files that are mounted as secrets.

For example to add your own oper configuration.

docker secret create secret-opers /path/to/your/opers.conf

docker service create --name inspircd --secret secret-opers inspircd/inspircd-docker

Build extras

To build extra modules you can use the --build-arg statement.

Available build arguments:

Argument Description
VERSION Version of InspIRCd. Uses -b-parameter from git clone
CONFIGUREARGS Additional parameters. Used to enable core extras like m_geo_maxmind
EXTRASMODULES Additional modules from inspircd-contrib repository like m_geocmd
BUILD_DEPENDENCIES Additional packages which are only needed during compilation
RUN_DEPENDENCIES Additional packages which are needed to run InspIRCd 
docker build --build-arg "BUILD_DEPENDENCIES=libmaxminddb-dev pcre-dev" --build-arg "RUN_DEPENDENCIES=libmaxminddb pcre" --build-arg "CONFIGUREARGS=--enable-extras m_geo_maxmind --enable-extras m_regex_pcre"  --build-arg "EXTRASMODULES=m_geocmd" --build-arg "VERSION=v1.2.3" inspircd-docker

Building additional modules

In case you want to develop InspIRCd modules, it is useful to run InspIRCd with modules which neither exist in core modules nor in extras.

You can put the sources these modules in the modules directory of this repository. They are automatically copied to the modules directory of InspIRCd.

It also allows you to overwrite modules.

Make sure you install all needed dependencies using ADDPACKAGES.

Updates and updating

To update your setup simply pull the newest image version from docker hub and run it.

docker pull inspircd/inspircd-docker

We automatically build our images weekly to include the current state of modern libraries.

Considering to update your docker setup regularly.

Hint: Check the "Breaking changes"-section when you notice problems.

Deprecated features

We provide information about features we remove in future.

  • INSP_OPER_PASSWORD - was replaced by INSP_OPER_PASSWORD_HASH as more descriptive name

Breaking changes

We document changes that possibly broken your setup and are no longer supported. Hopefully, we can provide useful information for debugging.

  • 046bb02 Update to InspIRCd 3.0 requires some config changes. If you run InspIRCd using docker-compose or by mounting a volume, make sure you update your config according to the docs page.

  • cdba94f ADDPACKAGES and DELPACKAGES are replaced by BUILD_DEPENDENCIES and RUN_DEPENDENCIES

Additional information

By default this image ships DNSBL settings for DroneBL and EFnet RBL.

This should provide a basic protection for your server, but also causes problems if you want to use Tor or open proxies.

Set INSP_ENABLE_DNSBL to no to disable them.

License

View license information for the software contained in this image.

Supported Docker versions

This image is officially supported on Docker version 17.06.0-CE.

Support for older versions (down to 1.12) is provided on a best-effort basis.

Please see the Docker installation documentation for details on how to upgrade your Docker daemon.

User Feedback

Issues

If you have any problems with or questions about this image, please contact us through a GitHub issue.

You can also reach many of the project maintainers via the #inspircd IRC channel on Teranova.

Contributing

You are invited to contribute new features, fixes, or updates, large or small; we are always thrilled to receive pull requests and do our best to process them as fast as we can.