Configure Edge View (Advanced Method)

Updated

Introduction

Edge View is a standalone application developed by ZEDEDA to provide you with secure, remote access to your edge nodes and applications. It allows you to use your edge assets through your terminal as if you were directly logged into them, enabling you to do hands-on maintenance and troubleshooting.

This article explains how to configure Edge View using the "advanced method". Earlier articles showed how to follow the Edge View UI wizard to perform basic Edge View configurations, such as ensuring the project has a valid Edge View policy, and applying that policy to an edge node.

The advanced configuration method involves creating SSH keys, activating the session on the edge node, downloading the script, and using Linux commands to make the script executable using the chmod command, and running the script. Lastly, we'll show you how to establish an SSH session to your edge node so you can run various troubleshooting commands.

Prerequisites

  • You must have either the SysManager or SysAdmin role in your ZEDEDA Cloud enterprise.
  • If you are following this procedure on a Windows laptop, you must have Docker or WSL v2 installed prior to downloading and running the Edge View client script from the node.

This is a series of articles. There are different paths you can follow to configure Edge View. You can follow them in the order shown below, but it is not necessary to do so. 

  1. Edge View Overview
  2. Configure Edge View using the ZEDEDA GUI
  3. Use the ZEDEDA CLI to Configure Edge View
  4. Configure Edge View (Advanced Method) - You are here!

As a security precaution, your edge device will no longer allow directly connected keyboards to operate after you have finished installing EVE-OS and connected the device to ZEDEDA Cloud. This is ZEDEDA’s implementation of “security by design.”

If you need to run troubleshooting commands directly from the node, you can use SSH (assuming you are connected to the same network as the node). Alternatively, you can use the Edge View feature, if it has been added to the edge node in the ZEDEDA GUI.

Initial Setup Steps

Before you can use Edge View, follow the steps below to set up the Edge View policy in the GUI, and generate the SSH keys.

  1. Create a project with “Type” set to “Standard”, and within that project enable the Edge View policy. 
    Note: You cannot modify the “Type” for an existing project, so we recommend creating a new project from scratch (unless you already have a project configured for Edge View).
    • Log into ZEDEDA GUI and select Administration > Projects.
    • Click the Add icon (upper right) to create a new project.
    • Enter the mandatory details, such as Name and Title.
    • For the Type, select Standard.
    • For the Profile, select Regular.
    • Click Next (twice) to advance to the Policies tab. From here, select the Edge View Policy checkbox to enable the Edge View feature within this project.
    • Review the default settings for the Edge View Policy, and if they look acceptable click Next.
    • Review the configuration details for this project, and click Add.
       
  2. Create the SSH keys on your laptop. (This is only required if you do not already have SSH keys generated. If you have already generated these keys, you can skip to step 3.)
    • Open a terminal and run ssh-keygen
    • After running ssh-keygen, cd to your .ssh directory. (This is the sub-directory within your home directory where the SSH keys are stored by default.)
    • Check that your public key is there; it should have “pub” in the name.
    • Your private key is the one without “pub” in the name.
       

  3. Start a ZCLI session and enable SSH. For details, see how to enable SSH, and then run the following command:

    zcli edge-node update NAME-OF-YOUR-EDGE_NODE --config=debug.enable.ssh:"YOUR PUBLIC KEY"
  4. Log into the ZEDEDA GUI, and make the following configurations:
    • Click Edge Nodes.
    • Select the edge node where you want to apply the Edge View policy.
    • Click the Basic Info tab.
    • Click the Edit icon (upper right).
    • Click into the Project drop-down and select the project containing the Edge View policy you just configured in step 1.
    • Click Save.

 

Access Control with SSH Key Pairs

To enhance security and track who is running commands on your edge nodes, you can limit access to Edge View to certain users. The system will authenticate users via SSH key pairs. The remote edge node verifies each command's signature using stored public keys. If the signature is valid, then the command will be executed, and each command will be logged with the public key information, appearing in the 'Events' tab for that edge node in the ZEDEDA GUI.

(Optional) To configure SSH Access Control:

  1. On the edge node: Add one or more SSH public keys as a configuration property using the command: keyedgeview.authen.publickey 
    Note: You can add multiple keys by separating them with a newline.
  2. On your laptop: You must specify the SSH private key path for Edge View to use it to sign the command. 
    You can do this in one of two ways:
    • Config File: Create a file at ~/.edgeview/config and add the line:
      EdgeviewSshKeyPath:</path/to/your/private_key>
    • Environment Variable: Set an environment variable in the terminal:
      export EdgeviewSshKeyPath=</path/to/your/private_key>

