Appendix D. Synchronizing Content Between Satellite Servers

Red Hat Satellite 6.3 uses Inter-Satellite Synchronization (ISS) to synchronize content between upstream and downstream servers. In the context of ISS, upstream refers to the server from which content is exported; downstream refers to the server into which content is imported.

ISS is designed to address two scenarios:

  • If you have both connected and disconnected Satellite Servers, and want to propagate content from the connected servers to the disconnected servers.
  • If you have a primary Satellite Server and want to propagate some, but not all, content to other Satellite Servers. For example, you might have Content Views (CVs) that are validated by the IT department, and you want to propagate the yum content from those CVs to a downstream Satellite.
Note

Be aware that you cannot use ISS to synchronize content from a Satellite Server to a Capsule Server. Capsule Server supports synchronization natively. For more information, see the Capsule Server Overview in the Architecture Guide.

Satellite 6.3 supports exports as a set of directories (default) or as ISO files. You can then import the resulting export to another Satellite Server. This replaces the katello-disconnected script in earlier Satellite versions, which exported repositories into a directory structure that could be later imported into another Satellite Server. In Satellite 6.3, all export and import functions are performed on the command line.

Note

Only RPM, kickstart, and ISO files are exported. Content View definitions and metadata, such as package filters, is not transferred. Satellite 6.3 does not support the export of Puppet, Docker, or OSTree content. Imports occur as a normal repository synchronization, and consequently always arrive in the Library environment.

The disconnected use case is used extensively by customers who have air-gapped networks where a Satellite and its clients are on a network that is never connected to the Internet. The only way that these disconnected Satellites are populated with content is by exports from a connected Satellite.

Important

Bidirectional synchronization is NOT used in a disconnected environment. Content never passes from the disconnected server to the connected server.

Figure D.1. Information Flow in ISS in an Air-gapped Network

Information Flow in ISS in an Air-gapped Network

D.1. Satellite Servers, Capsule Servers, and ISS

ISS serves a distinct purpose in a Red Hat Satellite deployment. If you intend to include ISS as part of your deployment, it equates to keeping a separate Satellite Server that you need to maintain, back up, and so on. ISS does not provide a failover mechanism for clients, and neither is it designed as a backup and recovery system. It is a means of providing information sharing between Satellite Servers. The primary use case for implementing ISS is when you have a Satellite Server that is not connected to the Internet or to external content, and you need to synchronize content with a Satellite that is connected to the Internet. This can apply when you need complete isolation of management infrastructure for security or other purposes.

If you do not want to maintain another management web UI and platform, and you want to perform management and provisioning to local clients, consider setting up a Capsule Server.

D.2. Prerequisites

  • In Red Hat Satellite 6, ISS is only available in Satellite 6.2 and later, which requires Red Hat Enterprise Linux 6.7, 7.2, or later.
  • The export directory needs to be large enough to accommodate at least one Red Hat Enterprise Linux export. By default, the export directory is /var/lib/pulp/katello-export/.
  • The /var/lib/pulp/ directory must have free storage space equivalent to the size of the repository being exported for temporary files created during the export process. This is in addition to the space required by the default export directory.
  • The downstream Satellite Server must have the required manifests and entitlements for any content that you intend to enable. You cannot enable repositories on a downstream Satellite for which no entitlements exist.
  • The repository download policy needs to be set to immediate. This policy specifies whether or not Satellite first downloads metadata and other repository information, and only downloads actual repositories when requested. ISS does not function correctly if this policy is not set to immediate.

Section D.5, “Configuring ISS” describes how to configure required options.

D.3. Supported Synchronization Options

Satellite 6.3 supports the following synchronization options:

  • Exporting repositories to a directory or ISO file.
  • Exporting all repositories in an Environment or CV version to a directory or ISO file. You can also recreate any custom products during the import process, but Red Hat products are not recreated because they must be created using a manifest.
  • Date-based incremental exports of RPM files and errata.

These synchronization options include a range of history details about the export and import, depending on the type of content. For example:

  • The repository synchronization history includes upstream source information, as well as the time the export occurred.
  • The CV synchronization history includes the export time and version, as well as the import time, version, and upstream source.

D.4. Using Chunked ISO Files

Satellite 6.3 supports exports to chunked ISO files. A chunked ISO is similar to a split ISO but with one significant difference. Satellite tracks the size of the ISO file, and if the total size of the files being added to the ISO exceeds that value, Satellite stops writing to the ISO and creates a new one in the series. The advantage of this is that you can specify the ISO file size (for example, 4.7 GB), and still export larger repositories. The result is multiple 4.7 GB ISO files that you can burn to DVDs.

