Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

3. Managing Resource-Level Content Updates

JBoss Operations Network can be used to store and deploy content to resources. This can be done to apply updates and patches (as with JBoss AS servers) or to set up repositories used for provisioning applications and deploying custom software.

3.1. About Content

Content for a resource can be almost anything, such as WAR and EAR files, configuration files, or scripts. JBoss ON provides a central framework to associate content, repositories, and resources in the inventory.

3.1.1. What Content Is: Packages

A package is anything that is installed on a platform or for a server or application. This can be an RPM, a JAR file, or even just a configuration file. A package simply provides some form of content for a resource. Packages can be sent to a resource through a JBoss ON-recognized repository or simply by uploading the package to the JBoss ON server and then sending it to the resource.
A resource can only be associated with or manage content if the resource plug-in identifies that content is available and the type of content that is supported. For example, application and web servers like JBoss AS/EAP and Tomcat support EAR, WAR, and JAR files as content; platforms support content like RPMs; but a database like PostgreSQL does not support any content types.
In a sense, content is both the software bits, scripts, or configuration files associated with a resource and also a resource itself. When content is added to a resource, it becomes a child resource in the JBoss ON hierarchy — but it can be managed, reverted, updated, or replaced by uploading new software bits. The parent resource (such as the application server) supports content; the child resource is a content backed resource.
Content can be added to a resource either by manually creating a child resource (and uploading the packages) or by adding the package to a content source and deploying it to the parent resource. The agent can also actively check for new content as part of its discovery scan and add any discovered content to its inventory. The agent's recurring package discovery scan has a default interval of 24 hours, as with the services scan.

3.1.2. Where Content Comes From: Providers and Repositories

Content sources are developers and distributors of content. Sources can be external third party software developers or internal development teams that create custom content. The type of content available from sources includes both software packages (such as RPMs or configuration scripts) and updates (version upgrades, patches, and errata).
A repository is a user-defined collection of software packages, which can come from one or multiple content sources. A repository may contain packages for an application or family of applications or for a specific purpose, like repositories for laptop configuration and repositories for installing web servers.
Repositories aren't siloed, separate containers for packages; they are essentially views that show a subset of available packages. All packages are stored in the JBoss ON database. A JBoss ON repository is a way of grouping those packages, both to make it easier to administer with resources and to provide a mechanism of access control for users (Section 3.1.4, “Authorization to Repositories and Packages”).
Resources can be subscribed to content repositories that are configured in JBoss ON, which provides a smooth and reliable mechanism for delivering consistent, administrator-configured content to resources.

3.1.3. Package Versions and History

Packages are versioned within JBoss ON itself. When a package is added to a resource or content source, the installer prompts for a version number; this is used as the UI display number.
This display version number is not required; if it is not given, then the JBoss ON server derives a number based on a calculated SHA-256 checksum for the package and the specification version and the implementation version in the META-INF/MANIFEST.MF file (for EARs and WARs). 
SPEC(IMPLMENTATION)[sha256=abcd1234]
Package Version Numbers

Figure 7. Package Version Numbers

For example, for a META-INF/MANIFEST.MF file with these version numbers: 
Manifest-Version: 1.0
Created-By: Apache Maven
Specification-Title: My Example App
Specification-Version: 1.0.0-GA
Specification-Vendor: Example, Corp.
Implementation-Title: My Example App
Implementation-Version: 1.x
Implementation-Vendor-Id: org.example
Implementation-Vendor: Example, Corp.
...
This creates a version number for the package like this: 
1.0.0-GA(1.x)[sha256=abcd1234]
If the META-INF/MANIFEST.MF file does not contain one of the specification version or the implementation version, then only one is used. For example, if only the implementation version is given: 
(1.x)[sha256=abcd1234]
If no version number is given, then the SHA is used as the identifier. (The SHA is used as the identifier internally, anyway.) 
[sha256=abcd1234]
For exploded WARs and EARs, the calculated SHA-256 checksum is added to the MANIFEST.MF file. This allows the agent to check the file during discovery scans to verify the version of the package quickly. 
Manifest-Version: 1.0
Created-By: Apache Maven
RHQ-Sha256: 570f196c4a1025a717269d16d11d6f37
...
For unexploded (archived) content, the checksum is recalculated with every package discovery scan and compared to the checksum in inventory.

Note

Exploded WARs and EARs can be deployed on JBoss and Tomcat servers. Because the content deployment process edits the META-INF/MANIFEST.MF file, the deployed content is not exactly identical to the content packages that were uploaded.
A clear versioning system makes it possible to handle package lifecycles in a clear and effective way. Updated content can be tracked as it is deployed, updates can be applied consistently, and packages can be reverted to a previous version. The same repository can also contain different versions of the same package, making it possible to apply different versions to different resources.

Note

Package versions from different content sources can be associated with the same repository.
Whenever a package is installed on a resource, it is recorded in the content history for the resource and the package. Since there can be multiple files associated with a single package, then there can be multiple files recorded in the content history, all associated with that package version.

Note

