Installation

Polymorphic Linux Overview

This section details how to install Polyverse’s polymorphic packages from an internet-connected machine. Polymorphic Linux becomes the primary repository on the targeted system. This allows all supported packages to be retrieved from the Polyverse scrambled binary repository, and any custom, private, or unsupported packages to be retrievable from their original repositories. Every package downloaded is unique to the specific customer, and each used package is replaced every twenty-four hours.

Make sure your operating system is up-to-date

yum update -y

Install Polymorphic Linux

Note: Replace the demo auth key with your own, user-specific auth key.

curl -s https://sh.polyverse.com | sh -s install <Your auth key here>

Reinstall all packages

yum update -y && yum reinstall -y \*

Please reboot after re-installation, unless you're running in a container.

The configuration and installation is complete at this point.

Back to top

Mirror Installed Packages

Overview

This section provides a simple approach to downloading Polymorphic Linux packages from an internet-connected host, and then installing those packages on a non-internet-connected host.

At a high-level, the steps are:

  • On an internet-connected host, install Polymorphic Linux, download the .rpm packages to a folder, and create an index file.
  • Copy the index and packages to a folder accessible by the non-internet-connected host.
  • Install packages directly from the folder.

All the tools and techniques to provide this offline installation capability are standard approaches to how this can be done for any other RPM-based Linux repo. They can be adjusted for use in Docker containers, VMs, or bare metal.

Install Polymorphic Linux and Download Packages on Internet Connected Host

Note: Replace the demo auth key with your own, user-specific auth key.

yum update -y
yum install -y yum-utils createrepo
curl -s https://sh.polyverse.com | sh -s install <Your auth key here>
yum reinstall -y \*
# Optional if you’ve already created this directory, or if you plan to use a different directory for the repo files.
mkdir /opt/pv
cd /opt/pv
yumdownloader $(yum list installed | tr "\n" "#" | sed -e 's/# / /g' | \
tr "#" "\n" | grep polyverse | grep -v polyverse-mirror | \
awk '{print $1}' | grep -v polyverse)
createrepo .

Copy the files

The contents of the current folder can be copied to a location that the non-internet-connected host can access, for instance a USB drive, or directly to a NAS/SAN, etc.

Install Polymorphic Linux Packages on Non-Internet Connected Host

Note: Replace the URL in red with the location that you copied the .rpm files from /opt/pv to. Also, be sure you've disabled all other repositories. You can do this by going to /etc/yum.repos.d/, editing each .repo file, and adding enabled=0, or changing enabled=1 to enabled=0 for each repository.

yum update -y
vi /etc/yum.repos.d/polyverse.repo
# START CONTENTS OF polyverse.repo
[polyverse]
name=Polymorphic Linux $releasever - $basearch
failovermethod=priority
baseurl=file:///opt/pv
enabled=1
gpgcheck=0
cost=1
# END CONTENTS OF polyverse.repo
yum update -y
yum reinstall -y \*
yum list installed
Back to top

Mirror Full Repository

Overview

This section details the steps for configuring and installing a local mirror of Polymorphic Linux for Red Hat Enterprise Linux. This is meant to synchronize packages for a given processor architecture. Setting up a variety of repositories for various Red Hat Enterprise Linux versions and processor architectures isn't covered in this document.

Technical Overview

Polyverse uses two repositories for serving packages:

  • polyverse-server
  • polyverse-mirror-server

polyverse-server: This is the main repository for Polyverse's scrambled binaries. Packages for a release are stored here.
polyverse-mirror-server: This is a a mirror of the official Red Hat repositories. This should always have more packages than polyverse-server, or the same amount.

Install Polymorphic Linux packages

Before setting up a mirror, we need to be sure the Polymorphic Linux repositories are installed on the machine hosting the mirror. Follow these installation steps:
Note: Replace the demo auth key in red with your own, user-specific auth key.

yum update -y
curl -s https://sh.polyverse.com | sh -s install <Your auth key here>

Set up the local Yum Repository Server

Replicate the public mirror with reposync

Reposync is a tool that allows you to synchronize each local directory with your current yum repositories. We will be using this command to download all of the relevant packages from the currently configured yum repositories.

Install reposync

Reposync is installed with the yum-utils package. Make sure the yum-utils package is installed by running:

yum install yum-utils createrepo

Install Apache

For this example, we want to serve the repository's packages over HTTP, or HTTPS, so we need to install Apache. If you want to serve the packages using a different protocol, skip the next three steps, but be aware that this will change the directory that you synchronize files to.

yum install httpd

Start Apache

Because we will place the repository in /var/www/html which is the default directory for Red Hat based Apache installations; we will not need to change any of the apache configuration. When implementing this you may want to review the configuration to ensure that it meets your security requirements.

chkconfig httpd on
service httpd start

Configure the Firewall to Allow Connections to Apache

This guide uses http via port 80 to allow repository clients to connect and interact with the repository. The system firewall will block these connections by default, so the following command must be run to configure the system to allow connections on port 80.

iptables -I INPUT 4 -p tcp -m state --state NEW -m tcp --dport 80 -j ACCEPT

