A Minecraft Paper server as a systemd service

The short command on the getting started page is java -Xms4G -Xmx4G -jar paper.jar --nogui. On this guest that process exited 1 in 0.01 seconds. The JVM said mmap failed to map 4294967296 bytes, error='Not enough space' (errno=12). MemTotal was 4,009,864 kB and SwapTotal was 0. The same jar, with -Xms2G -Xmx2G, under a systemd unit, logged Done (16.326s)! For help, type "help" and listened on *:25565.

The guest was Ubuntu 24.04.5 LTS, kernel 6.8.0-147-generic, glibc 2.39, qemu -m 4096 -smp 2. Java came from the Corretto install on that page: the full java-25-amazon-corretto-jdk package, plus libxi6, libxtst6, and libxrender1. The page's Ubuntu steps are the ones that ran. dpkg then recorded java-25-amazon-corretto-jdk at 1:25.0.5.0.10-1.

sudo apt-get update
sudo apt-get install -y ca-certificates \
  apt-transport-https gnupg wget
wget -O - \
  https://apt.corretto.aws/corretto.key \
  | sudo gpg --dearmor \
  -o /usr/share/keyrings/corretto-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/\
corretto-keyring.gpg] https://apt.corretto.aws \
stable main" | sudo tee \
  /etc/apt/sources.list.d/corretto.list
sudo apt-get update
sudo apt-get install -y \
  java-25-amazon-corretto-jdk \
  libxi6 libxtst6 libxrender1
java -version

The jar was Paper 26.3 build 237, 55,268,778 bytes. The sha256 is 57d8774b e83dbe2b e6a814e9 45f26a6b 82339af9 b1c82b76 8bbfdf4c 23fda56e. The build record that serves that file is the v3 builds endpoint for version 26.3, build 237. Its downloads object names paper-26.3-237.jar, that size, and that sha256. The v2 download URL now answers 410.

sudo useradd -r -m -d /opt/minecraft \
  -s /usr/sbin/nologin minecraft
sudo -u minecraft cp paper.jar /opt/minecraft/
cd /opt/minecraft
sha256sum paper.jar

sha256sum has to print that same digest, with the spaces removed. The first launch writes eula.txt with eula=false and stops. The file links the Minecraft EULA. Setting eula=true is the edit that let the next start continue. server.properties was already on disk from that first launch.

Which Java does Paper 26.3 ask for?

The getting started table says Paper 26.1 and later wants Java 25. Ubuntu 24.04.5 had no java binary. The Corretto package installed /usr/lib/jvm/java-25-amazon-corretto/bin/java and pointed /usr/bin/java at it. dpkg recorded the package as java-25-amazon-corretto-jdk version 1:25.0.5.0.10-1, Installed-Size 399,511 KiB. du -B1 -s on that JVM tree was 410,374,144 bytes.

java -version printed openjdk version "25.0.5", runtime Corretto-25.0.5.0.10, and a 64-bit Server VM, build 25.0.5+10-LTS. The first successful log line from the jar agreed: Running Java 25 (OpenJDK 64-Bit Server VM 25.0.5+10-LTS; Amazon.com Inc. Corretto-25.0.5.0.10) on this kernel. The next line was Loading Paper 26.3-237-main@7e88a0d for Minecraft 26.3. Plugin init reported Initialized 0 plugins.

The account is a system user with no login shell. id printed uid=999(minecraft). Home and the server directory are both /opt/minecraft. The jar landed there as paper.jar, and sha256sum matched the checksum from the download API. A shell session has nothing to attach to for this user. The unit starts the JVM as uid 999 anyway.

What happens to a 4G heap on this guest?

qemu -m 4096 left MemTotal at 4,009,864 kB. A heap of -Xmx4G asks the process to commit 4,294,967,296 bytes, which is 4,194,304 kB, 184,440 kB past MemTotal. SwapTotal was 0. The map failed before Paper printed a version line. /usr/bin/time -v recorded a maximum resident set of 22,272 kB, a wall time of 0.01 seconds, and exit status 1.

The stderr line was os::commit_memory(0x0000000700000000, 4294967296, 0) failed; error='Not enough space' (errno=12). The stdout lines were There is insufficient memory for the Java Runtime Environment to continue and Native memory allocation (mmap) failed to map 4294967296 bytes.

I then started the same jar from the shell with -Xms2G -Xmx2G. That run exited 0 in 12.14 seconds. Its maximum resident set was 1,881,816 kB. It downloaded mojang_26.3.jar, applied patches, and stopped on the EULA:

Failed to load eula.txt
You need to agree to the EULA
in order to run the server.
Go to eula.txt for more info.

