Setting up UnrealIRCd and Anope IRC Services on EC2

Having recently discovered sameroom.io I wanted to update the codetalk IRC server to be compliant with their authentication method. This basically just meant enabling SASL support, but while I was tinkering with stuff anyways, I thought I might as well streamline the setup process for the IRC server. In short, everything is fully automated and set up on AWS using EC2 and S3.

This will go through the process of doing exactly that, by talking about:

If you just want to throw yourself in the deep end, you can fork/clone the github repository, alter the configuration and script variables to fit your need and quickly be on with it. I recommend though that you skim through most of this to get an overview of what is happening.

SASL support

SASL (Simple Authentication and Security Layer) is a framework for authentication and data security. For all intents and purposes we won't bother with how it works specifically, since we are only interested in getting it running.

UnrealIRCd supports authenticating with SASL using a remote service that supports SASL. Here enters Anope which is commonly used for handling nickname registration and other IRC services. Since 1.9.x Anope has supported SASL. To enable it, it needs to be compiled with the sasl modules (which it should be by default).

The configuration for SASL is two part, a simple block for UnrealIRCd and a block for Anope.

UnrealIRCd: The following links the Anope services to the IRC server and sets the SASL server to the services server.

1
/* FILE: services.conf */
2
link services.myircserver.org {
3
    incoming {
4
        mask *;
5
    };
6
    outgoing {
7
        bind-ip  *;
8
        hostname 127.0.0.1;
9
        port     6697;
10
        options { ssl; autoconnect; };
11
    };
12
    password "MySecretPassword!";
13
    class    servers;
14
};
15

16
ulines {
17
	services.myircserver.org;
18
};
19
/* Enable SASL support */
20
set {
21
    sasl-server "services.myircserver.org";
22
};

Anope: Enabling SASL is fairly simple, and just requires that the module is loaded. The rest is handled by Anope.

1
/* FILE: modules.conf */
2
/* Load the SASL module m_sasl */
3
module { name = "m_sasl" }

If you are using the sample config in the github repo, then SASL is already included.

Installing UnrealIRCd

