A basic assumption from the start was that the IoT and edge devices could be in complex network environments with conditions such as:

• Limited connectivity

• Located behind firewalls without a public IP address

• IT staff not available at remote sites

• Devices deployed outside of the data center security perimeter

• Many different hardware platforms and configurations

Client-Server Architecture

Client

Connect Agent periodically sends heartbeats containing status information about the device including CPU, RAM, and disk usage and information about any processes being monitored.

Server

The Connect server manages all communications to and from the Connect Agents and performs a number of functions including the following:

• Receives regular status and monitoring messages from the clients

• Controls the software update process and all interactions with the agents including remote control and access, obtaining device details, and fetching files requested

• Processes all interactions between the user interface and the Connect Agents

Infrastructure Configurations

The Connect system supports a number of infrastructure configurations.

Multi-tenant Cloud

This includes a Connect account under a multi-tenant infrastructure, integrated with a single-tenant Artifactory for your software supply chain needs.

Private Cloud

In this arrangement, the complete environment is isolated, with both Connect and Artifactory hosted on one of the major cloud providers.

On Premises

This is an isolated, air-gapped environment, with Connect and Artifactory for setups that require separation from the outside world.

User Interface

Connect API

Security

JFrog Connect adheres to industry standards and complies with relevant security and safety regulations to ensure the security of your data. Connect is also dedicated to enabling you to comply with your own internal security policies.

Among its security features, Connect supports JSON Web Tokens (JWTs) and uses them to support secure interactions between a Connect project and the Connect Agent on a device.

Connect Multi-Tenant Cloud Architecture

The Connect servers, databases, storage, and cloud environment are all based on AWS products with AES-256 encryption and live zone fallback combined with an extra layer of security, a separate Amazon Virtual Private Cloud (Amazon VPC).

Part of JFrog Platform

JFrog Artifactory Edge

What’s Next?

Manage and Secure Your Supply Chain

Automate OTA Updates

Use a Trusted Artifact Framework

What’s Next?

Objectives

It is one thing to build a single update workflow and use it to deploy software to a few devices, but it is worth putting some thought and planning into how you will build and use workflows for maintaining your fleet over time. The goals of the methodology we recommend can be summarized in a few key points.

Make it robust

It is important to build an update mechanism that reduces chances of error and helps you get the most out of JFrog Connect capabilities. Just one example of this is using the On Failure and Rollback features. Once you specify what should happen when an action in the workflow fails, and you specify when and what type of rollback should occur, then you will know what the outcome of an action will be no matter what happens.

Another aspect of ensuring robustness is in building update flows that we know how to roll back. For example, if you run many commands that do different things like replacing packages on the OS, it might be very hard to build a proper rollback mechanism that turns everything back 100%, as you can't be sure exactly where the update failed and what specifically was done. Therefore, you should design and build flows that are highly controlled, so that in any case of failure you have a straightforward procedure for safe rollback.

Keep it simple

While the JFrog Connect options enable you practically infinite possibilities to build your workflow and your update flows specifically, our objective is to recommend practices that help you build a minimal, yet flexible set of workflows that cover the update tasks for your fleet.

Build for reuse

Build a process that you can repeat many times over. To gain confidence and consistency in your deployment method, you will want to create update flows that you can use over and over again. For example, you will need to know that you are performing exactly the same actions in your test environment as in production, and in production you may need to use exactly the same flows from one group of devices as in another. We’ll recommend practices for obtaining this kind of consistency so that you can have complete confidence in your deployments.

Think long-term

Think about how you will need to perform your software updates a few months or even a few years down the road so that you can start building your update flows the right way. This could include naming conventions for versions, workflows, and deployments and considerations such as containerization and management of binaries.

Key Concepts

The ideal update flow will involve choosing one or more Docker containers that reside on an Artifactory repository, defining some parameters for dynamic deployments, and choosing an app version. To help you understand the process more deeply, the key concepts are described below.

Containers & Docker Compose

We recommend using Docker Compose, whether your device software requires one or multiple containers. With Docker Compose, you use a YAML file to configure your application's services. For example, you specify which Docker images to pull from the repository, including one or any number of images. This enables you to easily manage the deployment of containers on the device.

Binary Repositories & Artifactory

While Connect can work with several binary repositories, we recommend JFrog Artifactory as the repository for large scale, enterprise class software deliveries. Artifactory:

• Offers a comprehensive solution for managing and distributing software binaries and artifacts, such as container images, application packages and installers, libraries, configuration files, and virtually any other type of binary data that is produced during the software development and delivery process.

• Supports all major package formats including Docker, Alpine, Maven, Gradle, Cargo, Conda, Conan, Debian, Go, Helm, Vagrant, YUM, P2, Ivy, NuGet, PHP, NPM, RubyGems, PyPI, Bower, CocoaPods, GitLFS, Opkg, SBT, Swift, Terraform and others.

• Has a flexible architecture that can work in cloud-native, self-hosted, and hybrid, environments.

Parameters & Dynamic Deployment

When you set up an update flow, you can parameterize any of the data fields. This enables you to reuse flows for multiple deployments while entering the values for the parameterized fields when you run the deployment.

For example, you build an update flow that uses Docker images. You need the flow to run the same action blocks in every deployment, but you intend to use a different Docker Compose configuration file for each deployment. You would make the path to this file a parameter that is filled in dynamically for each deployment. Connect would then pick up the correct configuration file for each deployment by looking in the path entered dynamically in each deployment.

You could take this a step further and use the Connect API to update your parameters upon deployment. This would be the recommended method to run automated deployments updating software for the entire fleet.

App Name & App Version

An App is simply a metadata name that you create for a deployment. When you deploy an update flow, you associate the app name and an app version with the deployment (e.g., one or more microservices or containers being deployed together) and the devices included in that deployment. In each deployment, you can update the app version as needed.

Once you have completed a few deployments, you can then use app and app version as a method of filtering devices for purposes of monitoring or performing further operations on those devices.

What’s Next?

JFrog Connect, part of the JFrog Platform, simplifies and secures the entire IoT development lifecycle. It unifies industry-leading artifact management, robust security, and enterprise-grade scalability for efficient and secure deployments of your IoT fleets.

Start Free

At the heart of the JFrog Platform is JFrog Artifactory, the industry standard for universal binary repository managers. Artifactory provides end-to-end automation and management of binaries and artifacts throughout the application delivery and deployment process.

Default JFrog Platform Account

Connect creates two repositories in your new Artifactory account:

• Connect-default-docker

• Connect-default-generic

JFrog Platform Instance

You can find your JFrog Platform instance domain at the bottom of the left navigation bar.

JFrog Instance Domain before April 2022

If you have registered to Connect before April 2022, do the following to find the JFrog Platform instance domain:

1. In the left sidebar, go to Updates and click the Create Update Flow tab.

1. Ensure the Connect Agent is 6.0.

2. Drag and drop the Artifacts action block and click it.

1. Ensure that the JFrog Account field is set to default-connect and click the eye to the right of the field. The instance domain is under JFrog Platform URL.

JFrog Xray

Configure Other Registries

Regardless of the default Artifactory instance, you can configure your Connect account to work with a registry other than Artifactory.

To set up Connect to work with a different registry, see Registry.

What’s Next?

Design

Connect Agent was designed with a few key points in mind to give you a simple and secure experience:

• Lightweight - Consumes about 4 MB of disk space and about 11 MB of RAM.

• Always on - The Connect Agent service is always running in the background. Even when there is no Internet connection, the agent will always keep the device accessible remotely when the connection returns.

• Zero dependencies - Designed to run like an add-on, i.e., no additional installations are required to make it work.

• Smart network behavior - Only communicates as a client, using port 443 with the Connect Server. No open network ports or listening servers are required on the edge and IoT devices.

Connect Agent Functions & Behavior

In addition, the Connect Agent:

• Facilitates the software updates to the edge device according to the blocks defined in the Update Flows

• Enables remote access and control commands to the device

• Enables creation and configuration of firewall rules on the devices

• Retrieves logs and any kind of data file stored on the device according to your request

The Connect Agent is project linked. This allows agents in different projects to have different configuration settings such as communication cycle and user access parameters. If you have multiple projects configured and you register a new agent, you will need to ensure that you associate the new agent with the intended project.

An agent acts as standalone software with regard to installation. If you re-install the same version of an agent on the same device, the new agent will have a different token and will be counted as a new device. In addition, the old device is not removed from the database in the Connect Server and appears in offline state in the web UI until you delete it.

Specifications and Compatibility

Connect Agent is designed for easy installation and compatibility on any Linux-based operating system and is suitable for use on a variety of hardware architectures including SOC, SOM, and SBC, as long as the OS is Linux-based.