Note: Support for SSH Access Control begins with EVE-OS v15.0.0. For details, see the LF-edge wiki.

 

Activating the Session

After completing the initial steps of setting up the Edge View policy, configuring the SSH keys, and (optionally) setting up SSH Access Control, you can now activate the session on the edge node and download the client script. (For details on what the script does, see How the Edge View Script Works.)

  1. Log into the ZEDEDA GUI and click the name of the Edge Node where you want to use Edge View.
  2. Click the Remote Access tab (at far-right).
    • If this is the first time activating a session on this node, the page will be mostly blank (except for the image of an edge node near the center of the page).
    • Below the image is a message that says: “You do not have an active Remote Access session”
    • Click the "Activate Session" link below this message.
    • The connection status for the edge node appears at upper right. After about 30-60 seconds, this should change to say “Activated”.
  3. Once the node has been activated, click the Download Script icon (left of "Activated") and to save it in your “Downloads” folder.
  4. Open a terminal session, and use the cd command to access your “Downloads” folder. Then, run the ls -lrt command. The output shows the last file that was downloaded. For example, you should see an entry similar to this: 
-rw-r--r--@ 1 zededa_user  staff  978 Dec 13 14:28 run.first_edge_node.1734146779.edgeview.sh
  1. You can make the file executable running the following command from your Downloads folder: 
    chmod 755 <file name> 
    For example:
chmod 755 run.first_edge_node.1734146779.edgeview.sh
  1. Now, run the command by prefacing it with “./” 
    You should see output similar to the following:
./run.first_edge_node.1734127774.edgeview.sh
Unable to find image 'lfedge/eve-edgeview:latest' locally
latest: Pulling from lfedge/eve-edgeview
8c6e9dd5d499: Download complete
3f71ee1f0256: Download complete
Digest: sha256:f367baf6b594080463ae4dcab3c69363d8b155dccb551f2f3e7e8944614143af
Status: Downloaded newer image for lfedge/eve-edgeview:latest
ZED-MBP connecting to wss://zedcloud.gmwtus.zededa.net/api/v1/edge-view
connect success to websocket server
Client endpoint IP: 76.158.71.195
Device IPs: [172.16.8.124]; Endpoint IP 12.203.60.163
  UUID: c3b9be50-d039-4957-8e0f-c258fdb9dc9f
  Device: first_edge_node, Enterprise: TestSetup-9603
  Controller: zedcloud.gmwtus.zededa.net  EVE-OS release 12.0.4-lts-kvm-amd64
, IMGA
  Edge-View Ver: 0.8.4, JWT expires at 2024-12-13T22:09:34Z
  2024-12-13T17:13:49Z(UTC), uptime 155274 (sec) = 1 days
  1. Note the IP address of your device, located within the square brackets in the output. (For example, in the output above, this is the row that says "Device IPs: [172.16.8.124]").
  2. Run the same command again (also from your Downloads folder), but this time, include the IP address of the device at the end of the command, as shown below:
./run.first_edge_node.1734127774.edgeview.sh tcp/172.16.8.124:22
  • Note that the end of the line:
    • tcp/
    • IP address of your device
    • port 22 (SSH default)
    • Entering this command creates a tunnel between your laptop and the edge node, wherever it may be located. You are greeted with a message containing "connect success to WebSocket server":
./run.first_edge_node.1734127774.edgeview.sh tcp/172.16.8.124:22
tcp mapping locally listening 1 ports to remote:
 0.0.0.0:9001 - 172.16.8.124:22
ZED-MBP connecting to
 wss://zedcloud.gmwtus.zededa.net/api/v1/edge-view
connect success to websocket server
Client endpoint IP: 76.158.71.195
Device IPs: [172.16.8.124]; Endpoint IP 12.203.60.163
 UUID: c3b9be50-d039-4957-8e0f-c258fdb9dc9f
 Device: first_edge_node, Enterprise: TestSetup-9603
 Controller: zedcloud.gmwtus.zededa.net  EVE-OS release 12.0.4-lts-kvm-amd64
