UnrealIRCd webpanel

The UnrealIRCd Administration WebPanel gives you an overview of your IRC network, with detailed information about servers, users and channels. You can easily add and remove server bans, spamfilters and do other administrative tasks, all from the convenience of your web browser. The admin panel uses UnrealIRCd's JSON-RPC feature.

Screenshots

• 
• 
• 

Requirements

Requirements:

• UnrealIRCd 6.0.6 or later
• A webserver (e.g. apache or nginx)
• PHP 8 or later, including php-zip and php-curl (important for plugins) and php-mbstring
• Composer
• Git (cmd-line)

As root:

// For apache
apt install apache2

// For nginx
apt install nginx

// PHP
apt install php php-zip php-curl php-mbstring

// Composer
apt install composer

The webpanel can run on the same machine as UnrealIRCd or can be hosted elsewhere.

PHP 8 was released in 2020 so is reasonably standard nowadays. If unsure, check out PHP 8 Installation instructions for help on installing it.

Installation

Configuring UnrealIRCd

In UnrealIRCd you need to load the required JSON-RPC modules. Simply put this in your unrealircd.conf:

include "rpc.modules.default.conf";

Then, open up a port (Listen block) and add at least one api user (Rpc-user block):

/* HTTPS on port 8600 for the JSON-RPC API */
listen {
        ip *;
        port 8600;
        options { rpc; }
}

/* API user */
rpc-user adminpanel {
        match { ip 127.*; }
        rpc-class full;
        password "password";
}

If you are not running the webpanel on the same machine as UnrealIRCd, then change the ip 127.*; from above to your web servers public IP.

Configuring the webpanel

This guide makes the following assumptions:

• Your webroot directory is /var/www/html and that the panel will be in a sub-directory called unrealircd-webpanel. In some distros or setups you have to install at another location.
• Your webuser is www-data (true for Debian/Ubuntu). Sometimes it is called nobody or something entirely different.

Note: On FreeBSD, the webroot directory is /usr/local/www/apache24/data (for Apache) and /usr/local/www/nginx-dist (for Nginx). The webuser is www. Therefore, to maintain consistency with the instructions below, whenever webroot /var/www/html/ and webuser www-data are mentioned, consider using the aforementioned webroot and webuser. By default, the FreeBSD base system only includes the su command for elevating privileges to root, but you should install doas pkg install security/doas or sudo pkg install security/sudo from the FreeBSD repository for elevating privileges and executing commands. Again, just to keep consistency with the instructions below, we are using sudo.

1. Go to your webserver root and clone the webpanel repository:

   cd /var/www/html
   sudo -u www-data git clone https://github.com/unrealircd/unrealircd-webpanel

   • If that command fails, like it gives 'Permission denied', then try this instead:

     sudo git clone https://github.com/unrealircd/unrealircd-webpanel
     sudo chown www-data:www-data unrealircd-webpanel -R

2. Go into the directory and run composer to install the dependencies (If you don't have composer, then install it first).

   cd unrealircd-webpanel
   sudo -u www-data composer install

3. Now surf to http://localhost/unrealircd-webpanel/ (adjust the URL to your case) and follow the instructions. The setup is split among two steps:
   • The initial setup which chooses an authentication backend and creates a user
   • Then it tells you to login
   • The final setup screen which connects to UnrealIRCd

Permissions

If the installer redirects you back to here, then you have not set the ownership and/or permissions correctly.

The webpanel needs to be able to write its own files (needed for the setup which writes to the configuration file, and also for using and installing plugins).

• On Debian/Ubuntu this user is normally called www-data, so you run:
  

  sudo chown www-data:www-data /var/www/html/unrealircd-webpanel -R

• If you use a different OS then sometimes the user is called nobody.
• If you are on a multi-user server with virtual hosting, and your user is already the "web user" (eg: sitexyz), then maybe you don't need to change anything.

If you prefer more strict permissions

If you are the type that does not like that the directory is writable by the web user, then you could tighten it.

IF you do that, then note that the following functionality will not work anymore:

• Using file auth as a backend (because this writes to the data/ directory), so you need to use the sql_auth backend.
• Updating to a newer version via the panel won't work (This feature does not exist yet)
• Adding and removing plugins via the panel won't work (This feature does not exist yet)

If this is really what you want then:

• During the initial setup we need to write to config/ so that directory must be writable by the web server
• After the initial setup, you could make everything read-only for the web user, like by chowning it to a different user.
• Whenever you upgrade to a newer version, your config/ needs to be writable again when the new panel first loads because there could be configuration changes that need to be written. After the first page load, you can remove the write permissions.

Again, you will loose some functionality, but it is possible.

Authentication

We have two authentication plugins:

• File-based
• SQL-based

File based authentication

This reads and writes to files in the data/ directory. It should work for everyone.

SQL Authentication

To use the SQL Authentication plugin you first need to create a database and a user in MySQL or MariaDB.

Typical commands to do so are:

CREATE DATABASE unrealircdwebpanel;
CREATE USER 'unrealircdwebpanel'@'localhost' IDENTIFIED BY 'your-random-password-here';
GRANT ALL ON unrealircdwebpanel.* TO 'unrealircdwebpanel'@'localhost';

During the setup you will need to enter the SQL username as unrealircdwebpanel, the username as unrealircdwebpanel and password you defined above in your-random-password-here.

If you don't know how to generate secure random passwords, you can use the following command to create one: openssl rand -base64 15 and use it as your-random-password-here.

Upgrading

If you want to update to the latest webpanel git version:

cd /var/www/html/unrealircd-webpanel
sudo -u www-data 'git pull && composer install'

Developers

Developers of the webpanel will naturally use the same procedure as above. However, sometimes you will want to update to a newer version of the unrealircd-rpc-php library. You then need to run:

# For devs only!
composer update
git commit composer.lock

Commiting the composer.lock file updates the dependency for all other users, that way a composer update by end-users will update to exactly the version that composer install just installed.