Hardware

The Connect Agent is compatible with popular hardware platforms such as NVIDIA Jetson, BeagleBone, and Raspberry Pi, and will work with any hardware platform meeting the following specifications:

Minimum total device resources:

• 30MB RAM

• 30MB Disk space

Core Architecture:

• ARM:

  • ARMv5, ARMv6, ARMv7, ARMv8 - 32 and 64 bit

  • Cortex-A required for all ARM processors

• Intel: x86 and x86_64

Operating System

You can use a wide range of operating systems, including Windows and the following Unix-based OSs:

• Yocto-based build

• Ubuntu

• Debian

• Centos

• Raspberry Pi OS

• Arch

• Custom Debian build

Required Software

Systemd/SysV (init.d) service manager must be installed on the client device.

Required Permission for Agent

The device must be configured to allow Write permission to the Connect Agent.

Agent Updates

From time to time a new version of the Connect Agent will become available. The Connect Agent updates ensure that IoT devices are running the latest software and are able to communicate with the JFrog platform effectively.

The new agent version is not deployed automatically. When a new version is available, you can initiate an OTA update process at your convenience to update the agents on your connected devices. The update process takes place in the following stages:

1. Agent Version Management: Connect keeps track of the versions of the agents running on each device and compares them to the latest version available.

2. Notification: When a new version of the agent is available, a notification appears in the web UI and a release note will be available.

3. Initiation: In the Connect Agent Update page, you initiate the OTA update process.

4. Update Verification: Connect verifies that the update has been applied successfully to each device. If a device fails to update, Connect can retry the update or alert the appropriate personnel.

5. Post-update Verification: After the update process completes, Connect can verify that the new version of the agent is running (online/offline) on each device.

Device Authentication

JFrog Connect Agent version 7.0 employs a trust mechanism that uses JSON Web Tokens (JWT) for secure interactions between the agent and a Connect project.

What’s Next?

Protocols

As one method of enhancing network security, there are no open ports or running servers on the edge devices. Communication with Connect Agent works via outbound requests to ensure zero attack surfaces for attackers.

• The edge device uses UDP and port 53 to resolve hostnames and connect with the JFrog Connect servers.

• The Connect Agent and servers communicate on TCP as follows:

  • All other client-server communication uses HTTPS TLS encryption on port 443

Server Allowed List

To use JFrog Connect, ensure that the following Outbound domains and IP addresses are on your allowed list:

For Future Use

The following IP addresses should also be added to the allowed list. They are currently not bound to any domains, but are reserved for future use.

Terminal & Port Tunneling

Terminal

• Domain: remote.control.jfconnect.io

• Static IP: 18.158.153.17

• Ports: 442, 443

Port Tunneling

• Domain: forwarding.jfconnect.io

• Static IP: 3.70.153.137

• Ports: Will try 22 first, then 443, then 80

What’s Next?

Prerequisites

To complete the update process described on this page, you will need the following:

Process Overview

Connect has created a process for updating software in your IoT devices that is simple and repeatable. The illustration below provides an overview of the process and the actors involved. The stages in the process are numbered to show the order of events, and each stage is described in detail below.

Stages in Update Process

The stages described in detail below correspond to the stages indicated in the illustration.

1. Create Docker Images and Compose YAML File

You use Docker to create your container images. You will also use Docker Compose to create a compose.yaml file.

We recommend using Docker Compose, whether your device software requires one or multiple containers. With Docker Compose, you use a YAML file to configure your application's services. This enables you to easily manage the deployment of numerous microservices that may require numerous containers on the device. (Your specification in the YAML can include one or any number of Docker images to pull.)

2. Upload Docker Images and Compose YAML to Artifactory

You upload your container images and compose.yaml file to repositories in Artifactory. (You upload the compose.yaml file to a generic repository and the Docker image to a Docker registry.) For more information, see Docker Compose Best Practice.

Your Artifactory repositories will serve as your central point of truth for all of the binaries and artifacts that need to be included in a release. Files you keep here might include container images, application packages, installers, libraries, and configuration files. Over time you will accumulate additional versions of the binaries, and they will all be available to you in Artifactory.

3. Create Release Bundle

4. Create Update Flow & Deployment

Build an Update Flow for Reuse

Using Connect, you create an Update Flow consisting of one or more actions. Use either Release Bundle or Deploy Docker as one of your actions. We recommend the following:

• Whether you use the Release Bundle or the Deploy Docker action block, choose Docker Compose in the configuration.

• Whether you deliver one or multiple containers, choose Docker Compose.

We also recommend parameterizing any of the fields in the update flow that will likely be different from one deployment to the next. You will fill in the values when the deployment actually runs. This is another practice that enables reuse of the update flow.

Once you have created a good update flow, you can reuse it tens or hundreds of times for subsequent software deployments.

Create Deployment

After creating the update flow, you implement it by creating a Deployment. A deployment is an object that associates the update flow with a group of devices and defines the triggering for the update to take place.

When you create a deployment, you will be prompted to enter the values for the parameters you defined in the update flow. For example,

5. JFrog Connect Instructs Devices to pull Artifacts

By default, when you save the deployment or when Connect receives the Deploy Update API command, Connect instructs the device to request the update artifacts. However, you can also schedule a later time for the deployment to run. This is ideal for updating the software at times when usage is low or other risk factors are low.

6. Connect Agent pulls YAML from Artifactory

The Connect Agent in the device receives the Deployment and uses the path and filename of the Docker Compose YAML to pull the file from Artifactory.

7. Docker Compose pulls Images from Artifactory

The Docker Compose YAML file received in the device uses the filename(s) and path(s) of the Docker image(s) to pull one or multiple Docker images from Artifactory.

8. Compose Agent updates Images in Device

The Docker Compose in the device updates the Docker images on the device with the new ones it received from Artifactory.

Reuse the Update Workflow

When you need to update the software again, you will repeat all the stages in the process above with one major exception: you will not need to create a new Update Workflow. Once you have built a single, robust update workflow and run a successful deployment, you can use the same workflow to deliver:

• Later versions of the Docker images (i.e., in the new deployment, change the Artifactory path value for the Docker Compose YAML)

• Different Docker images containing different microservices (i.e., in the new deployment, use a different Docker Compose YAML and change the Artifactory path value to pull the new YAML)

• The same Docker images to different groups of devices (i.e., in the new deployment, change the Group(s) to which the updates are delivered)

What’s Next?

For example, If you would like to make sure that all devices registered to your fleet are automatically updated with the latest software, or, some kind of configuration that initiates after a successful factory reset.

Instead of registering the device via the installation command or a pre-made image, we will use a Python script on the device that will register and deploy an update to itself.

Prerequisites:

• REST API enabled

• Be familiar with our API and tokens - Overview

• Python3 is installed on the device.

• requests library installed on the device

The script performs the following:

1. Registers the Device to Connect, according to the selected project

2. Deploying an update flow that was previously configured in the platform.

3. Even if the device is already registered, the update will still be deployed.

Instructions:

Take the code below and edit with the following configuration at the top:

• USER_TOKEN - Your user token, can be taken from Settings > Account > Show User Token.

• PROJECT_NAME - The name of the desired project that the device will be connected to.

• UPDATE_FLOW_ID - ID of the desired flow to be deployed on the device, the flow must be a part of the project above.

import requests
import subprocess
import os
import json
import time

# ----------------------------#


# Needed to be edit per user before running
USER_TOKEN = ""
PROJECT_NAME = ""
UPDATE_FLOW_ID = ""
# ----------------------------#


# Don't touch - will be added automatically by the script
DEVICE_TOKEN = ""
DEVICE_UUID = ""
# Don't touch - static paths and URLs
INSTALLATION_URL = """su -c 'wget -O - https://connect.jfrog.io/v2/install_connect | sh -s {} {}'"""
CONNECT_AGENT_PATH = "/etc/connect/service/ConnectAgent"
AGENT_FLAG_TO_GET_DEVICE_TOKEN = "--print-token"
DEPLOY_UPDATE_API_URL = "https://api.connect.jfrog.io/v2/deploy_update"
GET_DEVICE_DETAILS_API_URL = "https://api.connect.jfrog.io/v1/devices_details"


def is_connect_agent_exist_on_device():
    return os.path.exists(CONNECT_AGENT_PATH)


def install_connect_agent(user_token, project_name):
    final_installation_url = INSTALLATION_URL.format(user_token, project_name)

    subprocess.check_output(final_installation_url, shell=True)

    print("waiting 2 minutes before continuing the process...")

    time.sleep(120)


