Skip to content

Installation (v0.4.0)

Jump to bottom
Gabriele Baldoni edited this page Mar 29, 2023 · 12 revisions

Table of contents

  1. Requirements
  2. Building
    1. From source
    2. APT
  3. Starting Zenoh-Flow
    1. Zenoh plugin
    2. Standalone daemon
  4. Interacting with Zenoh-Flow: zfctl

Requirements

The following dependencies are required:

Building

Unless you are running a Debian-based distribution of Linux, you will need to build Zenoh-Flow from source. The available APT packages are detailed after.

From source

$ git clone https://github.com/eclipse-zenoh/zenoh-flow
$ cd zenoh-flow
$ cargo build --release --all-targets

This will produce the following:

  1. zenoh-flow-daemon: (executable) the standalone Zenoh-Flow daemon.
  2. zfctl: (executable) a command line tool to interact with Zenoh-Flow daemons.
  3. zplugin_zenoh_flow: the plugin version of Zenoh-Flow that a Zenoh router can load. The actual name and extension of this artefact will change according to your operating system (e.g. libzplugin_zenoh_flow.so on a Linux machine).
  4. cargo-zenoh-flow: (executable) a command line tool to help you create your nodes by generating boilerplate code. Alternatively, you can install it through cargo, running the command: cargo install cargo-zenoh-flow --version 0.4.0-alpha.1.

If you would like to implement your nodes in Python instead (or, in addition) of Rust, you have to perform additional steps that are detailed here: https://github.com/eclipse-zenoh/zenoh-flow-python

APT

You can add the APT repository and install Zenoh-Flow directly from your packet manager.

$ echo "deb [trusted=yes] https://download.eclipse.org/zenoh/zenoh-flow/debian-repo/0.4.0-alpha.2/$(. /etc/os-release && echo "$VERSION_CODENAME") /" | sudo tee -a /etc/apt/sources.list.d/zenoh-flow.list > /dev/null
$ sudo apt update

To install all available packages you can execute:

$ sudo apt install zfctl zenoh-plugin-zenoh-flow zenoh-flow-plugin-python zenoh-plugin-storage-manager

The cargo-zenoh-flow command line tool can still be installed through cargo:

$ cargo install cargo-zenoh-flow --version 0.4.0-alpha.2

Starting Zenoh-Flow

Before we can start a Zenoh-Flow runtime we need to configure, at least, one Zenoh router in the network to store Zenoh-Flow related information.

For that, add the following JSON snippet to the router's configuration under the storage_manager plugin section:

"storages": {
    "zfrpc": {
        "key_expr": "zf/runtime/**",
        "volume": "memory"
    },
    "zf": {
        "key_expr": "zenoh-flow/**",
        "volume": "memory"
    }
}

The "volume": "memory" lines specify that the data published under the key expressions will be stored in RAM and thus "forgotten" once the Zenoh router is stopped.

Having clarified this point, we can now start a Zenoh-Flow runtime. There are two ways of launching one: as a standalone daemon or as a Zenoh plugin.

Launching Zenoh-Flow as a standalone daemon relaxes the constraint on the presence of the Zenoh router: the daemon only needs access to a Zenoh router that exposes the correct storage, but both do not have to run on the same host.

Launching Zenoh-Flow as a Zenoh plugin requires less configuration: Zenoh and Zenoh-Flow's configurations are merged into one file.

To try out Zenoh-Flow we recommend running it as a plugin for this last reason.

Zenoh plugin

Two steps must be performed to launch Zenoh-Flow as a Zenoh plugin:

  1. Configure the Zenoh router to load the Zenoh-Flow plugin.
  2. Move the Zenoh-Flow plugin shared library to a location that the Zenoh router will search.

💡 A complete configuration can be accessed here. This configuration also sets up the router to store Zenoh-Flow related information using the memory storage.

To configure a Zenoh router to load the Zenoh-Flow plugin, add the following JSON lines to its configuration under the plugins sections:

"zenoh_flow": {
    "required": true,
    "path": "/etc/zenoh-flow",
    "pid_file": "/var/zenoh-flow/runtime.pid",
    "extensions": "/etc/zenoh-flow/extensions.d",
    "worker_pool_size": 4
}

Where to move the Zenoh-Flow plugin shared library depends on the configuration of your Zenoh router and the value associated with the key plugins_search_dirs. Hence, one would either need to (a) move the shared library to one of the listed folders, or (b) add the path where the library is located to the plugins_search_dirs.

Below we specify that the shared libraries of plugins can be found in either /usr/lib/ or /home/zenoh/zenoh-flow/target/release/.

"plugins_search_dirs": ["/usr/lib/", "/home/zenoh/zenoh-flow/target/release/"],

The last remaining step is to launch the Zenoh router that will in turn launch the Zenoh-Flow plugin:

$ zenohd -c <path_to_the_json_configuration>

Great! A Zenoh-Flow runtime is now active. To interact with it, we provide the command line tool zfctl.

Standalone daemon

To launch Zenoh-Flow as a standalone daemon two steps are required:

  1. Specify how it interacts with a Zenoh infrastructure.
  2. Specify its runtime configuration.

To specify how the daemon will interact with a Zenoh infrastructure, we provide the following JSON configuration file:

{
    "listen":{
        "endpoints":["tcp/0.0.0.0:7997"],
    },
    "mode":"peer",
}

In short, it specifies that the daemon can be contacted on 0.0.0.0:7997 (via TCP) and that it is acting as a peer. More information on how to configure a Zenoh application can be found on Zenoh's documentation.

To specify the runtime configuration of the daemon, we provide the following YAML configuration:

    name: zenoh-flow-daemon-0
    pid_file: /var/zenoh-flow/runtime.pid
    path: /etc/zenoh-flow
    extensions: /etc/zenoh-flow/extensions.d
    zenoh_config: /etc/zenoh-flow/zenoh-daemon.json
    worker_pool_size: 4

The line zenoh_config: /etc/zenoh-flow/zenoh-daemon.json tells the daemon where to locate the configuration file we created just before, specifying how it interacts with a Zenoh infrastructure.

Assuming the values are correct, you can open a new terminal and start a Zenoh-Flow daemon:

$ ./target/release/zenoh-flow-daemon -c ./zenoh-flow/zenoh-flow-daemon/etc/runtime.yaml

⚠️ If you want to start several Zenoh-Flow daemons on the same host, you need to create as many runtime.yaml configuration files and, for each, you need to, at least, change the name key. If you do not provide any name in the configuration file, Zenoh-Flow will by default take the value of the $HOST environment variable.

To interact with it, we provide the command line tool zfctl.

Interacting with Zenoh-Flow: zfctl

Let us preface this section by saying that you do not need to have a Zenoh-Flow daemon running on the same host as zfctl.

The command-line tool zfctl is meant to be used by client devices to interact with Zenoh-Flow daemons through Zenoh. Hence, the only requirement is for zfctl to be able to talk to a Zenoh router that is connected to some Zenoh-Flow runtime(s).

To connect to a Zenoh infrastructure, zfctl needs to know where to look. This is achieved through a configuration file:

{
    "connect":{
        "endpoints":["tcp/127.0.0.1:7447"]
    },
    "mode":"client",
}

The above configuration assumes that a Zenoh peer or router is listening on port 7447 on the same host.

Assuming that every component is in place and that they are able to communicate (i.e. a Zenoh storage is set to receive and send Zenoh-Flow related information, a Zenoh-Flow runtime is running, zfctl can communicate with the two), then you can open a terminal and enter:

$ ./target/release/zfctl list runtimes

Which should output something similar to this:

+--------------------------------------+----------------------+--------+
| UUID                                 | Name                 | Status |
+--------------------------------------+----------------------+--------+
| 73ee4d1f-d3ac-4688-ad8c-724bb3d551ba | zenoh-flow-daemon-0  | Ready  |
+--------------------------------------+----------------------+--------+

If you do have this output then you now have a working installation of Zenoh-Flow!

master

v0.4.0

v0.3.0 — Input Rules

Clone this wiki locally