ElixIRCd

Introduction

ElixIRCd is an IRCd (Internet Relay Chat daemon) server implemented in Elixir. It is designed to provide a robust and highly concurrent IRC server environment. Its implementation makes use of the functional nature of Elixir and leverages the built-in concurrency and memory database capabilities of the Erlang VM (BEAM) and OTP (Open Telecom Platform) principles to deliver an efficient and reliable platform for IRC operations.

Table of Contents

• Getting Started
  • Demo Server
  • Quick Start with Docker
  • Start from the Source Code
• Features
  • Commands
  • Modes
  • Services
  • IRCv3 Specifications
  • Server Capabilities
• Development
• Contributing
• License

Getting Started

Running ElixIRCd with the official Docker image is straightforward. Alternatively, you can connect to the demo server to explore its features or build your own release package from the source code.

Demo Server

The ElixIRCd demo server is a live instance of the server, allowing you to test and experience its features.

You can connect using any IRC client like Smuxi or a web-based client such as Kiwi IRC

• Server: irc.elixircd.org
• Ports: 6667 (plaintext) and 6697 (SSL/TLS)
• Alternative Ports: 6668 (plaintext) and 6698 (SSL/TLS)

Quick Start with Docker

To quickly start the ElixIRCd server using Docker with the official ElixIRCd image, run the following command:

docker run \
  -p 6667:6667 -p 6668:6668 -p 6697:6697 -p 6698:6698 \
  faelgabriel/elixircd

Remote Commands

# Connects to the running system via a remote shell
docker exec -it <container_name> ./bin/elixircd remote

# Gracefully stops the running system via a remote command
docker exec -it <container_name> ./bin/elixircd stop

Configuration

You can configure ElixIRCd by creating a elixircd.exs file and mounting it into the Docker container at /app/config/.

1. Create a elixircd.exs file based on the default configuration and customize it as desired.

2. Start the ElixIRCd server with your configuration file by mounting it into the Docker container:

   docker run \
     -p 6667:6667 -p 6668:6668 -p 6697:6697 -p 6698:6698 \
     -v ./elixircd.exs:/app/config/elixircd.exs \
     faelgabriel/elixircd

SSL Certificates

For development and testing environments, ElixIRCd automatically generates self-signed certificates by default for SSL listeners configured with keyfile: "priv/cert/selfsigned_key.pem" and certfile: "priv/cert/selfsigned.pem".

For production environments, you should configure SSL listeners with a valid certificate and key obtained from a trusted Certificate Authority (CA), and place them in your local priv/cert folder before mounting them into the Docker container at /app/priv/cert/.

1. Obtain an SSL certificate and key from a trusted Certificate Authority (CA), such as Let's Encrypt.

2. Update your elixircd.exs configuration file with the paths to the obtained SSL certificate files (e.g., priv/cert/fullchain.pem, priv/cert/privkey.pem, and priv/cert/chain.pem), and ensure these files are located in your local cert/ folder:

   # ... other configurations
   {:ssl, [port: 6697, certfile: "priv/cert/fullchain.pem", keyfile: "priv/cert/privkey.pem", cacertfile: "priv/cert/chain.pem"]},
   {:ssl, [port: 6698, certfile: "priv/cert/fullchain.pem", keyfile: "priv/cert/privkey.pem", cacertfile: "priv/cert/chain.pem"]}
   # ... other configurations

3. Start the ElixIRCd server with your configuration and certificate files by mounting the cert/ folder into the Docker container at /app/priv/cert/:

   docker run \
     -p 6667:6667 -p 6668:6668 -p 6697:6697 -p 6698:6698 \
     -v ./elixircd.exs:/app/config/elixircd.exs \
     -v ./cert/:/app/priv/cert/ \
     faelgabriel/elixircd

Additional SSL options can be found at the Ranch documentation.

MOTD (Message of the Day)

You can set the Message of the Day by creating a motd.txt file mounting it into the Docker container at /app/config/.

1. Create a motd.txt file with your desired message of the day.

2. Start the ElixIRCd server with your MOTD file by mounting it into the Docker container:

   docker run \
     -p 6667:6667 -p 6668:6668 -p 6697:6697 -p 6698:6698 \
     # ... other volume mounts
     -v ./motd.txt:/app/config/motd.txt \
     faelgabriel/elixircd

Start from the Source Code

To build your own ElixIRCd release from the source code and run the server, follow these steps:

1. Set up your development environment by following the instructions in the Development - Setting Up Your Environment section.