Synchronize with the system’s currently configured repositories

We’re placing all of the synchronized packages into /var/www/html so that the directory can be presented by Apache to any consumers of the repository. If you are using another protocol, such as ftp or nfs, then this directory may differ.

reposync -l -d --newest-only --download-metadata -p /var/www/html/

Optionally, if you want to place specific repositories on their own servers, you can synchronize that repository's packages using the following commands:

reposync -l -d --repoid=<repo-id> --newest-only --download-metadata -p /var/www/html/
  • -l enables yum plugin support
  • -d enables deleting of local packages no longer present in repository
  • --newest-only tell reposync to only pull the latest version of each package in the repos
  • --download-metadata enables downloading all the non-default metadata
  • -p specifies the path to download packages

Run this for each of the following repo IDs that you want to synchronize:

  • polyverse-server
  • polyverse-mirror-server

Each repo-id can be placed on the server of your choice.

Create Yum XML Metadata with createrepo

Yum leverages the createrepo tool to create the necessary XML metadata files for indicating what packages are available. Every time a repository is updated with new or removed packages, these XML metadata files will need to be updated with createrepo.

Note: Depending on how many packages your distro's repos have, createrepo may take a long time to finish.

createrepo /var/www/html/<repo-id>

You should do this for each repository.

Update the XML Metadata

In order to keep the yum repository updated, the reposync and createrepo utilities can be run as cron jobs. When updating the XML Metadata, it often saves time and reduces I/O operations by using the --update flag with the createrepo command.

createrepo --update /var/www/html/<repo-id>

This should be called for each repository.

Configure Yum Clients

Create the Repo Configuration File

Now that the Yum Repository server is setup, the clients will need to point to this new repository. This can be achieved by creating a repository configuration file.

vi /etc/yum.repos.d/polyverse.repo

Insert the following text into the /etc/yum.repos.d/polyverse.repo:

[polyverse-server]
name=polyverse-$releasever os
baseurl=http://ip_of_mirror_server/polyverse-server
gpgcheck=0
keepcache=0
enabled=1
priority=1

[polyverse-mirror-server]
name=polyverse-mirror-$releasever os
baseurl=http://ip_of_mirror_server/polyverse-mirror-server
gpgcheck=0
keepcache=0
enabled=1
priority=2

Notes about the configuration above:

  • If you decide to store each repository on a different server, use the IP of that server in the appropriate repository's configuration block.
  • The gpgcheck and gpgkey options are optional and can be enabled by setting gpgcheck=1.
  • This example uses HTTP to serve the repositories for clarity's sake, but there's no reason not to use HTTPS if you can.

Disable the Default Repositories

After creating the new repository file, any default repositories should be disabled, since polyverse-mirror-os and polyverse-mirror-updates contain any official packages that haven't been scrambled yet. This can be done by editing all of the repository (.repo) files found in /etc/yum.repos.d/ EXCEPT for polyverse.repo, using the following command:

vi <default files>.repo

Find every repository in each .repo file, and add enabled=0, or change enabled=1 to enabled=0 to disable that repository.

Refresh Yum Cached Repository List

After disabling the default repositories, and enabling the new local repository, yum’s cached repository list will need to be updated. This can be done with the following command.

yum makecache

Update and reinstall packages

At this point, you're ready to reinstall the packages being served from your new mirror.

yum update -y && yum reinstall -y \*
Back to top

Uninstalling Polymorphic Linux

Uninstalling Polyverse is a quick task. The high-level steps are as follows:

  1. Remove any references to the Polyverse scrambled binary repository from the system repository configuration files or folders
  2. Reinstall all packages so that they are downloaded from the remaining referenced repositories (which will not include Polyverse)

Remove the Polyverse Repository References

There is a script provided to automatically perform the removal of the Polyverse repository references. It can be executed using the following command:
Note: replace the auth key in red with your own auth key.

curl -s https://sh.polyverse.com | sh -s install <Your auth key here> --uninstall

Reinstall all packages

yum update -y
yum reinstall -y \*
yum list installed

The configuration and uninstallation is complete at this point.

Back to top

Troubleshooting

Missing Packages

The package may not actually be available. Use this command to determine if the package is available for download from the repository.

yum search <package_name>

Error: The operation would result in removing the booted kernel: kernel-core-<version>

When the console shows the following error, preventing a reinstallation of packages:

  1. Remove python3-dnf-plugins-core.noarch using the following command
    dnf remove python3-dnf-plugins-core.noarch
  2. Run the original command that resulted in the error to see if the issue was resolved

Public Issue Reference: https://bugzilla.redhat.com/show_bug.cgi?id=1348766

Failed System Boot After Kernel Installation

Since the debug kernel was installed in order to re-install the main kernel, boot back into the debug kernel and uninstall Polyverse. Go through the full steps found in this document, and reinstall the kernel from the non-Polyverse repository. This will put your system back into its original state, where it can boot into the kernel and troubleshooting can continue from there.

Back to top

The registered trademark Linux® is used pursuant to a sublicense from the Linux Foundation, the exclusive licensee of Linus Torvalds, owner of the mark on a world­wide basis.