maresh/hll_rcon_frontend repository overview

⁠Hell Let Loose (HLL) advanced RCON

An extended RCON tool for Hell Let loose, meant to replace and go WAY beyond the official tool.

It is essentially a website that you can self host (or if you ask around the discord, some people can probably host it for you)

⁠Included features:

• Live view on players + all expected actions: message, punish, kick, temporary ban (choose the time), permanent ban. Search for players, and sort by play time, punishments, name etc. etc.
• Live updating game view (can see players per team, squad, roles, levels, score, etc.) and perform actions on individuals, squads, the entire team or server.
• User account and audit logs, each moderator has it's own account so you know who did what on whom and when, all the rcon actions can get forwarded to your discord (change of settings included)
• Group actions - Easily apply the same action on multiple players with one click (say you want to switch or kick a whole squad)
• Live logs + filtering by type (kill, chat, vote, etc..), filtering by players
• Discord webhooks support, so that the chat, TK and kills can be forward to your discord server
• Trigger word that when written in the ingame chat will create an alert (tag a person(s) or a role(s) on discord) such as: !admin or just any word you want (insults if you want to chase those)
• Flag player with any emoji / icons you want + comment attached
• Auto loading of player's country from steam and displayed in live view
• History of players and player profile: All game sessions of players are recorded, all the names they used in the past, punishments they have received and by which admin, etc
• Apply actions on players even if they are not online anymore, from the player history you can flag, watch, perma ban, temp ban, lift all bans and add to VIP.
• Permanent logs, a search tool to look at the entire history of the game logs of your server, export logs as CSV
• Multi server support, you can host the rcon for multiple servers and they will share the same player database, you can apply temp and perma bans to all server with only one action, synch VIP, settings, broadcast messages etc...
• Automated broadcast loops
• Automated settings based on the player count of you server
• Shared text for punishments and various messages that you can preset so that you never have to type the reason for the kick anymore. It also remember new text you type if you want it (to autocomplete it the next time)
• Search through bans by name, reason or steam ID (for quick unbanning)
• Backup of your bans so that if you ever change your game server or add one the bans will be re-applied on the fly if the banned dude tries to join your new server
• Recording of you map history, you see which map were played and how long they lasted
• Ban (blacklist) people even if they have never set foot on your server yet
• Basic scoreboard showing you total kills / death / TK / death by TK for the last N minutes
• Backup and restore/import of VIPs
• All the basic settings, map rotation management, sliders for idle kick time, max ping etc..
• For power users and coders: You can add anything you want in the cron server or in the supervisor service so it's easy to code you own plugin (I myself have a votemap plugin and a bot that verifies players), an HTTP API to use all the features above and a CLI for a subset of those
• Put player on a watch list and be notified when they enter your server
• Live stats, per game or per session with a friendly public version, as well as historical games (bookmarkable)

• It's running 24/7 so you have A LOT features that you couldn't get with a simple desktop app (recording and forwarding of logs, discord alerts, player profile etc..)
• It's more secure / convenient, a website is centralized, meaning that all actions have to go through it, you don't need to give the real RCON password to you moderators, all activity is recorded in one place, you can share configuration with other, etc...
• It does not require any installation on the client side, you just need a browser

It's a 2 steps installation (5 if you include the pre-requisites), many not so technical people managed so you probably can too. The community grew quite big so if you still don't understand what to do after reading this just go and ask on discord :)

There's also a Wiki made by the community (Thanks [2.Fjg]bn.hall): https://github.com/MarechJ/hll_rcon_tool/wiki⁠

Join us on discord if you use it, for feedback, troubleshooting and informations about updates: https://discord.gg/hZx6gn3⁠

Here's a sample:

⁠How to install the App

⁠Pre-requisites:

