World backups

Schedule backups of every world to a local folder and your own S3 storage, then restore a world safely with /nusa backup.

On this page

NusaSpigot can back up every world on a schedule to a local folder and, if you want, upload the archives to S3-compatible storage that you own (AWS S3, Cloudflare R2, Backblaze B2, Wasabi or MinIO). A restore always happens on the next restart, so a running world is never touched.

Make a backup right now

Without any setup, you can make a backup straight away:

nusa backup now
nusa backup list

Archives are saved in the nusa-backups/ folder as backup-YYYYMMDD-HHMMSS.zip (UTC time, so they sort in creation order). nusa backup on its own shows the schedule, destination, retention and the last result.

Scheduled backups

Scheduled backups are off by default. Turn them on in the backup section of nusa-global.yml, then restart:

KeyExampleMeaning
backup.enabledtrueTurns on scheduled backups
backup.interval-minutes360Minutes between backups. 0 = only with /nusa backup now
backup.keep-local3Local archives to keep. Older ones are deleted
backup.keep-remote14Archives to keep in S3. 0 = never delete

Uploading to S3 storage

Fill in the backup.s3 section to upload every archive:

KeyExample
backup.s3.endpointYour S3 provider's endpoint address
backup.s3.regionauto (for R2) or your bucket's region
backup.s3.bucketmc-backups
backup.s3.prefixsurvival/

Access keys must never go in nusa-global.yml, because that file is shared with the Cloud Panel when the server is linked. Use one of these instead:

  • The environment variables NUSA_BACKUP_S3_ACCESS_KEY and NUSA_BACKUP_S3_SECRET_KEY, or
  • A nusa-backup-credentials.properties file next to nusa-global.yml:
access-key=YOUR_ACCESS_KEY
secret-key=YOUR_SECRET_KEY

Give that key write, read, list and delete access to your backup prefix only.

Restoring a world

A restore never touches a running world:

  1. List the archives with nusa backup list.
  2. Run nusa backup restore <id>. NusaSpigot explains what will happen.
  3. Confirm by adding confirm to the end of the same command. The archive is downloaded if it is not local, checked for damage and staged for restore.
  4. Restart the server. Before any world opens, the current world folders are moved to nusa-backups/pre-restore-<time>/ and the archive is extracted in their place.

Changed your mind? Run nusa backup restore cancel before restarting.

While a backup runs

Each world's autosave pauses briefly, everything is saved, and the archive is written on a separate thread. Autosave returns as soon as the archive is written, or after 30 minutes at most (which cancels that backup). Required permission: nusaspigot.command.backup (OP by default).

Next steps

Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…