def get_device_token():
    device_token = subprocess.check_output(CONNECT_AGENT_PATH + " " + AGENT_FLAG_TO_GET_DEVICE_TOKEN, shell=True)

    return device_token.decode('ascii')


def get_device_uuid(user_token, project_name, device_token):
    json_content = {'project_name': project_name,

                    'group_name': 'Production',

                    'user_token': user_token,

                    'device_token': device_token}

    call_request = requests.get(GET_DEVICE_DETAILS_API_URL, json=json_content)

    call_response = json.loads(call_request.text)

    return call_response["message"][0]["device_uuid"]


def deploy_update_flow(update_flow_id, user_token, project_name, device_uuid):
    print("deploying update flow {} on device {} ....".format(update_flow_id, device_uuid))

    json_content = {'user_token': user_token,

                    'metadata': {'comment': 'deploy app v1',

                                 'app': {'name': 'app', 'version': 'v1'}},
                                 
                    'deployment_configuration': {
                                 'flow_id': update_flow_id}

                    'devices_filter': {'project': {'name': project_name},

                                       'groups': [{'name': 'production'}],

                                       'filters': [{'type': 'specific_device',

                                                    'operand': 'is',

                                                    'value': device_uuid}]}

                    }

    call_request = requests.post(DEPLOY_UPDATE_API_URL, json=json_content)

    call_response = json.loads(call_request.text)

    if call_request.status_code == 200:

        print("process finished successfully")

    else:

        if call_request.status_code == 429:

            error = "API limit reached"

        else:

            error = call_response["error_message"]

        print(error)


if __name__ == '__main__':

    if not is_connect_agent_exist_on_device():

        if USER_TOKEN and PROJECT_NAME and UPDATE_FLOW_ID:

            install_connect_agent(USER_TOKEN, PROJECT_NAME)

        else:

            print(
                "one or all of the required parameters - user token, project name and update flow id were not provided, make sure to edit the script before running again")

            exit(1)

    else:

        print("JFrog Connect is already installed on device")

    if not DEVICE_TOKEN:
        DEVICE_TOKEN = get_device_token()

    if not DEVICE_UUID:
        DEVICE_UUID = get_device_uuid(USER_TOKEN, PROJECT_NAME, DEVICE_TOKEN)

    deploy_update_flow(UPDATE_FLOW_ID, USER_TOKEN, PROJECT_NAME, DEVICE_UUID)

2. Copy the script to the device

3. Choose when the script would run, some prefer having it running after the next power-on, while others initiate it with their on-device application.

What's Next?

How will you organize your fleet, create re-usable workflows, and use the many tools in Connect to manage your fleet efficiently over the long term?

In this chapter, we introduce some key concepts and walk you through an idealized use case that does not go into all the numerous variations possible. You can then use this as a model for building your own strategy according to your specific business needs.

What’s Next?

Prerequisites

You need the following before starting the procedure:

• Internet connectivity with the devices

Step 1: Register a Single Device

Complete the following steps:

2. Disconnect the device from the Internet.

Step 2: Prepare the Settings File

Using Connect Agent 7.0

1. Delete the settings.json file at the path indicated below: /etc/connect/service/settings.json

2. Create a new settings.json file in the same location and add the following content: {"pairing_token":"<pairing_token>", "device_name":"", "device_group":"", "software_version":"", "device_token":""}

3. Get the <pairing_token>. You can get your token in the Connect web UI. Go to Devices and click Register Device. To generate the token, click Generate Token.

4. Save the file. Do not reconnect the device to the Internet until you have duplicated the image.

Using Connect Agent 6.x or Lower

1. Delete the settings.json file at the path indicated below: /etc/connect/service/settings.json

2. Create a new settings.json file in the same location and add the following content: {"user_token":"<user_token>", "project_name":"<project_name>", "device_name":"", "device_group":"", "software_version":"", "device_token":""}

3. Change the <user_token> to your account token. You can find your token in the Connect web UI under Settings.

4. Change the <project_name> to the project you want the device to be registered to. You can find your projects in the Connect web UI under Settings.

