{"action":"created","comment":{"url":"https://api.github.com/repos/sonatype/nexus-book/pulls/comments/77241516","id":77241516,"diff_hunk":"@@ -1,298 +1,406 @@\n [[upgrading]]\n-==  Upgrading {nxrm}\n+==  Upgrading {nxrm} 3.1 or Later\n {inall}\n \n [[upgrade-introduction]]\n === Introduction\n \n-The upgrade feature provides a built-in supported method for replicating components and configurations from \n-{nxrm} versions 2.14 to 3.1. Future iterations of this feature will be available for versions beyond both 2.14 \n-and 3.1, alike.\n+{nxrm} 3 represents a shift in design that now supports a wider set of features requested by customers, as well\n+as a platform for a modern, expanded set of functionality still to come. Given these changes, many to the core\n+architecture, the upgrade process requires more attention than in previous versions.\n \n-This tool helps you build an upgrade plan which allows version 3 to talk to version 2 by way of a \n-capability that communicates with the upgrade tool. The plan you create with version 3 will provide a \n-wizard that guides you through an upgrade from the latest version of 2.x or higher to {nxrm} 3.1 or higher.\n+In this chapter, we've isolated the most common path for the upgrade process from {nxrm} version 2.14 (or later) \n+to 3.1 (or later) only. To help facilitate this process, capabilities have been added in both version 2.14 (or \n+later) and 3.1 (or later). Where appropriate we have also highlighted other upgrade paths for previous versions \n+as well. However, it's important to keep in mind that there may be specific items unique to your installation and \n+upgrade needs. For specific help outside this more standard path consult Sonatype's link:https://support.sonatype.com/hc/en-us/sections/204911768-Installation-Upgrade-and-Compatibility[Support \n+Knowledge Base articles], or contact support directly (available for {pro} customers).\n \n-During the majority of the upgrade process, version 2 should remain functioning at high capacity. You or your \n-organization should put strong emphasis on performance and stability when designing the upgrade plan.\n+[[why-upgrade]]\n+=== Why Upgrade?\n \n-NOTE: This chapter will cover a special feature used to upgrade from {nxrm} 2 to 3. However, the repository \n-manager provides alternative methods to upgrade if you are currently running older versions of 3, all the way \n-back to milestone 7. See our support knowledge base to walk you through the steps to upgrade from \n-https://support.sonatype.com/hc/en-us/articles/222159808[milestone 7 of version 3 to 3.0.0 final] or \n-https://support.sonatype.com/hc/en-us/articles/217967608[version 3.0.0 to a later version].\n+As of version 3.1 (or later) (or later) there is now wider feature and functionality equivalency to {nxrm} 2.\n+Highlights of new functionality available in version 3.1 (or later) include:\n \n-////\n-Expand this intro to give readers a 10-foot view of the upgrade tool\n-////\n+* Component Fabric (High Availability)\n+* Expanded Format Support\n+* Enhanced Metadata\n \n-[[upgrade-architecture]]\n-=== Supported Architecture for Upgrading\n+Of course, the choice to upgrade ultimately depends on the features your team is using today. In\n+many cases upgrading to version 3.1 (or later) 3.1 (or later)provides an enhanced set of features to support\n+modern development practices. However, it is a good idea to review Sonatype's support site to compare\n+link:https://support.sonatype.com/hc/en-us/articles/226495428-Nexus-Repository-Manager-Format-Language-Support[format support], link:https://support.sonatype.com/hc/en-us/articles/226489388-Nexus-Repository-Manager-2-x-to-3-x-Feature-Equivalency[feature equivalency], and link:[compatibility across versions].\n \n-There are two architectures that can be used for upgrading. You can have separate version 2 and version 3 \n-servers, or you can have both versions of 2 and 3 running on the same server in different service locations.\n- \n-[[upgrade-prep]]\n-=== Preparing for an Upgrade\n+[[upgrade-types]]\n+=== Upgrading Within Specific Versions of {nxrm}\n \n-If you decide to update versions 2 and 3 to the latest instances that allow you to upgrade, the most critical \n-decisions you or your organization make around the upgrade plan should include: \n+Upgrading from {nxrm} 2 to 3 requires version 2.14 (or later) and 3.1 (or later). To upgrade from an\n+older version, refer to the specific sections below.\n \n-* where they want your components to be transferred to when the upgrade is complete\n-* which of the two architectures is best for your upgrade plan\n-* designating a maintenance window for version 2 so you can take it down for a period, and the upgrade can \n-proceed with interruption\n-* how your system storage is structured and what ingestion methods are available to you\n+[[upgrade-version-two]]\n+==== Upgrading from 2.x to 2.14 (or later)\n \n-The upgrade tool only allows one transfer at a time. After it starts you must wait for the upgrade \n-to complete if you decide to transfer more content. If you press 'Abort' during the 'Preparing' or \n-'Synchronizing' phases the contents will not be transferred.\n+If you have a version of 2.x that is not 2.14 (or later), you must upgrade before starting the upgrade to {nxrm}\n+3. This requires that you first redirect the contents of the existing instance (2.x) to a newly downloaded\n+version of the latest instance (2.14 or later). See the\n+https://books.sonatype.com/nexus-book/reference/upgrading.html[Upgrading] chapter in the version 2 book for\n+instructions.\n \n-[[upgrade-performance]]\n-==== Performance and Tuning for Upgrading\n+[[upgrade-version-three]]\n+==== Upgrading from Milestone Releases to 3.1 (or later)\n+\n+Upgrading to the latest version of {nxrm} 3 can only be performed by users who have updated to the version 3\n+milestone 7 release, and then on to the latest the latest version of {nxrm} 3. This is a manual process, and\n+there are two ways to upgrade milestone releases to newer version: with the installer application or the\n+distribution file.\n \n-There are several ways to tune {nxrm} 2.14, or later, for a quicker upgrade. Review the current configuration in \n-your compatible version of 2 to clean up content that may hinder performance.\n+Before execution of this type of upgrade, be sure to manually back up the milestone 7 data directory to another\n+location. This is a crucial step when upgrading to newer versions. Follow the steps in the support\n+https://support.sonatype.com/hc/en-us/articles/217967608[knowledge base article].\n \n-When considering upgrade time and speed, take into account all enabled scheduled tasks on your version 2 \n-instance that you may not need. Depending on your configuration of version 2 you could optimize the \n-performance of the application by:\n+NOTE: Even if you choose not to update to version 3.1 (or later), if you're using a version 3 milestone release,\n+the instructions above apply.\n+\n+[[upgrade-process-expectations]]\n+=== Upgrade Process and Expectations\n+\n+The process of upgrading {nxrm} 2 to 3, is similar to any major enterprise application, and should be managed via\n+an upgrade plan. The upgrade plan is really just a specific checklist of all the steps required to perform\n+the upgrade from version 2.14 (or later) to 3.1 (or later).\n+\n+While the upgrade process is underway, you can continue to use version 2.14 (or later). Any repository content\n+that’s added, updated, or deleted is picked up by version 3.1 (or later). However, configuration changes are not.\n+\n+You should not make changes to items such as realm settings, permissions, roles, role assignments, HTTP\n+configuration, SSL certificates, or add new repositories. These types of configuration changes can cause the\n+upgrade process to fail.\n+\n+[[upgraded]]\n+==== What Is Upgraded\n+\n+As mentioned {nxrm} 3 represents a shift in design. This shift has involved a completely new architecture to\n+support more advanced features that support today's modern development practices and beyond. As such, a number of\n+core changes to data stored in version 3.1 (or later) will occur as part of the upgrade process. This includes:\n+\n+* *Component Storage Format (Files to Blobs)* - Components (artifacts) in {nxrm} 2 are stored as individual files\n+  on disk. {nxrm} 3 stores components as <<admin-repository-blobstores,blobs>>. The conversion process requires\n+  {nxrm} to iterate over every component stored in {nxrm}. This takes the bulk of the time required for\n+  the upgrade process.\n+* *Settings and Metadata* - Settings and some component metadata in {nxrm} 2 are stored across many files.\n+  Conversely, {nxrm} 3 loads equivalent settings into an link:http://http://orientdb.com/[OrientDB] database.\n+\n+[[not-upgraded]]\n+==== What Is Not Upgraded\n+\n+The file structures within your repository manager environment will differ between version 2.14 (or later) and\n+3.1 (or later). This means some support tools and configurations are not be included in the upgrade process. \n+Before <<upgrade-prep,preparing>> starting that process, as part of your plan, consider which setting and \n+configuration items will need to be reconfigured. The settings and configuration items list below will not be \n+upgraded automatically:\n+\n+* custom branding\n+* virtual repositories\n+* Java VM Settings, including custom system properties or variables\n+* operating system `nexus` service scripts\n+* operating system optimizations, such as increasing allowable open file handles\n+* environment variables affecting values used to control the repository manager\n+* third-party or custom-developed plugins develop \n+* Jetty Server XML Configuration Files\n+* unimplemented repository formats\n+* manual edits to other files under the `nexus` installation directory, such as edits to\n+  `nexus/WEB-INF/classes/ehcache.xml`\n+* custom log levels or edits to `logback.xml` configuration files (e.g.. custom log file rotation, file naming,\n+  log patterns)\n+\n+[[upgrade-repo-support]]\n+==== Repository Format Support\n \n-* disabling system feeds\n-* disabling repair tasks\n-* reviewing the enabled Custom Metadata capability\n-* removing unused snapshots\n-* removing old scheduled tasks not in use\n-* removing repositories no longer supported by the repository manager (e.g. \n-https://support.sonatype.com/hc/en-us/articles/217611787-codehaus-org-Repositories-Should-Be-Removed-From-Your-Nexus-Instance[Codehaus repositories])\n-* disabling 'Rebuild Maven Metadata Files' scheduled tasks\n-* increasing your file size limit\n+{nxrm} 3 provides a greatly expanded set of format support. For a complete list of formats supported across\n+versions, please see the\n+link:https://support.sonatype.com/hc/en-us/articles/226495428-Nexus-Repository-Manager-Format-Language-Supportassociated[KB article]. However, the list below represents repository formats as of version 2.14 (or later) that will\n+be included in the upgrade process to version 3.1 (or later).\n \n+* npm\n+* NuGet\n+* Site/Raw\n+* Maven2\n ////\n-This section can be expanded; each bullet point can attributed to real-life scenarios\n+* RubyGems\n ////\n \n-Another factor, the quality of your network, will arbitrarily impact the speed of ingestion methods \n-(e.g HTTP download).\n+[[upgrade-prep]]\n+=== Designing Your Upgrade Plan\n \n-[[upgrade-file-systems]]\n-==== File System Considerations\n+If you decide to upgrade, the following represent the most critical decisions to be made when creating your\n+upgrade plan:\n \n-As mentioned in <<admin-repository-blobstores,Chapter 4>> you can create new blob stores and determine the \n-amount of space for each, if more than one exists. In version 3, consider how you want to organize this storage \n-mechanism. Components in {nxrm} 2.x are stored as individual files on disk. {nxrm} version 3 stores components as \n-blobs. The conversion process requires the repository manager to iterate every component in your storage. This \n-process will take the bulk of the time required for upgrading.\n+* Identification of a maintenance window for version 2.14 (or later), allowing the upgrade to proceed without\n+  interruption\n+* Selection of an installation scenario that best supports your upgrade plan\n+* Selection of an upgrade method\n+* Procurement of required system storage, as well as location for content to be transferred to\n+* Identification of configurations that may result in failure, and prevent upgrade of certain components\n+* Review of security settings, and associated differences between version 2.14 (or later) and 3.1 (or later)\n+* Optimization, Performance, and Tuning*\n \n-When upgrading, make sure you have enough storage capacity in the destined file system(s). If you are using \n-the hard linking ingestion method, the bytes themselves are not duplicated (saving space), but you must ensure \n-there are enough free inodes for the content you want to transfer during upgrade.\n+[[upgrade-architecture]]\n+==== Supported Installation Scenarios for Upgrading\n \n-In the instance you have configured your repository manager HTTP context and path as a reverse proxy server\n-the traffic coming from version 2 could be busy, as you start the upgrade steps. Version 3 starts pulling \n-over the content with the upgrade tool as content is added to version 2.\n+There are two supported scenarios for upgrading:\n \n-NOTE: HTTP download ingestion puts more load on your version 2 instance than other ingestion methods, because \n-this method requires version 2 to serve all of the content. Copying and hard linking only have to be told where \n-the file is, and they obtain it from the file system, directly.\n+* Separate servers for version 2.14 (or later) and 3.1 (or later)\n+* Both versions of 2.14 (or later) and 3.1 (or later) running on the same server, but in different service\n+  locations\n \n-[[upgrade-content-prep]]\n-=== Preparing Content for Upgrade\n+//// \n+Begs the question if there are unsupported, or something we can add here to preven support questions.\n+////\n \n-*IQ Server*\n+[[upgrade-methods]]\n+==== Upgrade Methods\n \n-{inrmonly}\n+Upgrade is made possible by specific upgrade capabilities in both version 2.14 (or later) and 3.1 (or later)\n+(Upgrade: Agent and Upgrade, respectively), and an upgrade tool provided in version 3.1 (or later). Once the\n+'Upgrade: Agent' capability, mentioned in <<upgrade-start>>, is enabled and both repository manager instances are\n+communicating, you should consider one of three upgrade methods:\n \n-If upgrading {iq} settings and configuration, ensure that your licenses include the integration for both versions \n-2 and 3. Your configuration for 'IQ Server URL', 'Username', 'Password', and 'Request Timeout' will be included \n-in the upgrade. Additional configuration, such as analysis properties, trust store usage, and the enabled {iq} \n-connection itself will be replicated from versions 2 to 3.\n+////\n+Expand on what types of architectures might benefit from the listed options\n+////\n \n-*NuGet API Key*\n+*HTTP Downloading*\n \n-The upgrade tool will add all keys to {nxrm} 3 that are present in {nxrm} 2.14 when asked, even if the version 2 \n-NuGet API Key Realm is not active. This is because there is no explicit on or off setting for NuGet keys.\n+HTTP downloading is an upgrade method in which version 3.1 (or later) will make HTTP requests to version 2.14 (or\n+later). This is the slowest option for upgrading.\n \n-*Repository IDs*\n+If version 2.14 (or later) and 3.1 (or later) are on different machines and do not share access to the same file\n+system storage, you must use the HTTP download method.\n \n-Before migrating repositories to version 3, find the repository IDs in version 2 and plan how you will \n-rename any conflicting repositories in version 3. Contact our https://support.sonatype.com/hc/en-us[support \n-team] to learn on how to do this safely.\n+*File System Copying*\n \n-*Repository Groups*\n+In this upgrade method, version 2.14 (or later) will tell version 3.1 (or later) the location of the file and\n+where to retrieve the content.\n \n-Review the contents of your repository groups. If empty, the upgrade plan will not permit transfer, as validation \n-will fail.\n+This upgrade method will work if versions 2.14 (or later) and 3.1 (or later) are on the same machine, and\n+configured in a way that the mounts are accessible by the same path (from one machine to the other), this option\n+will work. It is a slightly faster process than the HTTP Download method, and has less impact on the performance\n+of version 2.14 (or later).\n \n-*User Tokens*\n+*Hard Linking*\n \n-The upgrade tool can only replicate pre-existing user tokens from version 2 to 3 if the 'Enabled' box in version \n-2 is checked. In version 2, click the 'User Token' tab, in the 'Administration' menu, and enable the setting. \n+This upgrade method will only work on the same {nxrm} filesystem in place. This means you must have configured\n+your instance of version 3.1 (or later) in such a way that you have a blob store defined in an appropriate\n+location where hard linking is possible.\n+\n+This is the fastest option because you will not have to move the bytes around.\n \n ////\n-link to user token chapter\n+We should say what this method is, similar to the others. It lacks some detail, especially about how one would\n+convert from 2.14 (or later) file system to the 3.1 (or later) blob store.\n ////\n \n+NOTE: The HTTP download method puts more load on your version 2.14 (or later) instance than other methods,\n+because this method requires version 2.14 (or later) to serve all of the content. Copying and hard linking only\n+have to be told where the file is, and they obtain it from the file system, directly.\n \n-*Repository Health Check and SSL Health Check*\n+[[upgrade-file-systems]]\n+==== File System Considerations\n \n-You can include both your existing {rhc} and its corresponding SSL trust store configuration when you upgrade \n-from version 2 to version 3. If you are a {oss} user you only have the ability to upgrade your settings from the \n-'Health Check: Configuration' capability. If you run {pro}, you can also upgrade your existing 'SSL: Health \n-Check' settings in version 2 to version 3. After the upgrade is complete settings for both 'Health Check: \n-Configuration' and 'SSL: Health Check' capabilities will be enabled in version 3, as they were in version 2.\n+While discussed in greater detail in <<admin-repository-blobstores,Chapter 4>>, {nxrm} 3 does allow you to\n+create new blob stores and determine the amount of space for each, if more than one exists. However, it is\n+important to consider how you want to organize this storage mechanism, and the differences in previous versions.\n \n-*Repository Targets and Target Privileges*\n+When upgrading, make sure you have enough storage capacity in the destination file system(s). For instance, if you\n+are using the hard linking <<upgrade-methods,method>>, the bytes themselves are not duplicated (saving space),\n+but you must ensure there are enough free inodes for the content you want to transfer during the upgrade process.\n \n-If upgrading your Repository Targets from version 2 to version 3, it is recommended you also upgrade your Target \n-Privileges and vice versa.  If you do not upgrade both, you may find that you need to make further adjustments to \n-version 3 configuration to have things work as they did in version 2.\n+Finally, if you have configured your repository manager HTTP context and path as a reverse proxy server,\n+the traffic coming from version 2.14 (or later) could be busy as you start the upgrade steps. \n \n-////\n-[[upgrade-security]]\n-==== Security and Upgrade\n+[[upgrade-support]]\n+==== Configuration Details for Upgrading\n \n-TBD\n+Due to fundamental changes in file structure between {nxrm} 2 and 3, you should review and compare the\n+configuration details to prevent any failures.\n \n-potential new section\n-////\n+*Repository IDs*\n \n-[[upgrade-methods]]\n-=== Upgrade Methods\n+Before upgrading repositories to version 3.1 (or later), find the repository IDs in version 2.14 (or later) and\n+plan how you will rename any conflicting repositories in version 3.1 (or later). Your repository IDs in version\n+2.14 (or later) may differ by letter case. This means you may have to manually edit the IDs in before the upgrade \n+process. Contact our link:https://support.sonatype.com/hc/en-us[support team] to learn on how to do this safely.\n \n-In order to start an upgrade, version 2 has to listen for version 3 to initiate communication. This is the core \n-property of the 'Migration: Agent'. When the upgrade wizard in version 3 helps you build an upgrade plan, it \n-talks to your version 2 instance through the migration-agent to find out what repositories exist (e.g. to list \n-them in the wizard user interface). When you pick them, version 3 tells version 2 to start compiling a full list \n-of what it has that needs replicating in each of those repositories. Ultimately, this creates a scheduled task \n-that walks through the repository storage folder, lists the files, then synchronizes them, storing the metadata \n-in the changelog database.\n+*Repository Groups*\n \n-On the version 3 side, components are stored as blobs. The conversion process requires version 3 to iterate over \n-every component in your storage.\n+Review the contents of your repository groups. If empty, the upgrade plan will not permit transfer, as validation \n+will fail.\n \n-Once the 'Migration: Agent' capability, mentioned in <<upgrade-start>>, is enabled and both repository \n-manager instances are stood up and communicating, you can consider one of three ingestion methods: HTTP download, \n-file system copying, or hard linking. The choice of ingestion method can be made on a repository-by-repository \n-basis, but there is an upgrade-wide default.\n+*User Tokens*\n \n-////\n-Expand on what types of architectures might benefit from the listed options\n-////\n+The upgrade tool can only replicate pre-existing user tokens from version 2.14 (or later) to 3.1 (or later) if\n+the 'Enabled' box in version 2.14 (or later) is checked. In version 2.14 (or later), click the 'User Token' tab,\n+in the 'Administration' menu, and enable the setting.\n \n-*HTTP Downloading*\n+*Repository Health Check and SSL Health Check*\n \n-HTTP downloading is an ingestion method in which version 3 will make HTTP requests to version 2. This is the \n-slowest option for upgrading.\n+You can include both your existing {rhc} and its corresponding SSL trust store configuration when you upgrade\n+from version 2.14 (or later) to 3.1 (or later). If you are a {oss} user you only have the ability to upgrade your\n+settings from the 'Health Check: Configuration' capability. If you are a {pro} user, you can also upgrade your\n+existing 'SSL: Health Check' settings from version 2.14 (or later) to 3.1 (or later). After the upgrade process is\n+complete, settings for both 'Health Check: Configuration' and 'SSL: Health Check' capabilities will be enabled in\n+version 3.1 (or later), as they were in version 2.14 (or later).\n \n-If {nxrm} 2.x and {nxrm} 3.x are on different machines and do not share access to the same file system storage, \n-you must use the HTTP download method.\n+*NuGet API Key*\n \n-*File System Copying*\n+The upgrade tool will add all keys to version 3.1 (or later) that are present in version 2.14 (or later) when\n+asked, even if the version 2.14 (or later) NuGet API Key Realm is not active. This is because there is no\n+explicit on or off setting for NuGet keys.\n \n-If versions 2 and 3 are on the same machine (or share access to the same file systems) then version 3 will \n-copy the files from version 2. Version 2 will tell version 3 the location of the file and where to retrieve the \n-content. \n+////\n+NO IQ Server capability in 3.1\n \n-Assuming versions 2 and 3 are on the same machine, configured in a way that the mounts are accessible by the same \n-path (from one machine to the other) this option will work. It is a slightly faster process than the download \n-method and has less impact on the performance of version 2.\n+*IQ Server*\n \n-*Hard Linking*\n+{inrmonly}\n+\n+If upgrading {iq} settings and configuration, ensure that your licenses include the integration for both versions \n+2 and 3. Your configuration for 'IQ Server URL', 'Username', 'Password', and 'Request Timeout' will be included \n+in the upgrade. Additional configuration, such as analysis properties, trust store usage, and the enabled {iq} \n+connection itself will be replicated from versions 2 to 3.\n+////\n \n-This method only works on the same file system. If you want to hard link, configure your instance of version 3 in \n-such a way that you have a blob store defined in an appropriate location where hard linking is possible.\n+[[upgrade-security]]\n+==== Security Compatibility from 2.14 (or later) to 3.1 (or later)\n \n-This is the fastest option because you will not have to move the bytes around.\n+Before you upgrade from version 2.14 (or later) to 3.1 (or later) review the differences in security settings\n+along the upgrade path. Known changes may affect roles and repository targets, that latter of which will no\n+longer exist in {nxrm} 3.\n \n-[[upgrade-process-expectations]]\n-=== Upgrade Process and Expectations\n+*Version 2.14 (or later) Roles*\n \n-While version 2 is active repository content will be added, updated, and deleted as the upgrade continues \n-within version 3. Version 3 will pick up these changes. However, configuration changes such as new \n-repositories, realm settings, permissions, roles and role assignments, HTTP configuration, and SSL certificates \n-should not be changed. After the upgrade starts such changes will not be picked up by version 3 and may result \n-in failure.\n+Roles upgraded from version 2.14 (or later) will be assigned a Role ID that starts with `nx2-` in {nxrm} 3. Role \n+descriptions created during the upgrade process will have the word (legacy) in their description.\n \n-[[upgrade-repo-support]]\n-=== Repository Format Support\n+*Version 2.14 (or later) Repository Targets*\n \n-Below is a list of repositories available in version 2 and 3 and which are supported by upgrading. For each of \n-these formats you can upgrade server-wide settings, security realm settings, and repository content.\n+If upgrading your Repository Targets from version 2.14 (or later) to 3.1 (or later), it is recommended you also\n+upgrade your Target Privileges and vice versa. If you do not upgrade both, you may find that you need to make\n+further adjustments to version 3.1 (or later) configuration to have things work as they did in version 2.14 (or\n+later).\n \n-* npm\n-* NuGet\n-* Site/Raw\n-* Maven2\n+Repository targets from version 2.14 (or later) will be converted to content selectors in version 3.1 (or later).\n+In contrast to repository targets, which rely on regular expressions for user permissions, content selectors use\n+a syntax called JEXL perform similar restrictions. If characters are not translatable the upgrade process will\n+replace unsupported characters with underscores (`_`). For example, a repository target in version 2.14 (or\n+later) named 'All (Any Repository)' will be converted to a selector permission named 'All_Any_Repository' in\n+version 3.1 (or later).\n+\n+[[upgrade-performance]]\n+==== Optimization, Performance, and Tuning\n+\n+When considering upgrade time and speed, take into account all enabled scheduled tasks and additional settings on\n+your version 2.14 (or later) instance that you may not need. Depending on your configuration of version 2.14 (or\n+later) you could optimize the performance of you upgrade by either turning off or deleting obsolete content and\n+tasks. As discussed in the link:\n+https://support.sonatype.com/hc/en-us/articles/213465138-How-can-I-configure-Nexus-to-reduce-disk-space-[article about performance and tuning for {nxrm} 2], identify then reduce your list of tasks in version 2.14 (or later) to\n+improve the speed of your repository manager. See some highlights, below:\n+\n+* *System feeds* - If your organization does not rely on system feeds, often used for team communication, \n+learn how to \n+https://support.sonatype.com/hc/en-us/articles/213464998-How-to-disable-the-System-Feeds-nexus-timeline-plugin-feature-to-improve-Nexus-performance[disable] them within your timeline plugin file\n+* *Repair index tasks* - These task support search in the repository manager user interface. Since these tasks do\n+  not need to be rebuilt that often, consider disabling them across all repositories\n+* *Snapshot removal tasks* - Enable both 'Remove Snapshots from Repository' and 'Remove Unused Snapshots From\n+  Repository', which deletes old component states no longer needed. * *Repositories no longer supported by the\n+  {nxrm}* - Remove any deprecated repositories, or other content. For example, if your repository manager\n+  contains any Maven 2 proxy repository with the domain name 'codehaus.org' should be deleted. See https://support.sonatype.com/hc/en-us/articles/217611787-codehaus-org-Repositories-Should-Be-Removed-From-Your-Nexus-Instance[Codehaus repositories], for more information\n+* *'Rebuild Maven Metadata Files'* - This scheduled task should only be run if you need to repair a corrupted\n+  Maven repository storage on disk. If run infrequently, you can disable it completely to reserve more space\n+  needed for your upgrade\n+* *Staging rules* - If you are a {pro} user that use the application for staging releases, redefine or reduce the\n+  number of configured rules to free up space.\n+* *Scheduled task for releases* - If you find empty 'Use Index' checkboxes under 'Task Settings', use the\n+  opportunity to disable or remove those specific tasks for releases\n+* *Smart Proxy Preemptive Fetch* - The most notable performance benefit is that hidden caches are utilized more\n+  efficiently\n+\n+////\n+* Reviewing the Custom Metadata capability (when enabled)\n+////\n+\n+To help you make deeper decisions around reducing scheduled tasks to improve the performance of your upgrade, see \n+the knowledge base article https://support.sonatype.com/hc/en-us/articles/213465208-What-do-the-scheduled-tasks-in-Nexus-do-and-how-often-should-I-run-them-['What do the scheduled tasks in Nexus do, and how often should I run them?'].\n \n [[upgrade-start]]\n === Starting the Upgrade\n \n-After considerations around system performance and storage are taken into account, there are a few basic steps \n-to start the upgrade:\n+After you've designed your upgrade plan and made considerations around system performance and storage are taken\n+into account, there are a few basic steps t o start the upgrade:\n \n-* Upgrade the repository manager to the latest version of 2.x and configure the upgrade capability that allows \n-you to synchronize that instance with {nxrm} 3.1 or later.\n-* Run 2.14 or later on one server, and version 3.1 or later on another non-conflicting server.\n-* Configure the migration-agent in version 2 and start the upgrade wizard in version 3.\n+* Upgrade the your existing version 2.x to 2.14 (or later) (see <<upgrade-version-two>>).\n+* Enable the upgrade capabilities in both version 2.14 (or later) and 3.1 (or later) that allow you to\n+  synchronize that instance between versions.\n \n-{nxrm} 3.1 provides a wizard to instruct you through upgrading in three phases:\n+With the above complete, you can now use the provide upgrade tool in version 3.1 (or later), which will instruct\n+you through upgrading in three phases:\n \n  * 'Preparing', the phase that prepares the transfer and creation of all components.\n  * 'Synchronizing', the phase that counts and processes all components set to upgrade.\n  * 'Finishing', the phase that performs final clean up, then closes the process.\n \n-To execute the upgrade plan you must open the connection between version 2 and 3. The connection finds what \n-repositories exist and lists them in the upgrade wizard. It enables the port you configured to run version 2 \n-remotely in order to communicate with version 3. The upgrade plan, as a whole, is a two-part process where \n-version 2 must be set up to listen for a version 3 instance in order for the former to talk to the latter.\n-\n [[upgrade-configuration]]\n-==== Enabling Upgrade in Version 2\n+==== Enabling the Upgrade Capability in Version 2.14 (or later)\n \n-In version 2, activate the 'Migration: Agent' capability to open the connection for the migration-agent. Follow \n-these steps:\n+In version 2.14 (or later), enable the 'Upgrade: Agent' capability to open the connection for the upgrade-agent.\n+Follow these steps:\n \n * Click 'Administration' in the left-hand panel\n * Open the 'Capabilities' screen\n * Select 'New' to prompt the 'Create new capability' modal\n-* Select 'Migration: Agent' as your capability 'Type'\n+* Select 'Upgrade: Agent' as your capability 'Type'\n * Click 'Add' to close the modal\n \n-In the lower section of the 'Capabilities' interface, the repository manager acknowledges the migration-agent as \n-'Active'. \n+In the lower section of the 'Capabilities' interface, the repository manager acknowledges the upgrade-agent as\n+'Active'.\n \n [[upgrade-plan]]\n-==== Enabling Upgrade in Version 3\n+==== Enabling the Upgrade Capability in Version 3.1 (or later)\n \n-Next, sign in to your version 3 instance. You will create a 'Migration' capability to enable the feature. When \n-enabled, the 'Migration' item appears in the 'Administration' menu, under 'System'. Follow these steps to \n-activate the capability:\n+In version 3.1 (or later), enable the 'Upgrade' capability to open the connection for the upgrade-agent, and\n+access the 'Upgrade' tool. Follow these steps:\n \n * Click 'System', to open the 'Capabilities' screen","path":"chapter-upgrading.asciidoc","position":544,"original_position":550,"commit_id":"852cf37de0e2277a231a603d3802dea7c486058f","original_commit_id":"7459201baa8094e064333753f43bdef26d229e4d","user":{"login":"annrollo","id":13008905,"avatar_url":"https://avatars.githubusercontent.com/u/13008905?v=3","gravatar_id":"","url":"https://api.github.com/users/annrollo","html_url":"https://github.com/annrollo","followers_url":"https://api.github.com/users/annrollo/followers","following_url":"https://api.github.com/users/annrollo/following{/other_user}","gists_url":"https://api.github.com/users/annrollo/gists{/gist_id}","starred_url":"https://api.github.com/users/annrollo/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/annrollo/subscriptions","organizations_url":"https://api.github.com/users/annrollo/orgs","repos_url":"https://api.github.com/users/annrollo/repos","events_url":"https://api.github.com/users/annrollo/events{/privacy}","received_events_url":"https://api.github.com/users/annrollo/received_events","type":"User","site_admin":false},"body":"Another case where it should be numerated list.","created_at":"2016-09-01T19:50:47Z","updated_at":"2016-09-01T19:50:47Z","html_url":"https://github.com/sonatype/nexus-book/pull/220#discussion_r77241516","pull_request_url":"https://api.github.com/repos/sonatype/nexus-book/pulls/220","_links":{"self":{"href":"https://api.github.com/repos/sonatype/nexus-book/pulls/comments/77241516"},"html":{"href":"https://github.com/sonatype/nexus-book/pull/220#discussion_r77241516"},"pull_request":{"href":"https://api.github.com/repos/sonatype/nexus-book/pulls/220"}}},"pull_request":{"url":"https://api.github.com/repos/sonatype/nexus-book/pulls/220","id":83144797,"html_url":"https://github.com/sonatype/nexus-book/pull/220","diff_url":"https://github.com/sonatype/nexus-book/pull/220.diff","patch_url":"https://github.com/sonatype/nexus-book/pull/220.patch","issue_url":"https://api.github.com/repos/sonatype/nexus-book/issues/220","number":220,"state":"open","locked":false,"title":"NEXUS-10736 review and associated updates.","user":{"login":"jwayman","id":2112401,"avatar_url":"https://avatars.githubusercontent.com/u/2112401?v=3","gravatar_id":"","url":"https://api.github.com/users/jwayman","html_url":"https://github.com/jwayman","followers_url":"https://api.github.com/users/jwayman/followers","following_url":"https://api.github.com/users/jwayman/following{/other_user}","gists_url":"https://api.github.com/users/jwayman/gists{/gist_id}","starred_url":"https://api.github.com/users/jwayman/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jwayman/subscriptions","organizations_url":"https://api.github.com/users/jwayman/orgs","repos_url":"https://api.github.com/users/jwayman/repos","events_url":"https://api.github.com/users/jwayman/events{/privacy}","received_events_url":"https://api.github.com/users/jwayman/received_events","type":"User","site_admin":false},"body":"Updates based on review for JIRA https://issues.sonatype.org/browse/NEXUS-10736\r\n\r\nReview HTML here: http://bamboo.s/browse/BOOK-NEXUS184-1/artifact/shared/site/nexus-book/3.1/reference/upgrading.html","created_at":"2016-08-29T18:31:40Z","updated_at":"2016-09-01T19:50:47Z","closed_at":null,"merged_at":null,"merge_commit_sha":"749d6c2ed671cd8de89715d51db00a12ca772180","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/sonatype/nexus-book/pulls/220/commits","review_comments_url":"https://api.github.com/repos/sonatype/nexus-book/pulls/220/comments","review_comment_url":"https://api.github.com/repos/sonatype/nexus-book/pulls/comments{/number}","comments_url":"https://api.github.com/repos/sonatype/nexus-book/issues/220/comments","statuses_url":"https://api.github.com/repos/sonatype/nexus-book/statuses/852cf37de0e2277a231a603d3802dea7c486058f","head":{"label":"sonatype:NEXUS-10736-upgrade-doc-review","ref":"NEXUS-10736-upgrade-doc-review","sha":"852cf37de0e2277a231a603d3802dea7c486058f","user":{"login":"sonatype","id":44938,"avatar_url":"https://avatars.githubusercontent.com/u/44938?v=3","gravatar_id":"","url":"https://api.github.com/users/sonatype","html_url":"https://github.com/sonatype","followers_url":"https://api.github.com/users/sonatype/followers","following_url":"https://api.github.com/users/sonatype/following{/other_user}","gists_url":"https://api.github.com/users/sonatype/gists{/gist_id}","starred_url":"https://api.github.com/users/sonatype/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sonatype/subscriptions","organizations_url":"https://api.github.com/users/sonatype/orgs","repos_url":"https://api.github.com/users/sonatype/repos","events_url":"https://api.github.com/users/sonatype/events{/privacy}","received_events_url":"https://api.github.com/users/sonatype/received_events","type":"Organization","site_admin":false},"repo":{"id":188759,"name":"nexus-book","full_name":"sonatype/nexus-book","owner":{"login":"sonatype","id":44938,"avatar_url":"https://avatars.githubusercontent.com/u/44938?v=3","gravatar_id":"","url":"https://api.github.com/users/sonatype","html_url":"https://github.com/sonatype","followers_url":"https://api.github.com/users/sonatype/followers","following_url":"https://api.github.com/users/sonatype/following{/other_user}","gists_url":"https://api.github.com/users/sonatype/gists{/gist_id}","starred_url":"https://api.github.com/users/sonatype/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sonatype/subscriptions","organizations_url":"https://api.github.com/users/sonatype/orgs","repos_url":"https://api.github.com/users/sonatype/repos","events_url":"https://api.github.com/users/sonatype/events{/privacy}","received_events_url":"https://api.github.com/users/sonatype/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/sonatype/nexus-book","description":"Repository Management with Nexus","fork":false,"url":"https://api.github.com/repos/sonatype/nexus-book","forks_url":"https://api.github.com/repos/sonatype/nexus-book/forks","keys_url":"https://api.github.com/repos/sonatype/nexus-book/keys{/key_id}","collaborators_url":"https://api.github.com/repos/sonatype/nexus-book/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/sonatype/nexus-book/teams","hooks_url":"https://api.github.com/repos/sonatype/nexus-book/hooks","issue_events_url":"https://api.github.com/repos/sonatype/nexus-book/issues/events{/number}","events_url":"https://api.github.com/repos/sonatype/nexus-book/events","assignees_url":"https://api.github.com/repos/sonatype/nexus-book/assignees{/user}","branches_url":"https://api.github.com/repos/sonatype/nexus-book/branches{/branch}","tags_url":"https://api.github.com/repos/sonatype/nexus-book/tags","blobs_url":"https://api.github.com/repos/sonatype/nexus-book/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/sonatype/nexus-book/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/sonatype/nexus-book/git/refs{/sha}","trees_url":"https://api.github.com/repos/sonatype/nexus-book/git/trees{/sha}","statuses_url":"https://api.github.com/repos/sonatype/nexus-book/statuses/{sha}","languages_url":"https://api.github.com/repos/sonatype/nexus-book/languages","stargazers_url":"https://api.github.com/repos/sonatype/nexus-book/stargazers","contributors_url":"https://api.github.com/repos/sonatype/nexus-book/contributors","subscribers_url":"https://api.github.com/repos/sonatype/nexus-book/subscribers","subscription_url":"https://api.github.com/repos/sonatype/nexus-book/subscription","commits_url":"https://api.github.com/repos/sonatype/nexus-book/commits{/sha}","git_commits_url":"https://api.github.com/repos/sonatype/nexus-book/git/commits{/sha}","comments_url":"https://api.github.com/repos/sonatype/nexus-book/comments{/number}","issue_comment_url":"https://api.github.com/repos/sonatype/nexus-book/issues/comments{/number}","contents_url":"https://api.github.com/repos/sonatype/nexus-book/contents/{+path}","compare_url":"https://api.github.com/repos/sonatype/nexus-book/compare/{base}...{head}","merges_url":"https://api.github.com/repos/sonatype/nexus-book/merges","archive_url":"https://api.github.com/repos/sonatype/nexus-book/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/sonatype/nexus-book/downloads","issues_url":"https://api.github.com/repos/sonatype/nexus-book/issues{/number}","pulls_url":"https://api.github.com/repos/sonatype/nexus-book/pulls{/number}","milestones_url":"https://api.github.com/repos/sonatype/nexus-book/milestones{/number}","notifications_url":"https://api.github.com/repos/sonatype/nexus-book/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/sonatype/nexus-book/labels{/name}","releases_url":"https://api.github.com/repos/sonatype/nexus-book/releases{/id}","deployments_url":"https://api.github.com/repos/sonatype/nexus-book/deployments","created_at":"2009-04-29T20:25:10Z","updated_at":"2016-08-30T15:53:41Z","pushed_at":"2016-09-01T19:40:55Z","git_url":"git://github.com/sonatype/nexus-book.git","ssh_url":"git@github.com:sonatype/nexus-book.git","clone_url":"https://github.com/sonatype/nexus-book.git","svn_url":"https://github.com/sonatype/nexus-book","homepage":"http://books.sonatype.com/nexus-book/reference/index.html","size":708235,"stargazers_count":52,"watchers_count":52,"language":"XSLT","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":25,"mirror_url":null,"open_issues_count":9,"forks":25,"open_issues":9,"watchers":52,"default_branch":"master"}},"base":{"label":"sonatype:nexus-3.1.x","ref":"nexus-3.1.x","sha":"c7408125625a376102dcae60e5388b8ac1625cda","user":{"login":"sonatype","id":44938,"avatar_url":"https://avatars.githubusercontent.com/u/44938?v=3","gravatar_id":"","url":"https://api.github.com/users/sonatype","html_url":"https://github.com/sonatype","followers_url":"https://api.github.com/users/sonatype/followers","following_url":"https://api.github.com/users/sonatype/following{/other_user}","gists_url":"https://api.github.com/users/sonatype/gists{/gist_id}","starred_url":"https://api.github.com/users/sonatype/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sonatype/subscriptions","organizations_url":"https://api.github.com/users/sonatype/orgs","repos_url":"https://api.github.com/users/sonatype/repos","events_url":"https://api.github.com/users/sonatype/events{/privacy}","received_events_url":"https://api.github.com/users/sonatype/received_events","type":"Organization","site_admin":false},"repo":{"id":188759,"name":"nexus-book","full_name":"sonatype/nexus-book","owner":{"login":"sonatype","id":44938,"avatar_url":"https://avatars.githubusercontent.com/u/44938?v=3","gravatar_id":"","url":"https://api.github.com/users/sonatype","html_url":"https://github.com/sonatype","followers_url":"https://api.github.com/users/sonatype/followers","following_url":"https://api.github.com/users/sonatype/following{/other_user}","gists_url":"https://api.github.com/users/sonatype/gists{/gist_id}","starred_url":"https://api.github.com/users/sonatype/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sonatype/subscriptions","organizations_url":"https://api.github.com/users/sonatype/orgs","repos_url":"https://api.github.com/users/sonatype/repos","events_url":"https://api.github.com/users/sonatype/events{/privacy}","received_events_url":"https://api.github.com/users/sonatype/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/sonatype/nexus-book","description":"Repository Management with Nexus","fork":false,"url":"https://api.github.com/repos/sonatype/nexus-book","forks_url":"https://api.github.com/repos/sonatype/nexus-book/forks","keys_url":"https://api.github.com/repos/sonatype/nexus-book/keys{/key_id}","collaborators_url":"https://api.github.com/repos/sonatype/nexus-book/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/sonatype/nexus-book/teams","hooks_url":"https://api.github.com/repos/sonatype/nexus-book/hooks","issue_events_url":"https://api.github.com/repos/sonatype/nexus-book/issues/events{/number}","events_url":"https://api.github.com/repos/sonatype/nexus-book/events","assignees_url":"https://api.github.com/repos/sonatype/nexus-book/assignees{/user}","branches_url":"https://api.github.com/repos/sonatype/nexus-book/branches{/branch}","tags_url":"https://api.github.com/repos/sonatype/nexus-book/tags","blobs_url":"https://api.github.com/repos/sonatype/nexus-book/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/sonatype/nexus-book/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/sonatype/nexus-book/git/refs{/sha}","trees_url":"https://api.github.com/repos/sonatype/nexus-book/git/trees{/sha}","statuses_url":"https://api.github.com/repos/sonatype/nexus-book/statuses/{sha}","languages_url":"https://api.github.com/repos/sonatype/nexus-book/languages","stargazers_url":"https://api.github.com/repos/sonatype/nexus-book/stargazers","contributors_url":"https://api.github.com/repos/sonatype/nexus-book/contributors","subscribers_url":"https://api.github.com/repos/sonatype/nexus-book/subscribers","subscription_url":"https://api.github.com/repos/sonatype/nexus-book/subscription","commits_url":"https://api.github.com/repos/sonatype/nexus-book/commits{/sha}","git_commits_url":"https://api.github.com/repos/sonatype/nexus-book/git/commits{/sha}","comments_url":"https://api.github.com/repos/sonatype/nexus-book/comments{/number}","issue_comment_url":"https://api.github.com/repos/sonatype/nexus-book/issues/comments{/number}","contents_url":"https://api.github.com/repos/sonatype/nexus-book/contents/{+path}","compare_url":"https://api.github.com/repos/sonatype/nexus-book/compare/{base}...{head}","merges_url":"https://api.github.com/repos/sonatype/nexus-book/merges","archive_url":"https://api.github.com/repos/sonatype/nexus-book/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/sonatype/nexus-book/downloads","issues_url":"https://api.github.com/repos/sonatype/nexus-book/issues{/number}","pulls_url":"https://api.github.com/repos/sonatype/nexus-book/pulls{/number}","milestones_url":"https://api.github.com/repos/sonatype/nexus-book/milestones{/number}","notifications_url":"https://api.github.com/repos/sonatype/nexus-book/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/sonatype/nexus-book/labels{/name}","releases_url":"https://api.github.com/repos/sonatype/nexus-book/releases{/id}","deployments_url":"https://api.github.com/repos/sonatype/nexus-book/deployments","created_at":"2009-04-29T20:25:10Z","updated_at":"2016-08-30T15:53:41Z","pushed_at":"2016-09-01T19:40:55Z","git_url":"git://github.com/sonatype/nexus-book.git","ssh_url":"git@github.com:sonatype/nexus-book.git","clone_url":"https://github.com/sonatype/nexus-book.git","svn_url":"https://github.com/sonatype/nexus-book","homepage":"http://books.sonatype.com/nexus-book/reference/index.html","size":708235,"stargazers_count":52,"watchers_count":52,"language":"XSLT","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":25,"mirror_url":null,"open_issues_count":9,"forks":25,"open_issues":9,"watchers":52,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/sonatype/nexus-book/pulls/220"},"html":{"href":"https://github.com/sonatype/nexus-book/pull/220"},"issue":{"href":"https://api.github.com/repos/sonatype/nexus-book/issues/220"},"comments":{"href":"https://api.github.com/repos/sonatype/nexus-book/issues/220/comments"},"review_comments":{"href":"https://api.github.com/repos/sonatype/nexus-book/pulls/220/comments"},"review_comment":{"href":"https://api.github.com/repos/sonatype/nexus-book/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/sonatype/nexus-book/pulls/220/commits"},"statuses":{"href":"https://api.github.com/repos/sonatype/nexus-book/statuses/852cf37de0e2277a231a603d3802dea7c486058f"}}}}
{"actor":{"display_login":"annrollo"}}