• It's recommended that you use Linux, you should be able to set it up anywhere that you can get Docker to run, but don't expect much or any support if you don't install on Linux
• Having some very basic shell (command prompt) skills. Feel free to ask for help on the Discord! (please consult Google, Stackoverflow, etc.)
• Having a dedicated server - This app is meant to run 24/7 - (If you don't have that, you can just run a cheap Virtual Private Server)
• The below need to be installed on the server where the rcon will run:
  • (Optional but recommanded) git: https://git-scm.com/downloads⁠ (if you don't use git you need to download the releases)
  • Docker Engine (Community) installed: https://docs.docker.com/engine/install/⁠
    • You can also use Docker Desktop but you may have issues with nested virtualization depending on your computer/server/VPS
  • Docker Compose installed: https://docs.docker.com/compose/install/⁠
    • You should be able to use either docker-compose or docker compose depending on what you have installed, just adjust the commands below accordingly, but docker-compose is deprecated now, this README and release announcements will show docker compose examples, if you haven't upgraded it is up to you to modify the commands and know what you are doing.

⁠Install steps

⁠1. Get the sources

git clone https://github.com/MarechJ/hll_rcon_tool.git
cd hll_rcon_tool

If you don't have git you can also download the latest zip release⁠, however it's much less practical for updating.

⁠Multiple Game Servers

You can use one CRCON for multiple game servers, or have separate CRCONs for one (or more) game server, but they need to be set up differently, see below.

For instance if you run multiple game servers (for instance US west, US east and/or an event server) it makes more sense to do one CRCON install rather than separate CRCONs for each game server.

⁠One CRCON Multiple Game Servers

When using a single CRCON installation for multiple game servers all of your admin accounts will have equal access to all of them, and all of your data will be stored in a single database.

This will make it difficult to separate your servers in the future (for instance if you are trying to use one CRCON for multiple communities by sharing a VPS) without starting from scratch and losing data.

Note: Setting up more than 3 game servers in a single installation will require you to edit your .env and docker-compose.yml and add new sections for each server past the third.

⁠Multiple CRCON Installations

If you do not want to mix admin accounts and database data you can clone it multiple times in different directories (see below) and then set each of them up (and then set up as many game servers per CRCON that you choose). This makes more sense when you're sharing the server you host CRCON on with other communities.

Note: When you run two or more CRCONs on the same machine you will have redis/postgres port conflicts and will need to resolve these in your .env and compose files.

git clone https://github.com/MarechJ/hll_rcon_tool.git hll_rcon_tool_server_number_2
cd hll_rcon_tool_server_number_2

From here all the commands assume that you are at the root of the git repository you just cloned!

⁠2. Set your server informations. Edit the .env file and fill in the blanks (for all your servers) like so:

Make a copy of default.env and name it .env (it must be named exactly .env, this is how Docker identifies it)

cp default.env .env

Note: if you don't see the .env file you need to activate the show hidden files option on Windows. On Linux don't forget the -a: ls -a

Note: If you make any changes to your .env you will have to recreate (docker compose up -d --remove-orphans your containers before it will take effect), (if you docker compose restart it will not take effect)

Note: The values in .env are used by docker when it starts the container and they're referenced in your compose files, you should only edit (unless you really know what you are doing) values in .env and not the compose files.

The comments in .env should be self explanatory, but these are the minimum you need to set the following environment variables. Do not add/delete/comment out/etc. fields unless you know what you are doing.

Global settings (affects all the servers inside of your CRCON installation)

HLL_DB_PASSWORD
RCONWEB_API_SECRET

Per server settings

HLL_HOST
HLL_PORT
HLL_PASSWORD

You must configure RCONWEB_SERVER_URL for each server you're setting up to match the URL you're hosting CRCON on, or you will be unable to access the admin site due to CSRF errors

Because of how Django handles CSRF protection, you won't be able to use the admin site until you've configured your server URL. This used to be set in the environment as RCONWEB_SERVER_URL but is now set through the GUI (or command line) as the server_url value in your CRCON settings (Settings > CRCON Settings in the GUI drop down menu) or the value of RconServerSettingsUserConfig if you set it via the CLI.

This must be set to whatever URL you're accessing CRCON from (look at your browser window), such as http://localhost:8010, or whatever your domain is.

For example if you are hosting using HTTPS on example.com you would set it to https://example.com For example if you are hosting using HTTP on 127.0.0.1 on port 8010 you would set it to http://127.0.0.1:8010

Note: when you're configuring multiple game servers inside one CRCON installation you need to make sure your RCONWEB_PORTs are unique and also not otherwise used on the machine your're hosting on, the defaults should work.

⁠3. Additional configuration

Many things are configurable, most of it is done through the GUI (or command line) to settings that are saved in the database. config/supervisord.conf controls how the services are started/restarted, etc.

Note for power users:

You can set the environment variables anyway that Docker accepts (setting them in the shell, specifying them on the command line, etc.) but it is much easier to just use the .env file and manage it that way. You can also manually edit the compose files, but it may cause you issues when upgrading and isn't recommended unless you know what you're doing.

More details⁠

⁠4. RUN it!

⁠Linux

docker compose up -d

⁠Windows

docker volume create redis_data
docker volume create postgres_data
docker compose -f docker-compose.yml -f docker-compose.windows.yml up -d

⁠Raspberry-Pi or any ARM32v7

docker compose -f docker-compose.yml -f docker-compose.arm32v7.yml up -d --build

The web application will be available on <your server ip>:$RCONWEB_PORT (you can use http://localhost:8010⁠ if you test from the machine where it's installed)

Note: If you are running it on Windows prior to 10 Docker runs in a virtual machine, so you have to find the IP⁠ of that VM.

⁠5. CHANGE YOUR ADMIN PASSWORD

Using your browser go to <your server ip>:$RCONWEB_PORT/admin (8010 is the default port) and login with user: admin password: admin FIRST THING YOU MUST DO IS CHANGE YOUR PASSWORD (see the red box in the top right):
After that you can start adding your users with this:
Make sure you specify their steam ID it will be used in upcoming features:
Once the user is created you'll end up on that page:
I recommend NOT CHANGING ANYTHING except for a select few of your most trusted staff members you can tick the Superuser status. Please note that users won't be able to change their password by themselves unless you tick the staff status so that they can access this admin page, however i DO NOT RECOMMEND doing as I won't be maintaining special permissions on admin models on the future (just manage password for them). To change the password of one of your user, in the users list click on him, then there:

Please note that the onlineadmins variable in the (auto) broadcast is broken due to accounts. It will be fixed and improved later.

You're done, ENJOY!

If you feel generous you can donate, the money will be use to reward contributing developer or content creator to create video tutorial, demos, documentation, etc.

⁠To update to the latest version:

Please join the discord and follow announcements, sometimes the update instructions vary from standard. If you are updating from an older version you should review the announcements in order and make any non-standard changes in order.

⁠Normal (most) updates

⁠Linux

Pull the changes from github:

git fetch --tags

Check out a tagged release (substitute the release you want):

git checkout v7.0.2

Get the newest docker images and restart your containers:

docker compose pull
docker compose up -d --remove-orphans

⁠Windows

Substitute the release you want in git checkout:

git fetch --tags
git checkout v7.0.2
docker compose pull && docker compose -f docker-compose.yml -f docker-compose.windows.yml up -d --remove-orphans

⁠Raspberry-Pi or any ARM32v7

Substitute the release you want in git checkout:

git fetch --tags
git checkout v7.0.2
docker compose -f docker-compose.yml -f docker-compose.arm32v7.yml up --build -d --remove-orphans

Or download the latest zip release⁠

Note: If you get any sort of git error messages when you pull you have to resolve these before you can upgrade. Unless you have been changing files this should never happen.

Note: that it's important you get the sources every time, or at least the docker-compose files, as new dependancies might be introduced

⁠To downgrade (in case of issue) to a previous version:

Check the available versions numbers on docker hub (or github releases): https://hub.docker.com/r/maresh/hll_rcon/tags⁠ https://github.com/MarechJ/hll_rcon_tool/releases⁠

Edit your .env file and change TAGGED_VERSION from latest to a specific tagged release you want the images for (it must match the release tag on Docker hub):

TAGGED_VERSION=9.1.1

Reverse any changes you made (from the previous upgrades, if any) you had to do as part of the upgrade process, consult the release notes or the announcement on the Discord.

⁠Note for multi servers beyond 3 servers

You can copy the the last server section in the docker-compose.yml file and paste it, while replacing all the _3 by _4, also add the required variable in your .env (copy a whole section and replace the _3 to _4 suffix) Also note that you must add this extra keys in your docker-compose.yml after HLL_REDIS_URL. And mind the DB number that should change with each server

      ....
      HLL_REDIS_URL: redis://redis:6379/1
      HLL_REDIS_HOST: redis
      HLL_REDIS_PORT: 6379
      HLL_REDIS_DB: 1
      ....

⁠How to use

Demo video coming soon

There's a public endpoint available to anybody without password on http://:/api/scoreboard

See User Guide⁠ for more information on how to use certain features of the app.

⁠Features to come

More or less in order of priorities

• Individual moderators accounts
• Audit trail
• Players sessions history (with records of actions applied to players)
• Deferred bans (from a blacklist)
• Custom preset punish/kick/ban messages
• Performance improvements for the player list view
• Auto randomisation of map rotation (scheduling of the endpoint: /api/do_randomize_map_rotation)
• Full log history (stored permanently)
• Action hooks on chat messages and players connect / disconnect
• Integration with Discord
• Leaderboard and all time stats

⁠Building your own Docker images

Docker images are hosted on Docker Hub⁠, but if you're running a fork, have made local modifications or the release you want isn't available for some reason, you can build your images locally.

⁠Set environment variables

If you don't already have a .env file created use default.env to make a template and you'll be able to build the images without setting the :

cp default.env .env

If you don't have a .env you wou must set the following environment variables to something, or the build will fail with an error that looks like invalid tag ":": invalid reference format (just use a copy of default.env):

BACKEND_DOCKER_REPOSITORY=
FRONTEND_DOCKER_REPOSITORY=
TAGGED_VERSION=

⁠Build the images

docker compose -f docker-compose.yml -f docker-compose.dev.yml build

⁠Run it!

Once the images are built (which can take a considerable amount of time depending on your hardware specs), and once it's configured properly (see the installation part of this README), then simply use docker compose to create the containers:

docker compose up -d --remove-orphans

If you don't want to use docker compose (which you really should, it's just easier) then you would have to properly set/create/run the Docker containers yourself, consult Docker's documentation please.

⁠Development Environment

Pull requests are always welcome! It can be a bit tricky setting up a local environment and it is hard to contribute without having a HLL game server to connect to (and it's impossible to host one yourself, they won't release the server files).

⁠Overview / Project Structure

The project is split up into several main components (the backend, frontend, services run by supervisord and redis and postgres that is shared across each image), and is intended to be run using Docker and docker compose. Each CRCON install can manage multiple game servers, and each game server (server 1, server 2, etc.) has its own set of images (backend_1, frontend_1, supervisor_1, etc.)

The backend is split into two major components, the rcon package and the rconweb package which is a Django web (WSGI) application.

rcon handles the implementation of the HLL RCON protocol⁠ and implements most of the core behavior/features that CRCON has.

rconweb handles all of the web portions (URL routing, authentication, sessions, etc.) once a HTTP request has been received by nginx in the frontend.

The supervisor container manages starting and restarting all of the optional/non optional (if you want a fully functioning CRCON) services, all of which are implemented in the rcon package or are a standalone program like rq or cron.

The frontend is a combination of nginx (used as a reverse proxy) and gunicorn web servers that handles all of the HTTP requests and serves all of the responses. The flow is incoming request -> nginx -> gunicorn -> nginx -> outgoing response. nginx handles serving all of the static content like HTML/css/images, and Django processes all of the API calls that return dynamic content.

⁠rcon package

The rcon package relies on several core classes.

rcon.connection.HLLConnection handles connecting to the game server (IP, port and RCON password), xor encoding/decoding⁠ content and sending/receiving raw bytes over TCP sockets.

rcon.commands.ServerCtl is the parent class of Rcon and handles managing a pool of HllConnection instances, validating/converting low level stuff (like stripping tabs from user generated content for HLL tab delimited lists), automatically retrying commands that fail, and sending the raw commands (such as get profanity) to the game server.

rcon.commands.ServerCtl can be used without any database or redis connection, but is of limited use and not published separately.

rcon.rcon.Rcon inherits from ServerCtl and handles parsing/structuring the raw text received from the game server into meaningful data, interacting with the database, caching command results, etc.

CRCON is not an async (ASGI) web app (async) or multi core (multiprocessing), but it does support running multiple slow (to the game server) requests simultaneously through thread pools⁠.

The rcon package also contains the implementation of most of CRCNs features, if you're not sure how something works, identify which API endpoint is doing the action, look in the URL routing in rconweb and you can see what parts of rcon are imported.

⁠rconweb

The rconweb package is a Django web app that actually exposes all of the URL endpoints and imports from rcon as needed when interacting with the game server versus the local CRCON backend (redis, postgres, etc.).

Some endpoints are explicitly exposed, but some (Rcon methods) are implicitly exposed (rconweb.api.views.expose_api_endpoint).

⁠supervisord

Due to the fact that Python is notoriously single threaded⁠, some core parts of CRCON have been broken out into services that run in their own Python interpreter so they can take advantage of multiple cores/threads on the system. This also enables faster network access since each individual network request (to the game server, steam API, discord, etc.) blocks until completion.

Other portions are optional services and have been split so users have more control over what runs.

The services are managed by supervisord⁠ and run inside of their own (supervisor) container.

⁠redis

Redis⁠ is used for two reasons in CRCON, caching and interprocess communication.

Every round trip to the game server can be significantly slow (in computing terms) and induces some amount of overhead on both CRCON and the game server.

Some commands are cached even if they have a very low cache time (such as retrieving logs from the game server) to avoid constantly reprocessing info on very short time frames and others are on a longer cache time because they rarely if ever change (such as the list of available maps from the game server).

This also condenses requests that occur almost simultaneously to be reduced to a single request that makes it to the game server, the remaining requests will be resolved from the cache (unless they happened before the first request has completed and cached its results).

Many portions of CRCON run in their own separate Python interpreter instances with their own section of memory, but by caching results with redis, we can communicate back and forth between interpre