2. Build a release package by running the following command, replacing 0.0.1 with the desired version:

   APP_VERSION=0.0.1 MIX_ENV=prod mix release

3. Start the ElixIRCd server by running the generated release:

   _build/prod/rel/elixircd/bin/elixircd start

Features

ElixiRCd adheres to the traditional IRC protocols as outlined in the foundational RFCs for the IRC protocol, includes integrated IRC services, and supports IRCv3 specifications.

Key RFCs include RFC 1459 (Internet Relay Chat Protocol), RFC 2810 (IRC: Architecture), RFC 2811 (IRC: Channel Management), RFC 2812 (IRC: Client Protocol), RFC 2813 (IRC: Server Protocol), and RFC 7194 (Default Port for IRC via TLS/SSL).

✅ Implemented - ✴️ Partially implemented - ❌ Not implemented

Commands

The commands are essential to the functionality of the ElixIRCd server, following standard IRC protocol for communication between clients and the server.

• PASS: Set a password for the connection. ✅
• NICK: Set or change a user's nickname. ✅
• USER: Specify username, hostname, servername, and real name. ✅
• JOIN: Join a channel or create one if it doesn't exist. ✅
• PART: Leave a channel. ✅
• MODE: Set or unset user or channel modes. ✅
• TOPIC: Set or get the topic of a channel. ✅
• NAMES: List all visible nicknames on a channel. ❌
• LIST: List channels and their topics. ✅
• INVITE: Invite a user to a channel. ✅
• KICK: Eject a user from a channel. ✅
• PRIVMSG: Send private messages between users or to a channel. ✅
• NOTICE: Send a message to a user or channel without automatic reply. ✅
• MOTD: Request the Message of the Day from the server. ✅
• WHOIS: Get information about a user. ✅
• WHO: Get information about users on a server. ✅
• WHOWAS: Get information about a user who has left. ✅
• USERHOST: Provide information about a list of nicknames. ✅
• USERS: List users logged into the server. ✅
• AWAY: Set an away message. ✅
• PING/PONG: Test the presence of an active connection. ✅
• QUIT: Disconnect from the server. ✅
• LUSERS: Get statistics about the size of the network. ✅
• ISON: Check if specified users are online. ✅
• VERSION: Respond to queries about the server's version. ✴️
• STATS: Provide server statistics. ✅
• INFO: Provide information about the server. ✅
• TIME: Provide the server's local time. ✅
• TRACE: Trace routes to a specific server or user. ✅
• ADMIN: Provide information about the server administrator. ✅
• OPER: Allow operators to gain elevated privileges on the server. ✅
• WALLOPS: Allow operators to distribute messages to users with 'wallop' privileges. ✅
• KILL: Allow operators to disconnect a user from the network. ✅
• REHASH: Enable operators to reload the server's configuration. ✅
• RESTART: Allow operators to restart the server. ✅
• DIE: Allow operators to shut down the server. ✅

Modes

Modes can be applied to channels or users to modify their behaviors. These can be set by users who have the appropriate permissions or automatically by the server.

User Modes

• +i (Invisible): Hides the user from WHO searches and WHOIS searches by those not in shared channels. ✅
• +o (Operator): Provides elevated privileges for network management and oversight. ✅
• +w (Wallops): Enables reception of global announcements or alerts from network operators. ✅
• +Z (Secure Connection): Indicates the user's connection is encrypted with SSL/TLS. ✅

Channel Modes

• +b (Ban): Prevents a user or host from joining the channel. ✅
• +i (Invite Only): Restricts channel access to invited users only. ✅
• +k (Key): Requires a password to join the channel. ✅
• +l (Limit): Limits the number of users who can join the channel. ✅
• +m (Moderated): Only users with voice or higher can send messages to the channel. ✅
• +n (No External Messages): Prevents messages from users not in the channel. ✅
• +o (Operator): Grants operator status to a user. ✅
• +p (Private): Hides the channel from the LIST command. ✅
• +s (Secret): Hides the channel from the LIST command and WHOIS searches. ✅
• +t (Topic): Restricts the ability to change the channel topic to operators only. ✅
• +v (Voice): Grants voice status to a user. ✅

Services

ElixIRCd includes integrated IRC services, eliminating the need to connect external services to the server.

• NickServ: Register and manage nicknames. ❌
• ChanServ: Register and manage channels. ❌

IRCv3 Specifications

The IRCv3 specifications add modern capabilities to the server. For more details, visit ircv3.net.

Enhanced Commands and Extensions

