rocky-tools/migrate2rocky/README.md

migrate2rocky -- Conversion Script
===========

Running this script will convert an existing CentOS 8 system to Rocky Linux 8.

### Usage

```bash
./migrate2rocky.sh -h
├── -h   # --> Display this help
├── -r   # --> Convert to Rocky
└── -V   # --> Verify switch

[!! USE WITH CAUTION !!]
```

### Disk Space Requirements

Please note the following disk space requirements.  These requirements may vary
from one system to another.  Failure to have adequate disk space available may
result in migrate2rocky leaving the system in an unstable state:

```
/usr   250M
/var   1.5G
/boot  50M
```

### Recommended Practice

When running this script, especially via a remote session, it is highly recommended to enter a screen or tmux session before running.  If a standard ssh or terminal session, such as the Cockpit Terminal window, is disrupted, the script will die and leave the system in a potential unrecoverable state.  For more on tmux sessions, please see:  https://github.com/tmux/tmux/wiki

### Known Issues

#### Running the script in Cockpit's Terminal Screen will be interrupted

Do not run this script through the Terminal screen built into Cockpit.  As the script runs the upgrades, Cockpit will be restarted and Terminal connection will disconnect, thus stopping the script and leaving the system in an unrecoverable state.  It may be possible to launch a screen or tmux session from the Cockpit Terminal, but USE AT YOUR OWN RISK.

#### Custom replacements of default repositories

This script expects the **original repository configuration being present, as well
as enabled** (i.e. for CentOS the `baseos` repo configuration in the
`/etc/yum.repos.d/CentOS-Linux-BaseOS.repo` file has to be present and enabled).
Also make sure that there are **no other repositories** which could interfere with the
original configuration.

Any distribution that has had its core repositories altered, removed, duplicated
or overridden may cause migrate2rocky to break or corrupt the system when run.
Any attempt to migrate such systems, even after reversing the changes made by such
software, is not supported in any way. In all cases you should backup your system
before using migrate2rocky and USE AT YOUR OWN RISK.

This especially happens on systems configured with a centralized package management
like Katello (RedHat Satellite 6) or Uyuni (RedHat Satellite 5, SUSE Manager).

#### RHEL migrations show error messages during conversion

```
  Installing       : rocky-release-8.3-13.el8.noarch                        2/5Error unpacking rpm package rocky-release-8.3-13.el8.noarch
...
error: unpacking of archive failed on file /usr/share/redhat-release: cpio: File from package already exists as a directory in system
error: rocky-release-8.3-13.el8.noarch: install failed
...
Error: Transaction failed
```

This results from conflicts in the directory structure of RHEL with that of
RockyLinux.  migrate2rocky will detect the issue and go on to remove the
conflicting directory and install rocky-release with the rpm command.

#### No matches found for the following enable plugin patterns: config-manager

The above error message is a display bug in dnf.  It does not affect the actual
dnf command or the migration.  You may safely ignore this message.
(RHBZ#1980712)

#### Grub still shows kernel entries from previous installation

This is normal.  The running kernel cannot be safely removed when migrate2rocky
is run.  The RockyLinux kernel should come up as the default highlighted kernel
on reboot but the other ones will remain until they are removed or replaced by
newer kernels.  If you want you can manually remove the old kernels after reboot
with dnf or rpm.

#### Symbolic links to Java programs in `/etc/alternatives` are gone

After migrating a system with an OpenJDK package installed you might encounter
that java does not work any more. There is a bug in the OpenJDK packages that
leads to losing the symbolic links in `/etc/alternatives` during the migration.
A bug report against the upstream packages has been filed
[here](https://bugzilla.redhat.com/show_bug.cgi?id=1976053).  As a workaround
you can use the following script to recreate the package default alternatives:
```
rpm -qa --scripts java-{1.8.0,11}-openjdk-{headless,devel} | sed -n '/postinstall/, /exit/{ /postinstall/! { /exit/ ! p} }' | sh
```

#### IPA fails to start after migration

This issue is caused by a version mismatch due to the way that modules work that
trick ipa into thinking that the package was downgraded even if it was not.  To
fix this issue run the following command after migration:
```
ipa-server-upgrade --skip-version-check
```
> Note: Since ipa-server-upgrade is a java program you will likely have to run
> the command to mitigate the "Symbolic links to Java programs..." issue above
> before running this command.

#### CentOS SIG repositories disappear after migrating to RockyLinux.

This is because the centos-release-* packages that contain the .repo files for
the individual repositories depend on centos-release.  Storage sig and related
release packages should be available soon from RockyLinux.  In the meantine you
can use a command like the following to install the .repo files and continue to
use the repository from CentOS (note please substitute the URL to the release
package for the repo that you need):
```
rpm2cpio <(curl http://mirror.centos.org/centos/8/extras/x86_64/os/Packages/centos-release-gluster9-1.0-1.el8.noarch.rpm) | cpio -iD/ \*.repo
```

#### Error "specified switch root path /sysroot does not seem to be an os tree"

This issue is caused by a GRUB issue after installation. Has been seen on Hetzner Dedicated Server upgrades from CentOS 8.4 -> Rocky 8.X
In order to resolve this issue, boot your dedicated server into a rescue system (for example, hetzner rescue system)
From here, you need to locate your partitions via `fdisk -l` and mount your `/` partition into a directory of your choosing (or `/mnt`).

Run the following commands (be sure to change the "mnt" to the directory of your mounted drives).
> Note: You may need to mount your `/boot` directory if your `/` and `/boot` directories are different. You can do this by doing `mount /dev/XXX /mnt/boot`
```
mount --rbind /dev  /mnt/dev
mount --rbind /proc /mnt/proc
mount --rbind /sys  /mnt/sys
chroot /mnt

grub2-mkconfig -o /boot/grub2/grub.cfg
```

### Latest Version

The latest version of this script can be found [here](https://github.com/rocky-linux/rocky-tools/).

### Debugging

The `migrate2rocky` script pipes everything shown on `stdout` and `stderr` to
`/var/log/migrate2rocky.log`.

If you run in to issues executing this script, please submit an issue
[here](https://github.com/rocky-linux/rocky-tools/issues).

Make sure to include the output log, and remove any sensitive information. (if
any)

Feel free to create a pull request if you think you've got the fix.