Arkive — the complete guide
Everything you need to install, configure and operate Arkive on Bukkit / Spigot / Paper / Folia, BungeeCord and Velocity. Use the sidebar to jump around; every config key in this guide is documented in the generated config.yml as well.
Requirements
| Jar | Runs on | Java | Notes |
|---|---|---|---|
Arkive-Bukkit.jar | Bukkit, Spigot, Paper, Purpur, Folia — 1.8 → latest | 8+ | Compiled against the 1.8 API; Folia uses the global region scheduler automatically. |
Arkive-Bungee.jar | BungeeCord, Waterfall | 8+ | Backs up the proxy folder. |
Arkive-Velocity.jar | Velocity 3.x, 4.x | 17+ | Native Adventure + SLF4J. |
Optional: PlaceholderAPI (Bukkit) for %arkive_*% placeholders, mysqldump/pg_dump for database dumps, an open port for one-click cloud linking.
Installation
- Drop the jar for your platform into
plugins/and start the server once.plugins/Arkive/config.ymlandmessages.ymlare generated. - Open
config.yml, setgeneral.server-nameand enable at least one entry understorages:(thelocalstorage is enabled by default). - Point your profile at those storages:
profiles.full.storages: [local, s3]. - Run
/arkive reload, then/arkive test— every storage must report ok. - Run
/arkive backup --forceand watch the console. Done — the schedule takes over from here.
Config changes are only picked up on /arkive reload or a restart. A running backup is never interrupted by a reload.
Your first backup
> arkive test
[Arkive] Testing 2 storage(s)...
[Arkive] ✔ local (Local) ok (3 ms)
[Arkive] ✔ s3 (S3) ok (412 ms)
> arkive backup --force
[Arkive] Backup full queued.
[Arkive] Backup full started, you may notice a short lag spike...
[Arkive] Archive RetacafeSMP-full-2026-09-17_04-00-00.zip created: 41,208 files, 6.4 GB -> 2.1 GB
[Arkive] Uploaded RetacafeSMP-full-2026-09-17_04-00-00.zip to s3 (S3) in 1m 48s @ 19.7 MB/s
[Arkive] Pruned 1 old archive(s) from s3
[Arkive] Backup full finished (2.1 GB, 4m 36s)
--force bypasses the skip-if-no-players rule. Without a profile name every enabled profile runs one after another. Players with arkive.notify see the start/finish messages in chat.
Files & folders
| Path | Purpose |
|---|---|
plugins/Arkive/config.yml | Main configuration (this guide). |
plugins/Arkive/messages.yml | Every chat/console message, colour codes with &. Missing keys are added on start. |
plugins/Arkive/backups/ | Default folder of the local storage. Automatically excluded from archives. |
plugins/Arkive/temp/ | Archives are assembled here before upload (change with general.temp-directory). Auto-excluded. |
plugins/Arkive/tokens/ | OAuth tokens for Google Drive / Dropbox / OneDrive. Auto-excluded from archives — keep it private. |
plugins/Arkive/restore/ | Downloads from /arkive restore. |
plugins/Arkive/web/keystore.p12 | Self-signed certificate for the web-link server. |
plugins/Arkive/history.json | Last 50 backup results (feeds /arkive history and placeholders). |
Profiles
A profile is one backup set: what to archive, when, where to upload it and how long to keep it. You can define as many as you like under profiles:. The key is the profile name and becomes the remote folder name.
profiles:
full: # whole server, nightly, off-site
enabled: true
schedule: { mode: cron, cron: "0 4 * * *" }
include: [] # empty = server root
exclude: ["logs/**", "*.jar", "session.lock"]
storages: [local, s3]
file-name: "{server}-{profile}-{timestamp}"
retention: { keep-last: 7, keep-weekly: 4, keep-monthly: 6 }
worlds: # worlds only, hourly, local
schedule: { mode: interval, interval: 1h, initial-delay: 10m }
include: [world, world_nether, world_the_end]
include-plugins: false
storages: [local]
retention: { keep-last: 24 }
| Key | Default | Meaning |
|---|---|---|
enabled | true | Disabled profiles are never scheduled but can still be run manually with /arkive backup <profile>. |
schedule.mode | interval | interval, cron or disabled (manual only). |
schedule.interval | 6h | Duration between runs (see durations). |
schedule.cron | 0 4 * * * | Five-field cron expression, evaluated in general.timezone. |
schedule.initial-delay | 2m | Delay before the first interval run after startup. |
include | [] | Paths relative to the server folder. Empty = everything. |
exclude | see config | Glob patterns (see include & exclude). |
include-worlds | true | false adds every loaded world folder to the excludes (game servers). |
include-plugins | true | false excludes plugins/**. |
storages | [local] | Storage ids to upload to. Empty = every enabled storage. |
file-name | {server}-{profile}-{timestamp} | Placeholders: {server}, {profile}, {timestamp}, {platform}. Extension is added automatically. |
retention.* | — | See retention. |
Only one backup runs at a time. Scheduled runs that collide with a running backup are skipped and logged; manual runs with several profiles are queued one after another.
Scheduling & cron
Durations
Used by interval, initial-delay and elsewhere: 90s, 30m, 6h, 1d, 1w, combinations like 1d12h, or a plain number (minutes). Minimum interval is 60 seconds.
Cron
Standard five fields — minute hour day-of-month month day-of-week — with *, lists (1,15), ranges (1-5), steps (*/6, 0-30/10), month and weekday names (jan, mon; Sunday is 0 or 7) and the shortcuts @hourly, @daily, @weekly, @monthly.
| Expression | Runs |
|---|---|
0 4 * * * | Every day at 04:00 |
30 */3 * * * | Every 3 hours at :30 |
0 2 * * sun | Sundays at 02:00 |
0 5 1 * * | First day of every month at 05:00 |
0 0,12 * * mon-fri | Weekdays at midnight and noon |
@hourly | Every hour at :00 |
Set general.timezone (e.g. Asia/Jakarta) so cron times and archive timestamps match your wall clock; empty means the JVM default. /arkive status shows the next run of every profile.
Backup on shutdown
backup.backup-on-shutdown: true runs every enabled profile while the server stops (the stop waits for it, up to 30 minutes). World saving is skipped during shutdown because the server flushes worlds itself.
Include & exclude
Include entries are paths relative to the server folder (world, plugins/Essentials, server.properties). Leave it empty to archive the whole server folder. Exclude entries are glob patterns matched against the relative path with forward slashes:
| Pattern | Matches |
|---|---|
logs/** | The logs folder and everything below it |
*.jar | Any file ending in .jar, at any depth (patterns without / match everywhere) |
plugins/*/cache/** | Every plugin's cache folder |
world/region/r.-1.*.mca | Specific files with wildcards |
plugins/dynmap/web/tiles/** | Large regenerable data |
Always excluded regardless of config: the temp directory, plugins/Arkive/tokens, every local storage folder, and the archive currently being written. Files that are locked (e.g. session.lock, open region files on Windows) or vanish mid-backup are skipped and listed in the manifest and history — they never fail the run.
Retention
After every successful upload Arkive lists the profile folder on that storage and deletes old archives according to the profile's retention:
| Key | Default | Rule |
|---|---|---|
keep-last | 10 | The newest N archives are protected. 0 = unlimited. |
max-age-days | -1 | Unprotected archives older than N days are deleted. |
max-total-size | "" | Oldest unprotected archives are deleted while the folder exceeds this size (20GB, 500MB). |
keep-daily | 0 | Protect the first archive of each of the last N days. |
keep-weekly | 0 | Protect the first archive of each of the last N ISO weeks. |
keep-monthly | 0 | Protect the first archive of each of the last N months. |
How the rules combine: an archive is protected when it is among the keep-last newest or picked by a daily/weekly/monthly rule. Unprotected archives are removed when keep-last is set (> 0), when they are older than max-age-days, or — oldest first — while the folder exceeds max-total-size. With keep-last: 0 only the age and size limits delete anything.
Simple rotation
retention: { keep-last: 14 }Always the 14 newest, nothing else.
Grandfather-father-son
retention:
keep-last: 7
keep-weekly: 4
keep-monthly: 6A week of dailies, a month of weeklies, half a year of monthlies.
Budget cap
retention:
keep-last: 0
max-total-size: 50GBKeep as many as fit in 50 GB.
Time based
retention:
keep-last: 3
max-age-days: 30Everything from the last 30 days, never fewer than 3.
/arkive prune [profile] applies the rules immediately on every ready storage. Arkive never deletes the archive it just uploaded.
Archives & manifest
Archives are zip (default, Zip64, any tool can open it) or tar.gz (backup.compression.format). compression.level goes from 0 (store, fastest) to 9 (smallest); 6 is a good balance, 1–3 if CPU is the bottleneck. Every archive contains arkive-manifest.json:
{
"generator": "Arkive", "version": "1.0.0",
"server": "RetacafeSMP", "platform": "Paper", "platformVersion": "1.21.4",
"profile": "full", "createdAt": "2026-09-17T04:00:00Z", "format": "zip",
"files": 41208, "rawBytes": 6871947673,
"worlds": ["world", "world_nether", "world_the_end"],
"include": [], "exclude": ["logs/**", "*.jar"],
"databases": ["main"], "skipped": ["session.lock (locked)"]
}
Remote layout on every backend: <path or prefix>/<profile>/<file-name>.zip. With backup.verify-checksum: true a SHA-256 of the archive is stored in history.json and sent to webhooks. When a local storage is among the targets the archive is written straight into it (no extra copy).
Storage: Local disk
storages:
local:
type: local
enabled: true
path: backups # relative to plugins/Arkive, or absolute: D:/Backups, /mnt/nas/mc
Any mounted drive or network share works. The folder is excluded from backups automatically. Several local storages (e.g. an internal disk and a NAS) are fine.
Storage: S3 & compatible
storages:
s3:
type: s3
enabled: true
endpoint: "" # empty for AWS, otherwise the provider URL
region: us-east-1
bucket: my-backups
access-key: "AKIA..."
secret-key: "..."
prefix: minecraft # key prefix inside the bucket
path-style: false # auto true when an endpoint is set
storage-class: "" # AWS only: STANDARD_IA, GLACIER_IR, DEEP_ARCHIVE
part-size-mb: 32 # multipart chunk for archives > 64 MB
chunked-encoding: true # set false if a provider rejects streaming signatures
| Provider | endpoint | region | Notes |
|---|---|---|---|
| AWS S3 | (empty) | your bucket's region | Optional storage-class. |
| Cloudflare R2 | https://<account-id>.r2.cloudflarestorage.com | auto | Token from R2 → Manage API Tokens with Object Read & Write. Use path-style: true. |
| Backblaze B2 | https://s3.<region>.backblazeb2.com | e.g. us-west-004 | Application key with read/write on the bucket. |
| MinIO | http://minio.local:9000 | us-east-1 | Self-hosted; http is fine on a LAN. |
| Wasabi | https://s3.<region>.wasabisys.com | e.g. eu-central-1 | |
| DigitalOcean Spaces | https://<dc>.digitaloceanspaces.com | e.g. nyc3 | |
| Hetzner Object Storage | https://<loc>.your-objectstorage.com | e.g. fsn1 |
If access-key is empty Arkive falls back to the AWS credential chain (environment variables, ~/.aws/credentials, instance profile) and logs a warning. Archives above 64 MB are sent as multipart uploads and aborted cleanly on failure. Test with /arkive test s3.
Storage: FTP / FTPS
ftp:
type: ftp
enabled: true
host: ftp.example.com
port: 21 # 990 for implicit TLS
username: user
password: "secret"
secure: false # true = FTPS
implicit-tls: false # implicit (port 990) instead of explicit AUTH TLS
passive: true # almost always right behind NAT
path: /backups
timeout-seconds: 30
Folders are created as needed. Prefer SFTP or FTPS — plain FTP sends the password unencrypted.
Storage: SFTP
sftp:
type: sftp
enabled: true
host: backup.example.com
port: 22
username: minecraft
password: "" # password auth, or ...
private-key: keys/id_ed25519 # ... key file (relative to plugins/Arkive or absolute)
private-key-passphrase: ""
path: backups # relative to the SSH home, or absolute /srv/backups
known-hosts: "" # optional known_hosts file
strict-host-key-checking: false
timeout-seconds: 30
Generate a key on the server with ssh-keygen -t ed25519 -f plugins/Arkive/keys/id_ed25519 and add the .pub to ~/.ssh/authorized_keys on the backup host. RSA, ECDSA and Ed25519 keys are supported (OpenSSH and PEM formats). Set strict-host-key-checking: true with a known-hosts file to pin the host key.
Storage: WebDAV
webdav:
type: webdav
enabled: true
url: https://cloud.example.com/remote.php/dav/files/<user>/MinecraftBackups
username: user
password: "app-password"
bearer-token: "" # alternative to basic auth
timeout-seconds: 60
| Service | URL pattern |
|---|---|
| Nextcloud / ownCloud | https://host/remote.php/dav/files/<user>/<folder> — use an app password. |
| Synology (WebDAV Server) | https://nas:5006/<shared-folder> |
| Hetzner Storage Box | https://<user>.your-storagebox.de/<folder> |
| Apache / nginx DAV | Any collection URL. |
Storage: Google Drive
google-drive:
type: google-drive
enabled: true
client-id: "....apps.googleusercontent.com"
client-secret: "GOCSPX-..."
folder: "Arkive Backups" # created in My Drive (or the shared drive)
shared-drive-id: "" # optional Google Workspace shared drive
Arkive uses your own OAuth client, so nothing goes through third-party servers. Create it once:
- Open Google Cloud Console, create a project and enable the Google Drive API.
- Configure the OAuth consent screen (External, add yourself as a test user — no verification is needed for personal use).
- Create credentials → OAuth client ID:
- TVs and Limited Input devices for the manual device-code flow, or
- Web application with the authorised redirect URI
https://<public-host>:<port>/callback/google-drivefor one-click linking.
- Put
client-idandclient-secretin the config,/arkive reload, then/arkive link google-drive.
Arkive only requests the drive.file scope: it can see and manage the files it created, nothing else in your Drive. Uploads are resumable and existing files with the same name are replaced.
Storage: Dropbox
dropbox:
type: dropbox
enabled: true
app-key: "..."
folder: "Arkive Backups"
- Create an app at dropbox.com/developers/apps: Scoped access, Full Dropbox or App folder.
- Permissions tab: enable
files.metadata.read,files.content.write,files.content.read,account_info.read. - For one-click linking add
https://<public-host>:<port>/callback/dropboxunder Redirect URIs. - Copy the App key into the config. No secret is needed (PKCE).
/arkive link dropbox— with web-link you just sign in; manually you paste the code back with/arkive link dropbox <code>.
Archives above 100 MB use upload sessions with 32 MB chunks.
Storage: OneDrive
onedrive:
type: onedrive
enabled: true
client-id: "00000000-0000-0000-0000-000000000000"
client-secret: "" # only for a confidential "Web" registration
tenant: common # common | consumers | organizations | <tenant-id>
folder: "Arkive Backups"
- Open Microsoft Entra admin center → App registrations → New registration. Supported account types: Personal Microsoft accounts and any organization.
- Authentication → enable Allow public client flows (needed for the device code).
- For one-click linking add the platform Mobile and desktop applications with redirect URI
https://<public-host>:<port>/callback/onedrive. - API permissions:
Files.ReadWrite,offline_access,User.Read(delegated). - Copy the Application (client) ID into the config and run
/arkive link onedrive.
Works with personal OneDrive and OneDrive for Business. Files above 4 MB use chunked upload sessions (10 MiB chunks).
Linking accounts (web-link)
Google Drive, Dropbox and OneDrive need a one-time authorisation. Arkive offers two ways:
A One-click web link
Arkive runs a small built-in HTTPS server. Click the printed link, sign in, done — the token is stored automatically. Needs one free port and a domain.
B Manual (device / paste code)
/arkive link <storage> --manual. Google & OneDrive show a short code to enter on a page; Dropbox gives a code to paste back. No inbound port needed.
Setting up the web link
web-link:
enabled: true
port: 8443 # a FREE port (extra allocation on hosting panels)
bind-address: "0.0.0.0"
public-host: mc.example.com # the DOMAIN of your server (Google refuses raw IPs)
https: true # providers require https; a self-signed cert is generated
on-demand: true # only listen while a link is in progress
timeout-minutes: 10
- Get a port. Pterodactyl / Pelican: Network tab → add an allocation → use that port. Self-hosted: pick a free port and open it in the firewall.
- Use a domain.
public-hostmust be a hostname that resolves to your server (the domain players connect with, or the panel's node domain). Google rejectshttps://1.2.3.4:8443. - Register the callback URL in the provider console exactly as
https://<public-host>:<port>/callback/<storage-id>(e.g.https://mc.example.com:8443/callback/google-drive). /arkive reloadthen/arkive link google-drive. Arkive prints the sign-in link, the callback URL, and warnings about your setup.- Open the link, sign in. Your browser shows a certificate warning once (self-signed) — continue. You land on a green "Linked!" page and the console confirms the account.
Port already in use → pick another allocation. public-host is an IP → Google will refuse it. https disabled → providers only allow plain http on localhost. keytool not found → your Java has no keytool; install a full JDK or place your own PKCS12 keystore (password arkive-web) at plugins/Arkive/web/keystore.p12.
Tokens are saved in plugins/Arkive/tokens/<id>.json, refreshed automatically, and never leave your server. /arkive unlink <id> deletes them. The callback server only accepts requests carrying a valid one-time state and stops itself after the link (on-demand mode).
Database dumps
backup:
databases:
main:
enabled: true
type: mysql # mysql | mariadb | postgres | custom
host: 127.0.0.1
port: 3306
database: minecraft
username: backup
password: "secret"
executable: "" # e.g. /usr/bin/mysqldump when not on PATH
extra-args: ["--skip-lock-tables"]
stats:
type: custom
command: "sqlite3 plugins/Stats/data.db .dump > {output}"
Each dump is written to arkive-databases/<id>.sql inside the archive. MySQL/MariaDB use mysqldump --single-transaction --quick --routines --triggers with the password passed through MYSQL_PWD (not visible in the process list); PostgreSQL uses pg_dump with PGPASSWORD. A failed dump makes the backup partial (the archive is still created and uploaded) and the error is reported in Discord and history. Dumps time out after 30 minutes.
Hooks
backup:
hooks:
before:
- "console:say Backup starting in a moment"
- "sh /opt/scripts/pause-dynmap.sh"
after:
- "console:say Backup finished"
- "/opt/scripts/notify.sh"
Entries prefixed with console: run as server console commands (on the main thread). Everything else runs in the OS shell (sh -c / cmd /c) from the server folder with a 10-minute timeout and these environment variables:
| Variable | Value |
|---|---|
ARKIVE_PROFILE | Profile name |
ARKIVE_TRIGGER | scheduled, manual (name), shutdown |
ARKIVE_STATUS | running (before) / success, partial, failed (after) |
ARKIVE_ARCHIVE | Absolute path of the archive (after hooks; empty if it was already deleted) |
ARKIVE_SERVER | general.server-name |
Hook failures are logged but never abort the backup.
Discord & webhooks
notifications:
discord:
enabled: true
webhook-url: "https://discord.com/api/webhooks/..."
username: "Arkive"
avatar-url: ""
on-start: false
on-success: true
on-failure: true
webhook:
enabled: true
url: "https://n8n.example.com/webhook/arkive"
headers:
Authorization: "Bearer xyz"
Discord receives a colour-coded embed (green success, yellow partial, red failed) with archive name, sizes, file count, duration, per-storage result and pruned counts. The generic webhook receives JSON:
{
"event": "backup.finish", "server": "RetacafeSMP", "timestamp": 1758081876000,
"result": {
"profile": "full", "trigger": "scheduled", "status": "SUCCESS",
"startedAt": 1758081600000, "finishedAt": 1758081876000,
"archiveName": "RetacafeSMP-full-2026-09-17_04-00-00.zip",
"archiveBytes": 2254857830, "rawBytes": 6871947673, "files": 41208,
"sha256": "9f86d0...", "error": null,
"skippedFiles": ["session.lock (locked)"],
"storages": { "local": "ok", "s3": "ok" },
"pruned": { "local": 1, "s3": 1 }
}
}
event is backup.start or backup.finish. Use it with n8n, Zapier, Uptime Kuma (push monitor), Home Assistant or your own API.
Restoring
- Find the archive:
/arkive list s3 full. - Download it:
/arkive restore s3 full RetacafeSMP-full-2026-09-17_04-00-00.zip --extract. The file lands inplugins/Arkive/restore/,--extractunpacks it next to it. - Stop the server.
- Copy the folders you need (e.g.
world/) from the restore folder over the live ones. Database dumps are inarkive-databases/— import them withmysql < main.sql/psql -f main.sql. - Start the server and delete the restore folder when you are done.
Arkive never overwrites live worlds or plugin data on its own. A wrong click must not be able to roll back a running server — restoring always involves you stopping the server and copying files consciously.
Archives are plain zip/tar.gz: you can also just download them from your bucket/Drive and extract them anywhere.
BungeeCord & Velocity
The proxy jars use exactly the same config, commands, storages and retention. Differences:
- The server root is the proxy folder (
config.yml,plugins/,modules/, …). There are no worlds;include-worldsandprepare-serverare no-ops. skip-if-no-playerstracks players across the whole network (join/leave on the proxy).- Console hooks run through the proxy command manager (
console:alert Backup doneon Bungee,console:velocity …on Velocity). - Velocity plugin id is
arkive; the data folder isplugins/arkive/.
Typical proxy setup: a small profile every 6 hours to the same S3 bucket under a different prefix (e.g. proxy), keep-last: 20.
Performance tuning
| Setting | Effect |
|---|---|
general.thread-priority | 1–10. Lower = less CPU competition with the main thread. 3 is a good default; use 1 on single-core hosts. |
backup.compression.level | Region files compress poorly; level 1–3 is often 2× faster for a few % larger archives. 0 = store only. |
general.upload-throttle-mbps | Caps upload bandwidth so players' latency is unaffected. |
general.temp-directory | Put it on the fastest disk. If a local storage is a target, the archive is written there directly. |
skip-if-no-players | Skips scheduled runs when nobody joined since the last backup — avoids identical archives overnight. |
| Excludes | Exclude logs/**, cache/**, libraries/**, versions/**, dynmap tiles, and plugin caches. A 6 GB server usually archives in a few minutes. |
| Profiles | Combine a frequent small worlds profile with a nightly full profile instead of one huge hourly backup. |
The only main-thread work is save-all before archiving and re-enabling auto-save afterwards; everything else (walking, compressing, hashing, uploading, pruning) happens on the Arkive worker thread.
config.yml reference
general
| Key | Default | Description |
|---|---|---|
server-name | server | Used in archive names, Discord embeds and the manifest. |
debug | false | Verbose logging: skipped files, upload progress, stack traces. |
temp-directory | "" | Staging folder; empty = plugins/Arkive/temp. |
timezone | "" | IANA zone for cron and timestamps, e.g. Asia/Jakarta. |
date-format | yyyy-MM-dd_HH-mm-ss | Java DateTimeFormatter pattern for {timestamp}. |
thread-priority | 3 | Backup worker thread priority 1–10. |
upload-throttle-mbps | 0 | Upload cap in megabits/s, 0 = unlimited. |
backup
| Key | Default | Description |
|---|---|---|
compression.format | zip | zip or tar.gz. |
compression.level | 6 | 0–9. |
skip-if-no-players | true | Skip scheduled runs without player activity since the last backup. |
prepare-server | true | save-all + pause auto-save while archiving (game servers). |
verify-checksum | true | SHA-256 of every archive. |
backup-on-shutdown | false | Run all enabled profiles on stop. |
delete-temp-after-upload | true | Remove the staging archive after uploads. |
upload-retries | 2 | Retries per storage with increasing delay. |
announce.start / finish / failure | true | In-game messages to players with announce.permission. |
announce.permission | arkive.notify | Who sees announcements. |
hooks.before / after | [] | See hooks. |
databases.* | {} | See database dumps. |
profiles.<name>
storages.<id>
type (local, s3, ftp, sftp, webdav, google-drive, dropbox, onedrive) and enabled are common to all; the rest is documented per storage. Type aliases: minio, b2, r2, wasabi → s3; ftps → ftp; nextcloud → webdav; gdrive → google-drive.
web-link
See linking accounts.
notifications
See Discord & webhooks.
Commands & permissions
| Command | Permission | Description |
|---|---|---|
/arkive help | arkive.use | Command list. |
/arkive backup [profile] [--force] | arkive.backup | Run one profile, or every enabled profile in sequence. --force ignores the no-players rule. |
/arkive status | arkive.status | Running backup (phase, progress, elapsed), profiles with last/next run, storages and their state. |
/arkive history | arkive.history | Last 10 results. |
/arkive list <storage> [profile] | arkive.list | Archives on a storage with size and date. |
/arkive test [storage] | arkive.test | Connectivity/credential test for one or all storages. |
/arkive link <storage> [code | --manual | --web] | arkive.link | Authorise a cloud account. Web flow when web-link is enabled, otherwise device/paste code. |
/arkive unlink <storage> | arkive.unlink | Delete the stored token. |
/arkive restore <storage> <profile> <archive> [--extract] | arkive.restore | Download (and unpack) into the restore folder. |
/arkive prune [profile] | arkive.prune | Apply retention now. |
/arkive reload | arkive.reload | Reload config, messages, storages, schedules and the web-link server. |
arkive.admin grants every command, arkive.notify receives announcements. Console always has full access. Aliases: /backup, /ark (Bukkit), /arkivebackup, /ark (proxies). Tab completion covers sub-commands, profiles, storages and flags.
Placeholders
With PlaceholderAPI installed on Bukkit/Paper, Arkive registers the arkive expansion automatically (no ecloud download needed). Use them in scoreboards, tab lists, holograms, MOTDs:
| Placeholder | Example |
|---|---|
%arkive_running% | true / false |
%arkive_phase% | uploading s3 42% or idle |
%arkive_progress% | 42 (empty when unknown) |
%arkive_current_profile% | full |
%arkive_last_status% | success, partial, failed, never |
%arkive_last_profile% | full |
%arkive_last_time% | 2026-09-17 04:04:36 |
%arkive_last_ago% | 2h 13m |
%arkive_last_size% | 2.1 GB |
%arkive_last_duration% | 4m 36s |
%arkive_last_files% | 41208 |
%arkive_last_archive% | RetacafeSMP-full-2026-09-17_04-00-00.zip |
%arkive_last_error% | Error text of the last run, or empty |
%arkive_next_profile% | Profile that runs next |
%arkive_next_time% | 2026-09-17 10:00:00 |
%arkive_next_in% | 5h 55m |
%arkive_profile_<name>_enabled% | true |
%arkive_profile_<name>_last_status% (also last_time, last_ago, last_size, last_duration, last_files, last_archive) | Per-profile values |
%arkive_profile_<name>_next_time% / _next_in% | Per-profile schedule |
%arkive_storage_<id>_type% | S3 |
%arkive_storage_<id>_status% | ready / not linked |
%arkive_storage_<id>_target% | Bucket / path / account |
%arkive_storages_count%, %arkive_profiles_count% | Counts |
%arkive_history_count%, %arkive_success_count%, %arkive_failed_count% | From the last 50 results |
Developers on any platform can call core.placeholders().resolve("last_status") directly.
messages.yml
Every message Arkive sends is in messages.yml. Colour codes use &, placeholders are written as {name} and listed next to each key. The prefix is prepended to most messages; help.lines is a multi-line block. Keys missing from an older file are added automatically on start, so updates never break your customisations.
prefix: "&8[&bArkive&8] &7"
backup:
started: "&7Backup &f{profile}&7 started, you may notice a short lag spike..."
finished: "&aBackup &f{profile}&a finished &8(&f{size}&8, &f{duration}&8)"
Troubleshooting
| Symptom | Cause & fix |
|---|---|
| Unable to load credentials from any of the providers in the chain | An S3-type storage has an empty access-key. Check every entry with type: s3 (also the ones you didn't mean to change) and run /arkive reload. Startup logs name the offending storage. |
| Bucket 'x' is not accessible (403) | Wrong keys, or the token has no permission on that bucket. For R2 create the token with Object Read & Write scoped to the bucket. |
| S3 upload fails with a signature / STREAMING-AWS4 error | Set chunked-encoding: false for that storage. |
| Port 8443 is already in use | Another process uses the web-link port. Pick a different allocation. |
| Google: redirect_uri_mismatch / invalid_request | The callback URL must match exactly (scheme, host, port, path) and must be a domain, not an IP. Register it on a Web application client. |
| Browser: certificate warning on the callback page | Expected — the certificate is self-signed. Continue. Delete plugins/Arkive/web/keystore.p12 after changing public-host to regenerate it. |
| keytool not found | Your Java runtime is a minimal JRE. Install a full JDK/JRE, or place your own PKCS12 keystore (password arkive-web) at plugins/Arkive/web/keystore.p12. |
| Storage 'x' is not linked | Run /arkive link x. Tokens live in plugins/Arkive/tokens/. |
| Backup partial with "N skipped" | Locked or vanished files (session.lock, open region files on Windows). Enable general.debug to see which; usually harmless. |
| Skipping backup: no player activity | Working as intended (skip-if-no-players). Use --force or disable the option. |
| SFTP: Auth fail | Check username, key path and that the public key is in authorized_keys. With a passphrase-protected key set private-key-passphrase. |
| Dropbox: 409 path/not_found on list | Folder does not exist yet — the first upload creates it. |
| Nothing happens on schedule | Check /arkive status for next; profiles with mode: disabled or enabled: false never run. Cron errors are logged on start. |
For anything else enable general.debug: true, reproduce, and post the log in the resource discussion or Discord.
FAQ
Does it lag the server?
No. One save-all on the main thread, then everything runs on a low-priority background thread with optional bandwidth throttling.
Is my data sent to Wureta?
Never. Arkive talks only to the storages you configure, using your own credentials and OAuth apps. There is no telemetry.
Can I backup to several places at once?
Yes — list several storage ids in a profile. Each storage gets its own retention pass and result.
Can I run it on a proxy and on the backend servers?
Yes, one licence covers all your servers. Use different server-name/prefix values so archives don't mix.
Can I use a different world container / multiple servers in one folder?
Use include with the exact folders you want, and separate profiles per server if they share a disk.
Where are updates?
Through the resource page where you bought it (SpigotMC / BuiltByBit). The version is printed on startup and in /arkive status.
Lite edition
Arkive Lite is the free build on SpigotMC, available for Bukkit / Spigot / Paper / Folia only. It uses the same engine, config, commands and docs with these limits:
| Feature | Lite | Full |
|---|---|---|
| Platforms | Bukkit / Spigot / Paper / Folia | + BungeeCord / Waterfall, Velocity |
| Storages | local, sftp, ftp | + s3 (AWS, R2, B2, MinIO, Wasabi…), google-drive, dropbox, onedrive, webdav |
| Profiles | 1 (the first one in the config) | unlimited |
| Database dumps | — | MySQL / MariaDB / PostgreSQL / custom |
| One-click cloud linking (web-link) | — | ✓ |
| Cron, retention, safe archiving, Discord, restore, hooks, placeholders | ✓ | ✓ |
Storages or profiles beyond the Lite limits are ignored with a warning in the console — nothing breaks. To upgrade, replace the jar with the full edition from BuiltByBit; your config.yml carries over unchanged.
Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.