PteroCrashguard
When a server dies, know why in seconds, with the logs already uploaded.
Requirements
| Panel | Pterodactyl 1.x (tested on 1.15) |
| Wings | Crash detection on (the default) |
| OS | Ubuntu or Debian |
| Web server | nginx or Caddy (Apache: manual setup) |
| Access | root |
| License | A Lattice license key with Ptero Crashguard |
Node.js is installed for you if it is missing.
Install
unzip ptero-crashguard-*.zip
cd ptero-crashguard-*/
sudo bash install.sh --license LAT-XXXXX-XXXXX-XXXXX-XXXXX --api-key ptlc_XXXXXXXX
Reload the panel. You will see a shield in the top bar.
| Option | Use |
|---|---|
--license KEY |
Your Lattice license key |
--api-key KEY |
Host API key, see below. Optional |
--panel PATH |
Panel folder if not /var/www/pterodactyl |
--panel-url URL |
Panel URL if it cannot be read from .env |
--port PORT |
Local port for the service (default 47813) |
--skip-proxy |
Do not touch the web server config |
API keys
Crashguard watches servers all the time, so the service needs a client API key to reach them.
| Key | Who sets it | Covers |
|---|---|---|
| Host key | The panel owner, with --api-key or ptero-crashguard apikey set |
Every server. Only root admins can watch these |
| Personal key | Any user, in the shield > API key tab | The servers that user can reach |
Create a key under Account > API Credentials. Leave the allowed IPs empty. For the host key, use a root admin account. A personal key must belong to the user who saves it.
Share console log needs no key. It uses the viewer's own login.
Command
ptero-crashguard is installed with the addon. Run it as root.
| Command | Does |
|---|---|
ptero-crashguard status |
Version, service, license, host key, watched servers and mclo.gs |
ptero-crashguard license set KEY |
Set your license key and restart |
ptero-crashguard license refresh |
Check your license with Lattice now |
ptero-crashguard apikey set KEY |
Set the host API key and restart |
ptero-crashguard apikey clear |
Remove the host API key and restart |
ptero-crashguard restart |
Restart the service |
ptero-crashguard logs |
Recent logs (logs follow to follow) |
ptero-crashguard patch |
Re-apply the panel patch after a panel update |
Update
Unzip the new version and run its installer. Settings, keys, watches and crashes are kept.
unzip ptero-crashguard-LATEST.zip
cd ptero-crashguard-LATEST/
sudo bash install.sh
Uninstall
| Command | Removes |
|---|---|
sudo bash uninstall.sh --keep-data |
Everything except your crashes and config |
sudo bash uninstall.sh --purge |
Everything |
Using it
- Shield > API key: save a key, unless you are a root admin and the host key is set.
- Shield > Destinations: add a Discord webhook or another webhook. Press Test. Optional.
- Shield > Watching: pick the servers to watch and where to send crashes.
- Shield > Crashes: every crash with its cause, the full log and the mclo.gs link.
- On a server's page, Shield > Share console log uploads the current console and checks it.
| Found in the log | Example |
|---|---|
| Out of memory | Killed by the system, Java heap, Node.js heap |
| Wrong Java version | "Needs Java 21, the server runs Java 17" |
| Startup problems | EULA not accepted, port in use, jar missing, bad Java flags |
| Plugins and mods | Missing dependency plugins, plugin failed to enable, mods that do not fit |
| Server froze | Watchdog stopped the server |
| Files | Disk full, damaged world, permission denied |
| Other runtimes | Missing Node.js or Python modules, native crashes |
mclo.gs adds its own Minecraft log analysis on top.
Other webhooks get a JSON POST with event, title, message, server, fields, logUrl and at.
Privacy
Crash logs and shared logs are uploaded to mclo.gs, a public log host.
mclo.gs removes IP addresses, but anyone with the link can read the log.
To keep logs on your panel only, set "mclogs": false in the config and run ptero-crashguard restart.
The console of watched servers streams to the panel machine, so the last lines before a crash are saved. Crashes are kept for 90 days, 50 per server.
Settings
File: /etc/ptero-crashguard/config.json. Run ptero-crashguard restart after changes.
| Key | Meaning |
|---|---|
licenseKey |
Your Lattice license key |
apiKey |
Host API key (optional) |
mclogs |
false turns uploads to mclo.gs off (default on) |
panelUrl |
Public panel URL |
panelUpstream |
How the service reaches the panel locally |
port |
Local service port |
logLevel |
info or debug |
Troubleshooting
| Problem | Fix |
|---|---|
| No shield | Hard refresh, then run ptero-crashguard status |
| "Ptero Crashguard is not active" | Run ptero-crashguard license. Set the key with ptero-crashguard license set KEY |
| Servers show 0 connected | The panel machine must reach your nodes on their Wings port |
| A crash was not recorded | Crash detection must be on for the server in Wings |
| "this API key belongs to another account" | Create the key while logged in as yourself |
| Shield gone after a panel update | Run ptero-crashguard patch |
| Anything else | ptero-crashguard logs |
Support
Open a ticket on Lattice: https://license.atlantisservices.net/support