Skip to content

Commit 01f1ad2

Browse files
yuravksboldyreva
yuravk
and
sboldyreva
authored
Update 'AlmaLinux Migration Guide' with how to migrate air-gapped machine (#602)
* Update 'AlmaLinux Migration Guide' with how to migrate air-gapped machine --------- Co-authored-by: Sofia Boldyreva <[email protected]>
1 parent 7dc5f0f commit 01f1ad2

File tree

1 file changed

+130
-23
lines changed

1 file changed

+130
-23
lines changed

‎docs/documentation/migration-guide.md‎

Lines changed: 130 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
title: 'Migration Guide'
33
---
44

5+
###### last updated: 2025-04-11
6+
57
# AlmaLinux Migration Guide
68

79
This guide describes how to convert your operating system to AlmaLinux using the [AlmaLinux Migration tool](https://github.com/AlmaLinux/almalinux-deploy).
@@ -17,49 +19,154 @@ What OSes can be converted:
1719

1820
This tool also supports cPanel, Plesk and DirectAdmin panels.
1921

20-
## How to Migrate
21-
2222
The minimal supported version of EL8 operating systems is 8.4. In case your OS version is lower, please, upgrade it.
2323

2424
:::tip
25-
It's recommended to have a backup or snapshot of your system. There'll be a restore point if something will go wrong.
25+
It's recommended to have a backup or snapshot of your system. There'll be a restore point if something goes wrong.
2626
:::
2727

2828
::: warning
29-
Make sure you are using reliable console access to your system. It's recommended the migration tool is run from inside main console or via ssh.
29+
Make sure you are using reliable console access to your system. It's recommended that the migration tool is run from inside main console or via ssh.
3030
:::
3131

32-
Follow these steps to convert your EL8 or EL9 system to AlmaLinux using CLI:
32+
## Migrating using AlmaLinux public repositories (Online Systems)
33+
34+
These steps are suitable for standard migrations on online systems that can access official AlmaLinux repositories during the migration process.
35+
36+
Convert your EL8 or EL9 system to AlmaLinux using CLI:
3337

3438
* Run the following command to update your operating system if needed:
35-
```
36-
sudo dnf update -y
37-
```
39+
```
40+
sudo dnf update -y
41+
```
3842

3943
* Run the following command to download [almalinux-deploy.sh](https://github.com/AlmaLinux/almalinux-deploy/blob/master/almalinux-deploy.sh) script:
40-
```
41-
curl -O https://raw.githubusercontent.com/AlmaLinux/almalinux-deploy/master/almalinux-deploy.sh
42-
```
44+
```
45+
curl -O https://raw.githubusercontent.com/AlmaLinux/almalinux-deploy/master/almalinux-deploy.sh
46+
```
4347
* Run the script:
44-
```
45-
sudo bash almalinux-deploy.sh
46-
```
48+
```
49+
sudo bash almalinux-deploy.sh
50+
```
4751
* Check the output for any errors. If the conversion went without any issues, you'll see that `Migration to AlmaLinux is completed` in the output.
4852
* Reboot the system to boot with AlmaLinux kernel:
53+
```
54+
sudo reboot
55+
```
56+
* Ensure that your system was successfully converted:
57+
* Check the release file:
58+
```
59+
$ cat /etc/redhat-release
60+
AlmaLinux release 8.7 (Stone Smilodon)
61+
```
62+
* Check that the system boots with AlmaLinux kernel by default:
63+
```
64+
$ sudo grubby --info DEFAULT | grep AlmaLinux
65+
title="AlmaLinux (4.18.0-425.3.1.el8.x86_64) 8.7 (Stone Smilodon)"
66+
```
67+
68+
## Migrating an air-gapped machine
69+
70+
These steps are recommended for migrating air-gapped machines that have no internet connection but have network access to a private mirror or access to a data storage device with a mirror.
71+
72+
The process involves at least two hosts:
73+
* A system with internet access to create a local AlmaLinux mirror or to store the mirror on a data storage device.
74+
* The target system that will be migrated.
75+
76+
### Requirements
77+
78+
To migrate an air-gapped machine, you have to create a local mirror to receive updates. For this purpose, the recommended storage space is at least 500GB per major version.
79+
80+
### Create a local, private AlmaLinux mirror
81+
82+
**These steps are to be performed on a host with Internet access.**
83+
84+
The `rsync` tool can be used to create a mirror.
85+
* Synchronize with the official AlmaLinux mirror via `rsync`:
86+
```shell
87+
/usr/bin/rsync -avSH --exclude='.~tmp~' --delete-delay --delay-updates rsync://rsync.repo.almalinux.org/almalinux/ /example-almalinux-mirror/
88+
```
89+
* If needed, create a cron task to sync your mirror periodically (we recommend updating the mirror every 3 hours):
90+
```shell
91+
0 */3 * * * sleep $(((RANDOM\%3500)+1)) && /usr/bin/flock -n /var/run/almalinux_rsync.lock -c "/usr/bin/rsync -avSH --exclude='.~tmp~' --delete-delay --delay-updates rsync://rsync.repo.almalinux.org/almalinux/ /example-almalinux-mirror/"
92+
```
93+
94+
The `/example-almalinux-mirror/` can be located on an external data storage device, so the device can be used on systems that don’t have direct access to the mirror you created.
95+
:::warning
96+
Don't forget to replace /example-almalinux-mirror/ directory with the directory you need.
97+
:::
98+
99+
### If the local mirror is on a device storage
100+
101+
If there's no access to a private mirror or the internet, you'll have to use a data storage device with a local private mirror created using the steps above. Ensure the device with the mirror is directly accessible to the migrating system, for example, by mounting it to the `/opt` directory.
102+
103+
Make sure the mirror on the device follows the AlmaLinux repository directory structure. Example for AlmaLinux 8, x86-64 arch:
104+
49105
```
50-
sudo reboot
106+
/opt
107+
├── almalinux-release-latest-8.x86_64.rpm
108+
├── RPM-GPG-KEY-AlmaLinux-8
109+
└── 8
110+
├── AppStream
111+
│ └── x86_64
112+
│ └── os
113+
│ ├── Packages
114+
│ └── repodata
115+
├── BaseOS
116+
│ └── x86_64
117+
│ └── os
118+
│ ├── Packages
119+
│ └── repodata
120+
├── PowerTools
121+
. └── x86_64
122+
. └── os
123+
. ├── Packages
124+
└── repodata
51125
```
126+
where:
127+
* `Packages` - folder with corresponding repository, all packages
128+
* `repodata` - folder with repository metadata
129+
130+
Note, it's mandatory you download the `almalinux-release` package and public GPG key corresponding to your release, like `almalinux-release-latest-8.x86_64.rpm` and `RPM-GPG-KEY-AlmaLinux-8` for AlmaLinux 8 x86_64, from [https://repo.almalinux.org/almalinux/](https://repo.almalinux.org/almalinux/) and place them into the root of `/opt`.
131+
132+
### Perform the migration
133+
134+
**These steps are to be performed on the target system that will be migrated.**
135+
136+
Convert your EL8 or EL9 system to AlmaLinux using CLI:
137+
138+
* It's highly recommended that your operating system have all the most recent packages.
139+
140+
* The [almalinux-deploy.sh](https://github.com/AlmaLinux/almalinux-deploy/blob/master/almalinux-deploy.sh) script is available on your system.
141+
142+
* Run the script using one of the following methods:
143+
144+
* If your AlmaLinux private local mirror is accessible via network, for example, at http://mirror.example.com/example-almalinux-mirror:
145+
```
146+
sudo bash almalinux-deploy.sh --local-repo=http://mirror.example.com/example-almalinux-mirror
147+
```
148+
149+
* If your AlmaLinux private mirror is stored locally in the file-system, for example, in the `/opt` directory:
150+
```
151+
sudo bash almalinux-deploy.sh --local-repo=file:///opt
152+
```
153+
154+
* Check the output for any errors. If the conversion went without any issues, you'll see that `Migration to AlmaLinux is completed` in the output.
155+
* Reboot the system to boot with AlmaLinux kernel:
156+
```
157+
sudo reboot
158+
```
52159
* Ensure that your system was successfully converted:
53160
* Check the release file:
54-
```
55-
$ cat /etc/redhat-release
56-
AlmaLinux release 8.7 (Stone Smilodon)
57-
```
161+
```
162+
$ cat /etc/redhat-release
163+
AlmaLinux release 8.7 (Stone Smilodon)
164+
```
58165
* Check that the system boots with AlmaLinux kernel by default:
59-
```
60-
$ sudo grubby --info DEFAULT | grep AlmaLinux
61-
title="AlmaLinux (4.18.0-425.3.1.el8.x86_64) 8.7 (Stone Smilodon)"
62-
```
166+
```
167+
$ sudo grubby --info DEFAULT | grep AlmaLinux
168+
title="AlmaLinux (4.18.0-425.3.1.el8.x86_64) 8.7 (Stone Smilodon)"
169+
```
63170
64171
## Migrating from CentOS versions lower than 8.4
65172

0 commit comments

Comments
 (0)