> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poplock.scyne.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshot & cron

> Set up the automated daily snapshot cron job and understand how the snapshot countdown and cleanup work.

The `snapshot.sh` script performs a nightly world backup. It broadcasts an
in-game countdown before stopping the server, takes a compressed snapshot, and
restarts automatically. Snapshots older than 7 days are deleted as part of the
same run.

## Snapshot behavior

When the cron job fires:

1. **If the server is online**, a 30-minute countdown begins. In-game chat
   warnings with an audible alert are broadcast at the following intervals:

   | Time remaining | Message                                                             |
   | -------------- | ------------------------------------------------------------------- |
   | 30 minutes     | "The server will go down for a daily snapshot in 30 minutes."       |
   | 15 minutes     | "The server will go down for a daily snapshot in 15 minutes."       |
   | 10 minutes     | "The server will go down for a daily snapshot in 10 minutes."       |
   | 5 minutes      | "The server will go down for a daily snapshot in 5 minutes."        |
   | 1 minute       | "The server will go down for a daily snapshot in 1 minute!"         |
   | 30 seconds     | "Server going down for snapshot in 30 seconds! Please log off now." |
   | 15 seconds     | "Server going down for snapshot in 15 seconds!"                     |
   | 5 seconds      | "Server going down for snapshot in 5 seconds!"                      |

2. The `stop` command is sent to the server console. If the server does not exit
   within 30 seconds, it is force-killed.

3. A `.tar.gz` snapshot is saved to `backups/` containing:
   * All world directories (`world`, `world_nether`, `world_the_end`, and any
     others matching the `world*` prefix)
   * `whitelist.json`
   * `server.properties`

4. The server is automatically restarted.

5. Any snapshot files older than 7 days are deleted from the `backups/`
   directory.

**If the server is offline** when the cron fires, the countdown is skipped
entirely and the snapshot is taken immediately.

## Cron setup

<Warning>
  The snapshot script takes 30 minutes to complete its countdown before stopping
  the server. Schedule the cron job at **11:30 PM** — not midnight — so the
  server actually goes down at midnight. Scheduling at midnight means the server
  won't stop until 12:30 AM.
</Warning>

<Steps>
  <Step title="Open the root crontab">
    The snapshot script must run as root (or the user owning the server
    directory) to have permission to stop the server and write backup files:

    ```bash theme={null}
    sudo crontab -e
    ```
  </Step>

  <Step title="Add the cron entry">
    Add the following line to schedule the snapshot every night at 11:30 PM:

    ```text theme={null}
    30 23 * * * /usr/local/bin/snapshot.sh >> /var/log/minecraft_snapshot.log 2>&1
    ```

    Output is appended to a log file so you can review past runs.
  </Step>

  <Step title="Verify the entry was saved">
    Confirm the cron entry is present:

    ```bash theme={null}
    sudo crontab -l
    ```
  </Step>
</Steps>

## Checking snapshot logs

To watch the log in real time during a snapshot run:

```bash theme={null}
tail -f /var/log/minecraft_snapshot.log
```

Example log output from a successful run:

```text theme={null}
[2025-04-03 23:00:01] Server is online. Starting 30-minute snapshot countdown.
[2025-04-03 23:00:01] Broadcasted: The server will go down for a daily snapshot in 30 minutes.
[2025-04-03 23:15:01] Broadcasted: The server will go down for a daily snapshot in 15 minutes.
[2025-04-03 23:20:01] Broadcasted: The server will go down for a daily snapshot in 10 minutes.
[2025-04-03 23:25:01] Broadcasted: The server will go down for a daily snapshot in 5 minutes.
[2025-04-03 23:29:01] Broadcasted: The server will go down for a daily snapshot in 1 minute!
[2025-04-03 23:29:31] Broadcasted: Server going down for snapshot in 30 seconds! Please log off now.
[2025-04-03 23:29:46] Broadcasted: Server going down for snapshot in 15 seconds!
[2025-04-03 23:29:56] Broadcasted: Server going down for snapshot in 5 seconds!
[2025-04-03 23:30:01] Broadcasted: Saving world states and stopping server for snapshot...
[2025-04-03 23:30:07] Creating snapshot: /usr/local/games/minecraft_server/java/backups/snapshot_20250403_233007.tar.gz
[2025-04-03 23:30:42] Snapshot successfully saved.
[2025-04-03 23:30:42] Restarting server...
[2025-04-03 23:30:42] Cleaning up snapshots older than 7 days...
[2025-04-03 23:30:43] Daily snapshot routine complete.
```

## Snapshot archive naming

Snapshot files follow the pattern `snapshot_YYYYMMDD_HHMMSS.tar.gz` and are
stored in:

```text theme={null}
/usr/local/games/minecraft_server/java/backups/
```

They can be restored interactively at any time with `serv restore`.