Many of the configuration screens shown in this section are only available to administrative users. {nxrm} allows the admin user to customize the list of repositories, create repository groups, customize server settings, and create routes or "rules" that Maven will use to include or exclude components from a repository.
{inall}
You can access global configuration by clicking on 'Server' under 'Administration' in the left-hand main menu. The server configuration screens' subsections are documented in the following sections..
{nxrm} sends email to users who need to recover user names and passwords, notifications for staging and a number of other uses. In order for these notifications to work, configure the SMTP server settings in this dialog.
You can configure the 'Hostname' and 'Port' of the SMTP server to use as well as 'Username' and 'Password'. The 'Connection' configuration allows you to configure {nxrm} to use plain or secure SMTP to connect to the server or to use STARTTLS for the connection, which would upgrade the initially established, plain connection to be encrypted. In all cases you will need to ensure that the correct port is used.
The 'System Email' parameter defines the email address used in the From: header of an email sent by the repository manager. Typically, this would be configured as a "Do-Not-Reply" email address or a mailbox or mailing list monitored by the administrators of the server.
Once you have configured the parameters you can use the 'Test SMTP settings' button to confirm the configured parameters and the successful connection to the server. You will be asked to provide an email address that should receive a test email message. Successful sending will be confirmed in another pop up message.
The HTTP Request Settings allow you to configure the identifier that the repository manager uses when it is making an HTTP request. You may want to change this if it needs to use an HTTP Proxy, and the Proxy will only work if the User Agent is set to a specific value.
You can also add extra parameters to place on a GET request to a remote repository. You could use this to add identifying information to requests.
The amount of time the repository manager will wait for a request to succeed when interacting with an external, remote repository can be configured with the Request Timeout and Request Retry Attempts settings.
The security settings displayed in Administration Security Settings allow you to activate and prioritize security realms by adding them to the 'Selected Realms' list on the left and placing them higher or lower on the list.
Effectively, this configuration determines what authentication realm is used to grant a user access and the order the realms are used.
- Xml Authenticating and Xml Authorizing Realm
-
These identify the internal storage of the repository manager. It is using XML files for storing the security details.
- (Enterprise) LDAP Authentication Realm
-
This realm identifies external storage in an LDAP system with details documented in [ldap].
- Crowd Realm
-
This realm identifies external storage in an Atlassian Crowd system with details documented in [crowd].
- Rut Auth Realm
-
This realm is external authentication in any system with the user authorization passed to the repository manager in a HTTP header field with details documented in Authentication via Remote User Token.
The 'User Token Realm' is required for user token support documented in Security Setup with User Tokens and the 'NuGet API-Key Realm' is needed for NuGet support documented in [nuget].
In addition, you can enable or disable anonymous access and set the username and password for anonymous access. The anonymous username and password are used to integrate with other realms that may need a special username for anonymous access. In other words, the username and password here are what we attempt to authorize when someone makes an anonymous request. You would change the anonymous username to guest if you wanted to integrate the repository manager with Microsoft’s Active Directory.
You can change the 'Base URL' for your repository manager installation, which is used when generating links in emails and RSS feeds. For example, the {pro} instance for Sonatype development is at https://repository.sonatype.org, and it makes use of this 'Base URL' field to ensure that links in emails and RSS feeds point back to the correct public URL. Internally {pro} is running on a different port and context than the public port 80 and root context.
If you are hosting the repository manager behind a proxy server and you want to make sure that it always uses the specified Base URL, check the 'Force Base URL' checkbox. If the Force Base URL is not checked, the repository manager will craft URLs in HTTP responses based on the request URL, but it will use the Base URL when it is generating emails.
|
Tip
|
These settings are especially important if the repository manager is proxied by an external proxy server
using a different protocol like HTTPS rather than plain HTTP known to it or a different hostname like
repository.somecompany.com instead of an IP number only.
|
If your repository manager instance needs to reach public repositories like the Central Repository via a proxy server, you can configure the connection to a proxy server for HTTP and a potentially a different for HTTPS connection. If you do not configure a proxy for HTTPS, the HTTP proxy server settings will be used.
You can specify 'Proxy Host' and 'Proxy Port' and, optionally, the authentication details for username, password, NT LAN Host and NT LAN Manager Domain. In addition, you can configure a number of hosts that can be reached directly and do not need to go through the proxy in the 'Non Proxy Host' setting. Administration Default HTTP Proxy Settings shows the 'Default HTTP Proxy Settings' administration interface. The HTTPS configuration interface looks the same and is found below the HTTP configuration.
|
Tip
|
This is a critical initial step for many Enterprise deployments of a repository manager, since these environments are typically secured via a HTTP/HTTPS proxy server for all outgoing internet traffic. |
When you proxy remote repositories that are not available all the time, the repository manager will automatically block and unblock them during downtimes. The 'System Notification Settings' allows you define 'Email Adresses' and roles for users that should receive notifications messages for these blocking and unblocking events.
{nxrm} uses a PGP Key Server to retrieve PGP keys when validating component signatures. To add a new key server, enter the URL in the 'Key Server URL' field and click on the 'Add' button. To remove a key server, click on the URL you wish to remove from the list and click on the 'Remove' button. Key servers are consulted in the order that they are listed in the 'Key Server URLs' list. To reorder your key servers, click and drag a URL in the 'Key Server URLs' list.
{nxrm} can notify you about the availability of new versions via the user interface. To enable this feature, check the Enable checkbox in the 'New Version Availability' section of the server settings as shown in Administration New Version Availability.
{inall}
To manage repositories, log in as the administrative user and click on 'Repositories' in the 'Views/Repositories' menu in the left-hand main menu.
{nxrm} provides for three different kinds of repositories: 'Proxy' Repositories, 'Hosted' repositories, and 'Virtual' repositories.
A 'Proxy Repository' is a proxy of a remote repository. By default, {nxrm} ships with the following configured proxy repositories:
- Apache Snapshots
-
This repository contains snapshot releases from the Apache Software Foundation.
- Codehaus Snapshots
-
This repository contains snapshot releases from Codehaus.
- Central
-
This is the 'Central Repository' containing release components. Formerly known as 'Maven Central', it is the default built-in repository for Apache Maven and directly supported in other build tools like Gradle, SBT or Ant/Ivy. {nxrm} connects to the Central Repository via HTTPS using the URL
https://repo1.maven.org/maven2/.
A 'Hosted Repository' is a repository that is hosted by the repository manager. {nxrm} ships with the following configured hosted repositories:
- 3rd Party
-
This hosted repository should be used for third-party dependencies not available in the public Maven repositories. Examples of these dependencies could be commercial, proprietary libraries such as an Oracle JDBC driver that may be referenced by your organization.
- Releases
-
This hosted repository is where your organization will publish internal releases.
- Snapshots
-
This hosted repository is where your organization will publish internal snapshots.
A 'Virtual Repository' serves as an adaptor to and from different types of repositories. Currently, {pro} supports conversion to and from Maven 1 repositories and Maven 2 repositories. In addition, you can expose any repository format as a NuGet or OBR repository. For example, a Maven 2 repository can contain OSGi Bundles, which can be exposed as a OSGi Bundle repository with the virtual repository Provider set to OBR.
By default it ships with a Central M1 shadow repository that exposes the Central repository in Maven 1 format.
The 'Repositories' window displayed in Repository Configuration Screen for a Proxy Repository allows you to create, update and delete different repositories with the 'Add', 'Delete' and 'Trash' button. Use the 'Refresh' button to update the displayed list of repositories and repository groups. The 'Trash' button allows you to empy the trash folder into which deleted components are copied, when any delete operations are performed from the user interface.
By default, the list of repositories displays the repositories configured and managed by the administrator. The drop down on the right of the 'Trash' button allows you to switch the list of repositories and view the repositories managed by the repository manager. There are staging repositories as documented in [staging] or procurement repositories as documented in [procure].
The list of repositories visible in Repository Configuration Screen for a Proxy Repository allows you to access more details for each repository by selecting a specific row which displays some information for each repository in the following columns:
- Repository
-
the name of the repository with repository groups displayed in bold
- Type
-
the type of the repository with values of proxy, hosted or virtual for repositories or group for a repository group
- Health Check
-
the result counts for a repository health check as documented in [rhc]
- Format
-
the format used for the storage in the repository with values such as maven2, nuget, site or others
- Policy
-
the deployment policy that applies to this repository. A policy applies only to Maven 1 and Maven 2 formatted repositories and allows usage of a 'Snapshot' or a 'Release' policy.
- Repository Status
-
the status of the repository as well as further information about the status. For example, information about SSL certification problems or the status of the remote repository even for a currently disabled proxy repository
- Repository Path
-
the direct URL path that exposes the repository via HTTP access and potentially allows access and directory browsing outside of the user interface
Clicking on a colum header allows you to sort the list in ascending or descending order based on the column data.
If you right-click on a row, you can trigger a number of actions on the current repository, depending on the repository type. Actions include:
- Expire Cache
-
expire the cache of hosted or a proxy repository or a repository group
- Rebuild Metadata
-
rebuid the metadata of a hosted Maven 2 repository
- Block Proxy / Allow Proxy
-
toggle between allowing or blocking the remote repository configured in a proxy repository
- Put Out Of Service / Put in Service
-
enable or disable the repository service to allow changing the availability of all components in it
- Repair Index / Update Index
-
repair or update the index of a hosted or proxy repository or a repository group
The bottom of Repository Configuration Screen for a Proxy Repository and Additional Configuration for a Proxy Repository combined show the repository configuration screen for a proxy repository in the repository manager. From this screen, you can manage the settings for proxying an external repository:
- Repository ID
-
The repository ID is the identifier that will be used in the URL. For example, the proxy repository for the Central Repository has an ID of central, this means that Maven and other tools can access the repository directly at http://localhost:8081/nexus/content/repositories/central. The 'Repository ID' must be unique in a given repository manager installation and is required.
- Repository Name
-
The display name for a repository is required.
- Repository Type
-
The type of repository (proxy, hosted, or virtual). You can’t change the type of a repository as it is selected when you create a repository.
- Provider and Format
-
'Provider' and 'Format' define in what format the repository manager exposes the repository to external tools. Supported formats depend on the installed plugins. {oss} includes support for Maven 1, Maven 2 and Site repositories. {pro} adds support for NuGet and OBR and additional plugins can add support for P2 and P2 Update Site and other formats.
- Repository Policy
-
If a proxy repository has a policy of release, then it will only access released versions from the remote repository. If a proxy repository has a policy of snapshot, it will download snapshots from the remote repository.
- Default Storage Location
-
Not editable, shown for reference. This is the default storage location for the local cached contents of the repository.
- Override Storage Location
-
You can choose to override the storage location for a specific repository. You would do this if you were concerned about storage and wanted to put the contents of a specific repository (such as central) in a different location.
- Remote Repository Access
-
This section configures proxy repositories and how the repository manager interacts with the remote repository, that is being proxied.
- Remote Storage Location
-
The 'Remote Storage Location' needs to be configured with the URL of the remote repository, that needs to be proxied. When selecting the URL to proxy it is beneficial to avoid proxying remote repository groups. Proxying repository groups prevents some performance optimization in terms of accessing and retrieving the content of the remote repository. If you require components from the group that are found in different hosted repositories on the remote repository server it is better to create multiple proxy repositories that proxy the different hosted repositories from the remote server on your repository manager instead of simply proxying the group.
- Download Remote Indexes
-
Download the index of a remote repository can be configured with this setting. If enabled, the repository manager will download the index, if it exists, and use that for its searches as well as serve that up to any clients that ask for the index (like m2eclipse). The default for new proxy repositories is enabled, but all of the default repositories included have this option disabled. To change this setting for one of the proxy repositories that ship with the repository manager, change the option, save the repository, and then re-index the repository. Once this is done, component search will return every component available on the Maven Central repository.
- Auto Blocking Enabled
-
If Auto blocking active is set to true, the repository manager will automatically block a proxy repository if the remote repository becomes unavailable. While a proxy repository is blocked, components will still be served to clients from a local cache, but the repository manager will not attempt to locate a component in a remote repository. The repository manager will periodically retest the remote repository and unblock the repository once it becomes available.
- File Content Validation
-
If set to true, the repository manager will perform a lightweight check on the content of downloaded files. This will prevent invalid content to be stored and proxied by the repository manager that otherwise can happen in cases where the remote repository (or some proxy between the repository manager and the remote repository) returns a HTML page instead of the requested file.
- Checksum Policy
-
Sets the checksum policy for a remote repository. This option is set to 'Warn' by default. The possible values of this setting are:
-
'Ignore' - Ignore the checksums entirely
-
'Warn' - Print a warning in the log if a checksum is not correct
-
'StrictIfExists' - Refuse to cache a component if the calculated checksum is inconsistent with a checksum in the repository. Only perform this check if the checksum file is present.
-
'Strict' - Refuse to cache a component if the calculated checksum is inconsistent or if there is no checksum for a component.
-
- Authentication
-
This section allows you to set a Username, Password, NT LAN Host, and NT Lan Manager Domain for a remote repository.
- Access Settings
-
This section allows for the detailed configuration of access to a repository.
- Deployment Policy
-
This setting controls how a Hosted repository allows or disallows component deployment. If this policy is set to 'Read Only', no deployment is allowed. If this policy is set to 'Disable Redeploy', a client can only deploy a particular component once and any attempt to redeploy an component will result in an error. If this policy is set to 'Allow Redeploy', clients can deploy components to this repository and overwrite the same component in subsequent deployments. This option is visible for hosted repositories as shown in Repository Configuration Access Settings for a Hosted Repository.
- Allow File Browsing
-
When set to true, users can browse the contents of the repository with a web browser.
- Include in Search
-
When set to true, this repository is included when you perform a search in the repository manager. If this setting is false, the contents of the repository are excluded from a search.
- Publish URL
-
If this property is set to false, the repository will not be published on a URL, and you will not be able to access this repository remotely. You would set this configuration property to false if you want to prevent clients for connecting to this repository directly.
- Expiration Settings
-
The repository manager maintains a local cache of components and metadata, you can configure expiration parameters for a proxy repository. The expiration settings are:
- Not Found Cache TTL
-
If the repository manager fails to locate a component, it will cache this result for a given number of minutes. In other words, if the repository manager can’t find a component in a remote repository, it will not perform repeated attempts to resolve this component until the 'Not Found Cache TTL' time has been exceeded. The default for this setting is 1440 minutes (or 24 hours).
- Artifact Max Age
-
Tells the repository manager what that maximum age of a component is, before it retrieves a new version from the remote repository. The default for this setting is -1 for a repository with a release policy and 1440 for a repository with snapshot policy.
- Metadata Max Age
-
The repository manager retrieves metadata from the remote repository. It will only retrieve updates to metadata after the 'Metadata Max Age' has been exceeded. The default value for this setting is 1440 minutes (or 24 hours).
- Item Max Age
-
Some items in a repository may be neither a component identified by the Maven GAV coordinates or metadata for such components. This cache value determines the maximum age for these items before updates are retrieved.
- HTTP Request Settings
-
In the 'HTTP Request Settings' you can change the properties of the HTTP request to the remote repository. You can also configure the 'User Agent' of the request, add parameters to a request, and set the timeout and retry behavior. The HTTP request configured is the request made from the repository manager to the remote repository being proxied.
Beyond these configurations in the user interface, {oss} supports the usage of cookies for remote repositories authentication. Together with the feature to enable circular redirects, this enables proxying repositories like the Oracle Maven repository. The following configuration can be added to nexus.properties and allows a functioning proxy repository to the URL https://maven.oracle.com.
# Comma separated list of hostnames that needs to accept circular redirections nexus.remoteStorage.enableCircularRedirectsForHosts=maven.oracle.com # Comma separated list of hostnames that benefit from using cookies nexus.remoteStorage.useCookiesForHosts=maven.oracle.com
The 'Summary' panel can be loaded by selecting a hosted, proxy, or virtual repository and then clicking on the 'Summary' tab. The 'Summary' tab of a hosted repository, as shown in Repository Summary Panel for a Hosted Repository, displays the distributionManagement settings that can be used to configure Maven to publish components to the hosted repository.
The 'Summary' panel for a proxy repository, as shown in Repository Summary Panel for a Proxy Repository, contains all of the repository identifiers and configuration as well as a list of groups in which the repository is contained.
The 'Summary' panel for a virtual repository, as shown in Repository Summary Panel for a Virtual Repository, displays repository identifiers and configuration as well as the groups in which the repository is contained.
What happens when the repository manager is unable to reach a remote repository? If you’ve defined a proxy repository and the remote repository is unavailable, the repository manager will now automatically block the remote repository. Once a repository has been auto-blocked, the repository manager will then periodically retest the remote repository and unblock the repository once it becomes available. You can control this behavior by changing the 'Auto Blocking Enabled' setting under the 'Remote Repository Access' section of the proxy repository configuration as shown in the following figure to 'True':
{inall}
Repository groups are a powerful feature of {nxrm}. They allow you to combine multiple repositories and other repository groups of the same repository format in a single repository group. This single group and the associated URL can then be used as a single access point to all components in a specific format sourced from an number of repositories.
This eases the configuration for the users and at the same time allows the adminstrators to add more repositories and therefore components without requiring changes on the client computers.
Use the left-hand panel 'Repositories' menu item in the 'Views/Repositories' menu to access the repositories and groups management interface.
To create a new repository group, press the 'Add' button above the repository list and select 'Repository Group'. In the configuration tab provide a 'Group ID' and 'Group Name'. The 'Group ID' will be part of the URL to the repository group and should therefore use a limited set of characters and not contain spaces. Ideally use only lowercase letters and numbers and characters like '-'.
The selection of the 'Provider' determines the repository 'Format' and therefore the list of 'Available Repositories' automatically. To add repositories to the repository group, drag them to the 'Ordered Group Repositories' or use the arrows between the two lists.
Note that the order of the repositories listed in 'Ordered Group Repositories' is important. When the repository manager searches for a component in a group, it will return the first match. To reorder a repository in this list, click and the drag the repositories and groups in the 'Ordered Group Repositories' selection list.
The order of repositories or other groups in a group can be used to influence the effective metadata that will be retrieved from a repository group. We recommend placing hosted repositories higher in the list than proxy repositories within the list. For proxy repositories the repository manager needs to periodically check the remote for updates, which will incur more overhead than a hosted repository lookup.
We also recommend placing repositories with a higher probability of matching the majority of components higher in this list. If most of your components are going to be retrieved from the Central Repository, putting 'Central' higher in this list than a smaller, more focused repository is going to be better for performance, as the repository manager is not going to interrogate the smaller remote repository for as many missing components.
Once a repository group is configured it can be used from the client as discussed in e.g. [config-maven], [npm-configuring], [rubygems-configuring] or [nuget-configuring] and further repositories can be added easily.
{nxrm} ships with one group: public. The Public Repositories group uses the Maven 2 repository format and combines the important external Central Repository with the hosted repositories: 3rd Party, Releases, and Snapshots.
In [config-maven] we configured Maven via the settings.xml to look for components in the public group managed by the repository manager. Group Configuration Screen shows the group configuration screen in the user interface. In this figure you can see the contents of the 'Public Repositories' group.
{inall}
Routing can be considered the internal activities the repository manager 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 the repository manager itself with automatic routing, documented in Automatic Routing. Fine grained control and further customizations in terms of access provision can be achieved with some manual routing configuration documented in Manual Routing Configuration.
Automatic routing is handled 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 '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 the repository manager 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.
The repository manager 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 repository groups that contain the hosted repository. You can access it in the 'Routing' tab of a hosted repository as displayed in 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.
The 'Routing' tab for a proxy repository displayed in 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.
For a proxy repository, the prefix file is either downloaded from the remote repository or generation is attempted by scraping the HTML directory listing of the remote repository. If a prefix file is published by the remote it is always used. The scraping strategy only used in cases where the repository manager can be sure the remote directory listing contains all available artifacts. For example, if the remote is hosted repository on a {nxrm}, or a well known format such as a Subversion based repository then the directory listing will be used if no prefix file is available.
The generation of the prefix file in all the repository managers deployments proxying each other greatly improves performance for all repository manager 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 automatically brings significant performance benefits to all {pro} and {oss} 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 Manual Routing Configuration.
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 component. 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 the repository manager to include or exclude specific repository content paths from a particular component search when the repository manager is trying to locate a component 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 components in a particular group ID from a particular repository. This is especially useful when you want your own organization’s components from the hosted Release and Snapshot repositories only.
Routes are applicable when you are trying to resolve a component from a repository group. Using routes allows you to modify the repositories the repository manager consults when it tries to resolve a component from a group of repositories.
Routing Configuration Screen 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
-
The repository manager uses the 'URL Pattern' will use to match a request. If the regular expression in this pattern is matched, the repository manager will either include or exclude the listed repositories from a particular component query. In Routing Configuration Screen the two patterns are:
^/(com|org)/somecompany/.*-
This pattern would match all paths that start with 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 components 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 starts with
/org/some-oss/. This particular exclusive route excludes the local hosted Releases and Snapshots directory for all components that match this path. When the repository manager tries to resolve components that match this path, it will exclude the Releases and Snapshots repositories. (?!/org/some-oss/.).-
Using this pattern in an exclusive route allows you to exclude everything, except the "org/some-oss" project(s). It uses a special negative matching regular expression.
- 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 components when the URL pattern has been matched. An exclusive rule type defines repositories which should not be searched for a particular component. A blocking rule will completely remove accessibility to the components under the specific pattern in a specified repository group.
- Ordered Route Repositories
-
The repository manager searches an ordered list of repositories to locate a particular component. 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 Routing Configuration Screen you can see the two dummy routes that are 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 components 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 components to the Releases and Snapshots repositories, this Route will make sure that the repository manager doesn’t waste time trying to resolve these components 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 the repository manager 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 component, and therefore the search effort is reduced. |
What if there is a conflict between two routes? The repository manager will process inclusive routes before it will process the exclusive routes. Remember that routes only affect the repository managers resolution of components when it is searching a Group. When it starts to resolve a component from a repository group it will start with the list of repositories in a group. If there are matching inclusive routes, the repository manager 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. The repository manager 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 component.
One straightforward use of routes is to create a route that excludes the Central Repository from all searches for your own organization’s hosted components. If you are deploying your own components to the repository manager under a groupId of org.mycompany, and if you are not deploying these components to a public repository, you can create a rule that tells the repository manager not to interrogate Central for your own organization’s components. This will improve performance because the repository manager will not need to communicate with a remote repository when it serves your own organization’s components. In addition to the performance benefits, excluding the Central Repository from searches for your own components will reduce needless queries to the public repositories.
|
Tip
|
This practice of defining an inclusive route for your internal components to only hit internal repositories
is a crucial best practice of implementing a secure component management in your organization and a recommended
step for initial configuration of the repository manager. Without this configuration, requests for internal
components 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 component
coordinates of com.example.website:secret-feature:1.0.
|
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 components with the specified pattern(s) from the group. As such, blocking routes are a simplified, coarse-grained access control.
|
Tip
|
Check out [procure] for fine-grained control of component availability and use blocking routes sparingly. |
To summarize, there are creative possibilities with routes that the designers of {pro} 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 a component is requested from a specific repository.
{inall}
The repository managerss allows you to schedule tasks that will be applied to all repositories or to specific repositories on a configurable schedule. Use the 'Scheduled Tasks' menu item in the 'Administration' menu to access the screen, shown in Managing Scheduled Tasks, that allows you to manage your Scheduled Tasks.
The list interface allows you to 'Add' new tasks and 'Run', 'Cancel', and 'Delete' existing tasks as well as 'Refresh' the list with respective buttons above the list.
When creating or updating a scheduled task, you can configure the following properties:
- Enabled
-
Enable or disable a specific task.
- Name
-
Provide a name to identify the task in the user interface and log files.
- Task Type
-
Specify the type of action the scheduled task executes. The list of available task types is documented in more detail below.
- Task Settings
-
Configure the task settings specific to the selected task type. Tasks affecting a repository have a setting called 'Repository/Group' that allows you to let the task affect all repositories and groups or only a specific one.
- Alert Email
-
Configure a notification email for task execution failures. If a scheduled task fails a notification email containing the task identifier and name as well as the stack trace of the failure will be sent to the configured email recipient.
- Recurrence
-
Configure the schedule for the task executions. Available choices are Manual, Once, Hourly, Daily, Weekly, Monthly and Advanced. All choices provide a custom user interface for scheduling the specific recurrence. Weekly scheduling requires at least one day of the week to be selected. The Advanced setting allows you to provide a CRON expression to configure more complex schedules.
The following kinds of scheduled task types are available:
- Backup All Configuration Files
-
This scheduled task will archive the contents of the sonatype-work/nexus/conf directory. Once a backup has been run, the contents of the backup will be available in sonatype-work/nexus/backup in a series of ZIP archives that use a datetimestamp in the filename. This task is a feature of {pro}.
- Backup npm metadata database
-
A backup archive of the npm metadata database is created in the sonatype-work/nexus/backup/npm with a date and time stamp in the filename. This backup is intended to be used for disaster recovery in case the npm metadata database got corrupted.
- Delete npm metadata
-
This task allows you to completely delete the npm metadata of a npm repository and should be only run manually upon advice from Sonatype support.
- Download Indexes
-
This scheduled task causes the repository manager to download indexes from remote repositories for proxied repositories. The Download Remote Indexes configuration also needs to be enabled on the proxy repository.
- Download NuGet Feed
-
This task allowed you to download the feed for a NuGet proxy repository. It should not be used any longer, since it has negative impacts on the performance of your {pro} or {oss} as well as Nuget.org. With {nxrm} 2.11.3+ it has been changed to perform no operation at all to avoid this problem. It is safe to remove any executions of this task.
- Drop Inactive Staging Repositories
-
Staging repositories can be dropped by user interaction or automated systems using the Nexus Staging Maven Plugin or Ant Task or a REST API call. Heavy users of the repository manager staging features observe that some staging and build promotion repositories are inevitably left behind. This scheduled task can be used to drop all these repositories. You can configure the duration of inactivity to include the days after the repositories are dropped as well as the status of the repositories. Any change of the staging repository like a state change from open to closed to promoted or released as well other changes to the repository meta data like a description update are counted as an activity. You can configure to 'Scan open repositories', 'Scan closed repositories', 'Scan promoted repositories' and 'Scan released repositories' for inactivity and therefore potentially drop them with this task. This will allow you to avoid accumulating a large number of stale staging repositories.
- Empty Trash
-
The Evict and Purge actions do not delete data from the repository manager working directory. They simply move data to be cleared or evicted to a trash directory under the work directory. This task deletes the data in this trash directory older than the number of days specified in the task setting 'Purge items older than (days)'.
- Evict Unused Proxied Items From Repository Caches
-
This scheduled task tells the repository manager to delete all proxied items that haven’t been "used" (referenced or retrieved by a client) in a number of days as specified in 'Evict items older than (days)'. This can be a good job to run if you are trying to conserve storage space and do not need all of the components in the future e.g., to reproduce old builds without renewed retrieval. This is particularly useful for a personal repository manager deployment with a large change rate of components combined with limited diskspace.
- Expire Repository Caches
-
Repositories have several caches to improve performance. This task expires the caches causing the repository manager to recheck the remote repository for a proxy repository or the file system for a hosted repository. You can configure the repository or group to be affected with the task setting 'Repository/Group'. Additionally you can provide a Repository Path to configure the content that should be expired.
- Mirror Eclipse Update Site
-
The P2 plugin allows you to mirror Eclipse update sites. This task can be used to force updates of repositories that went out of sync.
- Optimize Repository Index
-
To speed up searches in the repository manager, this task tells the internal search engine to optimize its index files. This has no affect on the indexes published by the repository manager. Typically, this task does not have to run more than once a week.
- Publish Indexes
-
Just as Maven downloads an index from a remote repository, the repository manager can publish an index in the same format. This will make it easier for people using m2eclipse or {nxrm} to interact with your repositories.
- Purge Nexus Timeline
-
The repository manager maintains a lot of data that relates to the interaction between itself, proxied remote repositories, and clients. While this information can be important for purposes of auditing, it can also take up storage space. Using this scheduled task you can tell the repository manager to periodically purge this information. The setting "Purge Items older than (days)" controls the age of the data to be deleted.
- Purge Orphaned API Keys
-
This scheduled tasks will delete old, unused API keys generated and used by various plugins. For example, it should be scheduled when using the User Token feature or NuGet repositories. It will purge orphaned API keys e.g., after users reset their token and should be scheduled to run regularly, specifically when internal security policies for password resets and you are using an external security provider like LDAP with this requirement for resets to access the repository manager.
- Rebuild Maven Metadata Files
-
This task will rebuild the maven-metadata.xml files with the correct information and will also validate the checksums (.mh5/.sha1) for all files in the specified Repository/Group. Typically this task is run manually to repair a corrupted repository.
- Rebuild NuGet Feed
-
If you are using NuGet, pushing your components into a NuGet hosted repository and are proxying that repository to other users, this task can be used to rebuild the feed.
- Rebuild P2 metadata and Rebuild P2 repository
-
These tasks can be used to rebuild the metadata or the full repository with a P2 format. You can specify a Repository/Group or a Repository Path to determine which content to affect.
- Rebuild hosted npm metadata
-
The npm metadata for a hosted repository can be rebuilt based on the components found in the storage of a hosted repository. The task can serve as a recovery tool in cases where the npm metadata database got corrupted or the component storage was created manually or via some external process like e.g. an rsync copying.
- Reconcile Repository Checksums
-
This task was used to repair checksums and should only be used upon specific advise from Sonatype support.
- Remove Releases From Repository
-
In many use cases of a repository manager, it is necessary to keep release components for long periods of time or forever. This can be necessary for reproducibility reasons, in order to ensure users have access to old versions or even just for audit or legal reasons. However, in other use cases, there is no value in keeping old release components. One example would be a when using a continuous delivery approach onto a single deployment platform with no roll back support. In other cases, it could also be impractical due to the mere number and size of the release components.
This scheduled task allows you to trigger the deletion of release components, supporting these use cases taking care of meta data updates, and removing the need to manually delete the components or use an external system to trigger the deletion.
To configure the task, you specify the repository where release components are to be deleted as well as the number of component versions to keep for a specific groupId and artifactId coordinate. The task generates a list of all versions of a component for each groupId and artifactId coordinate combination and sorts it according to the version number. The ordering is derived by parsing the version string and supports sematic versioning with additional semantics for specific classifiers. Further details can be found in the documentation for the implementing class GenericVersionScheme.
Optionally, the 'Repository Target' parameter can be used to narrow down the content of the repository that is analyzed, to determine if any deletion should occur. Choosing All(Maven2) is suitable to cause all Maven 2-formatted repositories to be analysed. If you want to only target a specific groupId and artifactId combination or a number of them you can create a suitable repository target as documented in Managing Repository Targets and use it in the configuration of the scheduled task.
- Remove Snapshots from Repository
-
Often, you will want to remove snapshots from a snapshot repository to preserve storage space. This task supports this deletion for time stamped snapshots as created by Maven 3.x in a deployment repository. Note that configuring and running this job is not enough to reclaim disk space. You will also need to configure a scheduled job to empty the trash folder. Files are not deleted by the 'Remove Snapshots' job. They are only moved into the trash folder. When you create a scheduled task to remove snapshots, you can specify the 'Repository/Group' to affect as well as:
- 'Minimum snapshot count'
-
This configuration option allows you to specify a minimum number of snapshots to preserve per component. For example, if you configured this option with a value of 2, the repository manager will always preserve at least two snapshot components. A value of -1 indicates that all snapshots should be preserved.
- 'Snapshot retention (days)'
-
This configuration option allows you to specify the number of days to retain snapshot components. For example, if you want to make sure that you are always keeping the last three day’s worth of snapshot components, configure this option with a value of 3. The minimum count overrides this setting.
- 'Remove if released'
-
If enabled and a released component with the same GAV coordinates is detected all snapshots will be removed.
- 'Grace period after release (days)'
-
This parameter allows you to specify a number of days before released snapshots are purged. If a release associated to a snapshot has an updated timestamp and falls within the set grace period, it will not be purged. This setting will give the respective project that references the snapshot dependency time to upgrade to the release component or the next snapshot version.
- 'Delete immediately'
-
If you want to have components deleted directly rather than moved to the trash, you can enable this setting.
When doing regular deployments to a snapshot repository via a CI server, this task should be configured to run regularly.
- Remove Unused Snapshots From Repository
-
This task allows you to have SNAPSHOT versions deleted from a Maven repository after they have not been requested for a specified number of days.
- Repair Repositories Index
-
In certain cases it might be required to remove the internal index as well as the published ones of a repository. This task does that and then rebuilds the internal index by first trying to download remote indexes (if a proxy repository), then scanning the local storage and updating the internal index accordingly. Lastly, the index is published for the repository as well. There should be no need to schedule this task. But when upgrading the repository manager, the upgrade instructions may sometimes include a manual step of executing this task.
- Rubygems: Purge Broken Files on Proxy
-
This task allows you to delete the broken metadata of a proxy gem repository.
- Rubygems: Rebuild Hosted Index Files
-
This task can be used to get the metadata file for a hosted gem repository recreated based on the actual components found in the repository.
- Rubygems: Synchronize Proxied Index File
-
This task can be used to force an update of the metadata in a Gem proxy repository and cause it to be synchronized with the metadata in the remote repository.
- Synchronize Shadow Repository
-
This service synchronizes a shadow (or virtual) repository with its master repository. This task is only needed when external changes affected a source repository of a virtual repository you are using.
- Update Repositories Index
-
If files are deployed directly to a repository’s local storage (not deployed through the user interface or client tools), you will need to instruct the repository manager to update its index. When executing this task, the repository manager will update its index by first downloading remote indexes (if a proxy repository) and then scan the local storage to index the new files. Lastly, the index is published for the repository as well. Normally, there should be no need to schedule this task. One possible exception would be if files are deployed directly to the local storage regularly.
- Yum: Generate Metadata
-
The metadata for a yum repository is created and maintained by the createrepo tool. This scheduled task allows you to run it for a specific repository and optionally configure the output directory.
Beyond these tasks any plugin can provide additional scheduled tasks, which will appear in the drop-down once you have installed the plugin.
The Evict and Purge actions do not delete data from the repository manager working directory. They simply move data to be cleared or evicted to a trash directory under the work directory. If you want to reclaim disk space, you need to clear the Trash on the Browse Repositories screen. If something goes wrong with a evict or clear service, you can move the data back to the appropriate storage location from the trash. You can also schedule the Empty Trash service to clear this directory on a periodic basis.
|
Tip
|
In order to keep the heap usage in check it is recommended that you schedule an "optimize indexes" task to run weekly. A number of other maintenance tasks should also be scheduled for production deployments. |
Setting up scheduled tasks adapted to your usage of the repository manager is an important first step. Go through the list of task types and consider your usage patterns of the repository manager. Also update your scheduled tasks when changing your usage. E.g., if you start to regularly deploy snapshots by introducing continuous integration server builds with deployment.
{inall}
Capabilities are features of the repository manager and plugins that can be configured by a user in the generic administration view accessible in the left-hand navigation menu 'Administration' under 'Capabilities'.
|
Warning
|
In many cases you will not need to configure anything in 'Capabilities' unless explicitly instructed to do so by the Sonatype support team. Execute any capability changes with caution, potentially backing up your configuration before proceeding. |
{nxrm} ships with a number of capabilities preinstalled and allows you to enable/disable them. An example capability is 'Outreach Management' displayed in Capabilities Management Interface with the Outreach Management Details Visible. The capabilities management interface supports adding new capabilities by pressing the 'New' button, copying a selected capability from the list by pressing the 'Duplicate' button and deleting a selected capability with the 'Delete' button. Pressing the 'Refresh' button updates the list of capabilities. The list of capabilities can be filtered with the search input box in the header of the list and sorted by the different columns by pressing a column header. The list uses the following columns:
- Status
-
The status column does not have a title. Enabled capabilities have a green checkmark added on top of a blue icon. If an enabled capability is not fully operational the icon displays a warning sign on top of the blue icon and the entire row is surrounded with a red border; you can find out further information in a warning message below the list of the capabilities and above the individual tabs. Disabled capabilities use a greyed out icon.
- Type
-
The 'Type' column provides the specific type of a capability in the list.
- Category
-
The 'Category' is optional and details the wider context the capability belongs to.
- Repository
-
The 'Repsitory' value is optional and references the repository for which the specific capability is configured.
- Description
-
The 'Description' column contains further descriptive information about the capability.
- Notes
-
The 'Notes' column can contain user created notes about the capability.
Every capability can be inspected and configured by selecting it in the list and using the tabs underneath the list.
The 'Summary' tab displays the 'Type' of the capability as well as optionally the 'Description', the 'Category' and the 'Repository'. The 'Notes' field can be used to provide a descriptive text about the capability or any other notes related to it and can be persisted by pressing the 'Save' button. The 'Discard' link can be used to reset any changes in the tab.
The 'Settings' tab allows you to activate or deactivate the capability with the 'Enabled' checkbox. Below this checkbox, each capability type has specific additional configuration parameters available. Mousing over the help icon beside the input field or checkbox reveals further information about the specific parameter. Once you have completed the configuration, press the 'Save' button. The 'Discard' link can be used to reset any changes in the tab.
The 'Status' tab displays a text message that details the status of the capability and any potential problems with the configuration. Depending on the capability, the reasons can vary widely. For example, the 'Secure Central' capability requires the repository manager to run on a JVM with specific security features. If the JVM is not suitable, an error message with further details is displayed in the 'Status' column.
The 'About' tab displays a descriptive text about the purpose of the capability.
Creating a new capability by pressing the 'New' button will display a new form allowing you to configure the capability in a dialog. The 'Type' drop-down allows you to decide what capability to create, and a selection changes the rest of the available information and configuration in the dialog. You can configure if the capability should be enabled with the 'Enabled' checkbox. Once you have completed the configuration, press 'Add' and the capability will be saved and appear in the list.
Many of the built-in capabilities and plugins can be configured in the 'Capabilities' administration section but also in other more user friendly, targeted user interface sections, e.g., the user token feature administrated by using the interface available via the 'User Token' menu item in the 'Security' left-hand menu as well as by editing the user token capability. Other capabilities are internal to repository manager functionality and sometimes managed automatically by the responsible plugin. Some optional configuration like the branding plugin is only done in the capabilities administration. The branding plugin allows the customization of the icon in the top left-hand corner of the user interface header and is described in Customizing the User Interface with Branding.
{inrmonly}
The branding plugin is part of {pro} and allows you to customize your repository manager instance by replacing the default {pro} logo in the top left-hand corner of the header with an image of your choice.
You can configure it by adding the 'Branding' capabililty as documented in Accessing and Configuring Capabilities and enabling it. By default, the branding plugin will look for the new logo in a file called branding.png in your data directory’s conf folder. By default, the location is therefore sonatype-work/nexus/conf/branding.png. The new logo needs to be a PNG image. To blend in well in the UI, it is recommended that it is of 60 pixels height and has a transparent background.
If it fails to find a new logo, the plugin will fall back to using the default logo.
Prior to {pro} 2.7, the branding plugin was an optional plugin and needed to be installed following the documentation in [install-additional-plugins]. In this case you needed to add a branding.image.path property to the 'nexus.properties' file in '$NEXUS_HOME/conf/':
branding.image.path=/data/images/nexus_logo.png
{inall}
The Outreach Plugin is installed and enabled by default in {oss} and {pro}. It allocates space underneath the search feature on the 'Welcome' tab for linking to further documentation and support resources. This data is retrieved from Sonatype servers.
In a case where this outgoing traffic from your repository manager instance or the resulting documentation and links are not desired, the plugin can be disabled. The plugin can be disabled in the settings for the 'Outreach:Management' capability as documented in Accessing and Configuring Capabilities.
You can safely remove the plugin as well without any other negative side effects. To do so, simply remove the 'nexus-outreach-plugin-X.Y.Z' folder in '$NEXUS_HOME/nexus/WEB-INF/plugin-repository/' and restart your repository manager instance.
{inall}
By default, the repository manager listens on port 8081. You can change this port, by changing the value in the $NEXUS_HOME/conf/nexus.properties file shown in Contents of conf/nexus.properties. To change the port, stop the repository manager, change the value of applicationPort in this file, and then restart it. Once you do this, you should see a log statement in $NEXUS_HOME/logs/wrapper.log telling you that the repository manager is listening on the altered port.
# Sonatype Nexus
# ==============
# This is the most basic configuration of Nexus.
# Jetty section
application-port=8081
application-host=0.0.0.0
nexus-webapp=${bundleBasedir}/nexus
nexus-webapp-context-path=/nexus
# Nexus section
nexus-work=${bundleBasedir}/../sonatype-work/nexus
runtime=${bundleBasedir}/nexus/WEB-INF
{inall}
You can configure the level of logging for the repository manager and all plugins as well as inspect the current log using the user interface. Access the 'Logging' panel by clicking on the 'Logging' menu item in the 'Administration' submenu in the main menu. Clicking on this link will display the panel shown in The Logging Panel with the Loggers Configuration.
The 'Loggers' tab in the panel allows you to configure the preconfigured loggers as well as add and remove loggers. You can modify the log level for a configured logger by clicking on the 'Level' value e.g., INFO. It will change into a drop-down of the valid levels including OFF, DEFAULT, INFO and others.
If you select a row in the list of loggers, you can delete the highlighted logger by pressing the 'Remove' button above the list. The 'Add' button beside it can be used to create new loggers in a dialog. You will need to know the logger you want to configure. Depending on your needs you can inspect the source of {oss} and the plugins as well as the source of your own plugins to determine the related loggers or contact Sonatype support for detailed help. In addition, it is important to keep in mind that some loggers will change between repository manager and plugin versions used.
The 'Reset' button allows you to remove all your custom loggers and get back to the setup shipped with the repository manager.
The loggers configured in the user interface are persisted into sonatype-work/nexus/conf/logback-overrides.xml and override any logging levels configured in the main log file logback-nexus.xml as well as the other logback-* files. If you need to edit a logging level in those files, we suggest to edit the overrides file. This will give you access to edit the configuration in the user interface at a later stage and also ensure that the values you configure take precedence.
The 'ROOT' logger level controls how verbose the logging is in general. If set to DEBUG, logging will be very verbose printing all log messages including debugging statements. If set to ERROR, logging will be far less verbose, only printing out a log statement if the system encounters an error. INFO represents an intermediate amount of logging.
|
Tip
|
When configuring logging, keep in mind that heavy logging can have a significant performance impact on an application and any changes in the user interface trigger the change to the logging immediately. |
In {nxrm} releases prior to 2.7, logging configuration needed to be done by editing the logback-nexus.xml file found in sonatype-work/nexus/conf.
Once logging is configured as desired, you can inspect the impact of your configuration on the 'Log' tab. It allows you to copy the log from the server to your machine by pressing the 'Download' button. The 'Mark' button allows you to add a custom text string into the log, so that you can create a reference point in the log file for an analysis of the file. It will insert the text you entered surrounded by * symbols as visible in Viewing the Log with a Mark.
The 'Refresh' button on the left triggers an immediate update of the log. The refresh drop-down on the right can be used to trigger updates of the log in regular time intervals or manually. The size drop-down beside it allows you to control the size of the log snippet displayed in the user interface.
{inall}
As documented in [install-additional-plugins], {pro} and {oss} are built as a collection of plugins supported by a core architecture and additional plugins can be installed.
You can use the Plugin Console to list all installed plugins and browse REST services made available by the installed plugins. To open the Plugin Console, click on the 'Plugin Console' link in the 'Administration' menu in the left-hand main menu.
Once you open the Plugin Console, you will see a list of plugins installed in your repository manager installation. Clicking on a plugin in this list will display information about the plugin including name, version, status, a description, SCM information about the plugin, and the URL of the plugin’s project web site and links to the plugin documentation.
All the functionality in the user interface is accessing the REST API’s provided by the different plugins. An example for the plugin documentation is the main documentation for the core Nexus API linked off the Nexus Restlet 1.x Plugin from Plugin Console and displayed in Documentation Website for the Core REST API
You can use the REST API to integrate the repository manager with your external systems.
If your external integration uses Java, or is otherwise JVM based, then you can use the {nxrm} client using the dependency from Nexus Client Core Dependency for Maven Projects with the version corresponding to your repository manager version.
<dependency>
<groupId>org.sonatype.nexus</groupId>
<artifactId>nexus-client-core</artifactId>
<version>2.12.1-01</version>
</dependency>
Examples of using the client library can be found in the Nexus Maven Plugins or the Nexus Ant Tasks.
The REST API can be invoked from many other programming and scripting languages. A simple example of using the curl command in a shell script is displayed in A curl Invocation Loading the List of Users from the repository manager.
curl -X GET -u admin:admin123 http://localhost:8081/nexus/service/local/users
{inall}
{pro} and {oss} use a role-based access control (RBAC) system that gives administrators very fine-grained control over who can read from a repository (or a subset of repositories), who can administer the server, and who can deploy to repositories. The security model in the repository manager is also so flexible as to allow you to specify that only certain users or roles can deploy and manage components in a specific repository under a specific groupId or asset class. The default configuration of {pro} and {oss} ships with four roles and four users with a standard set of permissions that will make sense for most users. As your security requirements evolve, you’ll likely need to customize security settings to create protected repositories for multiple departments or development groups. {pro} and {oss} provide a security model which can adapt to any scenario. The security configuration is done via menu items in the 'Security' submenu in the left-hand main menu.
The RBAC system is designed around the following four security concepts:
- Privileges
-
Privileges are rights to read, update, create, or manage resources and perform operations. The repository manager ships with a set of core privileges that cannot be modified, and you can create new privileges to allow for fine-grained targeting of role and user permissions for specific repositories.
- Targets
-
Privileges are usually associated with resources or targets. A target can be a specific repository or a set of repositories grouped in something called a repository target. A target can also be a subset of a repository or a specific set of assests within a repository e.g. all javadoc archives only. Using a target you can for example also apply a specific privilege to a single groupId and all components using it.
- Roles
-
Collections of privileges can be grouped into roles to make it easier to define collections of privileges common to certain classes of users. For example, deployment users will all have similar sets of permissions. Instead of assigning individual privileges to individual users, you use roles to make it easier to manage users with similar sets of privileges. A role has one or more privileges and/or one or more roles.
- Users
-
Users can be assigned roles and will model the individuals who will be logging into the repository manager and reading, deploying, or managing repositories.
{inall}
You can access the configuration of privileges via the 'Privileges' menu item in the 'Security' submenu in the left-hand main menu.
The repository manager has three types of privileges:
-
application privileges - covers actions a user can execute in the user interface,
-
repository target privileges - governs the level of access a user has to a particular repository or repository target, and
-
repository view privileges - controls whether a user can view a repository
Behind the scenes, a privilege is related to a single REST operation and method like create, update, delete, read.
To create a new privilege, click on the 'Add…' button in the 'Privileges' panel and choose 'Repository Target Privilege'. Creating a privilege will load the New Repository Target Privilege form shown in Creating a New Repository Target Privilege. This form takes a privilege name, a privilege description, the repository to target, and a repository target.
Once you create a new privilege, it will create four underlying privileges: create, delete, read, and update. The four privileges created by the form in Creating a New Repository Target Privilege are shown in Create, Delete, Read, and Update Privileges Created.
{inall}
A 'Repository Target' is a set of regular expressions to match on the path of components in a repository (in the same way as the routing rules work). {pro} and {oss} are preconfigured with a number of repository targets and allows you to create additional ones. Access the management interface visible in Managing Repository Targets via the 'Repository Targets' menu item in the left-hand 'Views/Repositories' sub menu.
Repository targets allow you to define, for example, a target called
Apache Maven with a pattern of ^/org/apache/maven/.*. This would
match all components with a groupId of 'org.apache.maven' and any
components within nested groupIds like 'org.apache.maven.plugins'.
A pattern that would capture more components like all components with
any part of the path containing 'maven' could be .maven..
The regular expressions can also be used to exclude components as
visible with the pattern (?!.-sources.).* in
Excluding Source Components from a Repository Targets where components with the qualifier
'-sources' are excluded. The syntax used for the expressions is the
Java syntax,
that is similar but not identical to the Perl syntax.
By combining multiple patterns in a repository target, you can establish a fine-grained control of components included and excluded.
Once you have created a repository target, you can utilize it as part of your security setup. You can add a new privilege that relates to the target and controls the CRUD (Create, Read, Update and Delete) operations for artifacts matching that path. The privilege can even span multiple repositories. With this setup you can delegate all control of components in 'org.apache.maven' to a "Maven" team. In this way, you don’t need to create separate repositories for each logical division of your components.
Repository targets are also be used for matching components for implicit capture in the Staging Suite as documented in [staging].
{inall}
{pro} and {oss} ship with a large number of roles predefined including 'Nexus Administrator Role', 'Nexus Anonymous Role', 'Nexus Developer Role', and 'Nexus Deployment Role'. Click on the 'Roles' menu item under 'Security' in the main menu to show the list of roles shown in Viewing the List of Defined Roles.
To create a new role, click on the 'Add…' button, select 'Nexus Role' and fill out the 'New Nexus Role' form shown in Creating a New Nexus Role.
When creating a new role, you will need to supply a 'Role ID', a 'Name' and a 'Description'. Roles are comprised of other roles and individual privileges. To assign a role or privilege to a role, click on 'Add' button under 'Role/Privilege Management' to access the 'Add Roles and Privileges' dialog displayed in The Dialog to Add Roles and Privileges. It allows you to filter the paged displayed of all the available roles and privileges with a filter text as well as narrowing the search to roles or privileges only. Using the filter and the paging you will be able to find the desired role or privilege quickly.
The built-in roles are managed by Nexus and cannot be edited or deleted. The role confirguration section below the list is visible but disabled for these roles.
A role is comprised of other roles and individual privileges. To view the component parts of a role, select the role in the Roles list and then choose the 'Role Tree' tab as shown in Viewing a Role Tree.
|
Tip
|
With the Repository Targets, you have fine-grained control over
every action in the system. For example, you could make a target that
includes everything except sources (.(?!-sources)\.) and assign that
to one role while giving yet another role access to everything. Using
these different access roles e.g., you can host your public and private
components in a single repository without giving up control of your
private components.
|
{inall}
{pro} and {oss} ships with three users: 'admin', 'anonymous', and 'deployment'. The admin user has all privileges, the anonymous user has read-only privileges, and the deployment user can both read and deploy to repositories. If you need to create users with a more focused set of permissions, you can click on 'Users' under 'Security' in the left-hand main menu. Once you see the list of users, you can click on a user to edit that specific user’s 'First Name', 'Last Name' and 'Email'. Editing a users 'Status' allows you to activate or disable a user altogether. You can also assign or revoke specific roles for a particular user.
Clicking the 'Add' button in the 'Role Management' section will bring up the list of available roles in a pop-up window visible in Adding Roles to a User. It allows you filter and search for roles and add one or multiple roles to the user.
A user can be assigned one or more roles that in turn can include references to other roles or to individual privileges. To view a tree of assigned roles and privileges, select the 'Role Tree' for a particular user as shown in User Role Tree.
If you need to find out exactly how a particular user has been granted a particular privilege, you can use the 'Privilege Trace' panel as shown in User Privilege Trace. The 'Privilege Trace' panel lists all of the privileges that have been granted to a particular user in the 'Privileges' section. Clicking on a privilege loads a tree of roles that grant that particular privilege to a user. If a user has been assigned a specific privilege by more than one Role or Privilege assignment, you will be able to see this reflected in the 'Role Containment' list.
Additional plugins can contribute further panels for the security configuration of a user. An example of an additional panel is the 'User Token' panel, added by the User Token feature of {pro} as documented in Security Setup with User Tokens.
{inrmonly}
When using Apache Maven with {pro} or {oss}, the user credentials for accessing the repository manager have to be stored in clear text in the user’s settings.xml file. Maven has the ability to encrypt passwords in setting.xml, but the need for it to be reversible in order to be used, limits its security. In addition, the general setup and use is cumbersome, and the potential need for regular changes due to strong security requirements e.g., with regular, required password changes triggers the need for a simpler and more secure solution.
Other build systems use similar approaches and can benefit from the usage of User Token as well.
The User Token feature of {pro} fills that need for Apache Maven as well as other build systems and users. It introduces a two-part token for the user, replacing the username and password with a user code and a pass code that allows no way of recovering the username and password from the user code and pass code values; yet can be used for authentication with the repository manager from the command line via Maven as well as in the UI.
This is especially useful for scenarios where single sign-on solutions like LDAP are used for authentication against the repository manager and other systems and the plain text username and password cannot be stored in the settings.xml following security policies. In this scenario the generated user tokens can be used instead.
User token usage is integrated in the Maven settings template feature of {pro} documented in [maven-settings] to further simplify its use.
The user token-based authentication can be activated by an administrator or user with the role usertoken-admin or usertoken-all by accessing the 'User Token' item in the 'Security' submenu on the left-hand main menu.
Once user token is 'Enabled' by activating the checkbox in the administration tab displayed in User Token Administration Tab Panel and pressing 'Save', the feature is activated and the additional section to Reset All User Tokens is available as well.
Selecting the 'Protect Content' feature configures the repository manager to require a user token for any access to the content URLs that includes all repositories and groups. This affects read access as well as write access e.g., for deployments from a build execution or a manual upload.
'Activating User Token' as a feature automatically adds the 'User Token Realm' as a 'Selected Realm' in the 'Security Settings' section as displayed in Selected Realms Server Security Settings with User Token Realm activated and available in the 'Server' section of the left-hand 'Administration' menu. If desired, you can reorder the security realms used, although the default settings with the 'User Token Realm' as a first realm is probably the desired setup. This realm is not removed when the User Token feature is disabled; however, it will cleanly pass through to the next realm and with the realm remaining any order changes stay persisted in case the feature is reactivated at a later stage.
Besides resetting all user tokens, an administrator can reset the token of an individual user by selecting the 'User Token' tab in the 'Users' administration from the 'Security' menu in the left-hand navigation displayed in User Token Reset for Specific User in Security Users Administration. The password requested for this action to proceed is the password for the currently logged in administrator resetting the token(s).
|
Warning
|
Resetting user tokens forces the users to update the
settings.xml with the newly created tokens and potentially breaks any
command line builds using the tokens until this change is
carried out. This specifically also applies to continuous integration
servers using user tokens or any other automated build executions.
|
With user token enabled, any user can access his/her individual tokens via their 'Profile' panel. To access the panel, select 'Profile' when clicking on the user name in the top right-hand corner of the user interface. Then select 'User Token' in the drop-down to get access to the 'User Token' screen in the 'Profile panel' displayed in User Token Panel for the Logged in Users in the Profile Section.
In order to be able to see this 'User Token' panel the user has to have the usertoken-basic role or the usertoken:current privilege. To access or reset the token you have to press the respective button in the panel and then provide your username and password in the dialog.
Resetting the token will show and automatically hide a dialog with a success message and accessing the token will show the dialog displayed in Accessing the User Token Information.
The User Token dialog displays the user code and pass code tokens in separate fields in the top level section as
well as a server section ready to be used in a Maven settings.xml file. When using the server section you simply
have to replace the ${server} placeholder with the repository id that references your repository manager you
want to authenticate against with the user token. The dialog will close automatically after one minute or can be
closed with the Close button.
The user code and pass code values can be used as replacements for username and password in the login dialog. It is also possible to use the original username and the pass code to log in to the user interface.
With content protection enabled, command line access to the repository manager will require the tokens to be supplied. Access to e.g., the releases repository via
curl -v --user admin:admin http://localhost:9081/content/repositories/releases/
has to be replaced with the usage of user code and pass code separated by colon in the curl command line like this
curl -v --user HdeHuL4x:Y7ZH6ixZFdOVwNpRhaOV+phBISmipsfwVxPRUH1gkV09 http://localhost:9081/content/repositories/releases/
User token values can be accessed as part of the Maven settings template feature automating updates as documented in [maven-settings].
|
Note
|
The user tokens are created at first access whether that is by using the user interface or the Nexus Maven Plugin. |
The user token feature is preconfigured with built-in parameters and no external configuration file is created by default. It is however possible to customize some behavior by creating a file 'sonatype-work/nexus/conf/usertoken.properties'.
The following properties can be configured:
- usertoken.userTokenServiceImpl.allowLookupByUserName
-
This parameter controls if username lookup is allowed when using a pass code. The default is set to true. If set to false, user code and pass code have to be used to authenticate, otherwise username and pass code is also possible. This would be the more secure setting.
- usertoken.userTokenServiceImpl.restrictByUserAgent
-
With this value set to true (the default), any access to the repository manager content with content protection enabled will only be allowed to browser-based access even without credentials. Other tools like curl or wget or other command-line tools will be blocked. With the more secure setting of false, any access without correct codes will be disallowed.
The 'usertoken.' prefix is optional when the properties are loaded from the 'usertoken.properties' file.
{inall}
{pro} and {oss} allow integration with external security systems that can pass along authentication of a user via the REMOTE_USER HTTP header field - Remote User Token 'Rut' authentication. There are either web-based container or server-level authentication systems like Shibboleth. In many cases, this is achieved via a server like Apache HTTPD or nginx proxying the repository manager. These servers can in turn defer to other authentication storage systems e.g., via the Kerberos network authentication protocol. These systems and setups can be described as Central Authentication Systems CAS or Single Sign On SSO.
From the users perspective, he/she is required to login into the environment in a central login page that then propagates the login status via HTTP headers. The repository manager simply receives the fact that a specific user is logged in by receiving the username in a HTTP header field.
The HTTP header integration can be activated by adding and enabling the 'Rut Auth' capability as documented in Accessing and Configuring Capabilities and setting the 'HTTP Header name' to the header populated by your security system. Typically, this value is REMOTE_USER, but any arbitrary value can be set. An enabled capability automatically causes the 'Rut Auth Realm' to be added to the 'Selected Realms' in the 'Security Settings' described in Security Settings.
When an external system passes a value through the header, authentication will be granted and the value will be used as the user name for configured authorization scheme. For example, on a default repository manager installation with the Xml authorization scheme enabled, a value of 'deployment' would grant the user the access rights in the user interface as the 'deployment' user.
A seamless integration can be set up for users if the external security system is exposed via LDAP and configured in the repository manager as LDAP authorization realm combined with external role mappings and in parallel the sign-on is integrated with the operating system sign-on for the user.