eula.txt pointed at the Minecraft EULA and contained eula=false. I changed that one value to eula=true. server.properties was already on disk from this run, with server-ip empty and server-port=25565.

What does the systemd unit contain?

The unit is /etc/systemd/system/paper.service. systemctl enable created the symlink under multi-user.target.wants. The guest stayed up. The record is the first start, ten idle minutes, and one systemctl restart.

[Unit]
Description=Paper Minecraft server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=minecraft
Group=minecraft
WorkingDirectory=/opt/minecraft
ExecStart=/usr/lib/jvm/java-25-amazon-corretto/bin/java \
  -Xms2G -Xmx2G -jar paper.jar --nogui
KillSignal=SIGINT
SuccessExitStatus=0 130 143
Restart=on-failure
RestartSec=10
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

KillSignal=SIGINT is what systemctl stop sends. SuccessExitStatus=0 130 143 treats the interrupt and the terminate exits as clean. The file also sets Restart=on-failure. The command I ran was systemctl restart, and NRestarts stayed 0. The JVM was only signaled through systemctl.

Before systemctl start, a TCP connect to 127.0.0.1:25565 on the guest raised ConnectionRefusedError [Errno 111] Connection refused. UFW was already active: default deny on incoming, allow on outgoing, 22/tcp and 25565/tcp allowed from anywhere. The guest has no second firewall in front of that. The path from this host into the guest was a user-net forward onto port 25565.

systemctl start reached the Done line in the journal:

Starting Minecraft server on *:25565
Done (16.326s)! For help, type "help"

ss showed LISTEN on *:25565 with backlog 4096. That * matches the empty server-ip. When the Done line appeared, ps RSS was 1,950,468 kB and systemd MemoryCurrent was 1,977,425,920 bytes. MemAvailable was 1,655,224 kB.

What does the server list see on 25565?

The multiplayer screen asks for a status payload before anyone logs in. I sent that handshake from the host, through the forward, while this first process was up. The payload was one JSON object:

{
  "description": "A Minecraft Server",
  "players": {"max": 20, "online": 0},
  "version": {
    "name": "Paper 26.3",
    "protocol": 777
  },
  "enforcesSecureChat": true
}

motd in server.properties is A Minecraft Server, and max-players is 20. enforce-secure-profile=true matches enforcesSecureChat true. Protocol 777 is what this build answered to a status handshake that sent protocol -1. Online players were 0. The handshake stopped at status, which is the server list, before login.

The generated server.properties also has white-list=true, online-mode=true, view-distance=10, and simulation-distance=10. I left those values. No player name was added. A status payload skips both checks, so login still has to pass online-mode and white-list.

A Wings install of Paper 26.3 on a different guest printed Done (24.330s) inside a 2 GiB container limit and settled at 752.01 MiB. This process had a 2G heap on a 4 GB guest and sat near that heap with the world empty. Ordering the game from a host, panel included, is Order the game from the host you want.

Where did the memory sit for ten minutes?

Nobody joined. The sampler wrote a row every 30 seconds, 21 rows, so the last row is 600 seconds after the first. ps RSS moved from 1,952,804 kB to 1,986,612 kB, a rise of 33,808 kB. MemAvailable moved from 1,652,140 kB to 1,633,084 kB. The last MemoryCurrent was 2,014,334,976 bytes. The journal had zero Can't keep up lines across that window and the restart after it.

systemctl restart then produced a second Done line, Done (9.730s)! For help, type "help". The new process was still uid 999. ps RSS right then was 1,684,832 kB, and MemoryCurrent was 1,697,083,392 bytes. ss still showed *:25565. /opt/minecraft was 234,930,176 bytes. The guest disk had been 2,677,972,992 bytes used before the JDK and the jar, and 3,553,255,424 bytes used after the restart, a rise of 875,282,432 bytes.

FAQ

Which Java version does Paper 26.3 need?

Paper's getting started table says 26.1 and later want Java 25. This guest ran Amazon Corretto 25.0.5, build 25.0.5+10-LTS, from package 1:25.0.5.0.10-1. The server log reported that same build.

Why did -Xmx4G fail when the guest was given 4 GB?

qemu -m 4096 left MemTotal at 4,009,864 kB. The 4G heap tried to commit 4,294,967,296 bytes and the kernel returned errno 12. The 2G heap is the one that reached Done.

Does the process run as root?

The unit sets User=minecraft. After the restart, ps showed uid 999.

What port do I open?

server-port was 25565 and server-ip was empty, so the listener was *:25565. UFW allowed 25565/tcp. A connect before the unit was up got connection refused. The status handshake after Done returned the JSON above.

Can a friend join with the file the jar wrote?

The status list can. A login still has online-mode=true and white-list=true, and this run added no names. The payload's player count stayed 0.