Get EVE-OS

Updated

Introduction

This guide describes how to get an EVE-OS image or installer file, the first step to installing, upgrading, or live-booting EVE-OS on an edge node.

Prerequisites

  • You have read EVE-OS image overview.
  • You have Docker installed and running.
  • You know your cluster’s hostname, such as zedcloud.gmwtus.zededa.net.

Configure Your EVE-OS Image Cluster

During first boot, a device running EVE-OS will try to connect to a ZEDEDA Cloud cluster to get its initial configuration.

  • Edge nodes will try to connect to the following cluster endpoint by default: zedcloud.zededa.net
  • If your enterprise is on a different cluster, you’ll need to create a .txt configuration file named "server" with a single line containing your cluster hostname.
  • Then, when you create your EVE-OS image file, you’ll inject your server file into your EVE-OS image.

The following procedure uses zedcloud.gmwtus.zededa.net as an example. Replace this with your cluster endpoint. 

MacOS or Linux

Follow these steps to create a server configuration for your EVE-OS image with MacOS or Linux.

  1. Open your terminal.

  2. Navigate to a directory of your choice. This example uses the your home directory, represented by the $HOME system variable.

    cd $HOME

  3. Create a directory called eve-overrides.

    mkdir eve-overrides

  4. Create a file called “server” within this directory and write the hostname of your cluster into it.

    echo zedcloud.gmwtus.zededa.net > $HOME/eve-overrides/server


    NOTE: If you run into issues indicating the server file is locked or read-only, you may need to unmount the locked server file. See post-install instructions for more details on unmounting the Linux file system.

Windows

Follow these steps to create a server configuration for your EVE-OS image with Windows.

  1. Open Powershell.

  2. Navigate to a directory of your choice. This example uses your home directory, represented by the $HOME system variable.

    cd $HOME

  3. Create a directory called eve-overrides.

    mkdir eve-overrides

  4. Create a file called “server” within this directory and write the hostname of your cluster into it.

    Set-Content -Path "$HOME\eve-overrides\server" -Value "zedcloud.gmwtus.zededa.net" -Encoding ASCII

Raspberry Pi compatibility

If you plan to install EVE-OS onto a Raspberry Pi (ARM) device, ensure that it meets the following hardware requirement.

  • Raspberry Pi 4 or 5 Model B with at least 4GB RAM
  • MicroSD card (16GB or larger recommended) 

Use the Latest LTS Version of EVE-OS Image

The procedures in this section each describe how to run a Docker container that will download EVE-OS resources from Docker Hub and generate a usable EVE-OS image. The latest follows: 

16.0.0-lts

Optional: Choose an alternate EVE-OS image version

This section will help you determine the name of the EVE-OS image that you need so you can find it in Docker Hub and download it.

Most use cases require the latest LTS version. Be sure that you understand your reason for using a different version.

Complete these subsections in order.

Find your EVE-OS version

This subsection is optional because examples in the following procedures all assume that you need the latest LTS version of EVE-OS. Use these resources here to find an alternate version:

Determine your EVE-OS image’s name

This subsection describes how to determine the name of the EVE-OS image that you need so you can find the image in Docker Hub.

Ensure you are familiar with the EVE-OS naming conventions before proceeding.

To determine the name of your EVE-OS image, follow these steps.

  1. Recall the EVE-OS version number you need. This is the first component of your image name. For example:

    16.0.0-lts

  2. Determine the system architecture (AMD64 or ARM64) of your edge node hardware. This is the second component of your image name. For example:

    16.0.0-lts-amd64

The following procedures use 16.0.0-lts-kvm-arm64 or 16.0.0-lts-kvm-amd64 as an example image name. Replace it with your image name. 

Search Docker Hub

You can verify that the image you need is available to download, search for it in Docker Hub.

  1. Go to Docker Hub.
  2. Click on the Tags tab.
  3. Enter your image name into the Filter Tags search field.
  4. Check the results for your image.

Choose a Download Procedure

Download procedures differ depending on the image's intended use. If you haven't already, see the EVE-OS image overview for the various uses. 

Open the terminal (macOS and Linux users) or Powershell (Windows users) and choose one of the following procedures.

Get an EVE-OS installer image (to install using USB or PXE)

