Backups

Artifactory enables you to configure the automatic backup of your system settings, then provide access to that backup in the case you need to restore it.

📘

Note

Starting from Artifactory 7.66, the server path to a backup can no longer start with JFROG_HOME/artifactory.

The following topics describe system backup and restore:

• Backup Strategy Overview
• Complete System Backup
• Backing Up Large Instances
• Disaster Recovery
• Restoring a System Backup

---

Backup Strategy Overview

Artifactory stores binaries and metadata separately. The metadata (checksums, repository paths, timestamps) resides in a database, while the actual binaries are stored in the filestore using SHA1 checksum-based naming. This architecture enables deduplication—identical files are never stored more than once—but it also means effective backup strategies must account for both components.

Choosing the Right Backup Approach

The appropriate backup method depends on your instance size:

⚠️

Large Instance Threshold

If your instance exceeds 500 GB of storage or contains more than 1 million artifacts, switch to component-based backups. System backups at this scale can take excessive time, potentially overlapping scheduled intervals and delaying recovery when needed.

Understanding Checksum-Based Storage

Artifactory uses checksum-based storage where files are named after their SHA1 checksum and organized into folders based on the first two characters of that checksum. For example, in a default installation, the filestore is located at $JFROG_HOME/artifactory/var/data/artifactory/filestore.

This structure enables deduplication but means the filestore alone cannot identify files without the corresponding database metadata. Always back up both components together.

---

Complete System Backup

You can automatically and periodically back up the entire Artifactory system. The backup process creates a time-stamped directory in the target backup directory. Backup content is stored in standard file system format and can be loaded into any repository, so Artifactory never locks you out.

📘

Note

• Backing up very large filestores: If you are backing up more than 1TB of storage, refer to this article for instructions.
• Deleting outdated files to reduce backup storage: It is recommended to manually delete the access.backup.<timestamp>.json file created when performing backup or system export. This file can be found in the $JFROG_HOME/artifactory/var/backup/access/ folder.

Prerequisites

In some user environments, the primary node is specifically configured with access to some NFS mount for Artifactory backups. With the introduction of Cloud-Native High Availability, where any node can create a backup, you need to set up access for all nodes to have write access to the mount for creating a backup. Alternatively, you can exclude all nodes from managing cluster-wide tasks except for a single node.

❗️

Path for Backup File

Starting from Artifactory version 7.66.x, the server path to backup can no longer start with $JFROG_HOME/artifactory directory. Therefore, you must store the backup outside the JFrog directory. The artifactory user must have access to the backup folder.

If you have any backups configured with the $JFROG_HOME/artifactory directory, you need to modify the path.

If you are moving to Cloud-Native High Availability on HA, we recommend that you have a shared drive path for backup paths. If you use a local drive path, the backup will be saved in whichever node triggers the backup operation, which can lead to confusion.

📘

Note

To define multiple backups, in the Administration module, select Artifactory | Backups. Each backup may have its own schedule and repositories to either process or exclude.

Creating a System Backup

1. In the navigation panel on the left-hand side of the screen, click Administration .

2. In the General section of this screen, click Settings. The Artifactory General Settings screen appears.

3. In the Services pane, click Backups. Backup settings are displayed.

   

4. From the top right-hand corner of the screen, click New Backup. The Backup Settings window is displayed. If previously configured, you can also choose an existing backup and change its properties.

5. Configure backup settings as required. When completed click Save. Settings are saved and the Backup is run when scheduled.

Backup Settings Reference

✅

Monitoring Backup Progress

During a system backup, Artifactory writes several messages to the $JFROG_HOME/artifactory/var/log/artifactory-service.log file. To monitor the backup process, look for messages that indicate the beginning and the end of a full system export as in the following example:

Text

2016-06-09 02:00:00,023 [art-exec-1] [INFO ] (o.a.s.ArtifactoryApplicationContext:508) - Beginning full system export...
...
2016-06-09 02:00:00,357 [art-exec-1] [INFO ] (o.a.s.ArtifactoryApplicationContext:620) - Full system export completed successfully.

System Backup Considerations

System backups create a complete duplicate of your data, including each artifact stored alongside its metadata. Because deduplication does not apply to backups, the backup size may exceed your current Artifactory storage size.

To reduce storage requirements for large instances, you can back up the filestore separately and perform a skeleton export of the database using the system export with Exclude Content enabled.

---

Backing Up Large Instances

For instances exceeding 500 GB or containing more than 1 million artifacts, back up each component separately: the database, the filestore, and the Artifactory Home directory.

Filestore Backup

Copy the entire filestore directory using your preferred method. A third-party backup solution with snapshot capabilities can provide better control and performance. Point it to your filestore location, which by default is $JFROG_HOME/artifactory/var/data/artifactory/filestore.

Options for filestore backup include:

• Periodic rsync to an NFS mount dedicated for snapshots
• Object storage services such as S3 with versioning enabled
• Enterprise backup solutions with snapshot capabilities

Database Backup

Back up the database using either active/passive replication or periodic snapshots. Without the database, the filestore is just a collection of checksum-named files that cannot be identified or restored.

⚠️

Timing Coordination