Versioning only matters to content knit with a resource, like EARs and WARs. Other types of content stored in content sources (like CLI scripts used for alerting) do not track versions. Content deployed in bundles handles versioning through the bundle definition, not the content system.

3.1.4. Authorization to Repositories and Packages

There are a lot of reasons that users need to be able to access content in repositories. The most common is to manage packages on resources, but there are other reasons, too, like using the server CLI scripts in a repository to respond to alerts.
JBoss ON provides a way to balance the need for clear and simple access to content with the need to protect private or sensitive information. JBoss ON defines clear authorization rules for content repositories.
Every user has the ability to create repositories and to upload packages to them — regardless of the permissions for that user.
When a repository is created, there are settings which control access to them:
  • Owner sets write access to a repository. It assigns the repository to belong to a specific user. If no user is specified, then only users with the manage repositories permission have the right to access those repositories.
  • Private sets read (download) access to the repository. It sets whether the repository can be viewed by anyone or only by the owner and users with the manage repositories permission. Public repositories are viewable by everyone, regardless of the owner.
Repository Ownership and Access Settings

Figure 8. Repository Ownership and Access Settings

Repo managers (users with the manage repositories permission) can change the ownership and privacy settings of a repository. Users without the manage repositories permission can change the privacy settings but they cannot change the ownership; the repository is always owned by them or managed by the repo manager.

Note

Be very careful when switching public repositories to private. Any operations which relied on those repositories, such as running server CLI scripts in response to alerts, will no longer work if the privileges of the user are insufficient to access the repository.
JBoss ON uses the repositories access control permission to define users with administrative access to repositories. Any user with that permission can manage any configured repository, regardless of who the repository's owner is. Repositories without an owner can only be managed by users with the repositories permission. Lastly, only users with this permission can associate a content source with a repository; all other users must add packages to the repository manually.

3.2. Creating a Content Source

  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select the Content Sources item.
  3. Below the list of current content sources, click the CREATE NEW button.
  4. Select the content source type, which defines how the content is delivered from the source. A content source type can be a remote URL, an HTTP server, a yum repository, or local disk.
  5. When the content source type is selected, a form automatically opens to fill in the basic details and configuration for the resource. These basic details identify the content source in the JBoss ON server and are the same for each content source type, while the configuration is specific to the content source type.
    • Give a unique name and optional description for the content source provider.
    • The schedule sets how frequently the content in the JBoss ON database is updated by the content source; this uses a standard Quartz Cron Syntax.
    • The lazy load setting sets whether to download packages only when they are installed (Yes) or if all packages should be download immediately.
    • The download mode sets how the content is stored in JBoss ON. The default is DATABASE, which stores all packages in the JBoss ON database instance. The other options are to store the packages on a network filesystem or not to store them at all.
  6. Fill in the other configuration information for the content source. The required information varies depending on the content source type. This is going to require some kind of connection information, such as a URL or directory path, and possibly authentication information, like a username and password.

3.3. Managing Repositories

A repository is essentially a mapping between the data in a content source and specific resources in the JBoss ON inventory.

3.3.1. Creating a Repository

  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select the Repositories item.
  3. Below the list of current repositories, click the CREATE NEW button.
  4. Fill in the name and a description. Additionally, set the authorization restrictions for the repository by setting an owner for the repo and whether it is public or private.
    Only users with the repositories permission can set an owner. All repositories created by users without the repositories permission automatically belong to that user.
  5. Click Save.
  6. On the Repositories page, click the name of the new repository in the list.
  7. Optional. To change the default synchronization schedule, click the Edit button and enter a new schedule, in a cron format, in the Sync Schedule field.
  8. Add content sources to supply content to the repository, as in Section 3.3.2.1, “Associating Content Sources with a Repository”.
    More than one content source can supply content to a repository.
  9. Associate resources with the repository, as in Section 3.3.3, “Associating Resources with the Repository”. A resource can only receive packages from a repository if it is associated with the repository.

    Note

    You can search for specific resources or types of resources and subscribe multiple resources at once.

3.3.2. Linking Content Sources to Repositories

There are a couple of ways to map the repositories to the right content sources. A repository can be subscribed to multiple content sources by editing the repository configuration. A content source can be added to multiple repositories simultaneously by importing the content source.
3.3.2.1. Associating Content Sources with a Repository
  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select the Repositories item.
  3. On the Repositories page, click the name of the repository in the list.
  4. In the Content Sources section of the repository's details page, click the Associate button to add existing content sources to the repository.
  5. Select checkboxes next to the content sources to associate with the repository.
  6. Click the ASSOCIATE SELECTED button.
3.3.2.2. Importing a Content Source into Repositories
If the same content source will be associated with multiple repositories, the content source can be imported into all of them simultaneously.
  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select the Repositories item.
  3. On the Repositories page, click the IMPORT button.
  4. Select the radio button by the name of the content source to import.
  5. When the content source is selected, then a list of available repositories for that content source automatically opens. In the Available repositories.... area, select the checkbox by the name of each repository to associate with the content source.
  6. Click the IMPORT SELECTED button.

Note