To get an EVE-OS installer image, follow these steps. These steps specify the latest LTS in their examples. To substitute another version, replace 16.0.0-lts-kvm-arm64 or 16.0.0-lts-kvm-amd64.

  1. Navigate to a directory of your choice.

    cd $HOME

  2. Create a directory for your EVE-OS image and navigate into it.

    mkdir eve-images && cd eve-images

  3. Download and generate your EVE-OS installer image. Choose the command for your edge node’s hardware architecture. If your controller cluster is zedcloud.zededa.net, the following commands don't need
    -v $HOME/eve-overrides:/in

    Windows
    AMD64 
    docker run -v $HOME/eve-iso:/out lfedge/eve:16.0.0-lts-kvm-amd64 -f raw installer_iso
    ARM64 
    docker run -v $HOME/eve-iso:/out lfedge/eve:16.0.0-lts-kvm-arm64 -f raw installer_iso
    MacOS and Linux
    AMD64 
    docker run -v $HOME/eve-overrides:/in lfedge/eve:16.0.0-lts-kvm-amd64 -f raw installer_raw > installer.raw
    ARM64 
    docker run -v $HOME/eve-overrides:/in lfedge/eve:16.0.0-lts-kvm-arm64 -f raw installer_raw > installer.raw

  4. Print the contents of your current directory to verify that the file installer.raw was created.

    ls
  5. Proceed to flashing an EVE-OS image.

Get an EVE-OS live image (to live-boot from USB or SD)

To get an EVE-OS image that you can live-boot on an edge node without onboard storage, follow these steps. These steps specify the latest LTS in their examples. To substitute another version, replace 16.0.0-lts-kvm-arm64 or 16.0.0-lts-kvm-amd64.

  1. Navigate to a directory of your choice.

    cd $HOME

  2. Create a directory for your EVE-OS image and navigate into it.

    mkdir eve-images && cd eve-images

  3. Download and generate your EVE-OS installer image. Choose the command for your edge node’s hardware architecture. If your controller cluster is zedcloud.zededa.net, the following commands don't need
    -v $HOME/eve-overrides:/in

    Windows
    AMD64 
    docker run -v $HOME/eve-iso:/out lfedge/eve:16.0.0-lts-kvm-amd64 live
    ARM64 
    docker run -v $HOME/eve-iso:/out lfedge/eve:16.0.0-lts-kvm-arm64 live


     

    MacOS and Linux
    AMD64 
    docker run -v $HOME/eve-overrides:/in lfedge/eve:16.0.0-lts-kvm-amd64 live > live.img
    ARM64 
    docker run -v $HOME/eve-overrides:/in lfedge/eve:16.0.0-lts-kvm-arm64 live > live.img

  4. Copy and save the serial number string (in UUID format) that was printed by the previous command in the last line of output. You'll need it when you onboard your edge node. Example:

    681cc64f-6633-49f3-988c-b0afde4a25fc

  5. Print the contents of your current directory to verify that the file installer.raw was created. 

    ls
  6. Proceed to flashing an EVE-OS image.

Get a rootfs EVE-OS image (to update existing EVE-OS installations and live images)

You don’t need to provide a server configuration for rootfs images.

Rootfs EVE-OS images are used to upgrade existing installations of EVE-OS by uploading them to ZEDEDA Cloud and deploying them from there.

To get an EVE-OS rootfs image, follow these steps. These steps specify the latest LTS in their examples. To substitute another version, replace 16.0.0-lts-kvm-arm64 or 16.0.0-lts-kvm-amd64.

  1. Navigate to a directory of your choice.

    cd $HOME

  2. Create a directory for your EVE-OS image and navigate into it.

    mkdir eve-images && cd eve-images

  3. Download and generate your EVE-OS installer image. Choose the command for your edge node’s hardware architecture. 

    Windows
    AMD64 
    docker run -v $HOME/eve-iso:/out lfedge/eve:16.0.0-lts-kvm-amd64 rootfs
    ARM64 
    docker run -v $HOME/eve-iso:/out lfedge/eve:16.0.0-lts-kvm-arm64 rootfs


     

    MacOS and Linux
    AMD64 
    docker run --rm lfedge/eve:16.0.0-lts-kvm-amd64 rootfs > 16.0.0-lts-kvm-amd64-rootfs.img
    ARM64 
    docker run --rm lfedge/eve:16.0.0-lts-kvm-arm64 rootfs > 16.0.0-lts-kvm-arm64-rootfs.img
  4. Print the contents of your current directory to verify that the file installer.raw was created. 
    ls
  5. Verify that you have your rootfs image: 16.0.0-lts-kvm-arm64_OR_16.0.0-lts-kvm-amd64.img
  6. Proceed to flashing an EVE-OS image.

Next Steps

If you generated an installer or a live EVE-OS image, you're ready to flash your EVE-OS image to a bootable drive. To flash it and install it on your edge node:  

  1. Flash an EVE-OS installer or live image.
  2. Install EVE-OS on your edge node.

If you generated a rootfs image, proceed to adding an EVE-OS rootfs image to ZEDEDA cloud.

Was this article helpful?
8 out of 10 found this helpful