Add a rootfs EVE-OS image to your Edge Infrastructure Services enterprise

Updated October 03, 2026 15:31

Introduction

This article describes how to get a new EVE-OS (Edge Virtualization Engine) rootfs image and how to add it to your Edge Infrastructure Services enterprise.

Before you read ahead, familiarize yourself with our EVE-OS images overview.

After you obtain your EVE-OS rootfs image, use one of two methods to add it to your enterprise:

Uploading copies an EVE-OS rootfs image from your local machine to one of your datastores. You place the physical image file into the datastore.
Uplinking associates an EVE-OS image entry in your enterprise with an EVE-OS rootfs image that already exists in a datastore. You register the image's metadata (its name, version, architecture, location, and SHA256 checksum) with Edge Infrastructure Services, so Edge Infrastructure Services knows where to find the image.

Both procedures result in a new EVE-OS rootfs image available in your enterprise.

Prerequisites

The ZEDEDA Command Line Interface (ZCLI) is running.
Docker is running on your local machine.
You have already created a data store, or you have access to a ZEDEDA-managed datastore.

Considerations

Available approaches

Note: At this time, you must upload EVE-OS images using ZCLI. This functionality is not currently available through the ZEDEDA GUI.

Limitations of uploading

For security and reliability purposes, ZEDEDA supports uploading only for ZEDEDA-managed datastores, as a convenience to ease onboarding.

If you try to upload an image to a datastore that ZEDEDA does not manage, you see an error similar to the following:

Image upload to datastore of type DATASTORE_TYPE_SOMEVENDOR not supported.

Get a New Rootfs EVE-OS Image

Complete the following procedure to get a rootfs version of EVE-OS before you upload or uplink it. When you upload or uplink an EVE-OS image, you must use a rootfs image. You cannot use an installer image, such as the image you use during a standard EVE-OS install procedure.

Choose the version that you want to add to your enterprise. For a list of current LTS versions of EVE-OS, see the EVE-OS LTS releases.
Open your terminal and navigate to your preferred working directory. This directory holds your EVE-OS rootfs image when you finish.
Get the full version name of the image. This is the exact name that you use for IMAGE_NAME when you add the image to your enterprise.
```
docker run --rm lfedge/eve:EVE_VERSION version
```
For example:
```
docker run --rm lfedge/eve:11.0.5-lts-kvm-amd64 version
```
The output displays as follows:
```
11.0.5-lts-kvm-amd64
```
For LTS and other release versions, the output usually matches the version that you pulled. For other builds, it can be different. For example, a 14.5-stable build returns a name similar to 0.0.0-14.5-stable-29901325-kvm-amd64. Always use the output of this command, not the version that you pulled.
Copy the output. You need it for IMAGE_NAME in the commands that follow.

Pull and generate a new EVE-OS rootfs image. The following example uses 11.0.5-lts-kvm-amd64.

docker run --rm lfedge/eve:EVE_VERSION rootfs > IMAGE_FILE_NAME.img

For example:

docker run --rm lfedge/eve:11.0.5-lts-kvm-amd64 rootfs > 11.0.5-lts-kvm-amd64-rootfs.img

Upload a Rootfs EVE-OS Image

Upload a rootfs image from your local machine to your ZEDEDA-managed datastore. These steps include ZCLI example commands. The GUI does not currently support uploading.

Log in to ZCLI.
Create an EVE-OS image entry in your enterprise.
Warning: The IMAGE_NAME value must exactly match the full version name that the version command returned in the preceding procedure (for example, 11.0.5-lts-kvm-amd64). Edge nodes use this name to identify the EVE-OS version. If the name does not match the version inside the image, nodes cannot confirm that the update completed. The image format for rootfs images should always be RAW.
```
zcli image create IMAGE_NAME --arch=AMD64_OR_ARM64 --datastore-name=DATASTORE_NAME --type=Eve --image-format=RAW --title=IMAGE_NAME
```
For example:
```
zcli image create 11.0.5-lts-kvm-amd64 --arch=AMD64 --datastore-name=Zededa-AWS-Image --type=Eve --image-format=RAW --title=11.0.5-lts-kvm-amd64
```

Upload your EVE-OS rootfs image.

zcli image upload IMAGE_NAME --chunked --path=PATH/TO/IMAGE_NAME

For example:

zcli image upload 11.0.5-lts-kvm-amd64 --chunked --path=./11.0.5-lts-kvm-amd64-rootfs.img

Verify that you can see your new image entry in your enterprise. Look for Status: Ready in the output.
```
zcli image show IMAGE_NAME
```
For example:
```
zcli image show 11.0.5-lts-kvm-amd64
```

Uplink a Rootfs EVE-OS Image

Use uplink to associate an EVE-OS image entry in your enterprise with an EVE-OS rootfs image that already exists in a datastore you host and manage yourself, such as an SFTP or HTTP server. Uplinking does not copy the image file. It only registers the image's metadata (its name, architecture, location, and SHA256 checksum) with Edge Infrastructure Services.

ZEDEDA-managed datastores (for example, Zededa-AWS-Image or Zededa-Azure-Image) do not provide file-level access, so you cannot copy an image file into them yourself. If you need to add an image to a ZEDEDA-managed datastore, use Upload a Rootfs EVE-OS Image instead. Use uplink only for a datastore that you host, where you are responsible for placing the image file at the location that Edge Infrastructure Services will reference.

Create an example SFTP datastore

If you do not already have a datastore that you host and manage, set up an example SFTP datastore as follows.

Enable SSH on the host that will serve the image.
Create a dedicated user account on that host, and set a password that you will enter when you configure the datastore in Edge Infrastructure Services.
Configure a DHCP reservation for the host so that it keeps a static IP address.
Create a datastore in Edge Infrastructure Services that points to this host, using the SSH credentials and static IP address.

Uplink the image

To uplink an EVE-OS rootfs image, follow these steps. The steps include ZCLI example commands. The GUI does not currently support uplinking.

Log in to ZCLI.
Copy your rootfs image file to the datastore that you host. For example, use scp or another file transfer tool to copy the image to your SFTP server.
Get the SHA256 checksum and the file size of the image. Run the following commands (adjust for your operating system) from the directory that contains your image.
```
shasum -a 256 IMAGE_FILE_NAME.img
stat -f %z IMAGE_FILE_NAME.img
```

Create an EVE-OS image entry in your enterprise.
Warning: The IMAGE_NAME value must exactly match the full version name that the version command returned (for example, 11.0.5-lts-kvm-amd64). The image format for rootfs images should always be RAW.

zcli image create IMAGE_NAME --arch=AMD64_OR_ARM64 --datastore-name=DATASTORE_NAME --type=Eve --image-format=RAW --title=IMAGE_NAME

For example:

zcli image create 11.0.5-lts-kvm-amd64 --arch=AMD64 --datastore-name=local-sftp-datastore --type=Eve --image-format=RAW --title=11.0.5-lts-kvm-amd64

Uplink your rootfs image. You must include the --image-url argument with the path to the image file on your datastore.
Warning: If you omit --image-url, ZCLI does not return an error. Instead, it silently sets the image URL to the image name, which registers the wrong location for your image. Always specify --image-url explicitly.

zcli image uplink IMAGE_NAME --datastore-name=DATASTORE_NAME --image-sha=SHA_256_VALUE --image-url=PATH_TO_IMAGE_ON_DATASTORE --image-size=IMAGE_SIZE_IN_BYTES

For example:

zcli image uplink 11.0.5-lts-kvm-amd64 --datastore-name=local-sftp-datastore --image-sha=629595dda5afec054c5d5fad485da3e6068994a7001534a4eaee5170696aa8f4 --image-url=/11.0.5-lts-kvm-amd64-rootfs.img --image-size=232476160

Verify that you can see your new image entry in your enterprise. Look for Status: Ready in the output.
```
zcli image show IMAGE_NAME
```
For example:
```
zcli image show 11.0.5-lts-kvm-amd64
```
Note: For an uplinked image, Status: Ready means that the image entry is registered in your enterprise. It does not confirm that the image file is at the location that you specified, or that the SHA256 checksum and size are correct. These details are checked when an edge node downloads the image. Before you update your edge nodes, double-check the image URL, checksum, and size, and make sure that your edge nodes can reach your datastore.

Next Steps

To update your edge nodes with your new rootfs EVE-OS image, see marking an EVE-OS rootfs image as default. Then see updating edge nodes with a latest image.

Was this article helpful?

3 out of 3 found this helpful