Use SSH to Access and Troubleshoot Edge Nodes

This article describes how to enable an edge node for SSH access, use the EVE-OS (Edge Virtualization Engine) console to manage applications on the node, and disable SSH access when you are done.

Prerequisites

• Docker must be running on your machine.
• ZCLI is running.
• Your target edge node needs to be online.
• You have already onboarded an edge node to Edge Infrastructure Services.

Enable SSH for an Edge Node

1. Check if you have an SSH key.

   Linux:

   cat ~/.ssh/id_rsa.pub

   Windows:

   type C:\Users\USER-NAME\.ssh\id_rsa.pub

   If you have an SSH key, it looks similar to the following:

   ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDflVAtUnN/K5tYcXLoEtMAACTNn2UtEV18kL0vyrr7EMfS29xL/Bzq0UcF2H2fV9yUn+0gA5F2xN/gT0YhH3F9b4z4j8T9fH2G6b8c9a3Z5s4x4c6f7e8g9h0k3b5c7a8f9g2d4e6h8k0j1m3n5p7r9s0t2v4w6x8y0z+A1B3C5D7F9G1H3J5K7L9M1N3P5R7T9V1X3Z5a7b9c1d3f5g7h9j1k3l5m7n9p1r3s5t7v9w1x3y5z7A9B3D5F7H9J1L3N5P7R9T1V3X5Z7a9c1d3f5g7h9j1k3l5m7n9p1r3s5t7v9w1x3y5zFAKEKEYEXAMPLEQWERTYUIOPASDFGHJKLZXCVBNM=

   If you don't have an SSH key, create one and follow the prompts.

   ssh-keygen -t rsa

2. Copy the output of the cat (or type) command.

3. Run the ZCLI container.

   Linux:

   docker run -it -v $PWD:/root zededa/zcli:latest

   Windows:

   docker run -it -v "%cd%":/root zededa/zcli:latest

4. Log in to the ZCLI.

5. Enable SSH access by pushing the SSH key to your node.

   Warning: This command replaces all of the SSH keys that are currently set on the node. If other users already have SSH access to the node, they lose it when you push your key. Before you continue, run zcli edge-node show EDGE_NODE --detail and check the debug.enable.ssh value under Edge Node Config. If keys are already set and those users still need access, include their keys with yours, as described after the example.

   zcli edge-node update EDGE_NODE --config=debug.enable.ssh:"YOUR_PUBLIC_KEY"

   Example:

   zcli edge-node update My_Node --config=debug.enable.ssh:"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDflVAtUnN/K5tYcXLoEtMAACTNn2UtEV18kL0vyrr7EMfS29xL/Bzq0UcF2H2fV9yUn+0gA5F2xN/gT0YhH3F9b4z4j8T9fH2G6b8c9a3Z5s4x4c6f7e8g9h0k3b5c7a8f9g2d4e6h8k0j1m3n5p7r9s0t2v4w6x8y0z+A1B3C5D7F9G1H3J5K7L9M1N3P5R7T9V1X3Z5a7b9c1d3f5g7h9j1k3l5m7n9p1r3s5t7v9w1x3y5z7A9B3D5F7H9J1L3N5P7R9T1V3X5Z7a9c1d3f5g7h9j1k3l5m7n9p1r3s5t7v9w1x3y5zFAKEKEYEXAMPLEQWERTYUIOPASDFGHJKLZXCVBNM="

   To give more than one user SSH access, set all of their public keys at the same time, with each key on its own line. For example, save each public key as a .pub file in the directory that you mounted into the ZCLI container, and then run:

   zcli edge-node update EDGE_NODE --config=debug.enable.ssh:"$(cat user1.pub user2.pub)"

6. Find the IP address of your edge node and save it for later use. If the IP address for the edge node is on a private network, you might need VPN access for this step.

   zcli edge-node show EDGE_NODE --detail

7. Exit the ZCLI to your machine's standard command line.

   exit

8. Connect to the node via SSH using the corresponding private key.

   ssh -i YOUR_PRIVATE_KEY_PATH root@DEVICE_IP

   Example:

   ssh -i ~/.ssh/id_rsa root@192.0.2.119

   Example response:

   The authenticity of host '192.0.2.119 (192.0.2.119)' can't be established.
   ED25519 key fingerprint is SHA256:fK8pL3xQ9zR7vW2yJn4bM5gH1cE0sT6uX9vA2rZpLmY.
   This key is not known by any other names.
   Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
   Warning: Permanently added '192.0.2.119' (ED25519) to the list of known hosts.
   EVE is Edge Virtualization Engine
   Take a look around and don't forget to use eve(1).
   862bab0f-a567-4fc2-98b1-c82c77cf74c9:~#

Manage Applications From the EVE-OS Console

After you connect to an edge node over SSH, you land at the EVE-OS console prompt. From this prompt, use the eve command to list the applications deployed to the node and to open a shell or console session inside one of them. ZEDEDA recommends using these commands only for troubleshooting purposes.

Note: The eve app commands are available in EVE-OS 16.10.0 and later, including 17.0.0-lts. On earlier versions, including the 14.5-lts and 16.0-lts releases, use the older commands listed in Older command aliases. To check the EVE-OS version of your node, run eve version.

List applications on the node

