Repository Management with Nexus

6.4. Managing Routing

Routing can be considered the internal activities Nexus performs in order to determine where to look for a specific component in a repository. The routing information has an impact on the performance of component retrieval as well as determining the availability of components.

A large portion of the performance gains achievable with correct and optimized routing information is configured by Nexus itself with automatic routing, documented in Section 6.4.1, “Automatic Routing”. Fine grained control and further customizations in terms of access provision can be achieved with some manual routing configuration documented in Section 6.4.2, “Manual Routing Configuration”.

6.4.1. Automatic Routing

Automatic routing is handled by Nexus on a per repository basis. You can access the configuration and further details in the Routing tab after selecting a repository in the list accessible via the Repositories item in the the Views/Repositories left-hand menu.

The routing information consists of the top two levels of the directory structure of the repository and is stored in a prefixes.txt file. It allows Nexus to automatically route only component requests with the corresponding groupId values to a repository, as found in the text file. This, in turns, avoids unnecessary index or even remote repository access and therefore greatly improves performance.

Nexus generates the prefixes.txt file for a hosted repository and makes it available for remote downloads. Each deployment of a new component will trigger an update of the file for the hosted repository as well as the prefix files for any repoisitory groups that contain the hosted repository. You can access it in the Routing tab of a hosted repository as displayed in Figure 6.19, “Automatic Routing for a Hosted Repository” by clicking on the Show prefix file link on the right. In addition, the Publishing section shows the Status of the routing information, a Message with further details, and the date and time of the last update in the Published On field.

figs/web/automatic-routing-hosted.png

Figure 6.19. Automatic Routing for a Hosted Repository


The Routing tab for a proxy repository displayed in Figure 6.20, “Automatic Routing for a Proxy Repository” contains the Discovery section. It displays the Status and a more detailed Message about the prefix file access. The Last run field displays the date and time of the last execution of the prefix file discovery. Such an execution can be triggered by pressing the Update now button. Otherwise, the Update Interval allows you to trigger a new discovery every one, two, three, six, nine or twelve hours or as a daily or weekly execution.

figs/web/automatic-routing-proxy.png

Figure 6.20. Automatic Routing for a Proxy Repository


For a proxy repository, the prefix file is either downloaded from the remote repository or a generation is attempted by scraping the remote repository. This generation is not attempted for remote Nexus repository groups, since they are too dynamic in nature and should not be proxied directly. Scraping of hosted or proxy repositories as well as Subversion-based repositories is supported.

The generation of the prefix file in all the Nexus deployments proxying each other greatly improves performance for all Nexus instances. It lowers network traffic and load on the servers, since failing requests and serving the respective HTTP error pages for a component that is not found is avoided for each component. Instead, the regularly light weight download of the prefix file establishes a good high-level knowledge of components available.

Automatic Routing is configured by Nexus automatically brings significant performance benefits to all Nexus instances proxying each other in a network and on the wider internet. It does not need to be changed apart from tweaking the update interval. To exercise even finer control than provided by Automatic Routing use Routing as documented in Section 6.4.2, “Manual Routing Configuration”.

6.4.2. Manual Routing Configuration

Nexus routes are like filters you can apply to groups in terms of security access and general component retrieval, and can reduce the number of repositories within a group accessed in order to retrieve an artifact. The administration interface for routes can be accessed via the Routing menu item in the View/Repositories menu in the left-hand navigation panel.

Routes allow you to configure Nexus to include or exclude specific repository content paths from a particular artifact search when Nexus is trying to locate an artifact in a repository group. There are a number of different scenarios in which you might configure a route.

The most commonly configured scenario is when you want to make sure that you are retrieving artifacts in a particular group ID from a particular repository. This is especially useful when you want your own organization’s artifacts from the hosted Release and Snapshot repositories only.

Routes are applicable when you are trying to resolve an artifact from a repository group. Using routes allows you to modify the repositories Nexus will consult when it tries to resolve an artifact from a group of repositories.

figs/web/repository-manager_route-config.png

Figure 6.21. Routing Configuration Screen in Nexus


Figure 6.21, “Routing Configuration Screen in Nexus” shows the Routing configuration screen. Clicking on a route will bring up a screen that will allow you to configure the properties of a route. The configuration options available for a route are:

URL Pattern

Nexus uses the URL Pattern will use to match a request to Nexus. If the regular expression in this pattern is matched, Nexus will either include or exclude the listed repositories from a particular artifact query. In Figure 6.21, “Routing Configuration Screen in Nexus” the two patterns are:

.*/(com|org)/somecompany/.*
This pattern would match all paths which includes either /com/somecompany/ or /org/somecompany/. The expression in the parenthesis matches either com or org, and the .* matches zero or more characters. You would use a route like this to match your own organization’s artifacts and map these requests to the hosted Releases and Snapshots repositories.
.*/org/some-oss/.*
This pattern is used in an exclusive route. It matches every path that contains /org/some-oss/. This particular exclusive route excludes the local hosted Releases and Snapshots directory for all artifacts that match this path. When Nexus tries to resolve artifacts that match this path, it will exclude the Releases and Snapshots repositories.
Example "(?!/org/some-oss/.)."
Using this pattern in an exclusive route allows you to exclude everything, except the "org/some-oss" project(s).
Rule Type
Rule Type can be either inclusive, exclusive or blocking. An inclusive rule type defines the set of repositories that should be searched for artifacts when the URL pattern has been matched. An exclusive rule type defines repositories which should not be searched for a particular artifact. A blocking rule will completely remove accessibility to the components under the specific pattern in a specified repository group.
Ordered Route Repositories
Nexus searches an ordered list of repositories to locate a particular artifact. This order only affects the order of routes used and not the order of the repositories searched. That order is set by the order of the repositories in the group repository’s configuration.

In Figure 6.21, “Routing Configuration Screen in Nexus” you can see the two dummy routes that Nexus has configured as default routes. The first route is an inclusive route, and it is provided as an example of a custom route an organization might use to make sure that internally generated artifacts are resolved from the Releases and Snapshots repositories only. If your organization’s group IDs all start with com.somecompany, and if you deploy internally generated artifacts to the Releases and Snapshots repositories, this Route will make sure that Nexus doesn’t waste time trying to resolve these artifacts from public repositories like the Central Repository or the Apache Snapshots repository.

The second dummy route is an exclusive route. This route excludes the Releases and Snapshots repositories when the request path contains /org/some-oss. This example might make more sense if we replaced some-oss with apache or codehaus. If the pattern was /org/apache, this rule is telling Nexus to exclude the internal Releases and Snapshots repositories when it is trying to resolve these dependencies. In other words, don’t bother looking for an Apache dependency in your organization’s internal repositories.

[Tip]

Exclusive rules will positively impact performance, since the number of repositories that qualify for locating the artifact, and therefore the search effort is reduced.

What if there is a conflict between two routes? Nexus will process inclusive routes before it will process the exclusive routes. Remember that routes only affect Nexus' resolution of artifacts when it is searching a Group. When Nexus starts to resolve an artifact from a repository group it will start with the list of repositories in a group. If there are matching inclusive routes, Nexus will then take the intersection of the repositories in the group and the repositories in the inclusive route. The order as defined in the group will not be affected by the inclusive route. Nexus will then take the result of applying the inclusive route and apply the exclusive route to that list of repositories. The resulting list is then searched for a matching artifact.

One straightforward use of routes is to create a route that excludes the Central Repository from all searches for your own organization’s hosted artifacts. If you are deploying your own artifacts to Nexus under a groupId of org.mycompany, and if you are not deploying these artifacts to a public repository, you can create a rule that tells Nexus not to interrogate Central for your own organization’s artifacts. This will improve performance because Nexus will not need to communicate with a remote repository when it serves your own organization’s artifacts. In addition to the performance benefits, excluding the Central Repository from searches for your own artifacts will reduce needless queries to the public repositories.

[Tip]

This practice of defining an inclusive route for your internal artifacts to only hit internal repositories is a crucial best practice of implementing a secure component lifecycle management in your organization and a recommended step for initial Nexus configuration. Without this configuration, requests for internal artifacts will be broadcasted to all configured external proxy repositories. This could lead to an information leak, where e.g., your internet traffic reveals that your organization works on a component with the artifact coordinates of com.yourcompany.website:new-super-secret-feature:1.0-SNAPSHOT.

In addition to defining inclusive and exclusive routes, you can define blocking routes. A blocking route can be created by creating a route with no repositories in the ordered list of repositories. It allows you to completely block access to artifacts with the specified pattern(s) from the group. As such, blocking routes are a simplified, coarse-grained access control.

[Tip]

Check out Chapter 10, Nexus Procurement Suite for fine-grained control of artifact availability and use blocking routes sparingly.

To summarize, there are creative possibilities with routes that the designers of Nexus may not have anticipated, but we advise you to proceed with caution if you start relying on conflicting or overlapping routes. Use routes sparingly, and use coarse URL patterns. Remember that routes are only applied to groups and are not used when an artifact is requested from a specific repository.