Since we want to automate the setup and installation, we need to install UnrealIRCd in a way that requires absolutely no user input. First off though, UnrealIRCd depends on some packages, and these will need to be installed.`

Since we are building UnrealIRCd from source, we will need some build tools. These can be found in the Development Tools group. Other than that, there are some curl, ssl and other libraries that needs to be installed.

1
# FILE: install-unrealircd.sh
2
yum -yq groupinstall "Development Tools" \
3
&& yum -yq install \
4
        curl \
5
        libcurl-devel \
6
        openssl-devel \
7
        openssl zlib \
8
        zlib-devel \
9
        ntp \
10
        c-ares \

Now we are able to compile UnrealIRCd from source. We will do all of this in one giant step:

1
# FILE: install-unrealircd.sh
2
# UnrealIRCd version
3
UNREAL_VERSION="unrealircd-4.0.0-rc3"
4

5
curl https://www.unrealircd.org/downloads/$UNREAL_VERSION.tar.gz | tar xz \
6
&& cd $UNREAL_VERSION \
7
&& ./configure \
8
    --enable-ssl \
9
    --with-showlistmodes \
10
    --with-shunnotices \
11
    --with-confdir=/etc/unrealircd/config \
12
    --with-cachedir=/etc/unrealircd/cache \
13
    --with-scriptdir=/etc/unrealircd/unreal \
14
    --with-tmpdir=/etc/unrealircd/tmp \
15
    --with-modulesdir=/etc/unrealircd/modules \
16
    --with-logdir=/etc/unrealircd/log \
17
    --with-docdir=/etc/unrealircd/doc \
18
    --with-datadir=/etc/unrealircd/data \
19
    --with-pidfile=/etc/unrealircd/pid \
20
    --with-bindir=/usr/bin/unrealircd \
21
    --with-permissions=0600 \
22
    --enable-dynamic-linking \
23
&& make \
24
&& make install

This will install UnrealIRCd into /etc/unrealircd with SSL enabled. Since we have SSL enabled, we will also need an SSL certificate! Luckily, this can also be done through without any user input. It does require some information though, so you should substitute the variables with your information.

1
# FILE: install-unrealircd.sh
2
# SSL certificate information
3
# The two-letter ISO abbreviation for your country
4
SSL_CERTIFICATE_COUNTRY="DK"
5
# The state or province where your organization is legally located
6
SSL_CERTIFICATE_STATE="Copenhagen"
7
# The city where your organization is legally located
8
SSL_CERTIFICATE_LOCATION="Copenhagen"
9
# The exact legal name of your organization
10
SSL_CERTIFICATE_ORGANIZATION="MyOrganization"
11
# Section of the organization
12
SSL_CERTIFICATE_ORGANIZATION_UNIT="IT"
13
# The fully qualified domain name for your web server
14
SSL_CERTIFICATE_COMMON_NAME="irc.myserver.org"
15
# Days the certificate is valid for
16
SSL_CERTIFICATE_DAYS=20000
17

18
mkdir -p /etc/unrealircd \
19
&& openssl req \
20
    -x509 \
21
    -newkey rsa:2048 \
22
    -keyout server.key.pem \
23
    -out server.cert.pem \
24
    -days $SSL_CERTIFICATE_DAYS \
25
    -nodes \
26
    -subj "/C=$SSL_CERTIFICATE_COUNTRY/ST=$SSL_CERTIFICATE_STATE/L=$SSL_CERTIFICATE_LOCATION/O=$SSL_CERTIFICATE_ORGANIZATION/OU=$SSL_CERTIFICATE_ORGANIZATION_UNIT/CN=$SSL_CERTIFICATE_COMMON_NAME" \
27
&& mv server.cert.pem /etc/unrealircd/config/ssl/ \
28
&& mv server.key.pem /etc/unrealircd/config/ssl/

Now you can put your configuration files into /etc/unrealircd/config. You can read more in the automating section about automatically including the configs.

Installing Anope IRC services

Again the goal is to install without any human interaction needed. This step will assume that UnrealIRCd has been installed first, since it needs some of the tools (namely the Development Tools packages).

Anope uses (or at least we use it here) cmake to build. This means we have to install cmake before doing anything else.

1
# FILE: install-anope.sh
2
yum -y install cmake

Now we can compile Anope IRC services from source. We will fetch it and compile it in one step:

1
# FILE: install-anope.sh
2
# Anope version
3
ANOPE_VERSION="2.0.2"
4

5
curl -L https://github.com/anope/anope/releases/download/$ANOPE_VERSION/anope-$ANOPE_VRSION-source.tar.gz | tar xz \
6
&& cd anope-$ANOPE_VERSION-source \
7
&& mv modules/extra/m_ssl_openssl.cpp modules/ \
8
&& mv modules/extra/m_sasl_dh-aes.cpp modules/ \
9
&& mkdir build \
10
&& cd build \
11
&& cmake \
12
    -DINSTDIR:STRING=/etc/anope \
13
    -DDEFUMASK:STRING=077  \
14
    -DCMAKE_BUILD_TYPE:STRING=RELEASE \
15
    -DUSE_RUN_CC_PL:BOOLEAN=ON \
16
    -DUSE_PCH:BOOLEAN=ON .. \
17
&& make \
18
&& make install

Depending on your SSL config you might also need to generate some certificates here. These are automatically generated in the full script included in the github repo, along with a sample configuration setup.

It is probably worth noting that two extra modules were included in the Anope build, namely m_ssl_openssl which enables SSL and m_sasl_dh-aes which enables AES on SASL. You can take a look at the extra modules in the modules/extra folder in the Anope source files.

Automating launch of EC2 and install

There are a couple of things that need to be set up first. For starters, we need to create a security group for the EC2 instance. You can do this in AWS Console -> EC2 -> Security Groups -> Create Security Group. If you don't know what you want to open here, open the two TCP ports 6667 and 6697 to anywhere, and the SSH port 22 to anywhere also. The last one is optional, but it is quite nice to be able to check out the logs if anything goes wrong.

After this we need to create an IAM role for the instance, so that it can fetch configuration files and install scripts from S3. You can do this in AWS Console -> Identify & Access Management -> Roles -> Create New Role and then name the role. You then need to attach a policy to it. This can either be full S3 access, or a more limited policy. For more on the latter see the post about generating S3 bucket specific policies.

Now to the fun part! This will assume that you are using the install scripts found in the github repo, and that you have uploaded them to S3. In the repo there is a script to quickly upload the install/install-anope.sh and install/install-unrealircd.sh scripts, along with tar/gzipping the config files and uploading them. The script is aptly named upload-to-s3.sh.

First off, we will create an init script, which the instance will run on the first launch. This will take care of installing everything and moving the files into place, using the install scripts mentioned earlier. By having a IAM role with S3 read access attached to it, we can download objects from the S3 bucket directly.

1
# FILE: init-ec2.sh
2
#!/bin/bash
3
# Bucket location
4
export AWS_S3_BUCKET="YourBucket/install"
5
export AWS_DEFAULT_REGION=eu-central-1
6

7
# Download the files from S3
8
echo "Downloading install files" >> /home/ec2-user/log.txt
9
aws s3 cp --region $AWS_DEFAULT_REGION s3://$AWS_S3_BUCKET/install/install-unrealircd.sh /home/ec2-user/install-unrealircd.sh >> /home/ec2-user/log.txt
10
aws s3 cp --region $AWS_DEFAULT_REGION s3://$AWS_S3_BUCKET/install/install-anope.sh /home/ec2-user/install-anope.sh >> /home/ec2-user/log.txt
11

12
# Make the scripts executable
13
echo "Making scripts executable" >> /home/ec2-user/log.txt
14
chmod +x /home/ec2-user/install-unrealircd.sh >> /home/ec2-user/log.txt
15
chmod +x /home/ec2-user/install-anope.sh >> /home/ec2-user/log.txt
16

17
# Installing UnrealIRCd
18
echo "Starting install of UnrealIRCd (check log-unrealircd.txt)" >> /home/ec2-user/log.txt
19
touch /home/ec2-user/log-unrealircd.txt
20
/home/ec2-user/install-unrealircd.sh >> /home/ec2-user/log-unrealircd.txt
21

22
# Installing Anope
23
echo "Starting install of Anope (check log-anope.txt)" >> /home/ec2-user/log.txt
24
touch /home/ec2-user/log-anope.txt
25
/home/ec2-user/install-anope.sh >> /home/ec2-user/log-anope.txt

The above fetches the scripts down, executes them which in turn installs UnrealIRCd and Anope.

While launching stuff from the console is indeed very fun...the first couple of times, it quickly gets tedious. Therefore we will utilize the AWS API, to create an EC2 instance, tag it and associate an elastic IP to it.

1
# FILE: launch-ec2-instance.sh
2
#!/bin/bash
3

4
# AWS user credentials
5
export AWS_ACCESS_KEY_ID=MyAccessKey
6
export AWS_SECRET_ACCESS_KEY=MySecretKey
7
export AWS_DEFAULT_REGION=eu-central-1
8

9
# EC2 instance details
10
NAME_TAG="irc.myserver.org"
11
IMAGE_ID="ami-bc5b48d0" # Amazon Linux AMI 2015.09.1 (HVM), SSD Volume Type
12
SNAPSHOT_ID="snap-f1a95375" # That snapshot depends on the AMI above
13
INSTANCE_TYPE="t2.micro"
14
KEY_NAME="irc-server"
15
SECURITY_GROUP="IRC"
16
IAM_ROLE="irc.codetalk.io"
17
ELASTIC_IP=168.1.1.1
18

19
# Launch an EC2 instance
20
echo "> Launching the EC2 instance..."
21
INSTANCE_ID=$( aws ec2 run-instances \
22
    --image-id $IMAGE_ID \
23
    --instance-type $INSTANCE_TYPE \
24
    --key-name $KEY_NAME \
25
    --security-groups $SECURITY_GROUP \
26
    --iam-instance-profile Name=$IAM_ROLE \
27
    --block-device-mapping DeviceName=/dev/xvda,Ebs="{SnapshotId=$SNAPSHOT_ID,VolumeSize=30,DeleteOnTermination=true,VolumeType=gp2}" \
28
    --user-data file://initec2.sh \
29
    | jq --raw-output '.Instances[0].InstanceId' )
30
echo "> Instance $INSTANCE_ID is launching"
31

32
# Add name, environment and company tags to the instance
33
echo "> Adding tags to the instance $INSTANCE_ID"
34
aws ec2 create-tags \
35
    --resources $INSTANCE_ID \
36
    --tags "[
37
        {\"Key\": \"Name\", \"Value\": \"$NAME_TAG\"}
38
    ]"
39

40
# Waiting for the instance to be running
41
echo "> Waiting until $INSTANCE_ID is running..."
42
aws ec2 wait instance-running --instance-ids $INSTANCE_ID
43
echo "> Instance is up"
44

45
# Associate an elastic IP with the instance
46
echo "> Associating the IP $ELASTIC_IP with instance $INSTANCE_ID"
47
ASSOC_ID=$( aws ec2 associate-address --instance-id $INSTANCE_ID --public-ip $ELASTIC_IP )
48
echo "> Done!"

The script should mostly be self-explanatory. The important parts are under the # EC2 instance details comment. Here are the values that you should configure to match what you need. The AMI ID can be found in the AMI store (you can start launching an instance and stop after the first screen).

GitHub repo, ready to fork!

All of the scripts and configuration files to set it all up can be found in this github repo. You'll want to change the configuration files in the config folder to fit your server details.

Furthermore you need to fit the credentials and server details to your own, in the init-ec2.sh, launch-ec2-instance.sh and upload-to-s3.sh scripts. Hopefully it should be evident from the naming of the variables, what it is they expect.