Skip to main content

​
Quick reference

CommandDescription
serv startStart the server in a background tmux session
serv stopGracefully stop the server
serv restartStop and restart the server
serv consoleAttach to the live server console
serv statusShow online/offline status, version, uptime, memory, and player count
serv backupTake a full manual backup (stops and restarts the server)
serv backup -sSilent backup — no output, useful for scripting
serv restoreInteractive restore menu listing all snapshots, backups, and undo points
serv updateCheck for and apply the latest PaperMC or Vanilla update
serv chkCheck for available updates without applying them
serv chk -sSilent update check — no output if already up to date

​
serv start

Starts the server inside a persistent background tmux session. 
serv start
Behavior:
  1. Checks whether a Java server process is already running. If one is found, it prints a warning and exits.
  2. Checks whether a tmux session named minecraft exists without an attached Java process (a zombie session). If found, the zombie is cleaned up before proceeding.
  3. Launches start.sh inside a new detached tmux session.
  4. Waits 3 seconds, then checks whether the process is alive.
Example output (success): 
Minecraft server started in background
Use 'serv console' to view the server console
Example output (already running): 
A Minecraft server is already running.
Use 'serv console' to attach or 'serv restart' to restart.
Example output (failed to start): 
Failed to start server! Check permissions:
1. Run: sudo chown -R <user>:<user> /usr/local/games/minecraft_server/java
2. Verify: ls -l /usr/local/games/minecraft_server/java/start.sh
3. Check error log: cat /tmp/minecraft_error.log

​
serv stop

Sends a graceful stop command to the server console and waits up to 30 seconds for the process to exit cleanly. 
serv stop
Behavior:
  1. Creates a stop_signal file in the server directory. This tells start.sh not to restart the server after it exits.
  2. Sends the stop command to the tmux session.
  3. Polls once per second for up to 30 seconds waiting for the Java process to exit.
  4. If the process is still alive after 30 seconds, force-kills it with pkill and destroys the tmux session.
Example output (graceful stop): 
Stopping Minecraft server...
Minecraft server stopped successfully
Example output (force kill): 
Stopping Minecraft server...
Server didn't stop gracefully. Force killing...

​
serv restart

Stops the server if running and immediately relaunches it in a new tmux session. 
serv restart
Behavior:
  1. Sends stop to the server console if a process is detected, waits 10 seconds, then kills the tmux session.
  2. Creates a new detached tmux session running start.sh.
Unlike serv stop, restart does not create a stop_signal file — the startup loop inside start.sh is free to restart on crash as normal.

​
serv console

Attaches your terminal to the live tmux session so you can read logs and type commands directly into the server console. 
serv console
To detach without stopping the server: press Ctrl+B, then D. The session name is minecraft and uses the socket at /tmp/minecraft-tmux. You can also attach manually: 
tmux -S /tmp/minecraft-tmux attach -t minecraft

​
serv status

Prints a summary of the server’s current state. 
serv status
When online, displays:
  • Online/offline status
  • Server version (Paper MC_VERSION-BUILD or Vanilla MC_VERSION, detected from the jar)
  • Process uptime
  • Memory usage (% of system RAM)
  • Player count (requires mcstatus — see below)
Example output: 
PopLock is Online
Ver: Paper 1.21.4-225
Running for: 02:14:33
Memory usage: 18.3%
Players: 3/20
Player count dependency: Player count requires the mcstatus Python package. If it is not installed: 
Player count unavailable - install mcstatus: 'pip install mcstatus'
Install it with: 
pip install mcstatus
When offline: 
PopLock is OFFLINE!!!

​
serv backup

Takes a full backup of the entire server directory as a .tar.gz archive. 
serv backup          # Interactive — prints progress
serv backup -s       # Silent — no output (suitable for cron or scripting)
Behavior:
  1. If the server is running, stops it first (using serv stop).
  2. Creates backups/minecraft_backup_YYYYMMDD_HHMMSS.tar.gz containing the full server directory, excluding backups/, cache, and build artifacts.
  3. If the server was running before the backup, restarts it automatically.
  4. If the server was offline when the backup started, it is left offline after the backup completes.
Example output: 
Server is running. Stopping for backup...
Stopping Minecraft server...
Minecraft server stopped successfully
Creating backup archive...
Backup successfully saved to: /usr/local/games/minecraft_server/java/backups/minecraft_backup_20250403_230001.tar.gz
Restarting server...
Minecraft server started in background
Use 'serv console' to view the server console

​
serv restore

Opens an interactive numbered menu listing every available archive in backups/. Selecting an entry will restore the server to that point in time. 
serv restore
Archive types shown in the menu:
TypeFilename patternCreated byContains
Daily Snapshotsnapshot_YYYYMMDD_HHMMSS.tar.gzsnapshot.sh (cron)World directories + whitelist.json + server.properties
Full Backupminecraft_backup_YYYYMMDD_HHMMSS.tar.gzserv backupEntire server directory
Restore Undorestore_undo.tar.gzserv restoreWhatever was replaced in the last restore
Restore procedure:
  1. Stop the server if it is running.
  2. Create an undo backup (restore_undo.tar.gz) of whatever files are about to be replaced.
  3. Wipe the target directories to ensure no stale chunk or player files survive.
  4. Extract the selected archive into the server directory.
  5. Remove any stale session.lock files from restored world directories.
  6. Restart the server if it was running before the restore.
To undo a restore: run serv restore again and select Restore Undo. Example menu output: 
Available Backups:
  [0] Daily Snapshot: 2025-04-03 23:00:01 (1.2G)
  [1] Daily Snapshot: 2025-04-02 23:00:03 (1.1G)
  [2] Full Backup: 20250401_120000 (2.4G)
  [3] Restore Undo (980M)

Select a backup to restore (or press Enter to cancel):

​
serv update

Checks the PaperMC or Mojang API for a newer version of the server jar and, after confirmation, downloads and installs it. 
serv update
Behavior:
  1. Detects whether the current jar is PaperMC or Vanilla by inspecting server.jar.
  2. Queries the appropriate API for the latest available version.
  3. Displays the current version and the latest available version.
  4. If already up to date, exits immediately.
  5. If an update is available, shows a summary of the planned actions and prompts for confirmation ([y/N]).
  6. Stops the server if running.
  7. Backs up the current server.jar to backups/jars/.
  8. Downloads the new jar, replacing server.jar.
  9. If the download fails, restores the backed-up jar automatically.
  10. Restarts the server.
Example output (PaperMC): 
Checking latest Paper release...
Current version : 1.21.4-220
Latest version  : 1.21.4-225

This will:
  1. Stop the server (if running)
  2. Back up paper.jar  →  /usr/local/games/minecraft_server/java/backups/jars/paper_1.21.4-220.jar
  3. Download paper-1.21.4-225.jar
  4. Restart the server

Proceed with update? [y/N]

​
serv chk

Checks for an available update and prints the result without making any changes. Useful for monitoring or scripting. 
serv chk         # Print update status
serv chk -s      # Silent — print nothing if already up to date
Example output (update available): 
Checking for updates...
Update available: Paper 1.21.4-225  (current: 1.21.4-220)
Run 'serv update' to upgrade.
Example output (up to date): 
Checking for updates...
Server is up to date — Paper 1.21.4-225
With -s, no output is produced when the server is up to date, making it suitable for use in cron jobs where you only want output when action is needed.