Use eve app list to display all applications deployed to the edge node, along with their current status.

# eve app list
DISPLAY NAME         APP UUID                               TYPE               STATUS
------------         --------                               ----               ------
Log-Test             c401b61d-9ade-48fd-ac4b-98741a52480a   CONTAINER(NOHYPE)  RUNNING
GH-Runner            e30db90e-bf75-4ceb-b04d-b372c3dc121b   CONTAINER(HVM)     RUNNING
My-VM                a1234567-0000-1111-2222-333344445555   VM(HVM)            HALTED

The TYPE column shows whether the application runs as a virtual machine (VM) or a container (CONTAINER), and the virtualization mode in parentheses. A type of CONTAINER(NOHYPE) means the container runs directly on the edge node without a virtual machine. Any other mode (for example, HVM or FML) means the container or virtual machine runs inside a virtual machine.

The STATUS column reflects the current state of the application, for example RUNNING, HALTED, or BOOTING.

Open a shell inside an application

Use eve app enter <application> to open an interactive shell inside a running application. Specify the application by its display name (shown in the eve app list output) or by its container ID.

# eve app enter Log-Test

This command replaces the older eve enter-user-app <application> command, which is still supported for backward compatibility.

The result depends on the application's type:

• For a native container (CONTAINER(NOHYPE)), you land in a shell inside the application itself, where you can inspect its processes, files, and network configuration.
• For a container or virtual machine that runs inside a virtual machine, you land in a shell inside the hosting virtual machine's shim process, not inside the application. EVE-OS displays a warning in this case. To reach the application itself, attach to its console instead. Refer to the next section.

List and attach to application consoles

A virtual machine application exposes a console that you can attach to directly, similar to connecting a monitor and keyboard to the virtual machine. Use eve app console with no arguments to list the available consoles on the edge node.

Note: Application consoles are supported on edge nodes that run the standard EVE-OS (EVE-kvm) variant. On nodes that run other variants, such as EVE-k, eve app console might not list any consoles.

# eve app console
PID     APP-UUID                                CONS-TYPE       CONS-ID
---     --------                                ---------       ---------
3883    e4e2f56d-b833-4562-a86f-be654d6387ba    VM              e4e2f56d-b833-4562-a86f-be654d6387ba.1.1/cons
4072    f6d348cc-9c31-4f8b-8c4f-a4aae4590b97    CONTAINER       f6d348cc-9c31-4f8b-8c4f-a4aae4590b97.1.2/cons
4072    f6d348cc-9c31-4f8b-8c4f-a4aae4590b97    VM              f6d348cc-9c31-4f8b-8c4f-a4aae4590b97.1.2/shim-cons

Each row represents one available console. The CONS-ID column shows the identifier that you pass to eve app console <id> to attach to that console.

Attach to a console by its ID.

# eve app console e4e2f56d-b833-4562-a86f-be654d6387ba.1.1/cons

This command replaces the older eve list-app-consoles and eve attach-app-console <console> commands, which are still supported for backward compatibility.

After you attach, press Enter to activate the session. To end the console session, press Ctrl-T followed by q.

Older command aliases

In EVE-OS 16.10.0 and later, EVE-OS keeps the following older commands as aliases so that existing scripts and documentation continue to work. ZEDEDA recommends using the new eve app commands on these versions.

On EVE-OS versions earlier than 16.10.0, including the 14.5-lts and 16.0-lts releases, only the older commands are available. On these versions, eve enter-user-app accepts only the application's container ID, not its display name. The container ID is the application UUID followed by a suffix, for example c401b61d-9ade-48fd-ac4b-98741a52480a.1.1. To list the container IDs on the node, run ctr --namespace eve-user-apps containers ls.

Disable SSH for an Edge Node

1. Log in to the ZCLI.

2. Disable SSH for your edge node by removing all the public keys from the node.

   zcli edge-node update EDGE_NODE --config=debug.enable.ssh:""

3. Close any SSH sessions that are still open. Disabling SSH blocks new SSH connections to the node, but it does not end sessions that are already open. In each open session, run exit. If you are not sure whether any sessions are still open, reboot the node to close them.

4. Verify that your public key is gone.

   zcli edge-node show EDGE_NODE --detail

   Before disabling SSH, the config looks similar to the following:

   Edge Node Config:
   debug.enable.ssh    ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDflVAtUnN/K5tYcXLoEtMAACTNn2UtEV18kL0vyrr7EMfS29xL/Bzq0UcF2H2fV9yUn+0gA5F2xN/gT0YhH3F9b4z4j8T9fH2G6b8c9a3Z5s4x4c6f7e8g9h0k3b5c7a8f9g2d4e6h8k0j1m3n5p7r9s0t2v4w6x8y0z+A1B3C5D7F9G1H3J5K7L9M1N3P5R7T9V1X3Z5a7b9c1d3f5g7h9j1k3l5m7n9p1r3s5t7v9w1x3y5z7A9B3D5F7H9J1L3N5P7R9T1V3X5Z7a9c1d3f5g7h9j1k3l5m7n9p1r3s5t7v9w1x3y5zFAKEKEYEXAMPLEQWERTYUIOPASDFGHJKLZXCVBNM=

   After disabling SSH, the config looks similar to the following:

   Edge Node Config:
   debug.enable.ssh