• Capability Negotiation: Capability negotiation mechanism between clients and servers. ✴️
• Message Tags: Additional metadata in messages. ❌
• Account Authentication and Registration: Secure SASL authentication mechanism. ❌
• Account Tracking: Account notifications and tagging. ❌
• Away Notifications: Real-time notifications of user "away" status changes. ❌
• Batches: Sending messages in batches. ❌
• Bot Mode: Identification of bots in channels. ❌
• Changing User Properties: Dynamic updating of user properties. ❌
• Client-Only Tags: Attaching metadata to messages not transmitted to the server. ❌
• Echo Message: Clients receive a copy of their sent messages. ❌
• Invite Notify: Notifications when a user is invited to a channel. ❌
• Labeled Responses: Associating responses with sent commands. ❌
• Listing Users: Enhanced user information in channel queries. ❌
• Message IDs: Unique identifiers for messages. ❌
• Monitor: Efficient tracking of user online/offline status. ❌
• Server Time: Timestamp information for messages. ❌
• Standard Replies: Standardized format for server and client replies. ❌
• Strict Transport Security (STS): Automatic TLS encryption upgrade. ❌
• UTF8ONLY: Indication of UTF-8 only traffic support. ❌
• WebIRC: Provision of real IP address for users connecting through gateways. ❌
• WebSocket Protocol: Enabling IRC over WebSockets for web clients. ❌

Commands

• CAP: Negotiate client capabilities with the server. ✴️
• AUTHENTICATE: Log in to a client account using SASL authentication. ❌
• ACCOUNT: Notify clients of friends' new logins. ❌
• CHGHOST: Notify clients about changes in friends' usernames and hostnames. ❌
• INVITE: Alert other clients when someone is invited to a channel. ❌
• JOIN: Extended to include usernames and hostnames in join messages. ❌
• MONITOR: Track when specific nicknames enter or leave the network. ❌
• NAMES: List nicknames on a channel, extended to include account names. ❌
• TAGMSG: Send messages with tags but without text content. ❌
• WEBIRC: Provide real IP addresses of clients connecting through a gateway. ❌
• WHO: Extended to allow clients to request additional information. ❌

Server Capabilities

• Connection Pooling: Efficient management of a pool of connections. ✅
• High Concurrency: Efficient handling of multiple connections and messages. ✅
• Horizontal Scalability: Ability to scale out by adding more servers to a cluster. ❌
• Server Linking: Ability to connect multiple servers to form a network. ❌
• SSL/TLS Support: Secure communication using SSL or TLS. ✅
• IPv6 Compatibility: Support for both IPv4 and IPv6 connections. ✅
• Rate Limiting: Prevent abuse by controlling message rates. ❌
• Connection Cloaking: Mask users' IP addresses to enhance privacy. ❌

Development

ElixIRCd is written in Elixir, so you'll need to have Elixir and Erlang installed on your machine. We recommend using asdf to easily install and manage Elixir and Erlang versions. Additionally, you need to have Git installed to clone the repository.

Setting Up Your Environment

Clone the Git Repository

If you don't have Git installed, follow the GitHub's Install Git guide.

Clone the ElixIRCd Git repository and navigate to the project directory:

git clone https://github.com/faelgabriel/elixircd.git
cd elixircd

Install Elixir and Erlang with asdf

If you don't have asdf installed, follow the instructions on the asdf website.

Add the necessary plugins and install the required versions:

# Add the Erlang plugin to asdf
asdf plugin-add erlang
# Add the Elixir plugin to asdf
asdf plugin-add elixir
# Install the versions specified in the .tool-versions file
asdf install

Install Dependencies

To install the project dependencies, run:

mix deps.get

Code Quality Assurance

Ensuring code quality assurance is essential for the stability of the project. You can run all the necessary checks, including compilation warnings, code formatting, linting, security analysis, dependency audits, documentation checks, and static analysis, with a single command:

mix check.all

Running Tests

To run the test suite with code coverage, use:

mix test --cover

Running Server in Interactive Mode

To start ElixIRCd in interactive mode, which is useful for development and debugging, run:

iex -S mix

This command starts an interactive Elixir shell (IEx) with your application running, allowing you to interact with your server in real-time.

Contributing

We welcome contributions to ElixIRCd! If you have an issue or feature request, please open an issue on the issue tracker. Additionally, feel free to pick up any open issues that haven't been assigned yet. We warmly welcome your pull requests.

Please see the contributing guidelines for details on how to contribute to this project.

License

This project is licensed under the AGPL License.