, IMGA
 Edge-View Ver: 0.8.4, JWT expires at 2024-12-13T22:09:34Z
 2024-12-13T17:21:25Z(UTC), uptime 155730 (sec) = 1 days
 tcp tunnel(idx 0): starts in chan 1, addr 172.17.0.1:56424 (remote port 22)
  1. To review:
    • Your SSH keys have been created (or located, if already they existed).
    • In ZEDEDA CLI, the SSH (key) has been enabled. The name of the edge node and your SSH public key was passed to the edge node.
    • The Project is in place and it contains the Edge View policy.
    • The edge node has been configured with the above Edge View policy.
    • In the Edge Node Status tab, the Edge View checkbox has been selected.
    • The “Download Script” has been downloaded and has been made executable with the chmod Linux command.
    • The script is run, as described above.
  2. You can now establish an SSH session to your edge node:
    • Note in the output of the previous command, you will see: 
      0.0.0.0:9001 -> 172.16.8.124:22
    • You will use 0.0.0.00 as the destination IP and port 9001 in the SSH command.
    • Enter the SSH command from your SSH folder; it should appear similar to the following:
ssh -i id_ed25519 root@0.0.0.0 -p 9001

Notes:
- After -i is the file name of your SSH private key. This command is being executed from the same directory as your private key. If you are NOT in that directory, then you will need to either cd to that directory, or enter the absolute path to your private key file.

  1. If successful, a message similar to the following should appear:
ssh -i id_ed25519 root@0.0.0.0 -p 9001
The authenticity of host '[0.0.0.0]:9001 ([0.0.0.0]:9001)' can't be established.
ED25519 key fingerprint is SHA256:C8WQIinydSmuO/uiVfMI7ObBKKhlqDZd/PSk0UKgvWQ.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])? Yes
Warning: Permanently added '[0.0.0.0]:9001' (ED25519) to the list of known hosts.
EVE is Edge Virtualization Engine
Take a look around and don't forget to use eve(1).
c3b9be50-d039-4957-8e0f-c258fdb9dc9f:~#

 

Re-establishing an SSH session if your Token Expires

The JWT token expires within a certain time frame. When this happens, the SSH session will be disconnected. To re-establish the SSH session again, follow these steps:

  1. Log into the ZEDEDA GUI > Edge Nodes, and then click on the edge node where you want to enable Edge View and make the following configurations:
    • Click the Remote Access tab.
    • In the middle of the page, click Activate Session.
    • The connection status appears at the upper right. Once the status says “Activated” (after 30 - 60 seconds), click the Download Script icon mentioned above.
  2. In your terminal session, find the latest “run” command in the directory where your downloaded files are saved by running the following command:
ls -lrt run.<NAME-OF-YOUR-EDGE_NODE>.*
  1. Run that script using the IP address and port as stated in step 8.
  2. SSH to your server like in step 10.

Once you have set up an active SSH session to your edge node, you can now run troubleshooting commands. 

Descriptions for many of the troubleshooting commands are provided in this section on troubleshooting. For more detailed descriptions, as well as options and output for the commands, see: https://lf-edge.atlassian.net/wiki/spaces/EVE/pages/14584954/EdgeView+Commands 

 

How the Edge View Script Works

As part of the process of configuring Edge View (advanced method), you must download a script from the ZEDEDA GUI. When you download and run the Edge View script, it begins a sequence of events that establishes a secure connection between the Edge View client running on your laptop, and the Edge View server on the edge node.

Here is a step-by-step description of how the process works:

1. Docker Image Launch: When the script launches, it pulls the container image (lfedge/eve-edgeview:latest) from Docker Hub. This image includes the Edge View client, which creates the secure tunnels, handles authentication, and routes traffic.

2. Secure Authentication (Using a JWT Token): The script injects a short-lived JWT token, which is your access credential. These credentials prove your identity to ZEDEDA Cloud, and confirm your permissions. When the token expires you will need to re-activate the session and download a fresh script.

3. WebSocket Tunnel Creation: Once authentication is complete, the container opens a WebSocket tunnel to ZEDEDA Cloud. This creates a secure pathway between your laptop and your edge node. This firewall-friendly approach works well in networks that have robust security measures.

4. Remote Access is Provisioned: Depending on the kind of session you're launching, one of the following will occur: 

A. Terminal Access: You get terminal access into the edge node to run diagnostics and commands.
OR, 
B. Web UI: A remote service (for example, a web interface on the edge node) is forwarded to your laptop, which you can open in your browser, using a local port mapping.

 

This is a series of articles. You can follow them in the order below, but it is not necessary to do so.

  1. Edge View Overview
  2. Configure Edge View using the ZEDEDA GUI
  3. Use the ZEDEDA CLI to Configure Edge View
  4. Configure Edge View (Advanced Method) - You are here!


After you’ve completed the series, you might be interested in the following articles. 

Was this article helpful?
1 out of 1 found this helpful