As described in Section 3.1.2, “Where Content Comes From: Providers and Repositories”, a repository is a user-defined view of a subset of packages stored in the JBoss ON database. A repository is not a separate container.
When adding a package to one repository through the UI, it may fail with an error claiming that the package already exists, even if the package isn't in the specified repository. This is because a package with the same name exists in another repository and it causes a collision in the database.
It is currently not possible to have the same package in two repositories or to move or share a package between repositories.
It is possible to work around this issue by using CLI scripts. The JBoss ON CLI scripts store the username of the person uploading the package in the package version data automatically. If a person has access to all of the packages one has uploaded, then it is possible to extrapolate which repository contains the package and then manage the package there.

3.3.3. Associating Resources with the Repository

Content can only be sent to a resource if that resource is first associated with a repository. A resource-repository association can be made by editing the resource entry or by editing the repository entry.
3.3.3.1. Adding Resources to a Repository
  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select the Repositories item.
  3. On the Repositories page, click the name of the repository to edit.
  4. In the Resources section, click the SUBSCRIBE button to add resources to the repository.
  5. Select checkboxes next to the resources to associate with the repository. It is possible to filter the list of resources by name or by type.
  6. Click the SUBSCRIBE SELECTED button.
3.3.3.2. Managing the Repositories for a Resource
A few resource types, like platforms, have content tabs in their configuration which allows them to control their content subscriptions.
  1. Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
  2. Click the Content tab of the resource.
  3. Open the Subscriptions subtab.
  4. The Available Repositories section has a list of repositories that the resource isn't subscribed to. Click the checkboxes by all of the repositories to subscribe the resource to.
  5. Click ADD SUBSCRIPTIONS.
The same process can be used to unsubscribe a resource from content repositories.

3.4. Uploading Packages

Packages can be pulled from a content source, but individual packages can also be uploaded directly to the JBoss ON server. A variety of package types are supported, including JAR files, RPMs, basic scripts, JBoss ON CLI scripts, and patches.
  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select the Repositories item.
  3. On the Repositories page, click the name of the repository in the list.
  4. Scroll to the bottom of the page, to the Upload Packages section.
  5. Click the Upload File button to upload the package.
  6. In the pop-up window, click the Add button to browse to the package, then click the Upload button.
  7. Some information about the package is automatically filled in, including the name and a default UI version number. Set the package type, architecture, and any other necessary information.
    If a version number is set, then this value is displayed in the UI. If not, then a version number is calculated, based on the spec version and implementation version in MANIFEST.MF (for EARs and WARs) or the calculated SHA-256 value for the package itself. Internally, the package is identified by the SHA value. 
    SPEC(IMPLMENTATION)[sha256=abcd1234]

    Note

    For exploded content for EARs and WARs, the calculated SHA-256 version number is written into the MANIFEST.MF file.
  8. Click the CREATE PACKAGE button to finish adding the package to the repository.

3.5. Synchronizing Content Sources or Repositories

The original source of content is external to JBoss ON, and the content packages are pulled into JBoss ON and stored. Any changes that are made at the original content source need to be pulled into JBoss ON by synchronizing the two sources.
Likewise, any changes in the content source are carried over to the repository when the source and repository are synchronized.

3.5.1. Scheduling Synchronization

Synchronization is already scheduled in the content source entry in JBoss ON. This schedule has the standard cron format. 
*     *    *    *     *  [sync-command]
-     -     -     -     -
|     |     |     |     |
|     |     |     |     +----- Day of Week (0=Sunday ... 6=Saturday)
|     |     |     +------- Month (1 - 12)
|     |     +--------- Date (1 - 31) 
|     +----------- Hour (0 - 23)
+------------- Minute (0 - 59)
For example, to synchronize the source with JBoss ON on Tuesday and Friday at 3am: 
0 3 * * 2,5
The Quartz documentation explains the cron syntax in more detail.
To edit the schedule synchronization times for a source:
  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select either the Content Sources orRepositories item.
  3. Click the name of the item to edit.
  4. Reset the cron schedule in the Sync Schedule field.
  5. Click Save.

3.5.2. Manually Synchronizing Content Sources or Resources

If a major change happens to the content source, then the changes can be manually sent over to the JBoss ON server by initiating a synchronization manually.
  1. In the top menu, click the Administration tab.
  2. In the Content menu table on the left, select the Content Sources or Repositories item.
  3. Click the name of the item to edit.
  4. Click the Synchronize button. All of the synchronization attempts, with the outcome of the operation, are listed at the bottom of the screen.

Note

You can test the connection to a source or repository by clicking the Test Connection button. This ensures that the JBoss ON server can connect to the content source before attempting to pull down the packages.
To synchronize multiple sources, stay on the main content sources or repositories page, select the checkbox by each of the content sources to synchronize, and click the Sync Selected button.

3.6. Tracking Content Versions for a Resource

Every time a package is installed on a resource through a repository, the resource shows the operation. This includes even installation failures. The content package history for a resource is viewable in the Content tab, under the History subtab.
Package History for a Resource

Figure 9. Package History for a Resource

The package history shows both the time the operation was initiated and completed and the user who initiated it. This is valuable for auditing changes, correlating incidents and response, and tracking resource configuration.