Transferring Files Between Artifactory Servers

Overview

Use the transfer-files command to transfer (copy) all files stored in one Artifactory instance to a different Artifactory instance. The command allows transferring files from single or multiple repositories. The command expects the relevant repository to already exist on the target instance and have the same name and type as the repositories on the source.

Limitations

Artifacts in remote repository caches are not transferred.
The file transfer process allows transferring files that were created or modified on the source instance after the process started. However, files that were deleted on the source instance after the process started are not deleted on the target instance by the process.
The custom properties of newly created or modified files are updated on the target instance. However, if only the custom properties of a file were modified on the source, but not the file's content, the properties are not modified on the target instance by the process.
The source and target repositories must have the same name and type.
Since the files are pushed from the source to the target instance, the source instance must have a network connection to the target.

Before You Begin

Ensure that you can log in to the UI of both the source and target instances with a user that has admin permissions and that you have the connection details for both instances.
Ensure that all repositories on the source Artifactory instance that you want to transfer also exist on the target instance with the same name and type.
Ensure that JFrog CLI is installed on a machine that has network access to both the source and target instances.

Running the Transfer Process

Step 1 - Set Up the Source Instance for File Transfer

To set up the source instance for file transfer, you must install the data-transfer user plugin on the primary node of the source instance. This section guides you through the installation steps.

Install JFrog CLI on the primary node machine of the source instance. For more information, see Installing JFrog CLI.
Configure the connection details of the source Artifactory instance with your admin credentials by running the following command from the terminal:
```
jf c add source-server
```
Ensure that the JFROG_HOME environment variable is set and holds the value of the JFrog installation directory, which usually points to the /opt/jfrog directory. If the variable is not set, set its value to point to the correct directory. For more information, see the JFrog Product Directory Structure article.
If the source instance has internet access, you can install the data-transfer user plugin automatically by running jf rt transfer-plugin-install source-server from the terminal. If the source instance does not have internet access, install the plugin manually. For more information, see Installing the Data-Transfer User Plugin Manually.

Step 2 - Push the Files from the Source to the Target Instance

Install JFrog CLI on any machine that has access to both the source and the target JFrog instances. To do this, follow the steps described here.

Run the following command to start pushing the files from all the repositories in source instance to the target instance.

jf rt transfer-files source-server target-server

This command may take a few days to push all the files, depending on your system size and your network speed. While the command is running, It displays the transfer progress visually inside the terminal.

If you're running the command in the background, you use the following command to view the transfer progress.

jf rt transfer-files --status

In case you do not wish to transfer the files from all repositories, or wish to run the transfer in phases, you can use the --include-repos and --exclude-repos command options. Run the following command to see the usage of these options.

jf rt transfer-files -h

If the traffic between the source and target instance needs to be routed through an HTTPS proxy, refer to this section.

You can stop the transfer process by hitting on CTRL+C if the process is running in the foreground, or by running the following command, if you're running the process in the background.

jf rt transfer-files --stop

The process will continue from the point it stopped when you re-run the command.

While the file transfer is running, monitor the load on your source instance, and if needed, reduce the transfer speed or increase it for better performance. For more information, see the Controlling the File Transfer Speed section.

A path to an errors summary file will be printed at the end of the run, referring to a generated CSV file. Each line on the summary CSV represents an error of a file that failed to be transferred. On subsequent executions of the jf rt transfer-files command, JFrog CLI will attempt to transfer these files again.

Once the jf rt transfer-files command finishes transferring the files, you can run it again to transfer files which were created or modified during the transfer. You can run the command as many times as needed. Subsequent executions of the command will also attempt to transfer files failed to be transferred during previous executions of the command.

Note:

Read more about how the transfer files works in this section.

Installing the data-transfer User Plugin on the Source Machine Manually

To install the data-transfer user plugin on the source machine manually, follow these steps.

Download the following two files from a machine that has internet access. Download data-transfer.jar from https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/[RELEASE]/lib/data-transfer.jar and dataTransfer.groovy from https://releases.jfrog.io/artifactory/jfrog-releases/data-transfer/[RELEASE]/dataTransfer.groovy
Create a new directory on the primary node machine of the source instance and place the two files you downloaded inside this directory.
Install the data-transfer user plugin by running the following command from the terminal. Replace the [plugin files dir] token with the full path to the directory which includes the plugin files you downloaded.
```
jf rt transfer-plugin-install source-server --dir "[plugin files dir]"
```

Installing JFrog CLI on the Source Instance Machine

