trueconf-eraser

A CLI utility that finds and stops stale conferences on TrueConf Server

English / Русский

Caution

The tool is intended to be run by an experienced administrator from a trusted machine, do not run it on servers with other users or processes.

It scans all active conferences and terminates the ones that match the configured criteria:

• the conference has been running longer than allowed;
• the number of registered users and/or guests does not exceed the configured limits.

📋 How it works

1. Fetches all active conferences (state=running).
2. Determines the session start time from /sessions; if it is unavailable, falls back to the conference created_at (or start_time).
3. For every conference, checks the elapsed time and the participants.
4. Logs what is being stopped and why. With --dry-run nothing is actually stopped.

💻 Requirements

• Operating system: Linux, macOS or Windows.
• TrueConf Server with the API v4.
• An OAuth 2.0 application with the required permissions (see below).
• HTTPS access to the server's /api/v4.

⚙️ Setting up TrueConf Server

Before the first run, create an OAuth 2.0 application on the server and grant it the following permissions:

• conferences:read
• conferences:write
• conferences.participants:read
• conferences.sessions:read

See the TrueConf Server API documentation for details.

📦 Installation

With pip:

pip install trueconf-eraser

or with uv:

uv tool install trueconf-eraser

🛠 Usage

The tool ships two equivalent commands that do exactly the same thing:

• tc-erase — the primary command;
• tc-clean — a short alias.

Parameters

Parameter	Short	Description	Required
--host	-h	TrueConf Server host, e.g. host.example.com (https:// is added automatically) or a full HTTPS URL	yes
--client-id	-id	OAuth 2.0 application ID	yes
--client-secret	-s	OAuth 2.0 application secret	yes
--max-users	-u	Max registered server users in a conference	yes
--max-guests	-g	Max guest participants in a conference	yes
--max-session-duration	-d	Max session duration in seconds	yes
--dry-run		Simulate the run without stopping anything	no
--verbose		Verbose output with debug information	no
--no-verify-ssl		Disable TLS certificate verification	no
--lang	-l	Output language: en or ru (default: en)	no

Certificate verification

TLS certificate verification is enabled by default (the bundled CA store is used).

• Public certificate (e.g. Let's Encrypt) — works out of the box, no extra flags needed.
• Self-signed certificate — not present in the default trust store, so verification fails. To use one, pass --no-verify-ssl; note that this disables TLS certificate verification entirely and exposes the connection to MITM attacks, so use it only on trusted networks.

Stop criteria

A conference is stopped when BOTH conditions are met:

1. Its duration exceeds --max-session-duration.
2. One of the participant conditions holds:
   • only registered server users and their count is ≤ --max-users;
   • only guests and their count is ≤ --max-guests;
   • both groups: registered users ≤ --max-users AND guests ≤ --max-guests.

Examples

Dry run (recommended before the real run) — 1 or fewer registered users, 15 or fewer guests, sessions older than one hour:

# Dry run: shows what would be stopped, but does not stop anything
tc-erase --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15 --dry-run

Stop conferences with the same criteria:

# Real run: actually stops the conferences that match the criteria
tc-erase --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15

Short flags:

# The same command using short flags (-h, -id, -s, -d, -u, -g)
tc-erase -h host.example.com -id YOUR_CLIENT_ID -s YOUR_CLIENT_SECRET \
  -d 3600 -u 1 -g 15

Output in Russian:

# Force the Russian output with --lang ru
tc-erase --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15 --lang ru

An unsupported language falls back to English:

# Unsupported language code: the output automatically falls back to English
tc-erase --lang fr --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15

🌍 Localization

Supported languages: en (default) and ru. If an unsupported language code is passed to --lang, the output falls back to English.

To add a new language:

1. Create app/locales/<code>.yml (see en.yml and ru.yml for the structure).
2. Add the code to SUPPORTED_LANGS in app/localization.py.

🩺 Troubleshooting

Problem	Solution
Authentication error	Check --client-id and --client-secret; make sure the application has the required permissions
TLS/SSL certificate error	Only for self-signed certificates: add --no-verify-ssl
No session times available	The tool automatically falls back to the conference created_at/start_time
“No active conferences.”	Nothing to clean up right now — that is fine