Get an SSH-enabled EVE-OS image

This article describes how to create an EVE-OS image with SSH enabled, which will enable you to connect to an edge node via SSH before onboarding it to your enterprise.

Prerequisites

Docker must be running on your machine.

Considerations

After you onboard your edge node, these bootstrap SSH settings are ignored (they apply only until the device is onboarded). To keep SSH access after onboarding, re-enable it through the ZCLI by setting debug.enable.ssh to your public key:

zcli edge-node update <edge-node-name> --config="debug.enable.ssh:$(cat ~/.ssh/id_rsa.pub)"

Part 1: get your SSH key

You'll need an SSH key for the next procedure. To get one, follow these steps.

1. Check if you have an SSH key.

   cat ~/.ssh/id_rsa.pub

2. Contingent: If the output of the previous command is blank, create a new SSH key.

   ssh-keygen -b 2048 -t rsa

   Note: ed25519 is the modern default if your tooling supports it: ssh-keygen -t ed25519. Adjust the key paths below accordingly (~/.ssh/id_ed25519.pub).

3. Copy your SSH key for use in next steps.

Part 2: add the custom configuration

EVE-OS reads its bootstrap SSH configuration from two locations on the config partition:

• authorized_keys  at the root of the config directory, holds your public key.
• GlobalConfig/global.json  in the GlobalConfig subdirectory, enables SSH via the debug.enable.ssh property. This file must be present for EVE-OS to load the bootstrap configuration.

1. Create the config directory, including the GlobalConfig subdirectory.

   mkdir -p /tmp/config/GlobalConfig

2. Add your SSH public key to a file named authorized_keys at the root of the config directory. PUBLIC_KEY_PATH is typically ~/.ssh/id_rsa.pub.

   PUBLIC_KEY_PATH=~/.ssh/id_rsa.pub
   cat "$PUBLIC_KEY_PATH" > /tmp/config/authorized_keys

3. Insert the ZEDEDA controller FQDN into a file named server at the root of the config directory. (In this example, the FQDN is zedcloud.zededa.net.)

   cat <<EOF > /tmp/config/server
   zedcloud.zededa.net
   EOF

4. Add the SSH configuration to GlobalConfig/global.json. The value of debug.enable.ssh must be your SSH public key (an empty string disables SSH).

   cat <<EOF > /tmp/config/GlobalConfig/global.json
   {
     "GlobalSettings": {
       "debug.enable.ssh": {
         "Key": "debug.enable.ssh",
         "ItemType": 3,
         "StrValue": "$(cat "$PUBLIC_KEY_PATH")"
       }
     }
   }
   EOF
   

Note: ItemType: 3 designates a string value — debug.enable.ssh stores the authorized public key itself, not a boolean.

Part 3: get the custom image installer

1. Pull and generate the image installer for your preferred EVE-OS version. The following example will get you an installer for the latest EVE-OS version.

   docker run -v /tmp/config:/in --rm lfedge/eve:latest installer_raw > installer-ssh.raw

2. Refer to Flash your EVE-OS image for guidance on installing EVE-OS onto your USB device.

Connect to your edge node via SSH

The value of YOUR_PRIVATE_KEY_PATH in the following command is typically ~/.ssh/id_rsa

ssh -i YOUR_PRIVATE_KEY_PATH root@DEVICE_IP