The difference between this and splitting large files is that the split utility is not aware of the ISO file format, which means that it does not create a new burnable ISO file for the next file in the series. This method requires that you copy all of the files to one place, concatenate those files, and then mount that single large ISO through loopback.

You can add the --iso-mb-size parameter to specify the size of ISO export files. The default value is 4380 MB, the size of a single-sided, single-layer DVD.

D.5. Configuring ISS

This section describes how to configure the required settings for ISS. It is important that these settings be configured correctly or your synchronization may fail.

D.5.1. Configuring an Export Destination

Inter-Satellite Synchronization by default uses the /var/lib/pulp/katello-export/ directory, as indicated by the 'pulp_export_destination' setting. To change this directory you must create the new directory and configure the Pulp export destination setting. Only Satellite Administrators can specify this directory, and SELinux and other permissions are also in place to prevent Satellite from writing to arbitrary file systems.

It can be helpful to create symbolic links to commonly used directories after they are exported. Exported repositories and CVs have the organization name and environment name prepended to the repository directory structure, which might create paths of overlong length.

Important

The directory used in this example is for demonstration purposes only. Confirm that the export directory has adequate space for the required export RPM and ISO files. Section 1.5, “Defining Content Management Storage” provides information on estimating storage requirements. A temporary file is created during the export process in the /var/lib/pulp/ directory. This means that storage space equal to twice the size of the repository being exported is required during the export process. The temporary file is deleted when the export is completed.

Create the Export Directory

  1. Create the export directory:

    # mkdir /var/www/html/pub/export
  2. Ensure the foreman user has read and write permissions on the export directory:

    # chown foreman:foreman /var/www/html/pub/export
  3. Configure the SELinux context:

    # semanage fcontext -a -t httpd_sys_rw_content_t \
    "/var/www/html/pub/export(/.*)?"
    # restorecon -RvF /var/www/html/pub/export
    # ls -Zd /var/www/html/pub/export
    drwxr-xr-x. foreman foreman system_u:object_r:httpd_sys_rw_content_t:s0 /var/www/html/pub/export

Configure the Export Destination

For CLI Users

To change the export destination, enter the following hammer command:

# hammer settings set \
--name pulp_export_destination \
--value your-export-directory

For example, to specify /var/www/html/pub/export/ as the export destination, enter:

# hammer settings set \
--name pulp_export_destination \
--value /var/www/html/pub/export

For Web UI Users

  1. In the web UI, navigate to Administer > Settings, and click the Content tab.
  2. Locate the 'pulp_export_destination' variable in the Name column, and click the Value field.
  3. Enter the export destination, for example /var/www/html/pub/export, in the Value field and click Save.

D.5.2. Configuring the Download Policy

ISS requires that the 'Download Policy' be set to immediate. You can set this globally so that it applies to new repositories created in all Organizations, or you can set it individually for every repository. Changing the default value does not change existing settings.

For CLI Users

To change the global default Download Policy, enter the following command:

# hammer settings set \
--name default_download_policy \
--value immediate

If required to change the policy for a specific repository, you can list the repositories for an organization as follows:

# hammer repository list \
--organization-label organization-label

To change the download policy for an existing repository, enter the following command:

# hammer repository update \
--organization-label organization-label  \
--product "Red Hat Enterprise Linux Server" \
--name "Red Hat Enterprise Linux 7 Server Kickstart x86_64 7.2"  \
--download-policy immediate

For Web UI Users

To change the global default Download Policy using the web UI:

  1. Navigate to Administer > Settings.
  2. On the Content tab, locate default_download_policy.
  3. In the Value field, click the edit icon.
  4. Set the value to immediate, and then click Save.

To change the Download Policy for an existing repository using the web UI:

  1. In the web UI, navigate to Content > Products, and click the required product name.
  2. On the Repositories tab, click the required repository name, locate the 'Download Policy' field, and click the edit icon.
  3. From the list, select Immediate, and then click Save.

D.6. Exporting Content

This section describes how to export different types of content from your upstream server, ready to be imported into to one or more downstream servers. For details on importing content, see Section D.7, “Importing Content”.

Synchronization between upstream and downstream servers is currently supported in disconnected deployments, for example in an air-gapped environment, where complete isolation is required.

D.6.1. Exporting Repositories

  1. Enter the hammer repository list command to list the repositories which can be exported and identify their IDs, which are used in the export.
  2. Enter the hammer repository export command to export content from your upstream server. This command exports content to the directory specified in 'pulp_export_destination' setting. ISS exports to a directory by default. You can add the '--export-to-iso 1' parameter to export to an ISO file instead. For example:

    # hammer repository export --id 1 [--export-to-iso 1]
Note

