Cloud customer?
Start for Free >
Upgrade in MyJFrog >
What's New in Cloud >

Search





Overview

Artifactory provides you the freedom of choice, hybrid environment support, automation, exhaustive and easily searchable metadata, storage flexibility, and so much more in comparison with Nexus Repository. If your team has decided to switch from Nexus Repository Manager to Artifactory, we have the a tool to make the transition quick and seamless for you. Read on to learn all about it.

The tool supports migration to a self-hosted installation of Artifactory from Nexus Repository Manager OSS and Nexus Repository Manager Pro.

The tool runs on the Nexus Repository Manager machine and migrates the following entities from Nexus Repository Manager to Artifactory.

  • Repositories
  • Artifacts
  • Users
  • Roles
  • Privileges
  • LDAP Connections and Groups

Migrating Privileges

Roles are mapped to Groups and Privileges are mapped to Permission Targets in Artifactory.

In Nexus 3, the following privileges will be migrated:

  • repo-view
  • repo-content-selector

Only "path == ", "or", and "path =^ " types of repo-content-selector conditions are considered. Privileges with other conditions are migrated, but the conditions are not added to those privileges.

Artifactory requires Docker repositories to have names in lower case. The migrator renames all docker repositories to lower case when it migrates the repositories to Artifactory.

When there is an existing repository with the same name as in Artifactory, the migration of artifacts will fail if the repository is of a different type than the Nexus Repository. If there are existing artifacts with same name inside a repository with the same name, the artifact from Nexus overwrites the existing artifact. To avoid these issues, verify that repositories have different names and there are no artifacts with the same name in the current repositories in Artifactory.

In addition, verify that there are no existing users with the same name in Artifactory before you begin migration. The migration script overwrites the existing users with the users from Nexus Repository Manager.

The tool uses Docker, installed on the Nexus Repository Manager machine, to facilitate the migration. 

Download the migration script from here.


Before You Begin

System Requirements

Before beginning migration, verify that the following system requirements are in place.

  • A fully-configured Artifactory instance. For more information on installing Artifactory, see Installing Artifactory.
  • The Artifactory host machine must have enough space to handle the temp cache directory of Nexus Migrator if the Nexus Repository uses the S3 blob store. You can get the minimum required space for temp cache directory with the following formula:

     Size of the largest file in the repository * Number of threads in the Artifactory instance

    The Artifactory instance must have additional memory equivalent to this value over the memory in the Nexus Repository instance. For example, if the largest file in the repository is 300 MB and the number of threads in the Artifactory machine is 4, the minimum space requirement for temp cache directory is 1200 MB.

  • Script execution is enabled in Nexus Repository Manager. For more information, refer to Nexus Repository Manager Documentation. A warning appears in Nexus Repository Manager after you enable script execution. You must run the migration tool from the Nexus Repository Manager host machine.
  • Ensure that the following directories exist in the Nexus Repository Manager host machine:
    • $datadir/etc and $datadir/blob for Nexus 3.
    • $datadir/conf and $datadir/storage for Nexus 2.

Migration is supported only from Nexus Repository Manager running on a Linux machine.

Prerequisites

  • Install Docker in the machine that hosts Nexus Repository Manager. 
  • The user in the Artifactory machine and the Nexus Repository Manager machine must have administrator privileges.

Working with Artifactory on Self-signed SSL Certificates

If your Artifactory is setup with self-signed SSL certificates, you need to create the following directory and copy the certificates under it.

mkdir -p <working directory>/migration/security/certs

JFrog Subscription Levels

Page Contents


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

  1. Run the following command to migrate all entities in a single step.

    ./jfrog-nexus-migrator-<version>.sh all
  2. 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.

  3. 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.

Artifactory does not support repositories with names that start with any character other than an alphabet. Therefore, the migrator tool renames these repositories as jfrog-<repository name in Nexus>. For example, if the repository name in Nexus Repository Manager is 101-Maven, the repository is renamed as jfrog-101-Maven in Artifactory. If you want to configure this name, you must run the migration script in multiple stages.


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.

  1. config

  2. getConfig

  3. createRepo

  4. migrateArtifact

  5. migrateSecurity

The following table provides information about the options available with the migrator script.

Option

Description

all

Run the migration script in a single step.

config, c

Configure information about Artifactory and Nexus Repository.

getConfig, gc

Get configuration information from Nexus Repository.

createRepo, cr

Create target repositories in Artifactory.

migrateArtifact, ma

Migrate artifacts from Nexus Repository to Artifactory.

You can also use the optional --repos command in addition to specify the repositories to migrate. 

For example, /jfrog-nexus-migrator-<version>.sh ma --repos="docker-local,maven-release" command, migrates docker-local and maven-release repositories and ignores the rest of the repositories.

You can also wildcards inputs to migrate all repositories that satisfies the condition. 

For example, /jfrog-nexus-migrator-<version>.sh ma --repos="docker*,maven*" command, migrates all repositories that start with docker or maven.

migrateSecurity, ms

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 tool migrates only those repositories and security entities added after you paused the process. In case of migration on a Nexus 2 installation, the tool migrates all repositories and security entities in the Nexus repository regardless whether they were migrated before you paused the migration process.

The 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
  • repoStatus.yaml (applies only to Nexus 3 migration)

Editing Migration Configuration [OPTIONAL]

After you run the migration tool with the config option, the tool creates the migrationConfig.yaml file inside <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
    repoRegex:
    - source: ^[0-9](.*)$
      target: jfrog-[REPO]
    userRegex:
    - source: ^[0-9](.*)$
      target: jfrog-[USER]
	- source: \s
      target: '-'
    groupRegex:
    - source: ^[0-9](.*)$
      target: jfrog-[GROUP]
	- source: \s
      target: '-'
    ldapRegex:
    - source: ^[0-9](.*)$
      target: jfrog-[LDAP]
	- source: \s
      target: '-'
    permRegex:
    - source: ^[0-9](.*)$
      target: jfrog-[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 migration 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.


Editing Repository Names [OPTIONAL]

After you run the migration tool with the getconfig option, the tool creates the repositories.list file.

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: jfrog-123nuget
    - source: 123Py
      target: jfrog-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: jfrog-123maven

You can edit values against the target field to the desired repository name in Artifactory.


Editing Security Entities [OPTIONAL]

After you run the migration tool with the getconfig option, the tool also creates the securityRegexMap.list file.

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: jfrog-8TestUserName
groups:
    8test: jfrog-8test
permissions:
    8privtest: jfrog-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 migration tool with the getconfig option, the tool creates the repositories.yaml file. 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
        123maven:
            repoLayout: maven-2-default
            type: maven
            handleReleases: "true"
        123nuget:
            repoLayout: simple-default
            type: nuget
        maven-releases:
            repoLayout: maven-2-default
            type: maven
            handleReleases: "true"
        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 migration tool with the getconfig option, the tool creates the security.json file. 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 of the JSON file.

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": "jfrog-8test",
            "description": "test"
        }
    ],
    "permissions": [
        {
            "name": "jfrog-8privtest",
            "includesPattern": "**",
            "principals": {
                "groups": {
                    "jfrog-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 tool creates a file, repoStatus.yaml, that maintains the status of migration 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.

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 RepoStatus.yaml file. If migration is aborted for any reason, the 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 RepoStatus.yaml file. If you run the migration process again, the tool checks the RepoStatus.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 RepoStatus.yaml file and run the migration process again.

  • No labels
Copyright © 2021 JFrog Ltd.