Migration Process
You can run the migration script, jfrog-nexus-migrator-<version>.sh, in a single stage and enter the required inputs for the different stages. You can also run the migration script to complete the different stages separately. If you run the stages separately, verify that you follow the correct sequence when you run the script.
You can run the migration process more than once to load any new repositories, artifacts, and security configuration in Nexus Repository Manager to Artifactory.
Running the Migration Script in Single Step
Run the following command to migrate all entities in a single step.
./jfrog-nexus-migrator-<version>.sh all
Add the following Artifactory configuration information.
JFrog Platform Server Name: Identifier for the JFrog Platform server.
JFrog Platform URL: URL to access the JFrog Platform that contains the Artifactory instance.
JFrog Access Token: API token to access the JFrog Platform. You can leave the field as blank and provide username and password in the subsequent steps.
JFrog Username: The username of a user with administrator privileges.
JFrog Password or API key: The API key or the password.
Enter the following configuration information for Nexus Server.
Nexus Working Directory
Nexus Repository Manager URL
Nexus Repository Manager Username
Nexus Repository Manager Password
Default Password for Artifactory Users
In the Nexus Repository Manager, navigate to Administration > System Information. The workingDirectory field provides the location of the Nexus Working Directory.
Enter the private IP of the Nexus server to improve the performance since the migration script runs on the same machine. Set the URL as http://<private ip>:<port>. If there is any context path configured for the Nexus server, enter the URL as http://<private ip>:<port>/<context-path>.
The default password for Artifactory users must adhere to the following rules:
- Minimum of eight characters
- Contain at least one number
- Contain at least one lower case alphabet
- Contain at least one upper case alphabet
The script fetches the configuration information from Nexus, creates corresponding repositories in Artifactory, migrates artifacts to Artifactory, and migrates security configuration to Artifactory. You can check the details of the artifacts and configuration migrated to Artifactory in the migration.log file, available in the working directory. The script creates YAML files and JSON files based on Nexus inside the folder, <working directory>/migration/nexus-migrator.
Check migration.log file to verify the status of migration. The log file details the migration status of the repositories, artifacts, and security entities.
Running the Migration Script in Multiple Stages
Run the script with the options in the following order if you want to go through the different stages individually.
configgetConfigcreateRepomigrateArtifactmigrateSecurity
The following table provides information about the options available with the migrator script.
Option | Description |
|---|---|
| Run the migration script in a single step. |
| Configure information about Artifactory and Nexus Repository. |
| Get configuration information from Nexus Repository. |
| Create target repositories in Artifactory. |
| Migrate artifacts from Nexus Repository to Artifactory. You can also use the optional For example, You can also wildcards inputs to migrate all repositories that satisfies the condition. For example, You can also use the following optional commands when you migrate from Nexus 3.
|
| Migrate users, groups, and permission targets from Nexus Repository to Artifactory. |
You can run the migration script with the getConfig, createRepo, migrateArtifact, and migrateSecurity options in sequence to load the new objects from the currently configured Nexus Repository Manager to Artifactory. If you pause the migration process on a Nexus 3 installation and resume at a later time, the migrator tool migrates only those repositories and security entities added after you paused the process. In case of migration on a Nexus 2 installation, the migrator tool migrates all repositories and security entities in the Nexus repository regardless whether they were migrated before you paused the migration process.
If you convert an existing repository to a federated repository, the migrator tool will migrate new artifacts to the federated repository.
The migrator tool creates YAML files and JSON files based on the Nexus Repository Manager inside the folder, <working directory>/migration/nexus-migrator.
The migrator tool creates the following configuration files:
- migrationConfig.yaml
- repositories.list
- repositories.yaml
- security.json
- securityLdapConf.yaml
- securityRegexMap.list
Editing Migration Configuration [OPTIONAL]
After you run the migrator tool with the config option, the migrator tool creates the migrationConfig.yaml file inside the folder, <working directory>/migration/nexus-migrator.
The following example shows a sample migrationConfig.yaml file.
config:
artifactory:
serverId: Arty
migrator:
threads: 2
workDir: /root/.jfrog
defaultPassword: xxxxxxxxxxxx
checksumCalc: false
logging: INFO
security:
convertExternalUsersGroupsToInternal: false
repoRegex:
- source: ^[0-9](.*)$
target: m-[REPO]
userRegex:
- source: ^[0-9](.*)$
target: m-[USER]
- source: \s
target: '-'
groupRegex:
- source: ^[0-9](.*)$
target: m-[GROUP]
- source: \s
target: '-'
ldapRegex:
- source: ^[0-9](.*)$
target: m-[LDAP]
- source: \s
target: '-'
permRegex:
- source: ^[0-9](.*)$
target: m-[PERM]
nexus:
majorVersion: 3
minorVersion: 32
url: http://xx.xx.xx.xxx:8081
username: admin
password: xxxxxx
dataDir: /opt/sonatype-work/nexus3/
Enabling checksum for artifact upload will increase memory utilization; therefore, verify that the Nexus machine has sufficient free resources if checksumCalc: true.
Update the value of threads under migrator in the YAML file to set the number of threads to be used by the migrator tool. By default, the number of threads is set to half the number of cores in the machine. If you find the performance of the Nexus Repository Manager machine to be sluggish, you can reduce this number and run the migrator tool again.
Update the value of target under repoRegex in the YAML file to set the name to prepend to those repositories with names starting with non-alphabets. Do not edit the values in the square bracket (such as [REPO]) since they are keywords used in Nexus. You can also add a new source and target to use a different name for a repository in Artifactory. For example, if there are repositories that start with the name "dfault" and you want to change it as "default", you can do so by adding a new source and target with the required values. If you want to replace a substring in the name of a repository, a user, group, LDAP settings name, LDAP group settings name, or permission, you can provide a regular expression to match the substring in the source and provide the replacement in the target. By default, entries are added in the migrationConfig.yaml file to replace space characters with a hyphen ( - ).
Update the value of logging under migrator in the YAML file to set the logging level. By default, the level is set as INFO. You can change the value to DEBUG to get more log messages to help you debug issues.
Set the value of convertExternalUsersGroupsToInternal to true if you want to convert all users and groups from an external source (for example, LDAP) to internal users and groups in artifactory.
Editing Repository Names [OPTIONAL]
After you run the migrator tool with the getconfig option, the migrator tool creates the repositories.list file inside the folder, <working directory>/migration/nexus-migrator.
The repositories.list file contains the list of repositories in Nexus and the corresponding names for the repositories to be created in Artifactory. You can edit the value of the repositories in Artifactory to any valid value supported by Artifactory.
The following example shows a sample repositories.list file.
repoName:
- source: 123nuget
target: m-123nuget
- source: 123Py
target: m-123Py
- source: maven-snapshots
target: maven-snapshots
- source: maven-central
target: maven-central
- source: nuget-group
target: nuget-group
- source: nuget.org-proxy
target: nuget.org-proxy
- source: maven-releases
target: maven-releases
- source: nuget-hosted
target: nuget-hosted
- source: maven-public
target: maven-public
- source: 123maven
target: m-123maven
You can edit values against the target field to the desired repository name in Artifactory.
Editing Security Entities [OPTIONAL]
After you run the migrator tool with the getconfig option, the migrator tool creates the securityRegexMap.list file inside the folder, <working directory>/migration/nexus-migrator.
The securityRegexMap.list file contains the list of security entities in Nexus and the corresponding names for the entities to be created in Artifactory. You can edit the value of the entities to any valid value supported by Artifactory.
The following example shows a sample securityRegexMap.list file.
users:
8TestUserName: m-8TestUserName
groups:
8test: m-8test
permissions:
8privtest: m-8privtest
You can edit values against the target field to the desired entity name in Artifactory.
Avoiding Repositories from Migration [OPTIONAL]
After you run the migrator tool with the getconfig option, the migrator tool creates the repositories.yaml file inside the folder, <working directory>/migration/nexus-migrator.
The repositories.yaml file contains the details of the repositories to be migrated to Artifactory. You can delete the repositories that you do not want to be migrated from this list.
The following example shows a sample repositories.yaml file.
Repositories:
localRepositories:
123Py:
repoLayout: simple-default
type: pypi
status: completed
123maven:
repoLayout: maven-2-default
type: maven
handleReleases: "true"
status: in_progress
123nuget:
repoLayout: simple-default
type: nuget
status: completed
maven-releases:
repoLayout: maven-2-default
type: maven
handleReleases: "true"
status: completed
maven-snapshots:
repoLayout: maven-2-default
type: maven
handleReleases: "true"
nuget-hosted:
repoLayout: simple-default
type: nuget
remoteRepositories:
maven-central:
type: maven
repoLayout: maven-2-default
url: https://repo1.maven.org/maven2/
handleReleases: "true"
nuget.org-proxy:
nuget:
downloadContextPath: api/v2/package
feedContextPath: api/v2
type: nuget
repoLayout: simple-default
url: https://api.nuget.org/v3/index.json
virtualRepositories:
maven-public:
type: maven
repositories:
- maven-releases
- maven-snapshots
- maven-central
repoLayout: maven-2-default
nuget-group:
type: nuget
repositories:
- nuget-hosted
- nuget.org-proxy
repoLayout: simple-default
Blobstores:
- name: default
type: File
path: default
You can delete the repository name and the corresponding repository block from the repositories.yaml file to avoid migration of the repository to Artifactory.
Avoiding Security Entities from Migration [OPTIONAL]
After you run the migrator tool with the getconfig option, the migrator tool creates the security.json file inside the folder, <working directory>/migration/nexus-migrator.
The security.json file contains the details of the security entities to be migrated to Artifactory. You can delete the entities that you do not want to be migrated from this list.
You can delete the entity name and the corresponding block from the security.json file to avoid migration of the entity to Artifactory.
If you remove any entity, remember to also remove its reference and any other section that is related to it. For example, if you remove a group section, you will need to remove that group name from any privileges that reference it.
The password field in the JSON file is base64 encoded. If you wish to change the password, enter the base64 encoded value of the password in the password field.
The following example shows a sample security.json file.
{
"users": [
{
"name": "deployment",
"email": "changeme1@yourcompany.com",
"password": "UGFzc3dvcmRAMTIz",
"realm": "internal",
"groups": [
"readers"
]
},
{
"name": "testadmin",
"email": "a@gmail.com",
"password": "UGFzc3dvcmRAMTIz",
"admin": true,
"realm": "internal",
"groups": [
"readers"
]
},
{
"name": "normaluser",
"email": "test@gmail.com",
"password": "UGFzc3dvcmRAMTIz",
"realm": "internal",
"groups": [
"TestPrivRole",
"readers"
]
}
],
"groups": [
{
"name": "TestPrivRole",
"description": "TestPrivRole"
},
{
"name": "m-8test",
"description": "test"
}
],
"permissions": [
{
"name": "m-8privtest",
"includesPattern": "**",
"principals": {
"groups": {
"m-8test": [
"r",
"w",
"d",
"n",
"m"
]
}
},
"repositories": [
"test1"
]
},
{
"name": "testcustom",
"includesPattern": "**",
"principals": {},
"repositories": [
"ANY"
]
}
]
}
Repository Migration Status
Migration of artifacts is done for each repository sequentially. the migrator tool creates a file, repositories.yaml, that maintains the migration status for each repository. The file contains the status of the repositories that are processed by the migrator tool. A repository can be in the in_progress state or completed state. The in_progress state indicates that the migration has started, but not complete. The completed state indicates that the artifact migration is successful. If the migration has not started, the status field is absent for the repository.
Migration status is maintained only for migration from Nexus 3.
in_progress
When the migrator tool starts migrating the artifacts in a repository, the status for that repository is set as in_progress in the repositories.yaml file. If migration is aborted for any reason, the migrator tool checks for the existence of the artifacts in the migrated repository in Artifactory and migrates only those files that are not already available.
completed
When the migration of all artifacts in a repository is complete, the migrator tool sets the status as completed in the repositories.yaml file. If you run the migration process again, the migrator tool checks the repositories.yaml file and skips the repositories that have the status as completed. If you know there are new artifacts added to that repository and want to migrate the new artifacts to Artifactory, set the status of the repository as in_progress and run the migration process again. If you want to run migration on the entire repository again, remove the entry for the repository from the repositories.yaml file, and run the migration process again.