If you use the '--export-to-iso' parameter, you need to specify either 1 (ISO) or 0 (directory). This parameter does not have a default value.

D.6.2. Exporting Content View Version to a Directory

You can export a specific version of a Content View to a directory. That means that you can label a particular version of a CV to suit your requirements. This way you can curate and track your exports and facilitate updates.

Prerequisites

  • Ensure all repositories within the CV have their download policy set to Immediate. You cannot export repositories with policies other than Immediate.
  • Ensure Products are synchronized to the required date.

For Web UI Users

  1. Navigate to Content > Content Views. Click Create New View. Enter following details to create a CV:

    1. Name — A plain text name for the CV. Enter Export_CV.
    2. Label — An internal ID for the CV. Red Hat Satellite 6 automatically completes this field based on what you have entered for Name.
    3. Description — An optional plain text description of the CV.
    4. Composite View — Defines whether or not to use a Composite Content View. Leave this option unselected.
  2. Click Save to submit your changes.
  3. On the Repository Selection screen, select the repositories to be added to the new CV from the Repository Selection table. Click Add Repositories to add selected packages to the CV.
  4. Navigate to Yum Content > Filters and click New Filter. Enter following details to create a filter for including non-errata packages:

    1. Name — A plain text name for the filter. Enter Non-errata Products.
    2. Content type — A list of the types of content to be included into the filter. Select Package.
    3. Inclusion type — A list defining whether the content are included or excluded from the CV. Select Include.
    4. Description — An optional plain text description of the filter. Enter Include all non-errata Products.
    5. Click Save.
    6. On the Include RPM screen, select the Include all RPMs with no errata check box.
  5. Navigate to Yum Content > Filters and click New Filter. Enter following details to create a filter for including errata packages in accordance with the required date range:

    1. Name — A plain text name for the filter. Enter Erratas untill YYYY-MM-DD.
    2. Content type — A list of the types of content to be included into the filter. Select Erratum - Date and Type.
    3. Inclusion type — A list defining whether the content is included or excluded from the CV. Select Include.
    4. Description — An optional plain text description of the filter. Enter Include errata products untill YYYY-MM-DD.
    5. Click Save.
    6. On the Erratum Date Range screen, select all Security, Enhancement and Bugfix errata types.
    7. Select the Updated On check box in Data type.
    8. Fill in the Start Date and End Date menus to configure the date range of Products for the filter.
    9. Click Save.
  6. Click Publish New Version, it is recommended to fill in the date ranges of repositories into the Description field. Ensure the Force Yum Metadata Regeneration check box is not selected.
  7. Click Save to publish the CV version ready for exporting.

For CLI Users

  1. Enter the hammer content-view create command to create a new CV:

    # hammer content-view create \
    --name "Export_CV" \
    --organization "Default Organization"
  2. Enter the hammer content-view add-repository command to add repositories to the CV:

    # hammer content-view add-repository \
    --name "Export_CV" \
    --product "Red Hat Satellite" \
    --repository "Red Hat Satellite Tools 6 for RHEL 7 Server RPMs x86_64" \
    --organization "Default Organization"
    # hammer content-view add-repository \
    --name "Export_CV" \
    --product "Red Hat Satellite Capsule" \
    --repository "Red Hat Satellite Capsule Tools 6.2 for RHEL 7 Server RPMs x86_64" \
    --organization "Default Organization"
  3. Create filters for the new CV:

    1. Enter the hammer content-view filter create command to create a filter for including non-errata packages:

      # hammer content-view filter create \
      --content-view "Export_CV" \
      --inclusion true \
      --name "Non-errata_Products" \
      --type rpm \
      --original-packages true \
      --organization "Default Organization"
    2. Enter the hammer content-view filter create command to create a filter for including errata packages:

      # hammer content-view filter create \
      --content-view "Export_CV" \
      --inclusion true \
      --name "Erratas until YYYY-MM-DD" \
      --type erratum \
      --organization "Default Organization"
    3. Enter the hammer content-view filter rule create command to create a rule defining the date range:

      # hammer content-view filter rule create \
      --content-view "Export_CV" \
      --content-view-filter "Erratas until YYYY-MM-DD" \
      --end-date YYYY-MM-DD \
      --types security,enhancement,bugfix \
      --organization "Default Organization"
  4. Enter the hammer content-view publish command to publish the CV version ready for exporting. It is recommended to fill in the date ranges of repositories under the --description option.

    # hammer content-view publish \
    --name "Export_CV" \
    --description "Repositories until YYYY-MM-DD" \
    --force-yum-metadata-regeneration true \
    --async \
    --organization "Default Organization"

