Attention

You are viewing an older version of the documentation. The latest version is v3.3.

Install ECI Packages¶

This section will help you set up an ECI repository and install ECI packages.

Setup the ECI Repository¶

A target running a compatible OS can install ECI packages from a hosted ECI repository. Alternatively, you can privately host the ECI repository on your own local network with packages you built or packages from the ECI release archive.

If you have already downloaded the ECI Repository, no additional preparation is required. Otherwise, follow the steps to download the ECI repository.

Attention

The private ECI APT repository only supports Debian* and Canonical Ubuntu*. There is no available private ECI Repository for Red Hat Enterprise Linux*.

logo_debian logo_ubuntu

This section explains the procedure to use the Linux build system to privately host the ECI APT repository on the local network and configure the APT package manager to use the privately hosted ECI APT repository.

Before setting up the Linux* build system, make sure that:

The Linux* build system meets the recommended system requirements.
Docker* (version 19.03.15 or higher) is installed and the user is part of the docker group. For information on installing and configuring Docker*, refer to the following:
- Install Docker*
- Manage Docker* as a non-root user

Note: If you are behind a proxy, make sure that you set the following environment variables: HTTP_PROXY, HTTPS_PROXY, and NO_PROXY.

The section is applicable to:

Do the following to set up a Linux* build system:

Download the ECI release archive, if not done already.
Copy the eci-release.tar.gz archive from the ECI release archive (release-eci_#.#.zip) to the Linux* build system. Make sure that there are no spaces in the directory path. For example, copy the archive to ~/Desktop. The eci-release.tar.gz archive is located in the ECI release archive within the Edge-Controls-for-Industrial directory as follows:
```
└── Edge-Controls-for-Industrial
    ├── Codesys_Example_Applications.zip
    ├── Dockerfiles.tar.gz
    └── eci-release.tar.gz
```
Extract the archive. In Canonical Ubuntu*, right-click the archive and select Extract Here.

The directory contents should be similar to the following:
On the Linux build system, open a terminal to the eci-release directory. In Canonical Ubuntu*, right-click anywhere in the directory explorer and select Open in Terminal.
At the terminal prompt, run the host_apt_repo.sh script without any parameters:
```
$ ./host_apt_repo.sh
```
A menu will be displayed based on either of the following scenarios:
- You are installing ECI Deb packages provided with the ECI release
- You are installing ECI Deb packages from a local build
Click the corresponding tab to continue.
The menu will display APT repository options for both Debian* and Canonical Ubuntu*:
- ECI packages for bullseye: ECI Deb packages provided with the ECI release for Debian* 11 (Bullseye)
- ECI packages for jammy: ECI Deb packages provided with the ECI release for Canonical Ubuntu* 22.04 (Jammy Jellyfish)
Select an option corresponding to the OS installed on the target system (Bullseye or Jammy Jellyfish).
The menu will display the APT repository options for both Debian* and Canonical Ubuntu*.

If you have built either core-bullseye or core-jammy, select the corresponding option:
- ECI packages for bullseye: ECI Deb packages provided with the ECI release for Debian* 11 (Bullseye)
- ECI packages for jammy: ECI Deb packages provided with the ECI release for Canonical Ubuntu* 22.04 (Jammy Jellyfish)
The Local build options are available only if you have built ECI targets packages-bullseye or packages-jammy.
- Local build ( packages-bullseye ): ECI Deb packages created from building packages-bullseye locally for Debian* 11 (Bullseye)
- Local build ( packages-jammy ): ECI Deb packages created from building packages-jammy locally for Canonical Ubuntu* 22.04 (Jammy Jellyfish)
Select a Local build option corresponding to the OS installed on the target system (Bullseye or Jammy Jellyfish).
A Docker* container with the Apache HTTP web server will open port 8080 and host the ECI APT repository on the network. If port 8080 is in use or restricted, edit the script and change the port assigned to the HTTPD_PORT variable (available at the beginning of the script). If any errors regarding Docker* occur, refer to Setup Notifications for common resolutions.

Attention

Hosting APT repositories using this method is not inherently secure! Production deployments should use security measures according to the environment and exposure.
When the APT repository server is ready, the script will display a few commands. In a later step, these commands will be executed on a target system.

Note: The target system must be connected to the same network used by the APT repository server and be able to connect to the port in use (default 8080).

The APT repository server will continue to run until you stop it. When stopped, target systems will not be able to download ECI Deb packages from this APT repository server. To stop the APT repository server, press Ctrl + C on the keyboard.

The section is applicable to:
If not already completed, prepare the target to install ECI Deb packages.
Copy the GPG key GPG-PUB-KEY-INTEL-ECI.gpg from the eci-release directory to the target system. This enables the ECI APT repository to be integrity-verified, enhancing security.
```
$ sudo cp  GPG-PUB-KEY-INTEL-ECI.gpg /etc/apt/trusted.gpg.d/
```
Note: It is not mandatory to add the GPG key. However, without the key, the APT package manager will display a warning that it could not verify signatures:
```
W: GPG error: http://10.0.2.15:8080/ isar Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 6350B922F48AD0FC
```

Run the commands, displayed by the host_apt_repo.sh script on the target system.

In this example, the following commands were executed:

sudo bash -c 'echo "deb [trusted=yes] http://10.0.2.15:8080/ isar main" > /etc/apt/sources.list.d/eci.list'
sudo bash -c 'echo "deb-src [trusted=yes] http://10.0.2.15:8080/ isar main" >> /etc/apt/sources.list.d/eci.list'
sudo bash -c 'echo -e "Package: *\nPin: origin 10.0.2.15\nPin-Priority: 1000" > /etc/apt/preferences.d/isar'
sudo bash -c 'echo "Acquire::http::Proxy::10.0.2.15 DIRECT;" >> /etc/apt/apt.conf.d/proxy.conf'

Install Real-time Linux Kernel¶

logo_debian logo_ubuntu

The section is applicable to:

Make sure that you have setup the ECI APT repository.

Before using the ECI APT repository, update the APT packages list:
```
$ sudo apt update
```
The APT package manager will download the latest list of packages available for all configured repositories.
Tip

If the APT package manager is unable to connect to the repositories, follow these APT troubleshooting tips:
- Make sure that the system has network connectivity.
- Make sure that the ports 80 and 8080 are not blocked by a firewall.
- Configure an APT proxy (if network traffic routes through a proxy server). To configure an APT proxy, add the following lines to a file at /etc/apt/apt.conf.d/proxy.conf (replace the placeholders as per your specific user and proxy server):
  Acquire::http::Proxy "http://user:password@proxy.server:port/"; Acquire::https::Proxy "http://user:password@proxy.server:port/";
ECI provides Deb packages named customizations-* which add a GRUB menu entry for ECI and prepares the system to be deterministic. Install these packages using the eci-customizations meta-package:
```
$ sudo apt install -y eci-customizations
```
ECI provides a firmware package which backports updates from upstream to bring better hardware support to the current distribution. Install this package:
```
$ sudo apt-get reinstall '(firmware-linux-nonfree|linux-firmware$)'
```
Next, install the ECI real-time Linux kernel. There are two options available: Linux Intel LTS PREEMPT_RT kernel and Linux Intel LTS Xenomai Dovetail kernel. It is recommended that you start with Linux Intel LTS PREEMPT_RT kernel, if you do not know which option to choose.

Click the corresponding tab to know more.
Linux Intel LTS PREEMPT_RT kernel is Intel’s Long-Term-Support kernel with PREEMPT_RT patches.
$ sudo apt install -y linux-intel-rt
Linux Intel LTS Xenomai Dovetail kernel is Intel’s Long-Term-Support kernel with Xenomai patches.
$ sudo apt install -y eci-xenomai

Depending on your Linux distribution, the default GRUB configuration may hide the GRUB boot menu. Perform the following commands to ensure that the GRUB menu is not hidden:

$ sudo sed -i 's/^GRUB_TIMEOUT_STYLE=hidden/GRUB_TIMEOUT_STYLE=menu/' /etc/default/grub
$ sudo sed -i 's/^GRUB_TIMEOUT=0/GRUB_TIMEOUT=5/' /etc/default/grub
$ sudo update-grub

Reboot the target system.
```
$ sudo reboot
```

logo_red-hat

The section is applicable to:

Make sure that you have setup the ECI DNF repository.

Install the RHEL DNF repository:
```
$ sudo subscription-manager repos --enable rhel-9-for-x86_64-rt-rpms
```
The DNF package manager will download the latest list of packages available for all configured repositories.
Tip

If the DNF package manager is unable to connect to the repositories, follow these DNF troubleshooting tips:
- Make sure that the system has network connectivity.
- Make sure that the port 80 is not blocked by a firewall.
- Configure an DNF proxy (if network traffic routes through a proxy server). To configure an DNF proxy, perform the following command (replace the placeholders as per your specific user and proxy server):
  $ sudo subscription-manager config --server.proxy_hostname=<proxy.server> --server.proxy_port=<port>
RHEL provides RPM packages group named RT which prepares the system to be deterministic. Install this package group:
```
$ sudo dnf groupinstall RT
```

Update the GRUB config to set the default kernel to the newly installed real-time kernel. List the available kernels:

$ sudo grubby --info=ALL

index=0
kernel="/boot/vmlinuz-5.14.0-284.30.1.rt14.315.el9_2.x86_64"
args="ro crashkernel=1G-4G:192M,4G-64G:256M,64G-:512M resume=/dev/mapper/rhel_vecow--debian11-swap rd.lvm.lv=rhel_vecow-debian11/root rd.lvm.lv=rhel_vecow-debian11/swap rhgb quiet intel_iommu=on iommu=pt"
root="/dev/mapper/rhel_vecow--debian11-root"
initrd="/boot/initramfs-5.14.0-284.30.1.rt14.315.el9_2.x86_64.img $tuned_initrd"
title="Red Hat Enterprise Linux (5.14.0-284.30.1.rt14.315.el9_2.x86_64) 9.2 (Plow)"
id="41b5c9e83a1b44d7bace7339a08afabe-5.14.0-284.30.1.rt14.315.el9_2.x86_64"
index=1
kernel="/boot/vmlinuz-5.14.0-284.25.1.el9_2.x86_64"
args="ro crashkernel=1G-4G:192M,4G-64G:256M,64G-:512M resume=/dev/mapper/rhel_vecow--debian11-swap rd.lvm.lv=rhel_vecow-debian11/root rd.lvm.lv=rhel_vecow-debian11/swap rhgb quiet intel_iommu=on iommu=pt"
root="/dev/mapper/rhel_vecow--debian11-root"
initrd="/boot/initramfs-5.14.0-284.25.1.el9_2.x86_64.img $tuned_initrd"
title="Red Hat Enterprise Linux (5.14.0-284.25.1.el9_2.x86_64) 9.2 (Plow)"
id="41b5c9e83a1b44d7bace7339a08afabe-5.14.0-284.25.1.el9_2.x86_64"

Set the default kernel to the real-time kernel. Hint: the real-time kernel usually contains rt in its name:

$ sudo grubby --set-default /boot/vmlinuz-5.14.0-284.30.1.rt14.315.el9_2.x86_64

The default is /boot/loader/entries/41b5c9e83a1b44d7bace7339a08afabe-5.14.0-284.30.1.rt14.315.el9_2.x86_64.conf with index 0 and kernel /boot/vmlinuz-5.14.0-284.30.1.rt14.315.el9_2.x86_64

Reboot the target system.
```
$ sudo systemctl reboot
```

What Next after Installing Real-time Linux Kernel¶

After installing the real-time Linux kernel, proceed to Complete and Verify Deployment.