Tip of the day: Log files can use JSON logging. You can also send the JSON data to IRCOps on IRC. The JSON is machine readable and contains lots of details about every log event. |
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[edit]
Requirements[edit]
Requirements:
- UnrealIRCd 6.0.6 or later
- A webserver (e.g. apache or nginx)
- PHP 8 or later
The webpanel can run on the same machine as UnrealIRCd or can be hosted elsewhere.
PHP 8 is relatively new, see PHP 8 Installation instructions for help on installing it.
Installation[edit]
Configuring UnrealIRCd[edit]
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.*; } 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[edit]
This guide makes the following assumptions:
- Your webroot directory is
/var/www/html
and that the panel will be in a sub-directory calledunrealircd-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 callednobody
or something entirely different.
- 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
- 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
- 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
- After the whole setup is done, choose Acounts on the left, click on your username and tick all permissions, Save
Permissions[edit]
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[edit]
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[edit]
We have two authentication plugins:
- SQL-based
- File-based
File based authentication[edit]
This reads and writes to files in the data/
directory. It should work for everyone.
SQL Authentication[edit]
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[edit]
If you want to update to the latest webpanel git version:
cd /var/www/html/webpanel sudo -u www-data 'git pull && composer install'
Developers[edit]
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.