To Determine Which Content View Version to Export:

  1. Enter the hammer content-view version list command to determine which version of a Content View to export. For example:

    $ hammer content-view version list \
    --organization "Default Organization"
    ---|-------------------------------|---------|-----------------------
    ID | NAME                          | VERSION | LIFECYCLE ENVIRONMENTS
    ---|-------------------------------|---------|-----------------------
    3  | Export_CV 2.0                 | 2.0     | Library
    2  | Export_CV 1.0                 | 1.0     | Library
    1  | Default Organization View 1.0 | 1.0     | Library
    ---|-------------------------------|---------|-----------------------

To Export a Content View Version:

  1. Enter the hammer content-view version export command to export a version of a Content View:

    # hammer content-view version export --id 3

D.6.3. Incremental Export

To avoid exporting large repositories when updating, you can use incremental updates to only export the recent updates from a Satellite Server. Incremental updates export the recent changes made in the local repository by using synchronization events set to a particular date and time.

To make an incremental-update repository, enter the hammer repository export command with the --since option. For example:

# hammer repository export \
--id 1 [--export-to-iso 1] \
--since ISO_Date

Where ISO_Date is in ISO 8601 format. For example, 2010-01-01T12:00:00Z.

The time stamp used for the calculations is the time that the RPMs were synchronized on Satellite Server. For example, if Red Hat adds RPMs to a repository on a Monday and then again on a Wednesday, you cannot synchronize your local repository on Thursday and then use a date of Tuesday to get only the Wednesday update.

In addition to exporting changes to a repository, this feature is useful with the Default Organization View Content View, but is not as useful for published CVs.

D.7. Importing Content

Red Hat Satellite 6.3 currently supports importing content that has been exported from an upstream Satellite Server in a disconnected environment. This method is used for disconnected Satellite Servers that have no Internet access, and requires the physical transfer of content between the servers, for example using a DVD.

D.7.1. Importing a Repository

Prerequisites

To Import a Repository:

  1. Make the data available for a repository over HTTP, not HTTPS. For example, copy the exported directory to the /var/www/html/pub/export/ directory on the downstream server, which is available over HTTP by default.
  2. In the web UI, navigate to Content > Subscriptions.
  3. Select Manage Manifests.
  4. On the Import/Remove Manifest tab, set the Red Hat CDN URL address field to match the location of a content directory and a listing file within the exported repository.

    For example, if the exported repository is located in /var/www/html/pub/export/Default_Organization-Red_Hat_Enterprise_Linux_7_Server_RPMs_x68_64, set the URL to be http://satellite.example.com/pub/export/Default_Organization-Red_Hat_Enterprise_Linux_7_Server_RPMs_x68_64/Default_Organization/Library/.

  5. Click Save.
  6. Navigate to Content > Red Hat Repositories and select the check box of the repository you have exported.

D.7.2. Importing a Content View as a Red Hat Repository

Prerequisites

Note

A custom repository can also be imported to a custom product, for example a disconnected Satellite. For more information about Red Hat Content Delivery Network (CDN) see Content Delivery Network (CDN) Structure in the Architecture Guide.

To Import a Content View:

  1. Make the data available for a repository over HTTP, not HTTPS. For example, copy it to the /var/www/html/pub/export/ directory on the downstream server.
  2. In the web UI, navigate to Content > Subscriptions.
  3. Select Manage Manifests.
  4. On the Import/Remove Manifest tab, set the Red Hat CDN URL address field to match the location of a content directory and a listing file within the exported Content View.

    For example, if the exported CV is located in /var/www/html/pub/export/Default_Organization-Export_CV-v1.0, set the URL to be http://satellite.example.com/pub/export/Default_Organization-Export_CV-v1.0/Default_Organization/content_views/Export_CV/1.0/

  5. Click Save.
  6. Navigate to Content > Red Hat Repositories and check the repository you have exported.
  7. On a downstream server, enter the hammer organization update command to add new repositories to an organization. Set the address to the directory corresponding to the version you want within the exported Content View as shown:

    $ hammer organization update \
    --name "Default Organization" \
    --redhat-repository-url \
    http://satellite.example.com/pub/export/Default_Organization-Export_CV-v1.0/Default_Organization/content_views/Export_CV/1.0/
    
    Organization updated

D.7.3. Incremental Import

When synchronizing from an incremental update, you must use the incremental synchronization settings. In the Satellite web UI, ensure the "Mirror on Sync" setting is disabled for the repositories before synchronizing. If you are using the Hammer CLI, you must add the "--incremental" option. If you do not use the incremental synchronization settings, the repository content will be deleted and only the content from the incremental update will remain. Recovering from an accidental overwrite requires a full export and then synchronizing again.