Knowledgebase

Are you tired of managing your IRC network through a command line interface? Do you wish there was a more user-friendly way to keep track of your servers, channels, and users? Look no further than the UnrealIRCd Web Panel!

This web-based tool provides a comprehensive overview of your IRC network, including all channels and users, as well as detailed information about individual servers and users. With the UnrealIRCd Web Panel, you can easily add and remove server bans and spamfilter entries, rehash your entire network, and filter lists of information based on input criteria, all from the convenience of your web browser.

One of the key features of the UnrealIRCd Web Panel is its user-friendly interface. The panel is designed to be easy to navigate, with all the information you need displayed in an organized and easy-to-understand format. This makes it much easier to manage your network, especially if you have multiple servers or a large number of users.

Additionally, the UnrealIRCd Web Panel is a great tool for keeping track of your network's activity. You can view detailed information about the channels and users on your network as well as manage your servers. This allows you to quickly identify and address any issues that may arise.

Overall, the UnrealIRCd Web Panel is a must-have tool for any administrator managing an IRC network. Its user-friendly interface and powerful management capabilities make it easy to keep track of your network and ensure that everything is running smoothly. So why not give it a try and see how it can improve your IRC network management experience?

Example Overview from Desktop

Prerequisites

• UnrealIRCd 6.0.6 or later
• A webserver (e.g. apache2)
• PHP 8 or later

The UnrealIRCd webpanel requires PHP 8. Installing PHP 8 may require special installation instructions:

Ubuntu 22.04 ships with PHP8, so simply run: apt-get install apache2 libapache2-mod-php

Sometimes it happens that multiple versions of PHP are installed. The webpanel will then give you an error page saying you are not using PHP8. This can happen that the CLI version of PHP may be on PHP8 but the Apache module uses PHP7.4. You can fix this by running a2dismod to disable the old PHP version (eg: php7.4) and a2enmod to enable the new PHP version. (eg: php8.2). Restart apache.

Ubuntu 20.04 does not include PHP8 but you can use an external repository for installing PHP8, see: How to install PHP 8 on Ubuntu 20.04

Sometimes it happens that multiple versions of PHP are installed. The webpanel will then give you an error page saying you are not using PHP8. This can happen that the CLI version of PHP may be on PHP8 but the Apache module uses PHP7.4. You can fix this by running a2dismod to disable the old PHP version (eg: php7.4) and a2enmod to enable the new PHP version. (eg: php8.2). Restart apache.

Debian 9/10/11 do not include PHP8 but you can use an external repository, follow the instructions at: How To Install PHP 8 on Debian 11

After PHP8 installation you are likely to have multiple PHP versions on the machine. You have to tell Apache to use PHP8:

• Run a2dismod to disable the old PHP version (eg: php7.4)
• Then run a2enmod to enable the new PHP version. (eg: php8.2)
• Restart apache.

Debian/Ubuntu Linux Specific Commands to Start/Stop/Restart Apache

You can either use service or /etc/init.d/ command as follows on Debian Linux version 7.x or Ubuntu Linux version Ubuntu 14.10 or older:

Restart Apache 2 web server, enter:

/etc/init.d/apache2 restart
OR
sudo /etc/init.d/apache2 restart
OR

sudo service apache2 restart

To stop Apache 2 web server, enter:

/etc/init.d/apache2 stop
OR
sudo /etc/init.d/apache2 stop
OR

sudo service apache2 stop

To start Apache 2 web server, enter:

/etc/init.d/apache2 start
OR
sudo /etc/init.d/apache2 start
OR

sudo service apache2 start

Future Debian 12 (ETA: mid-2023) will include PHP8.1

Installation

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 and add at least one api user:

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

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

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.

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
4. After the whole setup is done, choose Acounts on the left, click on your username and tick all permissions, Save

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:

• SQL-based
• File-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 create a user in MySQL or MariaDB.

Typical commands to do so are:

CREATE DATABASE unrealircdwebpanel;
CREATE USER 'unrealircdwebpanel'@'localhost' IDENTIFIED BY 'enter-some-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 as enter-some-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.