Take database snapshots before copying the filestore, and perform both operations close together. This avoids references to non-existent binaries or missing metadata entries.

Artifactory Home Backup

Back up the Artifactory Home directory to preserve configurations, properties, and logs.

❗️

Master Key Backup

The Master Key is critical. If lost, all encrypted passwords become unrecoverable during restoration. Always maintain a secure backup of your Master Key separately from other backups.

A full snapshot of the Artifactory Home directory preserves existing properties, custom configurations, and logs.

System Export with Exclude Content

A system export with Exclude Content enabled exports metadata and configurations without the binaries. This is equivalent to a database dump plus Artifactory Home configurations, exported as XML files representing your binaries and repository locations.

This approach is useful for:

• Creating a metadata-only backup alongside a separate filestore backup
• Preparing for migrations where the filestore will be copied separately

📘

Note

System export with Exclude Content is not recommended as your primary backup mechanism for large instances because export and restoration time increases with the number of artifacts due to database read/write operations.

---

Disaster Recovery

Disaster recovery (DR) ensures you can recover from events that cause irreversible damage or data loss. A DR setup also enables planned maintenance without downtime by shifting traffic to a secondary instance.

DR Architecture Options

Using Federated Repositories for DR

Federated Repositories are optimized for file synchronization across multiple topologies and up to 10 different JFrog Platform Deployments (JPDs). They act like local repositories but automatically synchronize content bidirectionally.

Prerequisites:

• Instances running the same Artifactory version (for versions below 7.49.3)
• Properly synchronized clocks across instances
• Trust established via binding or circle of trust for self-hosted instances

For each deployment repository requiring DR protection, either create it as a Federated Repository or convert an existing local repository.

⚠️

Terraform Backend Limitation

Federated Repositories do not support Terraform backends. The Terraform backend manages infrastructure state, and duplicating it could cause state inconsistencies. Federated repositories also do not support file locking in multi-repo environments, which Terraform requires for state consistency.

Manual DR with Replication

If Federated Repositories are not suitable, configure DR manually using repository replication:

• Local Replication: One Artifactory instance pushes artifacts to a target local repository in another instance.
• Remote Replication: A remote repository pulls artifacts from the source instance, populating its cache.

📘

Bidirectional Sync with Replication

Replication does not natively support bidirectional sync. To achieve this, use a Virtual Repository containing both a Local Repository (for deployments) and a Remote Repository (pointing to the other site). Configure the same structure on the other site for bidirectional synchronization.

Synchronizing Security Entities

Security entities (users, groups, permissions, tokens) are not synchronized by replication or Federated Repositories. Use Access Federation to sync these entities across instances.

To configure Access Federation:

1. Ensure Circle of Trust is established between instances.
2. In the Administration module, navigate to Access Federation.
3. Select the deployments to sync.
4. Choose which entities and permissions to synchronize.
5. Confirm the configuration.

Synchronizing Configurations

Repository and security entity synchronization does not include other configurations. To maintain consistent configurations across DR sites:

---

Restoring a System Backup

To restore a system backup, you need to perform a system import. For more information, see System Import and Export.

Migration Using System Export

System exports can be used for instance migration or cloning. This approach works best when setting up a new instance to migrate data into.

Method 1: Short Downtime Migration

1. Disable garbage collection on both servers: Admin > Advanced > Maintenance > Garbage Collection.
2. Copy $ARTIFACTORY_HOME/data/filestore from the old server to the new server's filestore folder.
3. Take the old server off the network to block new requests.
4. On the old server, perform a full system export with Exclude Content selected.
5. Shut down the old server.
6. Run rsync from $ARTIFACTORY_HOME/data/filestore to the new server one final time.
7. On the new server, perform a full system import (do not select Exclude Content).
8. Switch DNS or network traffic to the new server.
9. Re-enable garbage collection on the new server.

Method 2: Near-Zero Downtime Migration

1. Disable garbage collection on both servers.
2. Copy $ARTIFACTORY_HOME/data/filestore from the old server to the new server's filestore folder.
3. On the old server, perform a full system export with Exclude Content selected.
4. On the new server, perform a full system import (do not select Exclude Content).
5. Configure all local repositories on the old server to replicate to the new server with Sync Deletes disabled.
6. Switch DNS or network traffic to the new server.
7. Execute all replication jobs on the old server to sync the delta.
8. Shut down the old server.
9. Re-enable garbage collection on the new server.

📘

Note

The near-zero downtime method uses replication to synchronize artifacts deployed during the export/import process, avoiding data loss from the transition window.

---

Filestore Sharding

Filestore sharding increases artifact redundancy at storage time, reducing the risk of data loss before backups occur.

A sharded filestore is implemented across multiple physical mounts (M) with configurable redundancy (R), where R ≤ M. This means each binary can be stored on multiple mounts simultaneously.

Considerations:

• Sharding adds scalability but impacts performance
• Do not exceed 10 shards
• Additional mounts can be added later as storage needs grow
• Use the rebalancing API to distribute redundancy for existing binaries after adding mounts

Sharding complements but does not replace a proper backup strategy. It provides resilience against single-mount failures but not against site-wide disasters.