5. (Optional) You could set the value of <device_name> to “$HOSTNAME” or to some other variable. Then the device name that appears in the web UI will be the host name of each device (or a different name depending on the variable you use for the <device_name> value.

6. Save the file. Do not reconnect the device to the Internet until you have duplicated the image.

Step 3: Duplicate and Distribute the Image

1. Duplicate this device image, and burn it on other SD cards or eMMC flashes.

2. Boot a new device that has the duplicated image. Connect Agent will automatically recognize that it is running on new hardware and will register the device as a new device.

3. Repeat the step above for all of the devices with the new image.

The new devices now appear in the Web UI on the Devices page. You can view them there and edit any of the details as necessary.

Step 4: Set Device Name and Group Automatically

You can set the device name and group automatically either before or after the devices are registered.

After the device registers to the platform, the settings.json file is encrypted and you will not be able to modify it anymore.

Set after Registration

Set before Registration

You can set the device name and group by setting the <device_name> and <device_group> keys in the settings.json file before the device registers to the platform. This means that you are creating a unique settings file for each device, so it is recommended to write a script that will generate the files.

In order to set the device name and group correctly, we recommend including the following steps in your script:

1. Run a script on the device boot using crontab or init.d.

2. Check if /etc/connect/service/settings.json already exists. If it exists, finish the script.

3. If it doesn't exist, generate the device name (by any method you would like).

4. Create the /etc/connect/service/settings.json file including the correct values.

5. Change the file permissions by running chmod 777 /etc/connect/service/settings.json

If no device name or group has been defined, the Connect Agent will register the device with a generic name “New device” to the group “Production”.

Get Device Token

If you are using the Connect API, you will need the device token. To receive the device token, run the agent binary with the flag --print-token. The command is:

/etc/connect/service/ConnectAgent --print-token

What’s Next?

Log in to JFrog Platform

Using this method, you log in to JFrog Platform first, and then go from the Platform to Connect.

To log in to JFrog Platform, do the following:

1. In your web browser, enter the JFrog web address with your account name and type Enter. For example, if your account name is frogs123, then enter frogs123.jfrog.io and type the Enter key.

2. After the Welcome to JFrog page appears, enter your Username and Password, and click Login.

1. When the JFrog Platform page appears, go to the left navigation bar and choose Connect IoT.

The JFrog Connect dashboard page appears and you can start working in your Connect account.

Log in with Connect URL

Using this method, you log in directly to Connect using the URL to the Connect dashboard page.

To log in to Connect, do the following:

2. When prompted, enter your email address and click Continue.

1. After the Welcome to JFrog page appears, enter your Username and Password, and click Login.

The JFrog Connect dashboard page appears and you can start working in your Connect account.

What’s Next?

Once you understand the possibilities, you can choose the procedure that is right for you.

Connect Device Registration Algorithm

Therefore, a method for registering devices at scale must include:

• Obtaining the Connect Agent, for example, one of the following:

  • Register a single device from the web UI

  • Obtain the Connect Agent binary from JFrog Connect Support

• Creating an image for duplication, for example:

  • Freeze an image of a registered device

  • Build a Linux-based image that includes the Connect Agent binary

For the sake of simplicity, we describe two methods for registering large numbers of devices at a time that incorporate the above requirements. You can choose the method that is suitable for you.

Freeze Image on Device

In this method, you register a single device and then take a freeze of the OS image to copy to other devices. This method is advantageous if you have a real device with internet connectivity and the OS of that device is exactly what you want on all other devices.

This procedure consists of the following major steps:

2. Take a freeze of the OS image on the device.

3. Burn the image on SD cards or eMMC flashes.

Build Image with Agent

This method is suitable if you would like to build a custom image that includes the Connect Agent. For example, you may want to create an image that includes your off-the-shelf Linux-based OS, some applications that will run on the device, and the Connect Agent. As another example, you want to build a completely customized Linux- based OS for your IoT device and include the Connect Agent. You can create this image in a lab environment, i.e., on your PC, and an actual IoT device is not required.

This procedure consists of the following major steps.

1. Get a copy of the Connect Agent on your PC. (To obtain a copy of the Connect Agent binary, contact JFrog Connect Support.)

2. Copy the Connect Agent to your OS file system.

3. Burn the image on SD cards or eMMC flashes.

What’s Next?

Learn the detailed procedures for registering devices at scale:

Prerequisites

You need the following before starting the procedure:

• Internet connectivity with the device.

Connect a Device

To register a device, complete the following steps:

1. The Project-Device pairing token will be linked to the project that is in the main filter. In the Connect web UI, go to the project filter and choose the project to which the device will be paired.

1. In the Connect web UI, click Register Device on the top right.

2. In the Device Registration popup, choose whether the wget command should run as a root or non-root user on your device.

1. Generate the project-device pairing token.

2. (Optional) Enter values for the optional parameters. If you do not enter the values now, you can enter them later in the Devices page of the web UI.

1. Review the command generated at the bottom and copy it to your clipboard.

2. Open the command line terminal on your device, paste the command from your clipboard, and run it.

Optional Parameters

In Step 4 above, you can enter values for the optional parameters listed below. If you do not set them in the registration command, you can set them in the Devices page of the UI after the registration has been completed.

• Device Name: Sets a device name when the device is registered. If you don’t enter a device name, the device will be given the default name New Device followed by a number, for example, New Device 14.

• Group: Assigns the device to a specific group at registration time. The group must exist already.

• Application Name: The Connect Agent will be called the name that you enter.

• Application Version: If you entered an application name, you must also enter a version.

Troubleshooting

After you enter the registration command, you may need to wait several seconds until the new device appears on the Devices page. If the device does not appear, try the steps below.

1. Check the network connection of your device.

2. Ensure that systemd or SysV is installed.

3. If you are using SysV, ensure that the systemd directory does not exist: /etc/systemd/system.

4. Run the installation command as a root user.

What’s Next?

Step 1: Create a Project

To create a project, click the Project filter on the top left bar, and do the following:

1. In the dropdown menu, choose +Add Project.

1. Enter the following:

   • Project Name: A name for the project that is alphanumeric and does not contain spaces.

   • Project Key: A unique string that identifies your project. The project key can be used to group together objects that belong to the same project, for example, in the audit log. Starting with a letter, the project key is lowercase alphanumeric and has 2 to 32 characters.

Step 2: Configure the Project

When Connect creates a project, the project has default values. You can change these at any time.

• Device Locations: A new project will not have any devices assigned to it. However, when a device registers to the project, its location is set automatically by geolocation using the public IP address of that device. To reset the location using the current IP address, click Refresh Location.

Step 3: Add Users and Devices

To start populating your new project, you need to add some users. You can define Project Permissions which are project specific, so for example, you can create users who can see only this project, and not others. Likewise, you can make your new project invisible to some other users in your account.

To add users, go to the procedure in Add User to New Project.

There are several options for adding devices to the new project:

What’s Next?

Learn how to add users to a new project.

This method is suitable for off-the-shelf and custom linux-based operating systems. This procedure uses Yocto OS as an example, but it is applicable to other OS’s as well.

Prerequisites

You need the following before starting the procedure:

• Internet connectivity with the devices

OS Image Requirements

The requirements and parameters specifically for Yocto are shown below.

• Systemd or init.d and Cron. It is recommended to use Systemd: DISTRO_FEATURES_append = " systemd" VIRTUAL-RUNTIME_init_manager = "systemd" DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit" VIRTUAL-RUNTIME_initscripts = ""

• OpenSSH: CORE_IMAGE_EXTRA_INSTALL_append = " openssh"

For other operating systems, the requirements are similar:

• Systemd or init.d (systemd is recommended)

• Cron

• OpenSSH

Step 1: Obtain Connect Agent Binary

To obtain the Connect Agent binary file, contact JFrog Connect Support.

Step 2: Prepare Settings File

Using Connect Agent 7.0

1. Open the file connect/service/settings.json

2. Fill in the value for <pairing_token>. To find this, go to the Devices page and click Register Device. Below is an example of a settings.json file with the values filled in. {"pairing_token":"the-pairing-token", "device_name":"","device_group":"", "software_version":"", "device_token":""}

3. Save the file.

4. Copy the following files and folders to your OS (i.e., Yocto) file system:

   • /connect/ folder to /etc/

   • connect.service file to /etc/systemd/system/

   • connect.service file to /etc/systemd/system/multi-user.target.wants/

Using Connect Agent 6.x or Lower

1. Open the file connect/service/settings.json

2. Fill in the values for <user_token> and <project_name>. To find these, go to the Devices page and click Register Device. Below is an example of a settings.json file with the values filled in. {"user_token":"YourUserTokenXxxxyyyy","project_name":"Demo","device_name":"","device_group":"","software_version":"","device_token":""}

3. (Optional) If you leave the values of <device_name> and <device_group> blank, by default the devices will register with the generated name "New Device" and group "Production". However, you could set the value of <device_name> to “$HOSTNAME” or to some other variable. Then the device name that appears in the web UI will be the host name of each device (or a different name depending on the variable you use for the <device_name> value).

4. Save the file.

5. Copy the following files and folders to your OS (i.e., Yocto) file system:

   • /connect/ folder to /etc/

   • connect.service file to /etc/systemd/system/.

   • connect.service file to /etc/systemd/system/multi-user.target.wants/

Step 3: Duplicate and Distribute Image

1. Duplicate the OS image and burn it on your SD cards or eMMC flashes.

2. Boot the new devices that have the duplicated image. Connect Agent will automatically recognize that it is running on new hardware and will register the device as a new device.

What’s Next?

Once you have more than a few devices in your fleet, you need a way to segment the fleet into manageable subsets of devices. This becomes even more important when your fleet numbers in the hundreds, thousands, or even hundreds of thousands of devices.

Typically, you will want to distinguish between different sets of devices such as Testing and Production. In addition, there could be many other ways you need to separate between devices, such as different:

• Geographical and physical locations

• Departments and organizational divisions

• Hardware devices (e.g., cameras vs. robots)

• Hardware versions

• Operating systems

• Software applications and versions

Projects

The Project is the highest organizational level in a Connect account. An account must have at least one project. The first project is defined by default when you create an account. Once the account is created, you can create additional projects.

Each project is an entirely separate environment that enables you to differentiate between users and devices that belong to a different product or use case. Therefore, each project has its own settings and properties. For example, a project can have its own users, permissions, and subgroups of devices which are completely separate from other projects in your account. You can view the project settings in the Project tab of the Settings page.

Some typical uses of projects could be:

• A business that has facilities in different locations. Each location has its own project, as different people need access to the devices in those locations.

• Two different teams working on two different solutions. They would use the same Connect account, but be separated into two separate projects.

Manage Projects

Groups

Within a project, you can divide the devices into groups. All of the groups within a project have the same project configuration, but they are made up of different devices. A typical example would be groups that distinguish between different stages of a project, such as development, staging, and production.

When you register a new device, it is assigned by default to the Production group. If you already have additional group names defined, you can set the desired group for a device using a flag when you run the Registration command.

Devices can be assigned to groups using either the web UI or the Connect API.

Hierarchies

You can always create a new group in your project. In addition, you can create groups with a group. This enables you to create hierarchies that suit your business needs. Although there is no limit to the number of levels you can create in your group hierarchy, we recommend planning this carefully so that your structure does not go too deep. A flatter hierarchy structure makes it easier to remember where your devices are in the organization.

Manage Groups

Tags

A tag is a user-defined parameter that enables you to identify devices with unique attributes. Tags provide an additional way that you can group devices. In particular, tags enable you to associate devices that belong to different groups. The following are some examples of how you might use tags.

• You create a tag called Staging to indicate that a certain device is used for testing only.

• You create a tag called headless, which indicates that the device does not have a monitor connected to it. You might have a small number of Headless devices existing in several groups.

• You create a tag called new-gen, which you use to mark all devices that use a newer generation of hardware or software.

When you have tagged devices, you can then use the tag as a filter to select only certain devices. This enables you to perform numerous actions on a set of tagged devices such as updating software, stopping, starting, rebooting, and others.

Applications

You can use the Application feature to define Application names on sets of binaries that are deployed to the edge devices. This is, in effect, another way of grouping devices in your fleet. For example, all devices having Application X makes up a subset of devices that you can query on and perform various actions on. Like tags, applications returned in your searches could belong to a subset of devices in a group, or might belong to devices in different groups.

What’s Next?

Learn more about:

When you move a device, the following information is moved with it: device name, MAC address, IP address, location, description, device OS, UUID, and application name and version. Other information that is associated with the specific project, such as tags, monitoring, alerts, deployments, and deployment history, will not be moved with the device. Any tags, monitoring, or alerts required will have to be configured in the new project.

Prerequisites

• You have the following Project Permission in your current project and in the destination project: Register new devices and Move devices to other projects.

Step 1: Set Filter

Before you choose specific devices to move, you need to set the main device filter to display devices in the relevant segment of your fleet.

Step 2: Choose Devices and Move

To choose your devices and move them, do the following:

1. On the left side of the Devices table, mark the checkboxes next to the devices that will be moved. You can use the checkbox at the top of the column to mark all or unmark all of the devices.

1. Click Move to Project.

1. In Move Devices to Another Project, choose the parameters below and apply them.

   • Destination Project: The name of the project to which you are moving the device(s). The dropdown list will display only the projects in your account where you have permission to register devices.

   • Destination Group: The name of the group in the destination project where you are moving the devices.

After you have applied the move, you can switch to the other project and see that the devices appear in the Devices table. If you do not see them, you can search for them in the Search bar or apply a different filter to the Devices table.

What’s Next?

You can add many devices to a group at once (i.e., add devices in bulk). You can also use this procedure as a quick way to add a single device to a group.

To add devices to a group, do the following:

1. Go to the Devices page and mark the devices to add to a group. You can mark all the devices in view by marking the checkbox at the top of the column.

1. At the bottom of the Devices page, click Assign Group.

1. In the Assign Group popup, select the group for your devices and apply.

What’s Next?

If you don’t need a group any more, you can delete it. To delete a group, do the following:

1. Go to the Project tab in Settings and choose a group from the list of group names.

2. Click Delete.

1. If there are any devices in the group you have chosen, they will be deleted with the group unless you move them. This is your last opportunity to move them. To keep the devices, choose a group from the list and click Move Devices. If you intend to delete the devices along with the group, just delete the group.

What’s Next?

Once you have created a group, you can add devices to it. The procedure below describes a quick way to add a device to a group when you are viewing or editing device details.

1. Go to the Devices page and click the name of a device in the list.

2. In the General Details of the device, click Edit.

1. Choose a group from the list and save.

What’s Next?

Your default project that is created when your JFrog Connect account is created contains two default groups, Test and Production. You can change the names of these, create additional groups, and create subgroups within groups.

Create a Group

1. Go to the Project tab in Settings and click the Add (+) icon.

1. Enter a name for the group.

1. Choose the position of the group in your hierarchy. For example, choose Main Hierarchy if you want the new group to be at the top level. If you choose a different item in the dropdown list, the new group will be at the next level under that item.

What’s Next?

In JFrog Connect, you can change the name of an existing group at any time. To change a group name, do the following:

1. Go to the Project tab in Settings and choose a group from the list of group names.

1. Click Edit, enter your new name, and save.

What’s Next?

In JFrog Connect, you can remove tags from any edge device that has been tagged.

To remove a tag from one or more devices, do the following:

1. In the Devices page, mark the checkboxes next to the relevant devices. You can use the checkbox at the top of the column to mark all or unmark all of the devices.

1. Click Edit Tags.

1. In Remove Tags, choose one or more tags to remove from the devices you chose. If you don’t see the tag in the list, enter the first few letters of the tag name and then it should appear. Apply your changes.

Delete a Tag

To delete a tag entirely, remove the tag from all devices with that tag. Once the tag is removed from the last device, it is deleted from the database.

What’s New?

You can use tags to mark one or more devices within a group or mark devices that belong to different groups. Once you have tagged some devices, you can filter on the tag name in order to view and perform actions on the tagged devices only.

Connect provides a high degree of flexibility in tagging. There is no limit to the number of tags you can create or the number of tags a device can have. In addition, Connect enables you to tag several devices at once, without limit.

To tag one or multiple devices, do the following:

1. On the left side of the Devices table, mark the checkboxes next to the devices that will be tagged. You can use the checkbox at the top of the column to mark all or unmark all of the devices.

1. Click Edit Tags.

1. In Add Tags, enter the name of one or more tags. If a tag already exists, you can enter the first few letters and then choose the name that appears in the list. Apply your changes.

What’s New?

Remove Devices by Deleting Group

To remove bulk devices by deleting a group, do the following:

Remove Devices by Deleting Project

To remove bulk devices by deleting a project, do the following:

What’s Next?

Dashboard View

The Overview page provides a dashboard view of your fleet. To see the dashboard view, go to Overview at the top of the left navigation tree.

Product Fleet

The Product Fleet panel displays the number of devices online and offline and the total number of devices. If you click the panel, the Devices page will display.

Live Alerts

To see the actual alerts triggered, click on any of the numbers in the panel. The Alerts page will display showing the Triggered Alerts tab.

Notifications

Application Versions

Device Registration

Map

What’s Next?

When a device registers to JFrog Connect, the Google Maps geolocation service uses the device’s public IP address to assign it a location. This location is an estimate and might not be exact. This page describes how you can view devices on a map in JFrog Connect’s web UI and different methods to change the device location.

View Devices on Map

Viewing devices on the map is not available to on-prem customers.

You can adjust the position and magnification of the map to see all of the devices in the map.

Locate Device on the Map

If you know the device name, you can use the map to find the location of a device. Just choose the device name in the dropdown list, and the map will focus on that device and display its details.

Change Device Location

The different ways to change a device's location are described below.

Manual Location

To change a device’s location manually, do the following:

1. Go to Devices in the left navigation tree and select the device you need to change.

1. Choose Manual Location.

1. Enter the new location and save.

Refresh Location

You can refresh the locations of your devices for the whole project or for any subset of the project. However, the refresh function does not act on any device that has Manual Location configured.

To refresh devices, do the following:

1. Go to Settings in the left navigation tree and choose the Project tab.

2. Choose Refresh Location.

1. Select the devices to be refreshed and click Next.

2. Review the information in the summary and if it is correct, run the refresh.

What’s Next?

Removing a device completely from your fleet in JFrog Connect requires the following procedures:

1. Uninstall Connect Agent from Device

2. Delete Device from Connect Server

In both steps, which are described below, ensure that the device chosen is the device you intend to remove.

Step 1: Uninstall Connect Agent from Device

systemctl disable upswift --now 2>/dev/null ; systemctl disable connect --now 2>/dev/null ; rm -rf /etc/upswift/ /etc/connect/ /etc/system/systemd/upswift.service /etc/system/systemd/connect.service 2>/dev/null ;

Step 2: Delete Device from Connect Server

To delete a device from the Connect server, do the following:

1. In General Details, review the information to ensure that this is the device you want to delete, and click Edit.

1. Click Delete. If you are sure that you want to delete this device, click Delete Device in the confirmation popup.

What’s Next?

List of Devices

To view a list of devices and details about each device, go to the Devices page. The devices appearing in the list are according to the passive filter set at the top. If you do not see the device you are looking for, you can try the following:

• Change the passive filter.

• Page through the list using the arrows below the list.

• Use the Search bar to search by ID, name, group, application, tag, description, or MAC address.

Device Details

To drill down into the detailed device information, click a device in the table of devices and a side panel will appear. The side panel shows information about the device and in some cases, enables you to edit information or run commands:

• Technical Details: Shows a list of the IP Address, Hostname, OS, Node Name, Kernel Release, Kernel Version, Hardware, System Information, and MAC Addresses.

• Monitoring Information: Lists the processes monitored and shows basic parameters such as CPU, RAM, and disk space used on the device.

• Log Details: Provides information about the Update History.

• Application Details: Enables you to configure a new application on the device or edit an existing one.

• Alerts: Shows a shortlist of the latest alerts. You can also click Alerts and go to the full list.

• Commands: Run commands directly on the device.

Edit Device Details

You can change some of the general configuration settings of the device. In General Details, click Edit.

• Name: Change the name of the device.

• Group: Choose a group name from the list. This will cause the device to belong to a different group.

• Description: Enter a brief description of the device or change the existing description.

• Update Trigger: This creates a flag that determines if the device is available to receive updates. When the trigger is On, the device cannot receive updates. The device can receive updates only when the switch is turned Off.

Location

Choose the method by which the device location is determined:

• Automatic Location: Google Maps geolocation determines the location of the device based on the device’s public IP address. The location could change if you refresh locations.

• Manual Location: The device location is the location that you enter manually in this field. Google Maps validates the location when you enter it, and then it will not change if you run a refresh.

Save

After making your edits to the General Details, click Save.

What’s Next?

JFrog Connect provides two kinds of filters, Passive and Active, that give you full control of device data you want to display and specific devices you want to perform actions on. The filters are described in detail below.

Passive Filter Bar

Projects

You can choose the project, group, and any subgroups to be included in the filter criteria. In the project list, you will see only the projects that you have permission to see. If you are an admin, you will see all the projects in the account. The filter includes devices in a single project only, and does not act across projects.

Groups

Within a project, you can filter on any of the groups in the hierarchy.

• All Groups: The default at the top level is All Groups. This means that the devices included will be from all groups at this level any subgroups that you choose. Alternatively, you can choose a specific group at that level, for example, Group-A, as shown in the illustration below.

• All Hierarchies: This appears by default to the right of any group you choose. All Hierarchies means all subgroups within the group you chose. To include only a specific group, click All Hierarchies and the desired group in the list.

• Additional Group: Whenever you have chosen a specific group, you can choose an additional group on the same level by clicking Additional Group.

Additional Filters

You can use Additional Filters to pull out any subset of devices, including the following.

• Specific Device: Use this filter to view data of a specific device. When you choose this filter, all devices from the selected project and groups will be displayed as possible values in the search input. You can select only one specific device in a filter.

• Tag: Use this filter to view data of devices with a certain tag. You can filter on multiple tags. When you choose more than one tag, only data of devices that have ALL of the chosen tags will be shown (i.e., AND, not OR).

• Application: Use this filter to view data of devices having the selected app. You can specify the app version or Any to select all versions. Keep in mind that you can select only one application per filter.

• Device State: Use this filter to view data of devices that are currently online or offline.

• Deployment: Use this filter to view the data of devices that are part of the selected deployment with the chosen status. You can select only one deployment status for each deployment.

To create an Additional Filter:

1. Choose a filter from the list.

1. Complete the criteria statement with an is or is not operator and a target value, and apply.

You can add more filters if necessary. Below is an example of a filter with multiple criteria.

Active Filter Bar

Use the Active Filter bar whenever you perform an action on the devices. For example, you use the Active Filter when you create alerts or deploy software updates. The filter appears wherever you see the Select Devices button.

The Active Filter looks just like the Passive Filter and behaves the same way. The default values in the Active Filter are the values in your Passive Filter.

Total Affected Devices

Once you have selected your devices in the filter, you will see a summary indicating the total number of devices to be affected by the action and the applied filter. If this is not what you expected, you can go back and change your filter. Otherwise, click Finish, and the task will be performed on the devices.

The total affected device number that is shown might be different than the actual number of devices that receive the task. The devices that actually receive the task will be filtered at the time you run the task, which might be a few seconds or minutes after you select the filter attributes. (For example, some devices could change status during that time.)

Active Filter is Different from Passive Filter

If you have specified an active filter that is different from the passive filter, you might not see the results of your action in the Connect pages that use the passive filter, for example, data for all the relevant devices might not appear in the Overview, Devices, and Updates pages. To see the full results of the task you performed, change the passive filter to include all of the devices specified in your active filter.

What’s Next?

To create an Update Flow, do the following:

1. In the Connect web UI, go to Deployment in the left menu and click the Create Update Flow tab.

1. Add a Flow Name, e.g., update-docker-image.

2. Drag and drop the actions you need in the flow and complete the configuration for each action. To configure an action, click on it in the flow column.

3. To reboot the device after all the actions have run, mark Reboot after Update.

4. To configure a general rollback in case of failure, click Rollback.

5. Click Create Flow and then go to the Update Flows tab to view it in the list of flows.

What’s Next?

This section describes in detail each update flow action and provides examples so that you can get the most out of any update flow you create.

What’s Next?

From time to time a new version of the Connect Agent will become available. The Connect Agent updates ensure that IoT devices are running the latest JFrog software and are able to communicate with the JFrog platform effectively.

The new agent version is not deployed automatically. When a new version is available, the "Deploy latest agent update" button appears under the Agent Update tab. You can initiate an OTA update process at your convenience to update the agents on your connected devices, and you can choose which devices receive the update. The button will remain available until you have updated all devices in the project.

To update the Connect Agent version on your devices, do the following:

1. Go to Deployment in the left menus and click the Update Agent tab.

1. Click Deploy latest agent update.

2. In Select Devices, choose the relevant Groups of devices and apply any Additional Filters required. Click Next and run the update.

Once you have run the update flow, you can view the status of the agent updates

Once the update flow has completed, the display will indicate the number of devices that succeeded or failed to update the agent.

What’s Next?

The JFrog Connect Agent runs as a systemd service. Therefore, system environment variables are not reachable by the agent and cannot be used with Connect tools such as Remote Commands.

To make the environment variables reachable by the Connect Agent, you can load a file containing the variables to the agent’s service configuration. Once the file is loaded, you can use environment variables in Connect tools.

To load your environment variables to the Connect Agent, do the following:

1. Create the file: /etc/environment

2. Place your environment variables at the end of the file. For example:

1. Open the file /etc/systemd/system/connect.service, and right above the line that begins with ExecStart, enter the line:

1. Save and close the file. Execute the command:

1. Execute the command:

Once you have completed the steps above, any environment variable written inside the file /etc/environment, will be accessible from Connect tools.

File Modifications

If you modify the file /etc/environment, you will need to restart the Connect service for the changes to take effect. This includes adding, deleting or changing variables, and changing any values of the variables.

Delete Devices by Deleting Group

To remove bulk devices by deleting a group, do the following:

2. Uninstall the Connect Agent from each of the devices. This requires the following steps:

   1. Create a new update flow that uses the Run Command action. In the Command field, enter the command below: systemctl disable upswift --now 2>/dev/null ; systemctl disable connect --now 2>/dev/null ; rm -rf /etc/upswift/ /etc/connect/ /etc/system/systemd/upswift.service /etc/system/systemd/connect.service 2>/dev/null ;

   2. Deploy the update flow. When you select devices in the deployment creation, choose the Group that you created in Step 1. After the deployment is completed successfully on all the devices in the group, continue to the next step.

Delete Devices by Deleting Project

To remove bulk devices by deleting a project, do the following:

2. Uninstall the Connect Agent from the devices. You can use the same update flow and command as in Step 2 above. However, when you create the deployment and select devices, choose All Groups in the project. After the deployment is completed successfully, continue to the next step.

What’s Next?

JFrog Connect provides different methods for you to control the timing of software updates, including the following:

• Block or allow software updates to a single device by setting the update trigger in the Connect UI.

• Use the Update Trigger API to create update windows and update blocking windows for device groups in your fleet.

Set Update Trigger

The Update Trigger creates a device-based server flag that determines whether or not the edge device is available for updates. The On status indicates that the device will not receive updates. In the Off status (Connect’s default), the device can receive updates.

To block updates to a specific device, do the following:

1. Go to Devices in the left sidebar and click a device in the table of devices. If the device you want does not appear in the table, use the search box to find it.

1. Scroll down to the General Details panel and click Edit.

1. Click Update Trigger and Save.

Create an Update Window

When you deploy OTA updates to edge devices, there may be time periods when it is inappropriate or risky to send new updates. If, for instance, your device is in use by the end-user, a new update at that time might interfere with the user experience. Using the Update Trigger API call, you can manage from within your application when the device can receive updates, and when it can’t.

After setting the update trigger, your device will not receive new updates until you or your application unsets the trigger. By setting and unsetting the trigger at various times, you can create update windows that allow updates only during specific periods of time.

Example Use Case

A sample use case is a fleet of kiosk screen devices that are in use throughout the day, but are not used during the night. When the app is out of use, it goes into standby mode and comes out of standby upon first use in the morning.

When the app comes out of standby, it uses the Update Trigger API call to set the update trigger to On, so that it will not receive updates. When it goes to sleep again, the app unsets the update trigger so that it can receive updates while in standby mode. In effect, this creates an update window in which updates are allowed, and a blocking window in which the device will not accept updates.

For this use case to work, the Update Trigger API call would be used in the code of the kiosk app.

What’s Next?

The Run Command action is useful for performing a variety of actions on the edge device. You may need the Run Command as a prerequisite to other actions, for example, to create folders on the devices before delivering files or to stop a service before delivering an update.

You might also use Run Command after other actions, for example, to run a script that was delivered in a previous action or to delete artifacts no longer used.

Although you could create a workflow with a single run command action, you may use Run Command along with other actions. A customer example below illustrates how you might use the Run Command action in an update workflow.

Example: Run Command in Update Workflow

Pull Commands

A pull command used in the Run Command action cannot be reverted. Therefore, for pulling artifacts, we recommend using one of the pull actions such as Artifacts, Deploy Container or Clone Git Repository.

Prerequisites

JFrog Connect account and at least one device registered.

Drag the Action

1. Go to Deployment in the left menu and click Create Update Flow.

2. Drag the Run Command action and drop it in the workflow.

Configure the Action

Click the action to open and configure it.

1. Enter a name for the action, for example, Unzip Files.

2. Enter the full bash command to run, including the values of any parameters required.

1. Enter the expected exit code. Success is usually 0 in Linux shell systems, but it could be different depending on the specific command or script.

3. Save your action configuration.

You can run additional commands in the update workflow by adding more actions. You can also perform other actions in the same workflow just by adding and configuring the relevant actions.

If you plan to run several commands and need to specify a logic that is more complex, you might consider using the Run Script action.

What’s Next?

The Deploy Files action enables the quick distribution of one or more files to your devices. To deliver a file, the action facilitates a two-step process:

1. You upload of the requested file to Artifactory.

2. Devices pull the file from Artifactory.

This functionality is primarily utilized for quick deployment of specific files or binaries to your devices, eliminating the necessity to upload them beforehand.

Prerequisites

• JFrog Connect and JFrog Platform accounts. (You receive a JFrog Platform account automatically when you register for a JFrog Connect account.)

• Connect Agent 6.0 or later and at least one device registered.

• One or more files ready for deployment.

Drag the Action

To include the Deploy File action in your update flow, do the following:

1. Go to Deployment in the left menu and click Create Update Flow.

2. Drag the Deploy File action and drop it in the workflow.

Configure the Action

Click the action to open and configure it.

1. Enter a name for the action.

2. Enter (drag and drop or browse) the file in the file box.

1. Enter Device Destination Path. You can also make this a variable, for example {{device-destination-path}}. You will then enter the value for the variable upon deployment.

2. If you want to deliver more than one file, create a Deploy File action for each file.

4. Save your action configuration.

What’s Next?

Prerequisites

• JFrog Connect account and at least one device registered.

• Docker and/or Docker-compose installed

• One or more Docker images in the JFrog Platform ready for deployment. If you need to push an image to the JFrog Platform, use the docker tag and docker push commands as shown below.

Drag the Action

To include the Deploy Docker action in your update flow, do the following:

1. Go to Deployment in the left menu and click Create Update Flow.

2. Drag the Deploy Docker action and drop it in the workflow.

Configure the Action

Click the action to open and configure it.

1. Enter a name for the action.

Artifactory Edge

On Failure

After you have completed the configuration, click On Failure to configure your failure policy. Upon failure, the default Do Action is Revert Docker Compose File. This means that if the action or update fails, the rollback will revert to the Docker Compose file of the last successfully running application.

What’s Next?

The procedure describes how you get the following parameters from Artifactory:

• Image Path

• Image Tag

To get the image path and tag, do the following:

1. In the left navigation pane of JFrog Connect, choose JFrog Platform.

1. In the left navigation pane of JFrog Platform, choose Artifactory and Packages.

1. In Artifactory, choose your Docker package from the list of Docker packages.

1. In the Versions table, choose your version.

1. In the Version page, take the part from the platform URL up to the colon and enter it as the Image Path in the Deploy Docker configuration in Connect.

1. Take the text after the colon and enter it as the Image Tag.

Now you can complete the rest of your Deploy Docker action configuration in Connect and save it.

Connect enables you to deploy multiple containers by using Docker Compose capabilities. When you choose Docker Compose as your Deployment Type, JFrog Connect will upload the corresponding YAML file to Artifactory, and the edge device will pull it during the update.

The recommended approach to managing containers on edge devices is to use Docker Compose.

Prerequisites

• JFrog Platform Account. (You receive an account with JFrog Platform automatically when you register for a JFrog Connect account.)

• Connect Agent 6.0 or later on device(s).

• Docker and Docker Compose installed on your device(s).

• A Docker Compose configuration file located in Artifactory.

Configure Docker Compose Options

1. Enter the source of your Docker Compose YAML file, which may be one of the following, depending on the registry you chose.

1. Enter the path where the Docker Compose YAML file should be placed on the IoT device. The folder must already exist on this path or the update will fail. (You can create a folder using the Run Command action block.)

Configure On Failure Options

On Failure enables you to define what happens upon failure of the Deploy Container action. By default, when the action fails the Docker Compose file is automatically reverted, and everything is restored to its previous state.

Failures that are caused by container logic (e.g., Command fails or Invalid image architecture) are handled by the Docker Compose binary and are not regarded as an action failure.

Complete the Configuration

Save your action configuration.

If you are adding more actions to the workflow, continue to the next one. Otherwise, complete your workflow configuration and save it.

What’s Next?

Connect's Update Flow enables your edge devices to clone from a Git repository whether you are using a public Git repository or your own private repository for your code.

When you use the Clone Git Repository action, the edge devices will use the git clone command to pull your Git repo.

Prerequisites

• JFrog Connect account.

Drag the Action

To include the Clone Git Repository action in your update flow, do the following:

1. Go to Deployment in the left menu and click Create Update Flow.

2. Drag the Clone Git Repository action and drop it in the workflow.

Configure the Action

Click the action to open and configure it.

1. Enter a name for the action.

1. Git Repository URL: Enter the URL of the Git, for example, https://github.com/jfrog-connect/app-repo.git.

2. Device Destination Path: Enter the path where the Git will be installed on the device, for example, /home/user/App.

1. Configure your On Failure policy and instructions for rolling back, if necessary.

2. Save your action configuration.

On Failure and Rollback

• Continue Update Flow: If the Clone Git Repository action fails, Connect will simply continue with the next action in the update workflow.

• Run General Rollback: The action and the entire update workflow are rolled back.

As a general precaution, Connect Agent creates a backup of the relevant device folder in a temporary location. If a rollback is required, the agent restores the folder to its initial state.

Free Memory Requirement

To enable Rollback functionality, your device's free memory must be greater than the update size. Use the relationship below to calculate the amount of free memory required.

Free Memory Required > Current Folder Size + Update Size + 10MB

What’s Next?

Create an update flow that uses the Deploy Container action. When you select the Docker Image option, you will be able to pull a container image directly from a repository, whether it is public or your own private repository.

Prerequisites

Configure Docker Options Options

1. Enter the source of your Docker image, which may be one of the following, depending on the registry you chose.

2. Enter the Image Tag.

Add Run Options

1. Click Add Run Options to enter the run flag information.

2. Choose a command from the list and then enter the run flag. These are the same flags used in the docker run command.

3. Click Add (+) if you want to enter an additional run flag. You can run as many as you want.

Command

The Docker run command structure uses official docker commands, but in a structured manner.

To add the command to run in the Docker image, remove all parts except for [COMMAND] [ARG…]

For example, in the following CLI deployment:

the command will be: echo hello world

For [OPTIONS] use the Docker Run flags.

Delete Previous Image

Mark the checkbox to delete the current image after the new Docker image has been deployed. (This is the default setting.)

Configure On Failure Options

On Failure enables you to define what happens upon failure of the Deploy Docker action. By default, the first Docker image is stopped, and if the action fails, the new image is deleted and the previous image will start running once again. This returns everything to the previous state.

Failures that are caused by container logic (e.g., Command fails or Invalid image architecture) are handled by the Docker Compose binary and are not regarded as an action failure.

Complete the Configuration

Save your action configuration.

If you are adding more actions to the workflow, continue to the next one. Otherwise, complete your workflow configuration and save it.

What’s Next?

You might have several reasons to use the Run Script action, such as preparing the edge devices for installing a new software version or doing some special tasks after a version has been received. You may also have scripts that help to resolve issues in a software version that is running on the device.

Exit codes are utilized to confirm the successful execution of a script and ensure that the procedure completed without encountering any errors.

Example: Update Binaries on Device

Prerequisites

• JFrog Connect account and at least one device registered.

• A script file ready for deployment.

Drag the Action

To include the Run Script action in your update flow, do the following:

1. Go to Deployment in the left menu and click Create Update Flow.

2. Drag the Run Script action and drop it in the workflow.

Configure the Action

Click the action to open and configure it.

1. Enter a name for the action.

2. Enter (drag and drop or browse) the script file in the script box.

1. Enter the following:

   • Binary Path: The path on the device where the script should run.

   • Script Arguments: The values required for script arguments.

   • Expected Exit Code: Success is usually 0 in Linux shell systems, but it could be different depending on the specific command or script.

2. Save your action configuration.

You can run additional actions in the workflow.

What’s Next?

This page describes how you get some of the configuration parameters when you use the Download Release Bundle update flow action in JFrog Connect.

The procedure describes how you get the following parameters from Artifactory:

• Name

• Version

The procedures are different for Release Bundles v1 and v2. Both procedures are detailed below.

To get to Artifactory from Connect:

• Go to the left navigation pane and choose JFrog Platform.

Release Bundle v1

To get the configuration parameters for a release bundle v1:

1. In the left navigation pane of JFrog Platform, choose Distribution, and then choose Release Bundles.

1. In the Release Bundles table, take the name of your release bundle from the Name column and take its version from the Latest Version column. Enter these as the Name and Version in the Download Release Bundle action in Connect.

Now you can complete the rest of your Download Release Bundle action configuration in Connect and save it.

Release Bundle v2

To get the configuration parameters for a release bundle v2:

1. In the left navigation pane of JFrog Platform, choose Artifactory and Release Lifecycle.

1. In the Release Bundles table, take the name of your release bundle from the Name column and take its version from the Latest Version column. Enter these as the Name and Version in the Download Release Bundle action in Connect.

Now you can complete the rest of your Download Release Bundle action configuration in Connect and save it.

This page describes how you get the Artifactory Path that you need to configure an update flow action in JFrog Connect.

The procedure is applicable to the following update flow actions:

To get the Artifactory path, do the following:

1. In the left navigation pane of JFrog Connect, choose JFrog Platform.

1. In the left navigation pane of JFrog Platform, choose Artifactory and Artifacts.

2. In the General Info, copy the Repository Path to the clipboard.

1. Go to your Download Artifact action configuration in Connect (or any action where you need an Artifactory Path). Paste the Repository Path (already on the clipboard) into the Artifactory Path field.

Now you can complete the rest of your update flow action configuration in Connect and save it.

This document describes how to configure the Install Debian Package action and integrate it into your update flows.

Prerequisites

• At least one device registered with JFrog Connect.

• A local Artifactory repository. Connect does not support remote repositories.

• If you are using JFrog as your registry, Artifactory Project and Artifactory Environment must be set to All in the JFrog Registry Scope.

Drag the Action

To include the Install Debian Package action in your update flow, do the following:

1. Go to Deployment in the left menu bar and click Create Update Flow.

2. Drag the Install Debian Package action and drop it in the workflow.

Configure the Action

To configure the action, click on it and do the following:

1. Enter a name for the action.

1. Complete the following mandatory information:

   • Distribution: The appropriate Debian distribution for your target devices (e.g., Debian Buster, Debian Bullseye, Ubuntu Noble, Ubuntu Jammy).

   • Component: The component (e.g., main, universe, contrib) from which to install the package.

1. Set as Persistent Repository: Mark this box to add the JFrog Repository to the device system's list of available sources. When unmarked, the JFrog Repository will be removed right after the package installation.

2. Packages: Enter the Name and Version of the package. If you leave Version blank, the latest version of the package will be installed. If you want to install more than one package, click Add (+). Add an additional row for each additional package.

1. Update Command Options: The apt or apt-get command will be run on the device according to the Linux version. You can add options to tailor the update command to your needs.

2. Fix Broken: Check this box to run the apt or apt-get command with the --fix-broken option. This can be useful for resolving dependency issues during package installation.

3. Install Command Options: The apt or apt-get command will be run on the device according to the Linux version. You can add options to tailor the install command to your needs. The -y option (equivalent to --yes or --assume-yes) is set automatically. You can use any of the options supported by the apt package installer.

4. Command (View Only): This section displays the final command that will be executed on the target device. The command is generated based on the configuration options you have provided. Review this command to ensure it is correct before deploying the update flow.

Configure On Failure Policy

1. Configure your On Failure policy and instructions for rolling back, should a rollback be necessary.

2. Save your action configuration.

What’s Next?

JFrog Connect supports Release Bundles v1 and v2.

Download Release Bundle Action

The Download Release Bundle action enables you to deploy a versioned package of software artifacts to your edge devices. In addition, a release bundle has the ability to deploy Docker images using the Docker Compose engine.

Prerequisites

• Connect Agent 6.0 or later and at least one device registered.

• A release bundle that is ready for deployment.

Drag the Action

To include the Download Release Bundle action in your update flow, do the following:

1. Go to Deployment in the left menu and click Create Update Flow..

2. Drag the Download Release Bundle action and drop it in the workflow.

Configure the Action

Click the action to open and configure it.

1. Enter a name for the action.

1. Enter a Name for your release bundle and the Version of the release bundle that you used in Artifactory.

1. Enter the Device Destination Path. This is where the release bundle will be installed on the edge devices. The directory on the device must exist beforehand, otherwise, the update will fail. Connect does not automatically create directories when deploying updates. You may create a folder using the Run Command action in the General Section.

2. (Optional) If you have one or more files in your release bundle that need to go to different paths on the edge device, mark Release Bundle Artifact Path. Then specify the Release Bundle Path and the Device Destination Path for each file.

1. (Optional) If your release bundle includes Docker images, mark Docker Compose, then specify the Release Bundle Path and the Device Destination Path for the Docker Compose YAML file.

1. Configure your On Failure policy and instructions for rolling back, if necessary.

2. Save your action configuration.

Artifactory Edge

On Failure and Rollback

• Continue Update Flow: If the Download Release Bundle action fails, Connect will simply continue with the next action block in the update workflow.

• Run General Rollback: The action and the entire update workflow are rolled back.

• Do Action: The action to do when this action is rolled back. In this case, the action is to revert all files.

Revert all Files

As a general precaution, Connect Agent creates a backup of the relevant device folder in a temporary location. If a rollback is required, the agent restores the folder to its initial state.

Free Memory Requirement

In order to enable Rollback functionality, your device's free memory must be greater than the update size. To calculate the amount of free memory required, use the relationship below:

Free Memory Required > Current Folder Size + Update Size + 10MB

What’s Next?

The Download Artifact action enables you to create a workflow that pulls artifacts from your Artifactory instance and deploys them to your edge devices. You can one or multiple artifact actions in an update flow.

Deployments using Artifactory consider the checksums of the files delivered. Therefore, the devices will pull only the diffs when downloading updates to files.

Prerequisites

• JFrog Connect and JFrog Platform accounts. (You receive a JFrog Platform account automatically when you register for a JFrog Connect account.)

• Connect Agent 6.0 or later and at least one device registered.

• One or more files ready for deployment and stored in your Artifactory repository.

Drag the Action

To include the Download Artifact action in your update flow, do the following:

1. Go to Deployment in the left menu and click Create Update Flow.

2. Drag the Download Artifact action and drop it in the workflow.

Configure the Action

Click the action to open and configure it.

1. Enter a name for the action.

1. Enter the Artifactory Path, for example, generic-repo/1.0/file.txt. You can also make all or part of the path a parameter. For example, you could make the version folder a parameter: generic-repo/{{version}}/file.text. Then you enter the version value when the actual deployment is run.

1. If you want to deliver more than one artifact, add a new action for each artifact.

2. Enter the Device Destination Path. The directory on the device must exist beforehand, otherwise, the update will fail. Connect does not automatically create directories when deploying updates. You may create a folder using the Run Command action in the General Section.

3. Configure your On Failure policy and instructions for rolling back, if necessary.

4. Save your action configuration.

Artifactory Edge

On Failure and Rollback

• Continue Update Flow: If the Download Artifacts action fails, Connect will simply continue with the next action in the update workflow.

• Run General Rollback: The action and the entire update workflow are rolled back.

• Do Action: The action to do when this action is rolled back. In this case, the action is to revert all files.

Revert all Files

As a general precaution, Connect Agent creates a backup of the relevant device folder in a temporary location. If a rollback is required, the agent restores the folder to its initial state.

Free Memory Requirement

In order to enable Rollback functionality, your device's free memory must be greater than the update size. To calculate the amount of free memory required, use the relationship below:

Free Memory Required > Current Folder Size + Update Size + 10MB

What’s Next?

Availability: This feature is available to some customers by feature flag.

Prerequisites

• SWUpdate installed on the devices.

• SWUpdate image file (*.SWU) uploaded to the Artifactory repository. The SWU file includes the IMG file and sw-description file.

• The default upload limit in Artifactory is 100 MG. You may need to change this if your IMG file is larger.

SWUpdate File Example

The following is an example of an SWU file configured for a double-copy update.

software =
{
    version = "1.0";
    raspberrypi3 = {
        hardware-compatibility: ["1.0"];
        stable = {
            copy1 : {
                images: (
                    {
                        filename = "rootfs.img.gz";
                        sha256 = <sha256>;
                        type = "raw";
                        compressed = "zlib";
                        device = "/dev/mmcblk0p2";
                    }
                );
            };
            copy2 : {
                images: (
                    {
                        filename = "rootfs.img.gz";
                        sha256 = <sha256>;
                        type = "raw";
                        compressed = "zlib";
                        device = "/dev/mmcblk0p3";
                    }
                );
            };
        }
    }
}

• filename: The name of your compressed IMG file.

• compressed: String to indicate that the file indicated by filename is compressed and must be decompressed before being installed. The value denotes the compression type. The currently supported values are zlib and zstd.

• device: device: Device node as found in /dev or a symlink to it. This can be specified as an absolute path or a name in the /dev folder. For example, if /dev/mtd-dtb is a link to /dev/mtd3, then mtd3, mtd-dtb, /dev/mtd3, and /dev/mtd-dtb are valid names. For Raspberry Pi, the rootfs is usually /dev/mmcblck0p2. Usage depends on the handler. For files, this attribute indicates on which device the filesystem must be mounted. If not specified, the current rootfs will be used.