Install JFrog CLI on your source instance by using one of the [#JFrog CLI Installers]. For example:

curl -fL https://install-cli.jfrog.io | sh

Note

If the source instance is running as a docker container, and you're not able to install JFrog CLI while inside the container, follow these steps.

Connect to the host machine through the terminal.
Download the JFrog CLI executable into the correct directory by running this command:
curl -fL https://getcli.jfrog.io/v2-jf | sh
Copy the JFrog CLI executable you've just downloaded into the container, by running the following docker command. Make sure to replace [the container name] with the name of the container.
docker cp jf [the container name]:/usr/bin/jf
Connect to the container and run the following command to ensure JFrog CLI is installed:
jf -v

How Does Files Transfer Work?

Files Transfer Phases

The jf rt transfer-files command pushes files from the source to the target instance as follows:

The files are pushed for each repository, one by one, in sequence.
For each repository, the process includes the following three phases:
- Phase 1: Pushes all files in the repository to the target.
- Phase 2: Pushes files that were created or modified after Phase 1 started (diffs).
- Phase 3: Attempts to push files that failed to be transferred in earlier phases or previous executions.
If Phase 1 is complete for a repository, subsequent runs of the jf rt transfer-files command will only trigger Phase 2 and Phase 3. You can run the command as many times as needed until you are ready to move your traffic to the target instance permanently.

Tip: To help reduce the time it takes for Phase 2 to run, you may configure Event-Based Push Replication for some or all of the local repositories on the source instance. With Replication configured, when files are created or updated on the source repository, they are immediately replicated to the corresponding repository on the target instance. The replication can be configured at any time: before, during, or after the file transfer process.

Using Replication

To help reduce the time it takes for Phase 2 to run, you may configure Event Based Push Replication for some or all of the local repositories on the source instance. With Replication configured, when files are created or updated on the source repository, they are immediately replicated to the corresponding repository on the target instance. The replication can be configured at any time. Before, during or after the files transfer process.

Files Transfer State

You can run the jf rt transfer-files command multiple times to transfer files created or updated after previous runs. To achieve this, JFrog CLI stores the current state of the file transfer process in a directory named transfer located under the JFrog CLI home directory (usually ~/.jfrog/transfer).

JFrog CLI uses the state stored in this directory to avoid repeating actions. For example, once Phase 1 is completed for a repository, subsequent command executions will skip Phase 1 and run only Phase 2 and Phase 3.

To ignore the stored state and restart the file transfer from scratch, add the --ignore-state option to the jf rt transfer-files command.

Installing JFrog CLI on a Machine with Network Access to the Source and Target Machines

It is recommended to run the transfer-files command from a machine that has network access to the source Artifactory URL. This allows spreading the transfer load on all the Artifactory cluster nodes. This machine should also have network access to the target Artifactory URL.

Follows these steps to installing JFrog CLI on that machine.

Install JFrog CLI by using one of the [#JFrog CLI Installers]. For example:
```
curl -fL https://install-cli.jfrog.io | sh
```
If your source instance is accessible only through an HTTP/HTTPS proxy, set the proxy environment variable as described [#here].
Configure the connection details of the source Artifactory instance with your admin credentials. Run the following command and follow the instructions.
```
jf c add source-server
```
Configure the connection details of the target Artifactory instance as follows.
```
jf c add target-server
```

Controlling the File Transfer Speed

The jf rt transfer-files command pushes the binaries from the source instance to the target instance. This transfer can take days, depending on the size of the total data transferred, the network bandwidth between the source and the target instance, and additional factors.

Since the process is expected to run while the source instance is still being used, monitor the instance to ensure that the transfer does not add too much load to it. Also, you might decide to increase the load for faster a transfer rate, while you monitor the transfer. This section describes how to control the file transfer speed.

By default, the jf rt transfer-files command uses 8 working threads to push files from the source instance to the target instance. Reducing this value will cause slower transfer speed and lower load on the source instance, and increasing it will do the opposite. We therefore recommend increasing it gradually. This value can be changed while the jf rt transfer-files command is running. There's no need to stop the process to change the total of working threads. The new value set will be cached by JFrog CLI and also used for subsequent runs from the same machine. To set the value, simply run the following interactive command from a new terminal window on the same machine which runs the jf rt transfer-files command.

jf rt transfer-settings

Build-info repositories

When transferring files in build-info repositories, JFrog CLI limits the total of working threads to 8. This is done in order to limit the load on the target instance while transferring build-info.

Routing the Traffic from the Source to the Target Through an HTTPS Proxy

The jf rt transfer-files command pushes the files directly from the source to the target instance over the network. In case the traffic from the source instance needs to be routed through an HTTPS proxy, follow these steps.

Define the proxy details in the source instance UI as described in the Managing Proxies documentation.
When running the jf rt transfer-files command, add the --proxy-key option to the command, with Proxy Key you configured in the UI as the option value. For example, if the Proxy Key you configured is my-proxy-key, run the command as follows:
```
jf rt transfer-files my-source my-target --proxy-key my-proxy-key
```

PreviousRelease Lifecycle Management NextCleaning Up Unreferenced Files from a Git LFS Repository

Last updated 16 days ago