.
[](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22)
[](https://zenoh-c.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# C API
.
This repository provides a C binding based on the main [Zenoh implementation
written in Rust](https://github.com/eclipse-zenoh/zenoh).
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
1. Make sure that [Rust](https://www.rust-lang.org) is available on your
platform.
Please check [here](https://www.rust-lang.org/tools/install) to learn how
to install it.
If you already have the Rust toolchain installed, make sure it is
up-to-date with:
```bash
$ rustup update
```
.
3. Clone the [source] with `git`:
.
```bash
git clone https://github.com/eclipse-zenoh/zenoh-c.git
```
.
[source]: https://github.com/eclipse-zenoh/zenoh-c
.
3. Build:
.
Good CMake practice is to perform build outside of source directory, leaving
source tree untouched. The examples below demonstrates this mode of building.
On the other hand VScode by default creates build directory named 'build'
inside source tree. In this case build script sligthly changes its behavior.
See more about it in section 'VScode'.
.
By default build configuration is set to `Release`, it's not necessary to add
`-DCMAKE_BUILD_TYPE=Release` option on configuration step. But if your platform
uses multi-config generator by default (this is the case on Windows), you may
need to add option `--config Release` on build step. See more in CMake
[build-configurations] documenation. Option`--config Release` is skipped in
further examples for brewity. It's actually necessary for [Visual Studio
generators] only. For [Ninja Multi-Config] the build script is able to select
`Release` as the default configuration.
.
```bash
$ mkdir -p build && cd build
$ cmake ../zenoh-c
$ cmake --build . --config Release
```
.
The generator to use is selected with option `-G`. If Ninja is installed on
your system, adding `-GNinja` to `cmake` command can greatly speed up the build
time:
.
```bash
$ cmake ../zenoh-c -GNinja
$ cmake --build .
```
.
[build-configurations]:
https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
[Visual Studio generators]:
https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14
[Ninja]: https://cmake.org/cmake/help/latest/generator/Ninja.html
[Ninja Multi-Config]:
https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html
.
3. Install:
.
To install zenoh-c library into system just build target `install`. You need
root privileges to do it, as the default install location is `/usr/local`.
.
```bash
$ cmake --build . --target install
```
.
If you want to install zenoh-c libraries locally, you can set the
installation directory with `CMAKE_INSTALL_PREFIX`
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
$ cmake --build . --target install
```
.
By default only dynamic library is installed. Set
`ZENOHC_INSTALL_STATIC_LIBRARY` variable to install static library also:
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
-DZENOHC_INSTALL_STATIC_LIBRARY=TRUE
$ cmake --build . --target install
```
.
The result of installation is the header files in `include` directory, the
library files in `lib` directory and cmake package configuration files for
package `zenohc` in `lib/cmake` directory. The library later can be loaded with
CMake command `find_package(zenohc)`.
Link to targets `zenohc::lib` for dynamic library and `zenohc::static` for
static one in your CMakeLists.txt configuration file.
.
For `Debug` configuration the library package `zenohc_debug` is installed
side-by-side with release `zenohc` library. Suffix `d` is added to names of
library files (libzenohc**d**.so).
.
4. VScode
.
When zenoh-c project is opened in VSCode the build directory is set to
`build` inside source tree (this is default behavior of Microsoft [CMake
Tools]). The project build script detects this situation. In this case it
places build files in `target` directory and `Cargo.toml` file (which is
generated from `Cargo.toml.in`) into the root of source tree, as the rust
developers used to and as the rust build tools expects by default. This
behavior also can be explicitly enabled by setting
`ZENOHC_BUILD_IN_SOURCE_TREE` variable to `TRUE`.
.
[CMake Tools]:
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
.
## Building the Examples
.
The examples can be built in two ways. One is to select `examples` as a build
target of zenoh-c project (assuming here that the current directory is
side-by-side with zenoh-c directory):
.
```bash
$ cmake ../zenoh-c
$ cmake --build . --target examples
```
.
You may also use `--target
.
[](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22)
[](https://zenoh-c.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# C API
.
This repository provides a C binding based on the main [Zenoh implementation
written in Rust](https://github.com/eclipse-zenoh/zenoh).
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
1. Make sure that [Rust](https://www.rust-lang.org) is available on your
platform.
Please check [here](https://www.rust-lang.org/tools/install) to learn how
to install it.
If you already have the Rust toolchain installed, make sure it is
up-to-date with:
```bash
$ rustup update
```
.
3. Clone the [source] with `git`:
.
```bash
git clone https://github.com/eclipse-zenoh/zenoh-c.git
```
.
[source]: https://github.com/eclipse-zenoh/zenoh-c
.
3. Build:
.
Good CMake practice is to perform build outside of source directory, leaving
source tree untouched. The examples below demonstrates this mode of building.
On the other hand VScode by default creates build directory named 'build'
inside source tree. In this case build script sligthly changes its behavior.
See more about it in section 'VScode'.
.
By default build configuration is set to `Release`, it's not necessary to add
`-DCMAKE_BUILD_TYPE=Release` option on configuration step. But if your platform
uses multi-config generator by default (this is the case on Windows), you may
need to add option `--config Release` on build step. See more in CMake
[build-configurations] documenation. Option`--config Release` is skipped in
further examples for brewity. It's actually necessary for [Visual Studio
generators] only. For [Ninja Multi-Config] the build script is able to select
`Release` as the default configuration.
.
```bash
$ mkdir -p build && cd build
$ cmake ../zenoh-c
$ cmake --build . --config Release
```
.
The generator to use is selected with option `-G`. If Ninja is installed on
your system, adding `-GNinja` to `cmake` command can greatly speed up the build
time:
.
```bash
$ cmake ../zenoh-c -GNinja
$ cmake --build .
```
.
[build-configurations]:
https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
[Visual Studio generators]:
https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14
[Ninja]: https://cmake.org/cmake/help/latest/generator/Ninja.html
[Ninja Multi-Config]:
https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html
.
3. Install:
.
To install zenoh-c library into system just build target `install`. You need
root privileges to do it, as the default install location is `/usr/local`.
.
```bash
$ cmake --build . --target install
```
.
If you want to install zenoh-c libraries locally, you can set the
installation directory with `CMAKE_INSTALL_PREFIX`
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
$ cmake --build . --target install
```
.
By default only dynamic library is installed. Set
`ZENOHC_INSTALL_STATIC_LIBRARY` variable to install static library also:
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
-DZENOHC_INSTALL_STATIC_LIBRARY=TRUE
$ cmake --build . --target install
```
.
The result of installation is the header files in `include` directory, the
library files in `lib` directory and cmake package configuration files for
package `zenohc` in `lib/cmake` directory. The library later can be loaded with
CMake command `find_package(zenohc)`.
Link to targets `zenohc::lib` for dynamic library and `zenohc::static` for
static one in your CMakeLists.txt configuration file.
.
For `Debug` configuration the library package `zenohc_debug` is installed
side-by-side with release `zenohc` library. Suffix `d` is added to names of
library files (libzenohc**d**.so).
.
4. VScode
.
When zenoh-c project is opened in VSCode the build directory is set to
`build` inside source tree (this is default behavior of Microsoft [CMake
Tools]). The project build script detects this situation. In this case it
places build files in `target` directory and `Cargo.toml` file (which is
generated from `Cargo.toml.in`) into the root of source tree, as the rust
developers used to and as the rust build tools expects by default. This
behavior also can be explicitly enabled by setting
`ZENOHC_BUILD_IN_SOURCE_TREE` variable to `TRUE`.
.
[CMake Tools]:
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
.
## Building the Examples
.
The examples can be built in two ways. One is to select `examples` as a build
target of zenoh-c project (assuming here that the current directory is
side-by-side with zenoh-c directory):
.
```bash
$ cmake ../zenoh-c
$ cmake --build . --target examples
```
.
You may also use `--target
.
[](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22)
[](https://zenoh-c.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# C API
.
This repository provides a C binding based on the main [Zenoh implementation
written in Rust](https://github.com/eclipse-zenoh/zenoh).
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
1. Make sure that [Rust](https://www.rust-lang.org) is available on your
platform.
Please check [here](https://www.rust-lang.org/tools/install) to learn how
to install it.
If you already have the Rust toolchain installed, make sure it is
up-to-date with:
```bash
$ rustup update
```
.
3. Clone the [source] with `git`:
.
```bash
git clone https://github.com/eclipse-zenoh/zenoh-c.git
```
.
[source]: https://github.com/eclipse-zenoh/zenoh-c
.
3. Build:
.
Good CMake practice is to perform build outside of source directory, leaving
source tree untouched. The examples below demonstrates this mode of building.
On the other hand VScode by default creates build directory named 'build'
inside source tree. In this case build script sligthly changes its behavior.
See more about it in section 'VScode'.
.
By default build configuration is set to `Release`, it's not necessary to add
`-DCMAKE_BUILD_TYPE=Release` option on configuration step. But if your platform
uses multi-config generator by default (this is the case on Windows), you may
need to add option `--config Release` on build step. See more in CMake
[build-configurations] documenation. Option`--config Release` is skipped in
further examples for brewity. It's actually necessary for [Visual Studio
generators] only. For [Ninja Multi-Config] the build script is able to select
`Release` as the default configuration.
.
```bash
$ mkdir -p build && cd build
$ cmake ../zenoh-c
$ cmake --build . --config Release
```
.
The generator to use is selected with option `-G`. If Ninja is installed on
your system, adding `-GNinja` to `cmake` command can greatly speed up the build
time:
.
```bash
$ cmake ../zenoh-c -GNinja
$ cmake --build .
```
.
[build-configurations]:
https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
[Visual Studio generators]:
https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14
[Ninja]: https://cmake.org/cmake/help/latest/generator/Ninja.html
[Ninja Multi-Config]:
https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html
.
3. Install:
.
To install zenoh-c library into system just build target `install`. You need
root privileges to do it, as the default install location is `/usr/local`.
.
```bash
$ cmake --build . --target install
```
.
If you want to install zenoh-c libraries locally, you can set the
installation directory with `CMAKE_INSTALL_PREFIX`
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
$ cmake --build . --target install
```
.
By default only dynamic library is installed. Set
`ZENOHC_INSTALL_STATIC_LIBRARY` variable to install static library also:
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
-DZENOHC_INSTALL_STATIC_LIBRARY=TRUE
$ cmake --build . --target install
```
.
The result of installation is the header files in `include` directory, the
library files in `lib` directory and cmake package configuration files for
package `zenohc` in `lib/cmake` directory. The library later can be loaded with
CMake command `find_package(zenohc)`.
Link to targets `zenohc::lib` for dynamic library and `zenohc::static` for
static one in your CMakeLists.txt configuration file.
.
For `Debug` configuration the library package `zenohc_debug` is installed
side-by-side with release `zenohc` library. Suffix `d` is added to names of
library files (libzenohc**d**.so).
.
4. VScode
.
When zenoh-c project is opened in VSCode the build directory is set to
`build` inside source tree (this is default behavior of Microsoft [CMake
Tools]). The project build script detects this situation. In this case it
places build files in `target` directory and `Cargo.toml` file (which is
generated from `Cargo.toml.in`) into the root of source tree, as the rust
developers used to and as the rust build tools expects by default. This
behavior also can be explicitly enabled by setting
`ZENOHC_BUILD_IN_SOURCE_TREE` variable to `TRUE`.
.
[CMake Tools]:
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
.
## Building the Examples
.
The examples can be built in two ways. One is to select `examples` as a build
target of zenoh-c project (assuming here that the current directory is
side-by-side with zenoh-c directory):
.
```bash
$ cmake ../zenoh-c
$ cmake --build . --target examples
```
.
You may also use `--target
.
[](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22)
[](https://zenoh-c.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# C API
.
This repository provides a C binding based on the main [Zenoh implementation
written in Rust](https://github.com/eclipse-zenoh/zenoh).
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
1. Make sure that [Rust](https://www.rust-lang.org) is available on your
platform.
Please check [here](https://www.rust-lang.org/tools/install) to learn how
to install it.
If you already have the Rust toolchain installed, make sure it is
up-to-date with:
```bash
$ rustup update
```
.
3. Clone the [source] with `git`:
.
```bash
git clone https://github.com/eclipse-zenoh/zenoh-c.git
```
.
[source]: https://github.com/eclipse-zenoh/zenoh-c
.
3. Build:
.
Good CMake practice is to perform build outside of source directory, leaving
source tree untouched. The examples below demonstrates this mode of building.
On the other hand VScode by default creates build directory named 'build'
inside source tree. In this case build script sligthly changes its behavior.
See more about it in section 'VScode'.
.
By default build configuration is set to `Release`, it's not necessary to add
`-DCMAKE_BUILD_TYPE=Release` option on configuration step. But if your platform
uses multi-config generator by default (this is the case on Windows), you may
need to add option `--config Release` on build step. See more in CMake
[build-configurations] documenation. Option`--config Release` is skipped in
further examples for brewity. It's actually necessary for [Visual Studio
generators] only. For [Ninja Multi-Config] the build script is able to select
`Release` as the default configuration.
.
```bash
$ mkdir -p build && cd build
$ cmake ../zenoh-c
$ cmake --build . --config Release
```
.
The generator to use is selected with option `-G`. If Ninja is installed on
your system, adding `-GNinja` to `cmake` command can greatly speed up the build
time:
.
```bash
$ cmake ../zenoh-c -GNinja
$ cmake --build .
```
.
[build-configurations]:
https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
[Visual Studio generators]:
https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14
[Ninja]: https://cmake.org/cmake/help/latest/generator/Ninja.html
[Ninja Multi-Config]:
https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html
.
3. Install:
.
To install zenoh-c library into system just build target `install`. You need
root privileges to do it, as the default install location is `/usr/local`.
.
```bash
$ cmake --build . --target install
```
.
If you want to install zenoh-c libraries locally, you can set the
installation directory with `CMAKE_INSTALL_PREFIX`
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
$ cmake --build . --target install
```
.
By default only dynamic library is installed. Set
`ZENOHC_INSTALL_STATIC_LIBRARY` variable to install static library also:
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
-DZENOHC_INSTALL_STATIC_LIBRARY=TRUE
$ cmake --build . --target install
```
.
The result of installation is the header files in `include` directory, the
library files in `lib` directory and cmake package configuration files for
package `zenohc` in `lib/cmake` directory. The library later can be loaded with
CMake command `find_package(zenohc)`.
Link to targets `zenohc::lib` for dynamic library and `zenohc::static` for
static one in your CMakeLists.txt configuration file.
.
For `Debug` configuration the library package `zenohc_debug` is installed
side-by-side with release `zenohc` library. Suffix `d` is added to names of
library files (libzenohc**d**.so).
.
4. VScode
.
When zenoh-c project is opened in VSCode the build directory is set to
`build` inside source tree (this is default behavior of Microsoft [CMake
Tools]). The project build script detects this situation. In this case it
places build files in `target` directory and `Cargo.toml` file (which is
generated from `Cargo.toml.in`) into the root of source tree, as the rust
developers used to and as the rust build tools expects by default. This
behavior also can be explicitly enabled by setting
`ZENOHC_BUILD_IN_SOURCE_TREE` variable to `TRUE`.
.
[CMake Tools]:
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
.
## Building the Examples
.
The examples can be built in two ways. One is to select `examples` as a build
target of zenoh-c project (assuming here that the current directory is
side-by-side with zenoh-c directory):
.
```bash
$ cmake ../zenoh-c
$ cmake --build . --target examples
```
.
You may also use `--target
.
[](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22)
[](https://zenoh-c.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# C API
.
This repository provides a C binding based on the main [Zenoh implementation
written in Rust](https://github.com/eclipse-zenoh/zenoh).
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
1. Make sure that [Rust](https://www.rust-lang.org) is available on your
platform.
Please check [here](https://www.rust-lang.org/tools/install) to learn how
to install it.
If you already have the Rust toolchain installed, make sure it is
up-to-date with:
```bash
$ rustup update
```
.
3. Clone the [source] with `git`:
.
```bash
git clone https://github.com/eclipse-zenoh/zenoh-c.git
```
.
[source]: https://github.com/eclipse-zenoh/zenoh-c
.
3. Build:
.
Good CMake practice is to perform build outside of source directory, leaving
source tree untouched. The examples below demonstrates this mode of building.
On the other hand VScode by default creates build directory named 'build'
inside source tree. In this case build script sligthly changes its behavior.
See more about it in section 'VScode'.
.
By default build configuration is set to `Release`, it's not necessary to add
`-DCMAKE_BUILD_TYPE=Release` option on configuration step. But if your platform
uses multi-config generator by default (this is the case on Windows), you may
need to add option `--config Release` on build step. See more in CMake
[build-configurations] documenation. Option`--config Release` is skipped in
further examples for brewity. It's actually necessary for [Visual Studio
generators] only. For [Ninja Multi-Config] the build script is able to select
`Release` as the default configuration.
.
```bash
$ mkdir -p build && cd build
$ cmake ../zenoh-c
$ cmake --build . --config Release
```
.
The generator to use is selected with option `-G`. If Ninja is installed on
your system, adding `-GNinja` to `cmake` command can greatly speed up the build
time:
.
```bash
$ cmake ../zenoh-c -GNinja
$ cmake --build .
```
.
[build-configurations]:
https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
[Visual Studio generators]:
https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14
[Ninja]: https://cmake.org/cmake/help/latest/generator/Ninja.html
[Ninja Multi-Config]:
https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html
.
3. Install:
.
To install zenoh-c library into system just build target `install`. You need
root privileges to do it, as the default install location is `/usr/local`.
.
```bash
$ cmake --build . --target install
```
.
If you want to install zenoh-c libraries locally, you can set the
installation directory with `CMAKE_INSTALL_PREFIX`
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
$ cmake --build . --target install
```
.
By default only dynamic library is installed. Set
`ZENOHC_INSTALL_STATIC_LIBRARY` variable to install static library also:
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
-DZENOHC_INSTALL_STATIC_LIBRARY=TRUE
$ cmake --build . --target install
```
.
The result of installation is the header files in `include` directory, the
library files in `lib` directory and cmake package configuration files for
package `zenohc` in `lib/cmake` directory. The library later can be loaded with
CMake command `find_package(zenohc)`.
Link to targets `zenohc::lib` for dynamic library and `zenohc::static` for
static one in your CMakeLists.txt configuration file.
.
For `Debug` configuration the library package `zenohc_debug` is installed
side-by-side with release `zenohc` library. Suffix `d` is added to names of
library files (libzenohc**d**.so).
.
4. VScode
.
When zenoh-c project is opened in VSCode the build directory is set to
`build` inside source tree (this is default behavior of Microsoft [CMake
Tools]). The project build script detects this situation. In this case it
places build files in `target` directory and `Cargo.toml` file (which is
generated from `Cargo.toml.in`) into the root of source tree, as the rust
developers used to and as the rust build tools expects by default. This
behavior also can be explicitly enabled by setting
`ZENOHC_BUILD_IN_SOURCE_TREE` variable to `TRUE`.
.
[CMake Tools]:
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
.
## Building the Examples
.
The examples can be built in two ways. One is to select `examples` as a build
target of zenoh-c project (assuming here that the current directory is
side-by-side with zenoh-c directory):
.
```bash
$ cmake ../zenoh-c
$ cmake --build . --target examples
```
.
You may also use `--target
.
[](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22)
[](https://zenoh-c.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# C API
.
This repository provides a C binding based on the main [Zenoh implementation
written in Rust](https://github.com/eclipse-zenoh/zenoh).
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
1. Make sure that [Rust](https://www.rust-lang.org) is available on your
platform.
Please check [here](https://www.rust-lang.org/tools/install) to learn how
to install it.
If you already have the Rust toolchain installed, make sure it is
up-to-date with:
```bash
$ rustup update
```
.
3. Clone the [source] with `git`:
.
```bash
git clone https://github.com/eclipse-zenoh/zenoh-c.git
```
.
[source]: https://github.com/eclipse-zenoh/zenoh-c
.
3. Build:
.
Good CMake practice is to perform build outside of source directory, leaving
source tree untouched. The examples below demonstrates this mode of building.
On the other hand VScode by default creates build directory named 'build'
inside source tree. In this case build script sligthly changes its behavior.
See more about it in section 'VScode'.
.
By default build configuration is set to `Release`, it's not necessary to add
`-DCMAKE_BUILD_TYPE=Release` option on configuration step. But if your platform
uses multi-config generator by default (this is the case on Windows), you may
need to add option `--config Release` on build step. See more in CMake
[build-configurations] documenation. Option`--config Release` is skipped in
further examples for brewity. It's actually necessary for [Visual Studio
generators] only. For [Ninja Multi-Config] the build script is able to select
`Release` as the default configuration.
.
```bash
$ mkdir -p build && cd build
$ cmake ../zenoh-c
$ cmake --build . --config Release
```
.
The generator to use is selected with option `-G`. If Ninja is installed on
your system, adding `-GNinja` to `cmake` command can greatly speed up the build
time:
.
```bash
$ cmake ../zenoh-c -GNinja
$ cmake --build .
```
.
[build-configurations]:
https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
[Visual Studio generators]:
https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14
[Ninja]: https://cmake.org/cmake/help/latest/generator/Ninja.html
[Ninja Multi-Config]:
https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html
.
3. Install:
.
To install zenoh-c library into system just build target `install`. You need
root privileges to do it, as the default install location is `/usr/local`.
.
```bash
$ cmake --build . --target install
```
.
If you want to install zenoh-c libraries locally, you can set the
installation directory with `CMAKE_INSTALL_PREFIX`
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
$ cmake --build . --target install
```
.
By default only dynamic library is installed. Set
`ZENOHC_INSTALL_STATIC_LIBRARY` variable to install static library also:
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
-DZENOHC_INSTALL_STATIC_LIBRARY=TRUE
$ cmake --build . --target install
```
.
The result of installation is the header files in `include` directory, the
library files in `lib` directory and cmake package configuration files for
package `zenohc` in `lib/cmake` directory. The library later can be loaded with
CMake command `find_package(zenohc)`.
Link to targets `zenohc::lib` for dynamic library and `zenohc::static` for
static one in your CMakeLists.txt configuration file.
.
For `Debug` configuration the library package `zenohc_debug` is installed
side-by-side with release `zenohc` library. Suffix `d` is added to names of
library files (libzenohc**d**.so).
.
4. VScode
.
When zenoh-c project is opened in VSCode the build directory is set to
`build` inside source tree (this is default behavior of Microsoft [CMake
Tools]). The project build script detects this situation. In this case it
places build files in `target` directory and `Cargo.toml` file (which is
generated from `Cargo.toml.in`) into the root of source tree, as the rust
developers used to and as the rust build tools expects by default. This
behavior also can be explicitly enabled by setting
`ZENOHC_BUILD_IN_SOURCE_TREE` variable to `TRUE`.
.
[CMake Tools]:
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
.
## Building the Examples
.
The examples can be built in two ways. One is to select `examples` as a build
target of zenoh-c project (assuming here that the current directory is
side-by-side with zenoh-c directory):
.
```bash
$ cmake ../zenoh-c
$ cmake --build . --target examples
```
.
You may also use `--target
.
[](https://github.com/eclipse-zenoh/zenoh-c/actions?query=workflow%3A%22CI%22)
[](https://zenoh-c.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# C API
.
This repository provides a C binding based on the main [Zenoh implementation
written in Rust](https://github.com/eclipse-zenoh/zenoh).
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
1. Make sure that [Rust](https://www.rust-lang.org) is available on your
platform.
Please check [here](https://www.rust-lang.org/tools/install) to learn how
to install it.
If you already have the Rust toolchain installed, make sure it is
up-to-date with:
```bash
$ rustup update
```
.
3. Clone the [source] with `git`:
.
```bash
git clone https://github.com/eclipse-zenoh/zenoh-c.git
```
.
[source]: https://github.com/eclipse-zenoh/zenoh-c
.
3. Build:
.
Good CMake practice is to perform build outside of source directory, leaving
source tree untouched. The examples below demonstrates this mode of building.
On the other hand VScode by default creates build directory named 'build'
inside source tree. In this case build script sligthly changes its behavior.
See more about it in section 'VScode'.
.
By default build configuration is set to `Release`, it's not necessary to add
`-DCMAKE_BUILD_TYPE=Release` option on configuration step. But if your platform
uses multi-config generator by default (this is the case on Windows), you may
need to add option `--config Release` on build step. See more in CMake
[build-configurations] documenation. Option`--config Release` is skipped in
further examples for brewity. It's actually necessary for [Visual Studio
generators] only. For [Ninja Multi-Config] the build script is able to select
`Release` as the default configuration.
.
```bash
$ mkdir -p build && cd build
$ cmake ../zenoh-c
$ cmake --build . --config Release
```
.
The generator to use is selected with option `-G`. If Ninja is installed on
your system, adding `-GNinja` to `cmake` command can greatly speed up the build
time:
.
```bash
$ cmake ../zenoh-c -GNinja
$ cmake --build .
```
.
[build-configurations]:
https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html#build-configurations
[Visual Studio generators]:
https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#id14
[Ninja]: https://cmake.org/cmake/help/latest/generator/Ninja.html
[Ninja Multi-Config]:
https://cmake.org/cmake/help/latest/generator/Ninja%20Multi-Config.html
.
3. Install:
.
To install zenoh-c library into system just build target `install`. You need
root privileges to do it, as the default install location is `/usr/local`.
.
```bash
$ cmake --build . --target install
```
.
If you want to install zenoh-c libraries locally, you can set the
installation directory with `CMAKE_INSTALL_PREFIX`
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
$ cmake --build . --target install
```
.
By default only dynamic library is installed. Set
`ZENOHC_INSTALL_STATIC_LIBRARY` variable to install static library also:
.
```bash
$ cmake ../zenoh-c -DCMAKE_INSTALL_PREFIX=~/.local
-DZENOHC_INSTALL_STATIC_LIBRARY=TRUE
$ cmake --build . --target install
```
.
The result of installation is the header files in `include` directory, the
library files in `lib` directory and cmake package configuration files for
package `zenohc` in `lib/cmake` directory. The library later can be loaded with
CMake command `find_package(zenohc)`.
Link to targets `zenohc::lib` for dynamic library and `zenohc::static` for
static one in your CMakeLists.txt configuration file.
.
For `Debug` configuration the library package `zenohc_debug` is installed
side-by-side with release `zenohc` library. Suffix `d` is added to names of
library files (libzenohc**d**.so).
.
4. VScode
.
When zenoh-c project is opened in VSCode the build directory is set to
`build` inside source tree (this is default behavior of Microsoft [CMake
Tools]). The project build script detects this situation. In this case it
places build files in `target` directory and `Cargo.toml` file (which is
generated from `Cargo.toml.in`) into the root of source tree, as the rust
developers used to and as the rust build tools expects by default. This
behavior also can be explicitly enabled by setting
`ZENOHC_BUILD_IN_SOURCE_TREE` variable to `TRUE`.
.
[CMake Tools]:
https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools
.
## Building the Examples
.
The examples can be built in two ways. One is to select `examples` as a build
target of zenoh-c project (assuming here that the current directory is
side-by-side with zenoh-c directory):
.
```bash
$ cmake ../zenoh-c
$ cmake --build . --target examples
```
.
You may also use `--target
.
[](https://github.com/eclipse-zenoh/zenoh-backend-filesystem/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# File system backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on the host's file system to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_fs`**.
.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the `zenoh_backend_fs`
library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_FS_ROOT` environment variable to the directory
where you want the files to be stored (or exposed from).
If you don't declare it, the `~/.zenoh/zenoh_backend_fs` directory will be
used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storage-manager" plugin:
storage_manager: {
volumes: {
// configuration of a "fs" volume (the "zenoh_backend_fs" backend
library will be loaded at startup)
fs: {},
},
storages: {
// configuration of a "demo" storage using the "fs" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to file path
// this argument is optional.
strip_prefix: "demo/example",
volume: {
id: "fs",
// the key/values will be stored as files within this directory
(relative to ${ZENOH_BACKEND_FS_ROOT})
dir: "example"
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "fs" backend (the "zenoh_backend_fs" library will be loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/fs`
- Add the "demo" storage using the "fs" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example", volume: {id: "fs",
dir:"example"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored under ${ZENOH_BACKEND_FS_ROOT}/example
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
.
-------------------------------
## Configuration
### Extra configuration for filesystem-backed volumes
.
Volumes using the `fs` backend don't need any extra configuration at the volume
level. Any volume can use the `fs` backend by specifying the value `"fs"` for
the `backend` configuration key. A volume named `fs` will automatically be
backed by the `fs` backend if no other backend is specified.
.
-------------------------------
### Storage-level configuration for filesystem-backed volumes
.
Storages relying on a `fs` backed volume must/can specify additional
configuration specific to that volume, as shown in the example
[above](#setup-via-a-json5-configuration-file):
- `dir` (**required**, string) : The directory that will be used to store data.
.
- `read_only` (optional, boolean) : the storage will only answer to GET
queries. It will not accept any PUT or DELETE message, and won't write any
file. `false` by default.
.
- `on_closure` (optional, string) : the strategy to use when the Storage is
removed. There are 2 options:
- `"do_nothing"`: the storage's directory remains untouched (this is the
default behaviour)
- `"delete_all"`: the storage's directory is deleted with all its content.
.
- `follow_links` (optional, boolean) : If set to `true` the storage will follow
the symbolic links. The default value is `false`.
.
- `keep_mime_types` (optional, boolean) : When replying to a GET query with a
file for which the zenoh encoding is not known, the storage guess its mime-type
according to the file extension. If the mime-type doesn't correspond to a
supported zenoh encoding, this option will drive the returned value:
- `true` (default value): a [Custom
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Custom)
is returned with the description set to the mime-type.
- `false`: a [Raw
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Raw) with
APP_OCTET_STREAM encoding is returned.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to file system
Each **storage** will map to a directory with path:
`${ZENOH_BACKEND_FS_ROOT}/
.
[](https://github.com/eclipse-zenoh/zenoh-backend-filesystem/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# File system backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on the host's file system to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_fs`**.
.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the `zenoh_backend_fs`
library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_FS_ROOT` environment variable to the directory
where you want the files to be stored (or exposed from).
If you don't declare it, the `~/.zenoh/zenoh_backend_fs` directory will be
used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storage-manager" plugin:
storage_manager: {
volumes: {
// configuration of a "fs" volume (the "zenoh_backend_fs" backend
library will be loaded at startup)
fs: {},
},
storages: {
// configuration of a "demo" storage using the "fs" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to file path
// this argument is optional.
strip_prefix: "demo/example",
volume: {
id: "fs",
// the key/values will be stored as files within this directory
(relative to ${ZENOH_BACKEND_FS_ROOT})
dir: "example"
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "fs" backend (the "zenoh_backend_fs" library will be loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/fs`
- Add the "demo" storage using the "fs" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example", volume: {id: "fs",
dir:"example"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored under ${ZENOH_BACKEND_FS_ROOT}/example
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
.
-------------------------------
## Configuration
### Extra configuration for filesystem-backed volumes
.
Volumes using the `fs` backend don't need any extra configuration at the volume
level. Any volume can use the `fs` backend by specifying the value `"fs"` for
the `backend` configuration key. A volume named `fs` will automatically be
backed by the `fs` backend if no other backend is specified.
.
-------------------------------
### Storage-level configuration for filesystem-backed volumes
.
Storages relying on a `fs` backed volume must/can specify additional
configuration specific to that volume, as shown in the example
[above](#setup-via-a-json5-configuration-file):
- `dir` (**required**, string) : The directory that will be used to store data.
.
- `read_only` (optional, boolean) : the storage will only answer to GET
queries. It will not accept any PUT or DELETE message, and won't write any
file. `false` by default.
.
- `on_closure` (optional, string) : the strategy to use when the Storage is
removed. There are 2 options:
- `"do_nothing"`: the storage's directory remains untouched (this is the
default behaviour)
- `"delete_all"`: the storage's directory is deleted with all its content.
.
- `follow_links` (optional, boolean) : If set to `true` the storage will follow
the symbolic links. The default value is `false`.
.
- `keep_mime_types` (optional, boolean) : When replying to a GET query with a
file for which the zenoh encoding is not known, the storage guess its mime-type
according to the file extension. If the mime-type doesn't correspond to a
supported zenoh encoding, this option will drive the returned value:
- `true` (default value): a [Custom
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Custom)
is returned with the description set to the mime-type.
- `false`: a [Raw
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Raw) with
APP_OCTET_STREAM encoding is returned.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to file system
Each **storage** will map to a directory with path:
`${ZENOH_BACKEND_FS_ROOT}/
.
[](https://github.com/eclipse-zenoh/zenoh-backend-filesystem/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# File system backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on the host's file system to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_fs`**.
.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the `zenoh_backend_fs`
library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_FS_ROOT` environment variable to the directory
where you want the files to be stored (or exposed from).
If you don't declare it, the `~/.zenoh/zenoh_backend_fs` directory will be
used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storage-manager" plugin:
storage_manager: {
volumes: {
// configuration of a "fs" volume (the "zenoh_backend_fs" backend
library will be loaded at startup)
fs: {},
},
storages: {
// configuration of a "demo" storage using the "fs" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to file path
// this argument is optional.
strip_prefix: "demo/example",
volume: {
id: "fs",
// the key/values will be stored as files within this directory
(relative to ${ZENOH_BACKEND_FS_ROOT})
dir: "example"
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "fs" backend (the "zenoh_backend_fs" library will be loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/fs`
- Add the "demo" storage using the "fs" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example", volume: {id: "fs",
dir:"example"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored under ${ZENOH_BACKEND_FS_ROOT}/example
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
.
-------------------------------
## Configuration
### Extra configuration for filesystem-backed volumes
.
Volumes using the `fs` backend don't need any extra configuration at the volume
level. Any volume can use the `fs` backend by specifying the value `"fs"` for
the `backend` configuration key. A volume named `fs` will automatically be
backed by the `fs` backend if no other backend is specified.
.
-------------------------------
### Storage-level configuration for filesystem-backed volumes
.
Storages relying on a `fs` backed volume must/can specify additional
configuration specific to that volume, as shown in the example
[above](#setup-via-a-json5-configuration-file):
- `dir` (**required**, string) : The directory that will be used to store data.
.
- `read_only` (optional, boolean) : the storage will only answer to GET
queries. It will not accept any PUT or DELETE message, and won't write any
file. `false` by default.
.
- `on_closure` (optional, string) : the strategy to use when the Storage is
removed. There are 2 options:
- `"do_nothing"`: the storage's directory remains untouched (this is the
default behaviour)
- `"delete_all"`: the storage's directory is deleted with all its content.
.
- `follow_links` (optional, boolean) : If set to `true` the storage will follow
the symbolic links. The default value is `false`.
.
- `keep_mime_types` (optional, boolean) : When replying to a GET query with a
file for which the zenoh encoding is not known, the storage guess its mime-type
according to the file extension. If the mime-type doesn't correspond to a
supported zenoh encoding, this option will drive the returned value:
- `true` (default value): a [Custom
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Custom)
is returned with the description set to the mime-type.
- `false`: a [Raw
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Raw) with
APP_OCTET_STREAM encoding is returned.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to file system
Each **storage** will map to a directory with path:
`${ZENOH_BACKEND_FS_ROOT}/
.
[](https://github.com/eclipse-zenoh/zenoh-backend-filesystem/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# File system backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on the host's file system to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_fs`**.
.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the `zenoh_backend_fs`
library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_FS_ROOT` environment variable to the directory
where you want the files to be stored (or exposed from).
If you don't declare it, the `~/.zenoh/zenoh_backend_fs` directory will be
used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storage-manager" plugin:
storage_manager: {
volumes: {
// configuration of a "fs" volume (the "zenoh_backend_fs" backend
library will be loaded at startup)
fs: {},
},
storages: {
// configuration of a "demo" storage using the "fs" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to file path
// this argument is optional.
strip_prefix: "demo/example",
volume: {
id: "fs",
// the key/values will be stored as files within this directory
(relative to ${ZENOH_BACKEND_FS_ROOT})
dir: "example"
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "fs" backend (the "zenoh_backend_fs" library will be loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/fs`
- Add the "demo" storage using the "fs" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example", volume: {id: "fs",
dir:"example"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored under ${ZENOH_BACKEND_FS_ROOT}/example
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
.
-------------------------------
## Configuration
### Extra configuration for filesystem-backed volumes
.
Volumes using the `fs` backend don't need any extra configuration at the volume
level. Any volume can use the `fs` backend by specifying the value `"fs"` for
the `backend` configuration key. A volume named `fs` will automatically be
backed by the `fs` backend if no other backend is specified.
.
-------------------------------
### Storage-level configuration for filesystem-backed volumes
.
Storages relying on a `fs` backed volume must/can specify additional
configuration specific to that volume, as shown in the example
[above](#setup-via-a-json5-configuration-file):
- `dir` (**required**, string) : The directory that will be used to store data.
.
- `read_only` (optional, boolean) : the storage will only answer to GET
queries. It will not accept any PUT or DELETE message, and won't write any
file. `false` by default.
.
- `on_closure` (optional, string) : the strategy to use when the Storage is
removed. There are 2 options:
- `"do_nothing"`: the storage's directory remains untouched (this is the
default behaviour)
- `"delete_all"`: the storage's directory is deleted with all its content.
.
- `follow_links` (optional, boolean) : If set to `true` the storage will follow
the symbolic links. The default value is `false`.
.
- `keep_mime_types` (optional, boolean) : When replying to a GET query with a
file for which the zenoh encoding is not known, the storage guess its mime-type
according to the file extension. If the mime-type doesn't correspond to a
supported zenoh encoding, this option will drive the returned value:
- `true` (default value): a [Custom
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Custom)
is returned with the description set to the mime-type.
- `false`: a [Raw
value](https://docs.rs/zenoh/latest/zenoh/enum.Value.html#variant.Raw) with
APP_OCTET_STREAM encoding is returned.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to file system
Each **storage** will map to a directory with path:
`${ZENOH_BACKEND_FS_ROOT}/
.
[](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# InfluxDB backend
.
In Zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on an
[InfluxDB](https://www.influxdata.com/products/influxdb/) server
to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_influxdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
:warning: InfluxDB 2.x is not yet supported. InfluxDB 1.8 minimum is required.
.
-------------------------------
## :warning: Documentation for previous 0.5 versions:
The following documentation related to the version currently in development in
"master" branch: 0.6.x.
.
For previous versions see the README and code of the corresponding tagged
version:
-
[0.5.0-beta.9](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.9#readme)
-
[0.5.0-beta.8](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.8#readme)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_influxdb` library file is available in `~/.zenoh/lib`.
- You have an InfluxDB service running and listening on
`http://localhost:8086`
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing for example:
```json5
{
plugins: {
// configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
// configuration of a "influxdb" volume (the
"zenoh_backend_influxdb" backend library will be loaded at startup)
influxdb: {
// URL to the InfluxDB service
url: "http://localhost:8086",
private: {
// If needed: InfluxDB credentials, preferably admin for
databases creation and drop
//username: "admin",
//password: "password"
}
}
},
storages: {
// configuration of a "demo" storage using the "influxdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
// this option is optional
strip_prefix: "demo/example",
volume: {
id: "influxdb",
// the database name within InfluxDB
db: "zenoh_example",
// if the database doesn't exist, create it
create_db: true,
// strategy on storage closure
on_closure: "drop_db",
private: {
// If needed: InfluxDB credentials, with read/write
privileges for the database
//username: "user",
//password: "password"
}
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "influxdb" volume (the "zenoh_backend_fs" library will be loaded),
connected to InfluxDB service on http://localhost:8086:
`curl -X PUT -H 'content-type:application/json' -d
'{url:"http://localhost:8086"}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/influxdb`
- Add the "demo" storage using the "influxdb" volume:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",volume:{id:"influxdb",db:"zenoh_example",create_db:true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put some values at different time intervals
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-2" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-3" http://localhost:8000/demo/example/test
.
# Retrive them as a time serie where '_time=[..]' means "infinite time range"
curl -g 'http://localhost:8000/demo/example/test?_time=[..]'
```
.
.
-------------------------------
## Volume configuration
InfluxDB-backed volumes need some configuration to work:
.
- **`"url"`** (**required**) : a URL to the InfluxDB service. Example:
`http://localhost:8086`
.
- **`"username"`** (optional) : an [InfluxDB
admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#admin-users)
user name. It will be used for creation of databases, granting read/write
privileges of databases mapped to storages and dropping of databases and
measurements.
.
- **`"password"`** (optional) : the admin user's password.
.
Both `username` and `password` should be hidden behind a `private` gate, as
shown in the example [above](#setup-via-a-json5-configuration-file). In
general, if you wish for a part of the configuration to be hidden when
configuration is queried, you should hide it behind a `private` gate.
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a `influxdb` backed volume may have additional
configuration through the `volume` section:
- **`"db"`** (optional, string) : the InfluxDB database name the storage will
map into. If not specified, a random name will be generated, and the
corresponding database will be created (even if `"create_db"` is not set).
.
- **`"create_db"`** (optional, boolean) : create the InfluxDB database if not
already existing.
By default the database is not created, unless `"db"` property is not
specified.
*(the value doesn't matter, only the property existence is checked)*
.
- **`"on_closure"`** (optional, string) : the strategy to use when the Storage
is removed. There are 3 options:
- *unset* or `"do_nothing"`: the database remains untouched (this is the
default behaviour)
- `"drop_db"`: the database is dropped (i.e. removed)
- `"drop_series"`: all the series (measurements) are dropped and the database
remains empty.
.
- **`"username"`** (optional, string) : an InfluxDB user name (usually
[non-admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#non-admin-users)).
It will be used to read/write points in the database on GET/PUT/DELETE zenoh
operations.
.
- **`"password"`** (optional, string) : the user's password.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to InfluxDB concepts
Each **storage** will map to an InfluxDB **database**.
Each **key** to store will map to an InfluxDB
[**measurement**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#measurement)
named with the key stripped from the `"strip_prefix"` property (see below).
Each **key/value** put into the storage will map to an InfluxDB
[**point**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#point)
reusing the timestamp set by zenoh
(but with a precision of nanoseconds). The fileds and tags of the point is are
the following:
- `"kind"` tag: the zenoh change kind (`"PUT"` for a value that have been put,
or `"DEL"` to mark the deletion of the key)
- `"timestamp"` field: the original zenoh timestamp
- `"encoding"` field: the value's encoding flag
- `"base64"` field: a boolean indicating if the value is encoded in base64
- `"value"`field: the value as a string, possibly encoded in base64 for binary
values.
.
### Behaviour on deletion
On deletion of a key, all points with a timestamp before the deletion message
are deleted.
A point with `"kind"="DEL`" is inserted (to avoid re-insertion of points with
an older timestamp in case of un-ordered messages).
After a delay (5 seconds), the measurement corresponding to the deleted key is
dropped if it still contains no points.
.
### Behaviour on GET
On GET operations, by default the storage returns only the latest point for
each key/measurement.
This is to be coherent with other backends technologies that only store 1 value
per-key.
If you want to get time-series as a result of a GET operation, you need to
specify a time range via
the `"_time"`argument in your
[Selector](https://github.com/eclipse-zenoh/roadmap/tree/main/rfcs/ALL/Selectors).
.
Examples of selectors:
```bash
# get the complete time-series
/demo/example/**?_time=[..]
.
# get points within a fixed date interval
/demo/example/influxdb/**?_time=[2020-01-01T00:00:00Z..2020-01-02T12:00:00.000000000Z]
.
# get points within a relative date interval
/demo/example/influxdb/**?_time=[now(-2d)..now(-1d)]
```
.
See the [`"_time"`
RFC](https://github.com/eclipse-zenoh/roadmap/blob/main/rfcs/ALL/Selectors/_time.md)
for a complete description of the time range format
.
.
-------------------------------
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-backend-influxdb/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-influxdb` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-influxdb
```
.
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
built with the exact same Rust version than `zenohd`, and using for `zenoh`
dependency the same version (or commit number) than 'zenohd'.
Otherwise, incompatibilities in memory mapping of shared types between `zenohd`
and the library can lead to a `"SIGSEV"` crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
```bash
$ zenohd --version
The zenoh router v0.6.0-beta.1 built with rustc 1.64.0 (a55dd71d5 2022-09-19)
```
Here, `zenohd` has been built with the rustc version `1.64.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.64.0
```
.
And `zenohd` version corresponds to an un-released commit with id `1f20c86`.
Update the `zenoh` dependency in Cargo.lock with this command:
```bash
$ cargo update -p zenoh --precise 1f20c86
```
.
Then build the backend with:
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Package: zenoh-backend-influxdb
Version: 0.10.0-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 4801
Depends: zenoh-plugin-storage-manager (=0.10.0-rc)
Filename: 0.10.0-rc/zenoh-backend-influxdb_0.10.0-rc_arm64.deb
Size: 1489788
MD5sum: 402cfbb5a497ed25e684f915a6daf4e9
SHA1: 56689b08d0707168779d44f41148bd3c94749105
SHA256: 3b520c402ed04e4a526ea1c4760a88d1583202a0f83f5303880a19d0b2c2a13b
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Backend for Zenoh using InfluxDB
.
[](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# InfluxDB backend
.
In Zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on an
[InfluxDB](https://www.influxdata.com/products/influxdb/) server
to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_influxdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
:warning: InfluxDB 2.x is not yet supported. InfluxDB 1.8 minimum is required.
.
-------------------------------
## :warning: Documentation for previous 0.5 versions:
The following documentation related to the version currently in development in
"master" branch: 0.6.x.
.
For previous versions see the README and code of the corresponding tagged
version:
-
[0.5.0-beta.9](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.9#readme)
-
[0.5.0-beta.8](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.8#readme)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_influxdb` library file is available in `~/.zenoh/lib`.
- You have an InfluxDB service running and listening on
`http://localhost:8086`
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing for example:
```json5
{
plugins: {
// configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
// configuration of a "influxdb" volume (the
"zenoh_backend_influxdb" backend library will be loaded at startup)
influxdb: {
// URL to the InfluxDB service
url: "http://localhost:8086",
private: {
// If needed: InfluxDB credentials, preferably admin for
databases creation and drop
//username: "admin",
//password: "password"
}
}
},
storages: {
// configuration of a "demo" storage using the "influxdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
// this option is optional
strip_prefix: "demo/example",
volume: {
id: "influxdb",
// the database name within InfluxDB
db: "zenoh_example",
// if the database doesn't exist, create it
create_db: true,
// strategy on storage closure
on_closure: "drop_db",
private: {
// If needed: InfluxDB credentials, with read/write
privileges for the database
//username: "user",
//password: "password"
}
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "influxdb" volume (the "zenoh_backend_fs" library will be loaded),
connected to InfluxDB service on http://localhost:8086:
`curl -X PUT -H 'content-type:application/json' -d
'{url:"http://localhost:8086"}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/influxdb`
- Add the "demo" storage using the "influxdb" volume:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",volume:{id:"influxdb",db:"zenoh_example",create_db:true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put some values at different time intervals
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-2" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-3" http://localhost:8000/demo/example/test
.
# Retrive them as a time serie where '_time=[..]' means "infinite time range"
curl -g 'http://localhost:8000/demo/example/test?_time=[..]'
```
.
.
-------------------------------
## Volume configuration
InfluxDB-backed volumes need some configuration to work:
.
- **`"url"`** (**required**) : a URL to the InfluxDB service. Example:
`http://localhost:8086`
.
- **`"username"`** (optional) : an [InfluxDB
admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#admin-users)
user name. It will be used for creation of databases, granting read/write
privileges of databases mapped to storages and dropping of databases and
measurements.
.
- **`"password"`** (optional) : the admin user's password.
.
Both `username` and `password` should be hidden behind a `private` gate, as
shown in the example [above](#setup-via-a-json5-configuration-file). In
general, if you wish for a part of the configuration to be hidden when
configuration is queried, you should hide it behind a `private` gate.
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a `influxdb` backed volume may have additional
configuration through the `volume` section:
- **`"db"`** (optional, string) : the InfluxDB database name the storage will
map into. If not specified, a random name will be generated, and the
corresponding database will be created (even if `"create_db"` is not set).
.
- **`"create_db"`** (optional, boolean) : create the InfluxDB database if not
already existing.
By default the database is not created, unless `"db"` property is not
specified.
*(the value doesn't matter, only the property existence is checked)*
.
- **`"on_closure"`** (optional, string) : the strategy to use when the Storage
is removed. There are 3 options:
- *unset* or `"do_nothing"`: the database remains untouched (this is the
default behaviour)
- `"drop_db"`: the database is dropped (i.e. removed)
- `"drop_series"`: all the series (measurements) are dropped and the database
remains empty.
.
- **`"username"`** (optional, string) : an InfluxDB user name (usually
[non-admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#non-admin-users)).
It will be used to read/write points in the database on GET/PUT/DELETE zenoh
operations.
.
- **`"password"`** (optional, string) : the user's password.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to InfluxDB concepts
Each **storage** will map to an InfluxDB **database**.
Each **key** to store will map to an InfluxDB
[**measurement**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#measurement)
named with the key stripped from the `"strip_prefix"` property (see below).
Each **key/value** put into the storage will map to an InfluxDB
[**point**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#point)
reusing the timestamp set by zenoh
(but with a precision of nanoseconds). The fileds and tags of the point is are
the following:
- `"kind"` tag: the zenoh change kind (`"PUT"` for a value that have been put,
or `"DEL"` to mark the deletion of the key)
- `"timestamp"` field: the original zenoh timestamp
- `"encoding"` field: the value's encoding flag
- `"base64"` field: a boolean indicating if the value is encoded in base64
- `"value"`field: the value as a string, possibly encoded in base64 for binary
values.
.
### Behaviour on deletion
On deletion of a key, all points with a timestamp before the deletion message
are deleted.
A point with `"kind"="DEL`" is inserted (to avoid re-insertion of points with
an older timestamp in case of un-ordered messages).
After a delay (5 seconds), the measurement corresponding to the deleted key is
dropped if it still contains no points.
.
### Behaviour on GET
On GET operations, by default the storage returns only the latest point for
each key/measurement.
This is to be coherent with other backends technologies that only store 1 value
per-key.
If you want to get time-series as a result of a GET operation, you need to
specify a time range via
the `"_time"`argument in your
[Selector](https://github.com/eclipse-zenoh/roadmap/tree/main/rfcs/ALL/Selectors).
.
Examples of selectors:
```bash
# get the complete time-series
/demo/example/**?_time=[..]
.
# get points within a fixed date interval
/demo/example/influxdb/**?_time=[2020-01-01T00:00:00Z..2020-01-02T12:00:00.000000000Z]
.
# get points within a relative date interval
/demo/example/influxdb/**?_time=[now(-2d)..now(-1d)]
```
.
See the [`"_time"`
RFC](https://github.com/eclipse-zenoh/roadmap/blob/main/rfcs/ALL/Selectors/_time.md)
for a complete description of the time range format
.
.
-------------------------------
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-backend-influxdb/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-influxdb` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-influxdb
```
.
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
built with the exact same Rust version than `zenohd`, and using for `zenoh`
dependency the same version (or commit number) than 'zenohd'.
Otherwise, incompatibilities in memory mapping of shared types between `zenohd`
and the library can lead to a `"SIGSEV"` crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
```bash
$ zenohd --version
The zenoh router v0.6.0-beta.1 built with rustc 1.64.0 (a55dd71d5 2022-09-19)
```
Here, `zenohd` has been built with the rustc version `1.64.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.64.0
```
.
And `zenohd` version corresponds to an un-released commit with id `1f20c86`.
Update the `zenoh` dependency in Cargo.lock with this command:
```bash
$ cargo update -p zenoh --precise 1f20c86
```
.
Then build the backend with:
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Package: zenoh-backend-influxdb
Version: 0.10.0-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 5337
Depends: zenoh-plugin-storage-manager (=0.10.0-rc)
Filename: 0.10.0-rc/zenoh-backend-influxdb_0.10.0-rc_amd64.deb
Size: 1671028
MD5sum: 71259d952276fb71ebc92186fa2c7eec
SHA1: 2991431a9e96b5195e6f76cb446c4f05708e3f81
SHA256: 6433ba00de5315635b29d68634e3fc08e807dc25a65e4c8f8eaaade326e0c35a
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Backend for Zenoh using InfluxDB
.
[](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# InfluxDB backend
.
In Zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on an
[InfluxDB](https://www.influxdata.com/products/influxdb/) server
to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_influxdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
:warning: InfluxDB 2.x is not yet supported. InfluxDB 1.8 minimum is required.
.
-------------------------------
## :warning: Documentation for previous 0.5 versions:
The following documentation related to the version currently in development in
"master" branch: 0.6.x.
.
For previous versions see the README and code of the corresponding tagged
version:
-
[0.5.0-beta.9](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.9#readme)
-
[0.5.0-beta.8](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.8#readme)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_influxdb` library file is available in `~/.zenoh/lib`.
- You have an InfluxDB service running and listening on
`http://localhost:8086`
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing for example:
```json5
{
plugins: {
// configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
// configuration of a "influxdb" volume (the
"zenoh_backend_influxdb" backend library will be loaded at startup)
influxdb: {
// URL to the InfluxDB service
url: "http://localhost:8086",
private: {
// If needed: InfluxDB credentials, preferably admin for
databases creation and drop
//username: "admin",
//password: "password"
}
}
},
storages: {
// configuration of a "demo" storage using the "influxdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
// this option is optional
strip_prefix: "demo/example",
volume: {
id: "influxdb",
// the database name within InfluxDB
db: "zenoh_example",
// if the database doesn't exist, create it
create_db: true,
// strategy on storage closure
on_closure: "drop_db",
private: {
// If needed: InfluxDB credentials, with read/write
privileges for the database
//username: "user",
//password: "password"
}
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "influxdb" volume (the "zenoh_backend_fs" library will be loaded),
connected to InfluxDB service on http://localhost:8086:
`curl -X PUT -H 'content-type:application/json' -d
'{url:"http://localhost:8086"}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/influxdb`
- Add the "demo" storage using the "influxdb" volume:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",volume:{id:"influxdb",db:"zenoh_example",create_db:true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put some values at different time intervals
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-2" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-3" http://localhost:8000/demo/example/test
.
# Retrive them as a time serie where '_time=[..]' means "infinite time range"
curl -g 'http://localhost:8000/demo/example/test?_time=[..]'
```
.
.
-------------------------------
## Volume configuration
InfluxDB-backed volumes need some configuration to work:
.
- **`"url"`** (**required**) : a URL to the InfluxDB service. Example:
`http://localhost:8086`
.
- **`"username"`** (optional) : an [InfluxDB
admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#admin-users)
user name. It will be used for creation of databases, granting read/write
privileges of databases mapped to storages and dropping of databases and
measurements.
.
- **`"password"`** (optional) : the admin user's password.
.
Both `username` and `password` should be hidden behind a `private` gate, as
shown in the example [above](#setup-via-a-json5-configuration-file). In
general, if you wish for a part of the configuration to be hidden when
configuration is queried, you should hide it behind a `private` gate.
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a `influxdb` backed volume may have additional
configuration through the `volume` section:
- **`"db"`** (optional, string) : the InfluxDB database name the storage will
map into. If not specified, a random name will be generated, and the
corresponding database will be created (even if `"create_db"` is not set).
.
- **`"create_db"`** (optional, boolean) : create the InfluxDB database if not
already existing.
By default the database is not created, unless `"db"` property is not
specified.
*(the value doesn't matter, only the property existence is checked)*
.
- **`"on_closure"`** (optional, string) : the strategy to use when the Storage
is removed. There are 3 options:
- *unset* or `"do_nothing"`: the database remains untouched (this is the
default behaviour)
- `"drop_db"`: the database is dropped (i.e. removed)
- `"drop_series"`: all the series (measurements) are dropped and the database
remains empty.
.
- **`"username"`** (optional, string) : an InfluxDB user name (usually
[non-admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#non-admin-users)).
It will be used to read/write points in the database on GET/PUT/DELETE zenoh
operations.
.
- **`"password"`** (optional, string) : the user's password.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to InfluxDB concepts
Each **storage** will map to an InfluxDB **database**.
Each **key** to store will map to an InfluxDB
[**measurement**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#measurement)
named with the key stripped from the `"strip_prefix"` property (see below).
Each **key/value** put into the storage will map to an InfluxDB
[**point**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#point)
reusing the timestamp set by zenoh
(but with a precision of nanoseconds). The fileds and tags of the point is are
the following:
- `"kind"` tag: the zenoh change kind (`"PUT"` for a value that have been put,
or `"DEL"` to mark the deletion of the key)
- `"timestamp"` field: the original zenoh timestamp
- `"encoding"` field: the value's encoding flag
- `"base64"` field: a boolean indicating if the value is encoded in base64
- `"value"`field: the value as a string, possibly encoded in base64 for binary
values.
.
### Behaviour on deletion
On deletion of a key, all points with a timestamp before the deletion message
are deleted.
A point with `"kind"="DEL`" is inserted (to avoid re-insertion of points with
an older timestamp in case of un-ordered messages).
After a delay (5 seconds), the measurement corresponding to the deleted key is
dropped if it still contains no points.
.
### Behaviour on GET
On GET operations, by default the storage returns only the latest point for
each key/measurement.
This is to be coherent with other backends technologies that only store 1 value
per-key.
If you want to get time-series as a result of a GET operation, you need to
specify a time range via
the `"_time"`argument in your
[Selector](https://github.com/eclipse-zenoh/roadmap/tree/main/rfcs/ALL/Selectors).
.
Examples of selectors:
```bash
# get the complete time-series
/demo/example/**?_time=[..]
.
# get points within a fixed date interval
/demo/example/influxdb/**?_time=[2020-01-01T00:00:00Z..2020-01-02T12:00:00.000000000Z]
.
# get points within a relative date interval
/demo/example/influxdb/**?_time=[now(-2d)..now(-1d)]
```
.
See the [`"_time"`
RFC](https://github.com/eclipse-zenoh/roadmap/blob/main/rfcs/ALL/Selectors/_time.md)
for a complete description of the time range format
.
.
-------------------------------
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-backend-influxdb/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-influxdb` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-influxdb
```
.
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
built with the exact same Rust version than `zenohd`, and using for `zenoh`
dependency the same version (or commit number) than 'zenohd'.
Otherwise, incompatibilities in memory mapping of shared types between `zenohd`
and the library can lead to a `"SIGSEV"` crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
```bash
$ zenohd --version
The zenoh router v0.6.0-beta.1 built with rustc 1.64.0 (a55dd71d5 2022-09-19)
```
Here, `zenohd` has been built with the rustc version `1.64.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.64.0
```
.
And `zenohd` version corresponds to an un-released commit with id `1f20c86`.
Update the `zenoh` dependency in Cargo.lock with this command:
```bash
$ cargo update -p zenoh --precise 1f20c86
```
.
Then build the backend with:
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Package: zenoh-backend-influxdb
Version: 0.10.0-rc
Architecture: armhf
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 4156
Depends: zenoh-plugin-storage-manager (=0.10.0-rc)
Filename: 0.10.0-rc/zenoh-backend-influxdb_0.10.0-rc_armhf.deb
Size: 1280768
MD5sum: 76dd25575a3151221b6edf18663f23a9
SHA1: 8eb85bafe8705b718487d44680fdef38c8a03515
SHA256: f2a89e4918e3bebf07f9d13e1e6100437d8e6b717a33a577d349c658129c7ce1
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Backend for Zenoh using InfluxDB
.
[](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# InfluxDB backend
.
In Zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on an
[InfluxDB](https://www.influxdata.com/products/influxdb/) server
to implement the storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_influxdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
:warning: InfluxDB 2.x is not yet supported. InfluxDB 1.8 minimum is required.
.
-------------------------------
## :warning: Documentation for previous 0.5 versions:
The following documentation related to the version currently in development in
"master" branch: 0.6.x.
.
For previous versions see the README and code of the corresponding tagged
version:
-
[0.5.0-beta.9](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.9#readme)
-
[0.5.0-beta.8](https://github.com/eclipse-zenoh/zenoh-backend-influxdb/tree/0.5.0-beta.8#readme)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_influxdb` library file is available in `~/.zenoh/lib`.
- You have an InfluxDB service running and listening on
`http://localhost:8086`
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing for example:
```json5
{
plugins: {
// configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
// configuration of a "influxdb" volume (the
"zenoh_backend_influxdb" backend library will be loaded at startup)
influxdb: {
// URL to the InfluxDB service
url: "http://localhost:8086",
private: {
// If needed: InfluxDB credentials, preferably admin for
databases creation and drop
//username: "admin",
//password: "password"
}
}
},
storages: {
// configuration of a "demo" storage using the "influxdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
// this option is optional
strip_prefix: "demo/example",
volume: {
id: "influxdb",
// the database name within InfluxDB
db: "zenoh_example",
// if the database doesn't exist, create it
create_db: true,
// strategy on storage closure
on_closure: "drop_db",
private: {
// If needed: InfluxDB credentials, with read/write
privileges for the database
//username: "user",
//password: "password"
}
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "influxdb" volume (the "zenoh_backend_fs" library will be loaded),
connected to InfluxDB service on http://localhost:8086:
`curl -X PUT -H 'content-type:application/json' -d
'{url:"http://localhost:8086"}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/influxdb`
- Add the "demo" storage using the "influxdb" volume:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",volume:{id:"influxdb",db:"zenoh_example",create_db:true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put some values at different time intervals
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-2" http://localhost:8000/demo/example/test
curl -X PUT -d "TEST-3" http://localhost:8000/demo/example/test
.
# Retrive them as a time serie where '_time=[..]' means "infinite time range"
curl -g 'http://localhost:8000/demo/example/test?_time=[..]'
```
.
.
-------------------------------
## Volume configuration
InfluxDB-backed volumes need some configuration to work:
.
- **`"url"`** (**required**) : a URL to the InfluxDB service. Example:
`http://localhost:8086`
.
- **`"username"`** (optional) : an [InfluxDB
admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#admin-users)
user name. It will be used for creation of databases, granting read/write
privileges of databases mapped to storages and dropping of databases and
measurements.
.
- **`"password"`** (optional) : the admin user's password.
.
Both `username` and `password` should be hidden behind a `private` gate, as
shown in the example [above](#setup-via-a-json5-configuration-file). In
general, if you wish for a part of the configuration to be hidden when
configuration is queried, you should hide it behind a `private` gate.
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a `influxdb` backed volume may have additional
configuration through the `volume` section:
- **`"db"`** (optional, string) : the InfluxDB database name the storage will
map into. If not specified, a random name will be generated, and the
corresponding database will be created (even if `"create_db"` is not set).
.
- **`"create_db"`** (optional, boolean) : create the InfluxDB database if not
already existing.
By default the database is not created, unless `"db"` property is not
specified.
*(the value doesn't matter, only the property existence is checked)*
.
- **`"on_closure"`** (optional, string) : the strategy to use when the Storage
is removed. There are 3 options:
- *unset* or `"do_nothing"`: the database remains untouched (this is the
default behaviour)
- `"drop_db"`: the database is dropped (i.e. removed)
- `"drop_series"`: all the series (measurements) are dropped and the database
remains empty.
.
- **`"username"`** (optional, string) : an InfluxDB user name (usually
[non-admin](https://docs.influxdata.com/influxdb/v1.8/administration/authentication_and_authorization/#non-admin-users)).
It will be used to read/write points in the database on GET/PUT/DELETE zenoh
operations.
.
- **`"password"`** (optional, string) : the user's password.
.
-------------------------------
## **Behaviour of the backend**
.
### Mapping to InfluxDB concepts
Each **storage** will map to an InfluxDB **database**.
Each **key** to store will map to an InfluxDB
[**measurement**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#measurement)
named with the key stripped from the `"strip_prefix"` property (see below).
Each **key/value** put into the storage will map to an InfluxDB
[**point**](https://docs.influxdata.com/influxdb/v1.8/concepts/key_concepts/#point)
reusing the timestamp set by zenoh
(but with a precision of nanoseconds). The fileds and tags of the point is are
the following:
- `"kind"` tag: the zenoh change kind (`"PUT"` for a value that have been put,
or `"DEL"` to mark the deletion of the key)
- `"timestamp"` field: the original zenoh timestamp
- `"encoding"` field: the value's encoding flag
- `"base64"` field: a boolean indicating if the value is encoded in base64
- `"value"`field: the value as a string, possibly encoded in base64 for binary
values.
.
### Behaviour on deletion
On deletion of a key, all points with a timestamp before the deletion message
are deleted.
A point with `"kind"="DEL`" is inserted (to avoid re-insertion of points with
an older timestamp in case of un-ordered messages).
After a delay (5 seconds), the measurement corresponding to the deleted key is
dropped if it still contains no points.
.
### Behaviour on GET
On GET operations, by default the storage returns only the latest point for
each key/measurement.
This is to be coherent with other backends technologies that only store 1 value
per-key.
If you want to get time-series as a result of a GET operation, you need to
specify a time range via
the `"_time"`argument in your
[Selector](https://github.com/eclipse-zenoh/roadmap/tree/main/rfcs/ALL/Selectors).
.
Examples of selectors:
```bash
# get the complete time-series
/demo/example/**?_time=[..]
.
# get points within a fixed date interval
/demo/example/influxdb/**?_time=[2020-01-01T00:00:00Z..2020-01-02T12:00:00.000000000Z]
.
# get points within a relative date interval
/demo/example/influxdb/**?_time=[now(-2d)..now(-1d)]
```
.
See the [`"_time"`
RFC](https://github.com/eclipse-zenoh/roadmap/blob/main/rfcs/ALL/Selectors/_time.md)
for a complete description of the time range format
.
.
-------------------------------
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-backend-influxdb/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-influxdb` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-influxdb
```
.
.
-------------------------------
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
built with the exact same Rust version than `zenohd`, and using for `zenoh`
dependency the same version (or commit number) than 'zenohd'.
Otherwise, incompatibilities in memory mapping of shared types between `zenohd`
and the library can lead to a `"SIGSEV"` crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
```bash
$ zenohd --version
The zenoh router v0.6.0-beta.1 built with rustc 1.64.0 (a55dd71d5 2022-09-19)
```
Here, `zenohd` has been built with the rustc version `1.64.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.64.0
```
.
And `zenohd` version corresponds to an un-released commit with id `1f20c86`.
Update the `zenoh` dependency in Cargo.lock with this command:
```bash
$ cargo update -p zenoh --precise 1f20c86
```
.
Then build the backend with:
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-influxdb
Package: zenoh-backend-rocksdb
Version: 0.10.0-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 8633
Depends: zenoh-plugin-storage-manager (=0.10.0-rc)
Filename: 0.10.0-rc/zenoh-backend-rocksdb_0.10.0-rc_arm64.deb
Size: 2628352
MD5sum: 7cb2aeffb7a6a2bd623d153275223910
SHA1: 37bd7a955b51aa87922457e96bbc8970e270af72
SHA256: fbd3460fa9bf3faf696eafef97abfee996cced9ac8b1890ea36751fb1e4d5c8e
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Backend for Zenoh using RocksDB
.
[](https://github.com/eclipse-zenoh/zenoh-backend-rocksdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# RocksDB backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on [RocksDB](https://rocksdb.org/) to implement the
storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_rocksdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_rocksdb` library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_ROCKSDB_ROOT` environment variable to the
directory where you want the RocksDB databases
to be stored. If you don't declare it, the `~/.zenoh/zenoh_backend_rocksdb`
directory will be used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storages" plugin:
storage_manager: {
volumes: {
// configuration of a "rocksdb" volume (the "zenoh_backend_rocksdb"
backend library will be loaded at startup)
rocksdb: {}
},
storages: {
// configuration of a "demo" storage using the "rocksdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "demo/example",
volume: {
id: "rocksdb",
// the RocksDB database will be stored in this directory
(relative to ${ZENOH_BACKEND_ROCKSDB_ROOT})
dir: "example",
// create the RocksDB database if not already existing
create_db: true
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "rocksdb" backend (the "zenoh_backend_rocksdb" library will be
loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/rocksdb`
- Add the "demo" storage using the "rocksdb" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example",volume: {id:
"rocksdb",dir: "example",create_db: true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored in the RocksDB database
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a RocksDB-backed volume must specify some additional
configuration as shown [above](#setup-via-a-json5-configuration-file):
- **`"dir"`** (**required**, string) : The name of directory where the RocksDB
database is stored.
The absolute path will be `${ZENOH_BACKEND_ROCKSDB_ROOT}/
.
[](https://github.com/eclipse-zenoh/zenoh-backend-rocksdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# RocksDB backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on [RocksDB](https://rocksdb.org/) to implement the
storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_rocksdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_rocksdb` library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_ROCKSDB_ROOT` environment variable to the
directory where you want the RocksDB databases
to be stored. If you don't declare it, the `~/.zenoh/zenoh_backend_rocksdb`
directory will be used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storages" plugin:
storage_manager: {
volumes: {
// configuration of a "rocksdb" volume (the "zenoh_backend_rocksdb"
backend library will be loaded at startup)
rocksdb: {}
},
storages: {
// configuration of a "demo" storage using the "rocksdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "demo/example",
volume: {
id: "rocksdb",
// the RocksDB database will be stored in this directory
(relative to ${ZENOH_BACKEND_ROCKSDB_ROOT})
dir: "example",
// create the RocksDB database if not already existing
create_db: true
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "rocksdb" backend (the "zenoh_backend_rocksdb" library will be
loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/rocksdb`
- Add the "demo" storage using the "rocksdb" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example",volume: {id:
"rocksdb",dir: "example",create_db: true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored in the RocksDB database
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a RocksDB-backed volume must specify some additional
configuration as shown [above](#setup-via-a-json5-configuration-file):
- **`"dir"`** (**required**, string) : The name of directory where the RocksDB
database is stored.
The absolute path will be `${ZENOH_BACKEND_ROCKSDB_ROOT}/
.
[](https://github.com/eclipse-zenoh/zenoh-backend-rocksdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# RocksDB backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on [RocksDB](https://rocksdb.org/) to implement the
storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_rocksdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_rocksdb` library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_ROCKSDB_ROOT` environment variable to the
directory where you want the RocksDB databases
to be stored. If you don't declare it, the `~/.zenoh/zenoh_backend_rocksdb`
directory will be used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storages" plugin:
storage_manager: {
volumes: {
// configuration of a "rocksdb" volume (the "zenoh_backend_rocksdb"
backend library will be loaded at startup)
rocksdb: {}
},
storages: {
// configuration of a "demo" storage using the "rocksdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "demo/example",
volume: {
id: "rocksdb",
// the RocksDB database will be stored in this directory
(relative to ${ZENOH_BACKEND_ROCKSDB_ROOT})
dir: "example",
// create the RocksDB database if not already existing
create_db: true
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "rocksdb" backend (the "zenoh_backend_rocksdb" library will be
loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/rocksdb`
- Add the "demo" storage using the "rocksdb" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example",volume: {id:
"rocksdb",dir: "example",create_db: true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored in the RocksDB database
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a RocksDB-backed volume must specify some additional
configuration as shown [above](#setup-via-a-json5-configuration-file):
- **`"dir"`** (**required**, string) : The name of directory where the RocksDB
database is stored.
The absolute path will be `${ZENOH_BACKEND_ROCKSDB_ROOT}/
.
[](https://github.com/eclipse-zenoh/zenoh-backend-rocksdb/actions?query=workflow%3A%22CI%22)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# RocksDB backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh documentation](http://zenoh.io/docs/manual/backends/) for more
details.
.
This backend relies on [RocksDB](https://rocksdb.org/) to implement the
storages.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`zenoh_backend_rocksdb`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
-------------------------------
## **Examples of usage**
.
Prerequisites:
- You have a zenoh router (`zenohd`) installed, and the
`zenoh_backend_rocksdb` library file is available in `~/.zenoh/lib`.
- Declare the `ZENOH_BACKEND_ROCKSDB_ROOT` environment variable to the
directory where you want the RocksDB databases
to be stored. If you don't declare it, the `~/.zenoh/zenoh_backend_rocksdb`
directory will be used.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
```json5
{
plugins: {
// configuration of "storages" plugin:
storage_manager: {
volumes: {
// configuration of a "rocksdb" volume (the "zenoh_backend_rocksdb"
backend library will be loaded at startup)
rocksdb: {}
},
storages: {
// configuration of a "demo" storage using the "rocksdb" volume
demo: {
// the key expression this storage will subscribes to
key_expr: "demo/example/**",
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "demo/example",
volume: {
id: "rocksdb",
// the RocksDB database will be stored in this directory
(relative to ${ZENOH_BACKEND_ROCKSDB_ROOT})
dir: "example",
// create the RocksDB database if not already existing
create_db: true
}
}
}
},
// Optionally, add the REST plugin
rest: { http_port: 8000 }
}
}
```
- Run the zenoh router with:
`zenohd -c zenoh.json5`
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router, with write permissions to its admin space:
`zenohd --adminspace-permissions rw`
- Add the "rocksdb" backend (the "zenoh_backend_rocksdb" library will be
loaded):
`curl -X PUT -H 'content-type:application/json' -d '{}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/rocksdb`
- Add the "demo" storage using the "rocksdb" backend:
`curl -X PUT -H 'content-type:application/json' -d
'{key_expr:"demo/example/**",strip_prefix:"demo/example",volume: {id:
"rocksdb",dir: "example",create_db: true}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/demo`
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
```bash
# Put values that will be stored in the RocksDB database
curl -X PUT -d "TEST-1" http://localhost:8000/demo/example/test-1
curl -X PUT -d "B" http://localhost:8000/demo/example/a/b
.
# Retrive the values
curl http://localhost:8000/demo/example/**
```
.
-------------------------------
## Volume-specific storage configuration
Storages relying on a RocksDB-backed volume must specify some additional
configuration as shown [above](#setup-via-a-json5-configuration-file):
- **`"dir"`** (**required**, string) : The name of directory where the RocksDB
database is stored.
The absolute path will be `${ZENOH_BACKEND_ROCKSDB_ROOT}/
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/vSDSpqnbkm)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
# S3 backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh
documentation](https://zenoh.io/docs/manual/plugin-storage-manager/#backends-and-volumes)
for more details.
.
This backend relies on [Amazon S3](https://aws.amazon.com/s3/?nc1=h_ls) to
implement the storages. It is also compatible to work with
[MinIO](https://min.io/) object storage.
.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`libzenoh_backend_s3`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
---
.
## **Examples of usage**
.
Prerequisites:
.
- You have a zenoh router (`zenohd`) installed, and the `libzenoh_backend_s3`
library file is available in `~/.zenoh/lib`. Alternatively we can set a symlink
to the library, for instance by running:
.
```
ln -s ~/zenoh-backend-s3/target/release/libzenoh_backend_s3.dylib
~/.zenoh/lib/libzenoh_backend_s3.dylib
```
.
- You have an S3 instance running, this could be an AmazonS3 instance or a
MinIO instance.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API
(see https://zenoh.io/docs/manual/plugin-storage-manager/).
.
**Setting up a MinIO instance**
.
In order to run the examples of usage from the following section, it is
convenient to launch a MinIO instance. To launch MinIO on a Docker container
you first, install MinIO with
.
```
docker pull minio/minio
```
.
And then you can use the following command to launch the instance:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data quay.io/minio/minio server data --console-address
':9090'
```
.
If successful, then the console can be accessed on http://localhost:9090.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
.
```json5
{
plugins: {
// Configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
s3: {
// AWS region to which connect (see
https://docs.aws.amazon.com/general/latest/gr/s3.html).
// This field is mandatory if you are going to communicate with an
AWS S3 server and
// optional in case you are working with a MinIO S3 server.
region: "eu-west-1",
.
// Endpoint where the S3 server is located.
// This parameter allows you to specify a custom endpoint when
working with a MinIO S3
// server.
// This field is mandatory if you are working with a MinIO server
and optional in case
// you are working with an AWS S3 server as long as you specified
the region, in which
// case the endpoint will be resolved automatically.
url: "https://s3.eu-west-1.amazonaws.com",
.
// Optional TLS specific parameters to enable HTTPS with MinIO.
Configuration shared by
// all the associated storages.
tls: {
// Certificate authority to authenticate the server.
root_ca_certificate: "/home/user/certificates/minio/ca.pem",
},
},
},
storages: {
// Configuration of a "demo" storage using the S3 volume. Each
storage is associated to a
// single S3 bucket.
s3_storage: {
// The key expression this storage will subscribes to
key_expr: "s3/example/*",
.
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "s3/example",
.
volume: {
// Id of the volume this storage is associated to
id: "s3",
.
// Bucket to which this storage is associated to
bucket: "zenoh-bucket",
.
// The storage attempts to create the bucket, but if the bucket
already exists and is
// owned by you, then with 'reuse_bucket' you can associate that
preexisting bucket to
// the storage, otherwise it will fail.
reuse_bucket: true,
.
// If the storage is read only, it will only handle GET requests
read_only: false,
.
// strategy on storage closure, either `destroy_bucket` or
`do_nothing`
on_closure: "destroy_bucket",
.
private: {
// Credentials for interacting with the S3 bucket
access_key: "SARASAFODNN7EXAMPLE",
secret_key: "asADasWdKALsI/ASDP22NG/pWokSSLqEXAMPLEKEY",
},
},
},
},
},
// Optionally, add the REST plugin
rest: { http_port: 8000 },
},
}
```
.
- Run the zenoh router with:
```
zenohd -c zenoh.json5
```
.
**Volume configuration when working with AWS S3 storage**
.
When working with the AWS S3 storage, the region must be specified following
the region names indicated in the [Amazon Simple Storage Service endpoints and
quotas
](https://docs.aws.amazon.com/general/latest/gr/s3.html) documentation. The url
of the endpoint is not required as the internal endpoint resolver will
automatically
find which one is the endpoint associated to the region specified.
.
All the storages associated to the volume will use the same region.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
// AWS region to which connect
region: "eu-west-1",
}
},
...
}
```
.
**Volume configuration when working with MinIO**
.
Inversely, when working with a MinIO S3 storage, then we need to specify the
endpoint of the storage rather than the region, which will be ignored by the
MinIO server. We can save ourselves to specify the region in that case.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
url: "http://localhost:9000",
}
},
...
}
```
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router:
```
cargo run --bin=zenohd
```
- Add the "s3" backend (the "zenoh_backend_s3" library will be loaded):
```
curl -X PUT -H 'content-type:application/json' -d '{url:
"http://localhost:9000", private: {access_key: "AKIAIOSFODNN7EXAMPLE",
secret_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/s3
```
- Add the "s3_storage" storage using the "s3" backend:
```
curl -X PUT -H 'content-type:application/json' -d '{key_expr:"s3/example/*",
strip_prefix:"s3/example", volume: {id: "s3", bucket: "zenoh-bucket",
create_bucket: true, region: "eu-west-3", on_closure: "do_nothing", private:
{access_key: "AKIAIOSFODNN7EXAMPLE", secret_key:
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage
```
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
.
```bash
# Put values that will be stored in the S3 storage
curl -X PUT -H 'content-type:application/json' -d '{"example_key":
"example_value"}' http://0.0.0.0:8000/s3/example/test
.
# To get the stored object
curl -X GET -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the previous object
curl -X DELETE -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the whole storage and the bucket if configured (note in order for
this test to work, you need to setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage'
.
# To delete the whole volume (note in order for this test to work, you need to
setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/volumes/s3'
```
.
## **Enabling TLS on MinIO**
.
In order to establish secure communication through HTTPS we need to provide a
certificate of the certificate authority that validates the server credentials.
.
TLS certificates can be generated as explained in the [zenoh documentation
using Minica](https://zenoh.io/docs/manual/tls/). When running
.
```
minica --domains localhost
```
.
a private key, a public certificate and a certificate authority certificate is
generated:
.
```
└── certificates
├── localhost
│  ├── cert.pem
│  └── key.pem
├── minica-key.pem
└── minica.pem
```
.
On the config file, we need to specify the `root_ca_certificate` as this will
allow the s3 plugin to validate the MinIO server keys.
Example:
.
```
tls: {
root_ca_certificate: "/home/user/certificates/minio/minica.pem",
},
```
.
Here, the `root_ca_certificate` corresponds to the generated _minica.pem_ file.
.
The _cert.pem_ and _key.pem_ files correspond to the public certificate and
private key respectively. We need to rename them as _public.crt_ and
_private.key_ respectively and store them under the MinIO configuration
directory (as specified in the [MinIO
documentation](https://min.io/docs/minio/linux/operations/network-encryption.html#enabling-tls)).
In case you are using running a docker container as previously shown, then we
will need to mount the folder containing the certificates as a volume;
supposing we stored our certificates under `${HOME}/minio/certs`, we need to
start our container as follows:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data -v ${HOME}/minio/certs:/certs quay.io/minio/minio
server data --certs-dir certs --console-address ':9090'
```
.
Finally the volume configuration should then look like:
.
```
storage_manager: {
volumes: {
s3: {
// Endpoint where the S3 server is located
url: "https://localhost:9000",
.
// Configure TLS specific parameters
tls: {
root_ca_certificate:
"/home/user/certificates/minio_certs/minica.pem",
},
}
},
```
.
_Note: do not forget to modify the endpoint protocol, for instance from
`http://localhost:9090` to `https://localhost:9090`_
.
---
.
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
.
- https://download.eclipse.org/zenoh/zenoh-backend-s3/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-s3` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-s3
```
.
---
.
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
> built with the exact same Rust version than `zenohd`. Otherwise,
incompatibilities in memory mapping
> of shared types between `zenohd` and the library can lead to a `"SIGSEV"`
crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
.
```bash
$ zenohd --version
zenohd v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0 (84c898d65
2023-04-16)
The zenoh router v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0
(84c898d65 2023-04-16)
```
.
Here, `zenohd` has been built with the rustc version `1.69.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.69.0
```
.
And then build the backend with:
.
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-s3
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-s3
Package: zenoh-backend-s3
Version: 0.10.0-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 10890
Depends: zenoh-plugin-storage-manager (=0.10.0-rc)
Filename: 0.10.0-rc/zenoh-backend-s3_0.10.0-rc_arm64.deb
Size: 2769628
MD5sum: eff8c4419df1201db82d12c75ae6495f
SHA1: 7b72ca7101ba8380076ef66db7e77a73fa4f3c5c
SHA256: 713736d04108f7156d6b8025ab25d47739d2d424b33140e11012fa3029b51245
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Backend for Zenoh using AWS S3 API
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/vSDSpqnbkm)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
# S3 backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh
documentation](https://zenoh.io/docs/manual/plugin-storage-manager/#backends-and-volumes)
for more details.
.
This backend relies on [Amazon S3](https://aws.amazon.com/s3/?nc1=h_ls) to
implement the storages. It is also compatible to work with
[MinIO](https://min.io/) object storage.
.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`libzenoh_backend_s3`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
---
.
## **Examples of usage**
.
Prerequisites:
.
- You have a zenoh router (`zenohd`) installed, and the `libzenoh_backend_s3`
library file is available in `~/.zenoh/lib`. Alternatively we can set a symlink
to the library, for instance by running:
.
```
ln -s ~/zenoh-backend-s3/target/release/libzenoh_backend_s3.dylib
~/.zenoh/lib/libzenoh_backend_s3.dylib
```
.
- You have an S3 instance running, this could be an AmazonS3 instance or a
MinIO instance.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API
(see https://zenoh.io/docs/manual/plugin-storage-manager/).
.
**Setting up a MinIO instance**
.
In order to run the examples of usage from the following section, it is
convenient to launch a MinIO instance. To launch MinIO on a Docker container
you first, install MinIO with
.
```
docker pull minio/minio
```
.
And then you can use the following command to launch the instance:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data quay.io/minio/minio server data --console-address
':9090'
```
.
If successful, then the console can be accessed on http://localhost:9090.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
.
```json5
{
plugins: {
// Configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
s3: {
// AWS region to which connect (see
https://docs.aws.amazon.com/general/latest/gr/s3.html).
// This field is mandatory if you are going to communicate with an
AWS S3 server and
// optional in case you are working with a MinIO S3 server.
region: "eu-west-1",
.
// Endpoint where the S3 server is located.
// This parameter allows you to specify a custom endpoint when
working with a MinIO S3
// server.
// This field is mandatory if you are working with a MinIO server
and optional in case
// you are working with an AWS S3 server as long as you specified
the region, in which
// case the endpoint will be resolved automatically.
url: "https://s3.eu-west-1.amazonaws.com",
.
// Optional TLS specific parameters to enable HTTPS with MinIO.
Configuration shared by
// all the associated storages.
tls: {
// Certificate authority to authenticate the server.
root_ca_certificate: "/home/user/certificates/minio/ca.pem",
},
},
},
storages: {
// Configuration of a "demo" storage using the S3 volume. Each
storage is associated to a
// single S3 bucket.
s3_storage: {
// The key expression this storage will subscribes to
key_expr: "s3/example/*",
.
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "s3/example",
.
volume: {
// Id of the volume this storage is associated to
id: "s3",
.
// Bucket to which this storage is associated to
bucket: "zenoh-bucket",
.
// The storage attempts to create the bucket, but if the bucket
already exists and is
// owned by you, then with 'reuse_bucket' you can associate that
preexisting bucket to
// the storage, otherwise it will fail.
reuse_bucket: true,
.
// If the storage is read only, it will only handle GET requests
read_only: false,
.
// strategy on storage closure, either `destroy_bucket` or
`do_nothing`
on_closure: "destroy_bucket",
.
private: {
// Credentials for interacting with the S3 bucket
access_key: "SARASAFODNN7EXAMPLE",
secret_key: "asADasWdKALsI/ASDP22NG/pWokSSLqEXAMPLEKEY",
},
},
},
},
},
// Optionally, add the REST plugin
rest: { http_port: 8000 },
},
}
```
.
- Run the zenoh router with:
```
zenohd -c zenoh.json5
```
.
**Volume configuration when working with AWS S3 storage**
.
When working with the AWS S3 storage, the region must be specified following
the region names indicated in the [Amazon Simple Storage Service endpoints and
quotas
](https://docs.aws.amazon.com/general/latest/gr/s3.html) documentation. The url
of the endpoint is not required as the internal endpoint resolver will
automatically
find which one is the endpoint associated to the region specified.
.
All the storages associated to the volume will use the same region.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
// AWS region to which connect
region: "eu-west-1",
}
},
...
}
```
.
**Volume configuration when working with MinIO**
.
Inversely, when working with a MinIO S3 storage, then we need to specify the
endpoint of the storage rather than the region, which will be ignored by the
MinIO server. We can save ourselves to specify the region in that case.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
url: "http://localhost:9000",
}
},
...
}
```
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router:
```
cargo run --bin=zenohd
```
- Add the "s3" backend (the "zenoh_backend_s3" library will be loaded):
```
curl -X PUT -H 'content-type:application/json' -d '{url:
"http://localhost:9000", private: {access_key: "AKIAIOSFODNN7EXAMPLE",
secret_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/s3
```
- Add the "s3_storage" storage using the "s3" backend:
```
curl -X PUT -H 'content-type:application/json' -d '{key_expr:"s3/example/*",
strip_prefix:"s3/example", volume: {id: "s3", bucket: "zenoh-bucket",
create_bucket: true, region: "eu-west-3", on_closure: "do_nothing", private:
{access_key: "AKIAIOSFODNN7EXAMPLE", secret_key:
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage
```
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
.
```bash
# Put values that will be stored in the S3 storage
curl -X PUT -H 'content-type:application/json' -d '{"example_key":
"example_value"}' http://0.0.0.0:8000/s3/example/test
.
# To get the stored object
curl -X GET -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the previous object
curl -X DELETE -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the whole storage and the bucket if configured (note in order for
this test to work, you need to setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage'
.
# To delete the whole volume (note in order for this test to work, you need to
setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/volumes/s3'
```
.
## **Enabling TLS on MinIO**
.
In order to establish secure communication through HTTPS we need to provide a
certificate of the certificate authority that validates the server credentials.
.
TLS certificates can be generated as explained in the [zenoh documentation
using Minica](https://zenoh.io/docs/manual/tls/). When running
.
```
minica --domains localhost
```
.
a private key, a public certificate and a certificate authority certificate is
generated:
.
```
└── certificates
├── localhost
│  ├── cert.pem
│  └── key.pem
├── minica-key.pem
└── minica.pem
```
.
On the config file, we need to specify the `root_ca_certificate` as this will
allow the s3 plugin to validate the MinIO server keys.
Example:
.
```
tls: {
root_ca_certificate: "/home/user/certificates/minio/minica.pem",
},
```
.
Here, the `root_ca_certificate` corresponds to the generated _minica.pem_ file.
.
The _cert.pem_ and _key.pem_ files correspond to the public certificate and
private key respectively. We need to rename them as _public.crt_ and
_private.key_ respectively and store them under the MinIO configuration
directory (as specified in the [MinIO
documentation](https://min.io/docs/minio/linux/operations/network-encryption.html#enabling-tls)).
In case you are using running a docker container as previously shown, then we
will need to mount the folder containing the certificates as a volume;
supposing we stored our certificates under `${HOME}/minio/certs`, we need to
start our container as follows:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data -v ${HOME}/minio/certs:/certs quay.io/minio/minio
server data --certs-dir certs --console-address ':9090'
```
.
Finally the volume configuration should then look like:
.
```
storage_manager: {
volumes: {
s3: {
// Endpoint where the S3 server is located
url: "https://localhost:9000",
.
// Configure TLS specific parameters
tls: {
root_ca_certificate:
"/home/user/certificates/minio_certs/minica.pem",
},
}
},
```
.
_Note: do not forget to modify the endpoint protocol, for instance from
`http://localhost:9090` to `https://localhost:9090`_
.
---
.
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
.
- https://download.eclipse.org/zenoh/zenoh-backend-s3/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-s3` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-s3
```
.
---
.
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
> built with the exact same Rust version than `zenohd`. Otherwise,
incompatibilities in memory mapping
> of shared types between `zenohd` and the library can lead to a `"SIGSEV"`
crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
.
```bash
$ zenohd --version
zenohd v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0 (84c898d65
2023-04-16)
The zenoh router v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0
(84c898d65 2023-04-16)
```
.
Here, `zenohd` has been built with the rustc version `1.69.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.69.0
```
.
And then build the backend with:
.
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-s3
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-s3
Package: zenoh-backend-s3
Version: 0.10.0-rc
Architecture: armhf
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9542
Depends: zenoh-plugin-storage-manager (=0.10.0-rc)
Filename: 0.10.0-rc/zenoh-backend-s3_0.10.0-rc_armhf.deb
Size: 2441424
MD5sum: e16f8e18281b0fea6472deab059dbc9e
SHA1: 9a18777bd55f962cee87f9275777e05e8c92f03f
SHA256: 9c58157ce92644558021b78a68a8adc016b56eeaf3fff3162b123be4402fb838
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Backend for Zenoh using AWS S3 API
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/vSDSpqnbkm)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
# S3 backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh
documentation](https://zenoh.io/docs/manual/plugin-storage-manager/#backends-and-volumes)
for more details.
.
This backend relies on [Amazon S3](https://aws.amazon.com/s3/?nc1=h_ls) to
implement the storages. It is also compatible to work with
[MinIO](https://min.io/) object storage.
.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`libzenoh_backend_s3`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
---
.
## **Examples of usage**
.
Prerequisites:
.
- You have a zenoh router (`zenohd`) installed, and the `libzenoh_backend_s3`
library file is available in `~/.zenoh/lib`. Alternatively we can set a symlink
to the library, for instance by running:
.
```
ln -s ~/zenoh-backend-s3/target/release/libzenoh_backend_s3.dylib
~/.zenoh/lib/libzenoh_backend_s3.dylib
```
.
- You have an S3 instance running, this could be an AmazonS3 instance or a
MinIO instance.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API
(see https://zenoh.io/docs/manual/plugin-storage-manager/).
.
**Setting up a MinIO instance**
.
In order to run the examples of usage from the following section, it is
convenient to launch a MinIO instance. To launch MinIO on a Docker container
you first, install MinIO with
.
```
docker pull minio/minio
```
.
And then you can use the following command to launch the instance:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data quay.io/minio/minio server data --console-address
':9090'
```
.
If successful, then the console can be accessed on http://localhost:9090.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
.
```json5
{
plugins: {
// Configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
s3: {
// AWS region to which connect (see
https://docs.aws.amazon.com/general/latest/gr/s3.html).
// This field is mandatory if you are going to communicate with an
AWS S3 server and
// optional in case you are working with a MinIO S3 server.
region: "eu-west-1",
.
// Endpoint where the S3 server is located.
// This parameter allows you to specify a custom endpoint when
working with a MinIO S3
// server.
// This field is mandatory if you are working with a MinIO server
and optional in case
// you are working with an AWS S3 server as long as you specified
the region, in which
// case the endpoint will be resolved automatically.
url: "https://s3.eu-west-1.amazonaws.com",
.
// Optional TLS specific parameters to enable HTTPS with MinIO.
Configuration shared by
// all the associated storages.
tls: {
// Certificate authority to authenticate the server.
root_ca_certificate: "/home/user/certificates/minio/ca.pem",
},
},
},
storages: {
// Configuration of a "demo" storage using the S3 volume. Each
storage is associated to a
// single S3 bucket.
s3_storage: {
// The key expression this storage will subscribes to
key_expr: "s3/example/*",
.
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "s3/example",
.
volume: {
// Id of the volume this storage is associated to
id: "s3",
.
// Bucket to which this storage is associated to
bucket: "zenoh-bucket",
.
// The storage attempts to create the bucket, but if the bucket
already exists and is
// owned by you, then with 'reuse_bucket' you can associate that
preexisting bucket to
// the storage, otherwise it will fail.
reuse_bucket: true,
.
// If the storage is read only, it will only handle GET requests
read_only: false,
.
// strategy on storage closure, either `destroy_bucket` or
`do_nothing`
on_closure: "destroy_bucket",
.
private: {
// Credentials for interacting with the S3 bucket
access_key: "SARASAFODNN7EXAMPLE",
secret_key: "asADasWdKALsI/ASDP22NG/pWokSSLqEXAMPLEKEY",
},
},
},
},
},
// Optionally, add the REST plugin
rest: { http_port: 8000 },
},
}
```
.
- Run the zenoh router with:
```
zenohd -c zenoh.json5
```
.
**Volume configuration when working with AWS S3 storage**
.
When working with the AWS S3 storage, the region must be specified following
the region names indicated in the [Amazon Simple Storage Service endpoints and
quotas
](https://docs.aws.amazon.com/general/latest/gr/s3.html) documentation. The url
of the endpoint is not required as the internal endpoint resolver will
automatically
find which one is the endpoint associated to the region specified.
.
All the storages associated to the volume will use the same region.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
// AWS region to which connect
region: "eu-west-1",
}
},
...
}
```
.
**Volume configuration when working with MinIO**
.
Inversely, when working with a MinIO S3 storage, then we need to specify the
endpoint of the storage rather than the region, which will be ignored by the
MinIO server. We can save ourselves to specify the region in that case.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
url: "http://localhost:9000",
}
},
...
}
```
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router:
```
cargo run --bin=zenohd
```
- Add the "s3" backend (the "zenoh_backend_s3" library will be loaded):
```
curl -X PUT -H 'content-type:application/json' -d '{url:
"http://localhost:9000", private: {access_key: "AKIAIOSFODNN7EXAMPLE",
secret_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/s3
```
- Add the "s3_storage" storage using the "s3" backend:
```
curl -X PUT -H 'content-type:application/json' -d '{key_expr:"s3/example/*",
strip_prefix:"s3/example", volume: {id: "s3", bucket: "zenoh-bucket",
create_bucket: true, region: "eu-west-3", on_closure: "do_nothing", private:
{access_key: "AKIAIOSFODNN7EXAMPLE", secret_key:
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage
```
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
.
```bash
# Put values that will be stored in the S3 storage
curl -X PUT -H 'content-type:application/json' -d '{"example_key":
"example_value"}' http://0.0.0.0:8000/s3/example/test
.
# To get the stored object
curl -X GET -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the previous object
curl -X DELETE -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the whole storage and the bucket if configured (note in order for
this test to work, you need to setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage'
.
# To delete the whole volume (note in order for this test to work, you need to
setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/volumes/s3'
```
.
## **Enabling TLS on MinIO**
.
In order to establish secure communication through HTTPS we need to provide a
certificate of the certificate authority that validates the server credentials.
.
TLS certificates can be generated as explained in the [zenoh documentation
using Minica](https://zenoh.io/docs/manual/tls/). When running
.
```
minica --domains localhost
```
.
a private key, a public certificate and a certificate authority certificate is
generated:
.
```
└── certificates
├── localhost
│  ├── cert.pem
│  └── key.pem
├── minica-key.pem
└── minica.pem
```
.
On the config file, we need to specify the `root_ca_certificate` as this will
allow the s3 plugin to validate the MinIO server keys.
Example:
.
```
tls: {
root_ca_certificate: "/home/user/certificates/minio/minica.pem",
},
```
.
Here, the `root_ca_certificate` corresponds to the generated _minica.pem_ file.
.
The _cert.pem_ and _key.pem_ files correspond to the public certificate and
private key respectively. We need to rename them as _public.crt_ and
_private.key_ respectively and store them under the MinIO configuration
directory (as specified in the [MinIO
documentation](https://min.io/docs/minio/linux/operations/network-encryption.html#enabling-tls)).
In case you are using running a docker container as previously shown, then we
will need to mount the folder containing the certificates as a volume;
supposing we stored our certificates under `${HOME}/minio/certs`, we need to
start our container as follows:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data -v ${HOME}/minio/certs:/certs quay.io/minio/minio
server data --certs-dir certs --console-address ':9090'
```
.
Finally the volume configuration should then look like:
.
```
storage_manager: {
volumes: {
s3: {
// Endpoint where the S3 server is located
url: "https://localhost:9000",
.
// Configure TLS specific parameters
tls: {
root_ca_certificate:
"/home/user/certificates/minio_certs/minica.pem",
},
}
},
```
.
_Note: do not forget to modify the endpoint protocol, for instance from
`http://localhost:9090` to `https://localhost:9090`_
.
---
.
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
.
- https://download.eclipse.org/zenoh/zenoh-backend-s3/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-s3` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-s3
```
.
---
.
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
> built with the exact same Rust version than `zenohd`. Otherwise,
incompatibilities in memory mapping
> of shared types between `zenohd` and the library can lead to a `"SIGSEV"`
crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
.
```bash
$ zenohd --version
zenohd v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0 (84c898d65
2023-04-16)
The zenoh router v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0
(84c898d65 2023-04-16)
```
.
Here, `zenohd` has been built with the rustc version `1.69.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.69.0
```
.
And then build the backend with:
.
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-s3
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-s3
Package: zenoh-backend-s3
Version: 0.10.0-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 12097
Depends: zenoh-plugin-storage-manager (=0.10.0-rc)
Filename: 0.10.0-rc/zenoh-backend-s3_0.10.0-rc_amd64.deb
Size: 3043856
MD5sum: da4ad688feed254b43989a6a75c5945d
SHA1: c9f0e47d748faab4d59e44b48bb1dcebdc388f6a
SHA256: ebfddae2d7ce5c3974cf6c201d2b4fcc03db884bf0d892a43521dc31ccaf30c5
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Backend for Zenoh using AWS S3 API
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/vSDSpqnbkm)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
.
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
# S3 backend
.
In zenoh a backend is a storage technology (such as DBMS, time-series database,
file system...) alowing to store the
keys/values publications made via zenoh and return them on queries.
See the [zenoh
documentation](https://zenoh.io/docs/manual/plugin-storage-manager/#backends-and-volumes)
for more details.
.
This backend relies on [Amazon S3](https://aws.amazon.com/s3/?nc1=h_ls) to
implement the storages. It is also compatible to work with
[MinIO](https://min.io/) object storage.
.
Its library name (without OS specific prefix and extension) that zenoh will
rely on to find it and load it is **`libzenoh_backend_s3`**.
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
---
.
## **Examples of usage**
.
Prerequisites:
.
- You have a zenoh router (`zenohd`) installed, and the `libzenoh_backend_s3`
library file is available in `~/.zenoh/lib`. Alternatively we can set a symlink
to the library, for instance by running:
.
```
ln -s ~/zenoh-backend-s3/target/release/libzenoh_backend_s3.dylib
~/.zenoh/lib/libzenoh_backend_s3.dylib
```
.
- You have an S3 instance running, this could be an AmazonS3 instance or a
MinIO instance.
.
You can setup storages either at zenoh router startup via a configuration file,
either at runtime via the zenoh admin space, using for instance the REST API
(see https://zenoh.io/docs/manual/plugin-storage-manager/).
.
**Setting up a MinIO instance**
.
In order to run the examples of usage from the following section, it is
convenient to launch a MinIO instance. To launch MinIO on a Docker container
you first, install MinIO with
.
```
docker pull minio/minio
```
.
And then you can use the following command to launch the instance:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data quay.io/minio/minio server data --console-address
':9090'
```
.
If successful, then the console can be accessed on http://localhost:9090.
.
### **Setup via a JSON5 configuration file**
.
- Create a `zenoh.json5` configuration file containing:
.
```json5
{
plugins: {
// Configuration of "storage_manager" plugin:
storage_manager: {
volumes: {
s3: {
// AWS region to which connect (see
https://docs.aws.amazon.com/general/latest/gr/s3.html).
// This field is mandatory if you are going to communicate with an
AWS S3 server and
// optional in case you are working with a MinIO S3 server.
region: "eu-west-1",
.
// Endpoint where the S3 server is located.
// This parameter allows you to specify a custom endpoint when
working with a MinIO S3
// server.
// This field is mandatory if you are working with a MinIO server
and optional in case
// you are working with an AWS S3 server as long as you specified
the region, in which
// case the endpoint will be resolved automatically.
url: "https://s3.eu-west-1.amazonaws.com",
.
// Optional TLS specific parameters to enable HTTPS with MinIO.
Configuration shared by
// all the associated storages.
tls: {
// Certificate authority to authenticate the server.
root_ca_certificate: "/home/user/certificates/minio/ca.pem",
},
},
},
storages: {
// Configuration of a "demo" storage using the S3 volume. Each
storage is associated to a
// single S3 bucket.
s3_storage: {
// The key expression this storage will subscribes to
key_expr: "s3/example/*",
.
// this prefix will be stripped from the received key when
converting to database key.
// i.e.: "demo/example/a/b" will be stored as "a/b"
strip_prefix: "s3/example",
.
volume: {
// Id of the volume this storage is associated to
id: "s3",
.
// Bucket to which this storage is associated to
bucket: "zenoh-bucket",
.
// The storage attempts to create the bucket, but if the bucket
already exists and is
// owned by you, then with 'reuse_bucket' you can associate that
preexisting bucket to
// the storage, otherwise it will fail.
reuse_bucket: true,
.
// If the storage is read only, it will only handle GET requests
read_only: false,
.
// strategy on storage closure, either `destroy_bucket` or
`do_nothing`
on_closure: "destroy_bucket",
.
private: {
// Credentials for interacting with the S3 bucket
access_key: "SARASAFODNN7EXAMPLE",
secret_key: "asADasWdKALsI/ASDP22NG/pWokSSLqEXAMPLEKEY",
},
},
},
},
},
// Optionally, add the REST plugin
rest: { http_port: 8000 },
},
}
```
.
- Run the zenoh router with:
```
zenohd -c zenoh.json5
```
.
**Volume configuration when working with AWS S3 storage**
.
When working with the AWS S3 storage, the region must be specified following
the region names indicated in the [Amazon Simple Storage Service endpoints and
quotas
](https://docs.aws.amazon.com/general/latest/gr/s3.html) documentation. The url
of the endpoint is not required as the internal endpoint resolver will
automatically
find which one is the endpoint associated to the region specified.
.
All the storages associated to the volume will use the same region.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
// AWS region to which connect
region: "eu-west-1",
}
},
...
}
```
.
**Volume configuration when working with MinIO**
.
Inversely, when working with a MinIO S3 storage, then we need to specify the
endpoint of the storage rather than the region, which will be ignored by the
MinIO server. We can save ourselves to specify the region in that case.
.
The volumes section on the config file will look like:
.
```
storage_manager {
volumes: {
s3: {
url: "http://localhost:9000",
}
},
...
}
```
.
### **Setup at runtime via `curl` commands on the admin space**
.
- Run the zenoh router:
```
cargo run --bin=zenohd
```
- Add the "s3" backend (the "zenoh_backend_s3" library will be loaded):
```
curl -X PUT -H 'content-type:application/json' -d '{url:
"http://localhost:9000", private: {access_key: "AKIAIOSFODNN7EXAMPLE",
secret_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/volumes/s3
```
- Add the "s3_storage" storage using the "s3" backend:
```
curl -X PUT -H 'content-type:application/json' -d '{key_expr:"s3/example/*",
strip_prefix:"s3/example", volume: {id: "s3", bucket: "zenoh-bucket",
create_bucket: true, region: "eu-west-3", on_closure: "do_nothing", private:
{access_key: "AKIAIOSFODNN7EXAMPLE", secret_key:
"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"}}}'
http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage
```
.
### **Tests using the REST API**
.
Using `curl` to publish and query keys/values, you can:
.
```bash
# Put values that will be stored in the S3 storage
curl -X PUT -H 'content-type:application/json' -d '{"example_key":
"example_value"}' http://0.0.0.0:8000/s3/example/test
.
# To get the stored object
curl -X GET -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the previous object
curl -X DELETE -H {} -d '{}' http://0.0.0.0:8000/s3/example/test
.
# To delete the whole storage and the bucket if configured (note in order for
this test to work, you need to setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/storages/s3_storage'
.
# To delete the whole volume (note in order for this test to work, you need to
setup adminspace read/write permissions)
curl -X DELETE
'http://0.0.0.0:8000/@/router/local/config/plugins/storage_manager/volumes/s3'
```
.
## **Enabling TLS on MinIO**
.
In order to establish secure communication through HTTPS we need to provide a
certificate of the certificate authority that validates the server credentials.
.
TLS certificates can be generated as explained in the [zenoh documentation
using Minica](https://zenoh.io/docs/manual/tls/). When running
.
```
minica --domains localhost
```
.
a private key, a public certificate and a certificate authority certificate is
generated:
.
```
└── certificates
├── localhost
│  ├── cert.pem
│  └── key.pem
├── minica-key.pem
└── minica.pem
```
.
On the config file, we need to specify the `root_ca_certificate` as this will
allow the s3 plugin to validate the MinIO server keys.
Example:
.
```
tls: {
root_ca_certificate: "/home/user/certificates/minio/minica.pem",
},
```
.
Here, the `root_ca_certificate` corresponds to the generated _minica.pem_ file.
.
The _cert.pem_ and _key.pem_ files correspond to the public certificate and
private key respectively. We need to rename them as _public.crt_ and
_private.key_ respectively and store them under the MinIO configuration
directory (as specified in the [MinIO
documentation](https://min.io/docs/minio/linux/operations/network-encryption.html#enabling-tls)).
In case you are using running a docker container as previously shown, then we
will need to mount the folder containing the certificates as a volume;
supposing we stored our certificates under `${HOME}/minio/certs`, we need to
start our container as follows:
.
```
docker run -p 9000:9000 -p 9090:9090 --user $(id -u):$(id -g) --name minio -e
'MINIO_ROOT_USER=AKIAIOSFODNN7EXAMPLE' -e
'MINIO_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' -v
${HOME}/minio/data:/data -v ${HOME}/minio/certs:/certs quay.io/minio/minio
server data --certs-dir certs --console-address ':9090'
```
.
Finally the volume configuration should then look like:
.
```
storage_manager: {
volumes: {
s3: {
// Endpoint where the S3 server is located
url: "https://localhost:9000",
.
// Configure TLS specific parameters
tls: {
root_ca_certificate:
"/home/user/certificates/minio_certs/minica.pem",
},
}
},
```
.
_Note: do not forget to modify the endpoint protocol, for instance from
`http://localhost:9090` to `https://localhost:9090`_
.
---
.
## How to install it
.
To install the latest release of this backend library, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
.
- https://download.eclipse.org/zenoh/zenoh-backend-s3/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download the `.zip` file.
Unzip it in the same directory than `zenohd` or to any directory where it can
find the backend library (e.g. /usr/lib or ~/.zenoh/lib)
.
### Linux Debian
.
Add Eclipse Zenoh private repository to the sources list, and install the
`zenoh-backend-s3` package:
.
```bash
echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" |
sudo tee -a /etc/apt/sources.list > /dev/null
sudo apt update
sudo apt install zenoh-backend-s3
```
.
---
.
## How to build it
.
> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active
development. When you build from git, make sure you also build from git any
other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.).
It may happen that some changes in git are not compatible with the most recent
packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in
mantaining compatibility between the various git repositories in the Zenoh
project.
.
At first, install [Cargo and
Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). If
you already have the Rust toolchain installed, make sure it is up-to-date with:
.
```bash
$ rustup update
```
.
> :warning: **WARNING** :warning: : As Rust doesn't have a stable ABI, the
backend library should be
> built with the exact same Rust version than `zenohd`. Otherwise,
incompatibilities in memory mapping
> of shared types between `zenohd` and the library can lead to a `"SIGSEV"`
crash.
.
To know the Rust version you're `zenohd` has been built with, use the
`--version` option.
Example:
.
```bash
$ zenohd --version
zenohd v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0 (84c898d65
2023-04-16)
The zenoh router v0.7.0-rc-365-geca888b4-modified built with rustc 1.69.0
(84c898d65 2023-04-16)
```
.
Here, `zenohd` has been built with the rustc version `1.69.0`.
Install and use this toolchain with the following command:
.
```bash
$ rustup default 1.69.0
```
.
And then build the backend with:
.
```bash
$ cargo build --release --all-targets
```
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-backend-s3
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-backend-s3
Package: zenoh-bridge-dds
Version: 0.10.0-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 10899
Depends: libc6 (>= 2.29)
Filename: 0.10.0-rc/zenoh-bridge-dds_0.10.0-rc_amd64.deb
Size: 3455680
MD5sum: 01c44059e6cf73ac1c751a0178398444
SHA1: ffb3376ac75995491d8b1d65ab44c2bd27cec339
SHA256: ea4cf37aec6f6bdeec1a30026509f16307d10d95b555e8ca677ff5c18978c864
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS2 and DDS in general
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Package: zenoh-bridge-dds
Version: 0.10.0-rc
Architecture: armhf
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9164
Depends: libc6:armhf (>= 2.31)
Filename: 0.10.0-rc/zenoh-bridge-dds_0.10.0-rc_armhf.deb
Size: 3082172
MD5sum: 8bf8cb4661544e87673e402d17020a41
SHA1: 330664c2d4799aae55db3bdd7d1e96995ff36022
SHA256: 24012aa34ecce88c02058fbf02b4fdd617b93d2e6bbb4d16a707dfeeb0055e21
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS2 and DDS in general
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Package: zenoh-bridge-dds
Version: 0.10.0-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9530
Depends: libc6:arm64 (>= 2.31)
Filename: 0.10.0-rc/zenoh-bridge-dds_0.10.0-rc_arm64.deb
Size: 3135084
MD5sum: 928b61d534e73492de48c571f841cb2f
SHA1: fef0e4d4b6d7d0ba24de653bf279a8bb9cf41187
SHA256: e5f1a2be1f9a762c323033b2e73c0984f5a3d2d38cf637af913c8e14839c4a14
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS2 and DDS in general
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Package: zenoh-bridge-dds
Version: 0.10.0-rc
Architecture: armel
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9632
Depends: libc6:armel (>= 2.31)
Filename: 0.10.0-rc/zenoh-bridge-dds_0.10.0-rc_armel.deb
Size: 3077192
MD5sum: 39d7a69f43909648fa02ddf7e05ee3dc
SHA1: 1108e3aacaa4751265608003b817343486bafe67
SHA256: ef78a43d69c0b2a0f93b6df6118052af104b2fc65d60c02edd9dc6f3a3eaabf8
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS2 and DDS in general
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds
Package: zenoh-bridge-mqtt
Version: 0.10.0-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 10028
Depends: libc6 (>= 2.29)
Filename: 0.10.0-rc/zenoh-bridge-mqtt_0.10.0-rc_amd64.deb
Size: 3141324
MD5sum: 7f06a9f21d53805e0735b9b06f43f09a
SHA1: a4963f2d1d115750c8b5e0649a5bebe19c31e103
SHA256: 4ca54fc05f432afbb089c638472e80b1a27409307aae2aa8a74122e677ca8b54
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for MQTT
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-mqtt
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-mqtt
Package: zenoh-bridge-mqtt
Version: 0.10.0-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 8684
Depends: libc6:arm64 (>= 2.31)
Filename: 0.10.0-rc/zenoh-bridge-mqtt_0.10.0-rc_arm64.deb
Size: 2845720
MD5sum: dba296f3356241858e390dc7b3a64ca5
SHA1: 83e88cf0f08bbf16386a0b389e1c33e81f2a77d1
SHA256: 831b25812a2f809c0d995122b83c384560afb351ee706354f01f3c8eda717e56
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for MQTT
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-mqtt
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-mqtt
Package: zenoh-bridge-ros1
Version: 0.10.0-rc
Architecture: armel
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9918
Depends: libc6:armel (>= 2.31)
Filename: 0.10.0-rc/zenoh-bridge-ros1_0.10.0-rc_armel.deb
Size: 3033252
MD5sum: dec263191740bd70d4a11a29eb6ee025
SHA1: e73b98d1e7e31165f9fdb355cf33211b8ece7b0c
SHA256: 4b9961c979e13015cff2eec98fcad662a85a2384cef24aa3c1579eb5ef065ca6
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS1
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Package: zenoh-bridge-ros1
Version: 0.10.0-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9744
Depends: libc6:arm64 (>= 2.31)
Filename: 0.10.0-rc/zenoh-bridge-ros1_0.10.0-rc_arm64.deb
Size: 3050764
MD5sum: 6f5a759c3bb4774135f14dda77c4ca09
SHA1: b4d88dcb18dc5d88304eab9626ce3af8474a50ee
SHA256: 17db2d020af61bc553bc0c2e7616ec626ba6f86e748e77570064219e2ec04564
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS1
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Package: zenoh-bridge-ros1
Version: 0.10.0-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 11276
Depends: libc6 (>= 2.29)
Filename: 0.10.0-rc/zenoh-bridge-ros1_0.10.0-rc_amd64.deb
Size: 3391332
MD5sum: 52b53496825c9fe8350aeabc089834c9
SHA1: 0c7d629bc96287b7c54c26afc558fe1b5ea8f4be
SHA256: a2aeb719c59c9ee30f4699a280db9eeef697da06e7c40acf23bbf88c02228bb4
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS1
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Package: zenoh-bridge-ros1
Version: 0.10.0-rc
Architecture: armhf
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9658
Depends: libc6:armhf (>= 2.31)
Filename: 0.10.0-rc/zenoh-bridge-ros1_0.10.0-rc_armhf.deb
Size: 3022472
MD5sum: e39734f898011bfe56429a2eebc53530
SHA1: 7a9b3a2495d3a82676604312194df26f1108952f
SHA256: 09bc979e9d93e69d8f14fd4f1e479dc6a38241a80bbd8bdba46f4cd67442a528
Section: net
Priority: optional
Homepage: http://zenoh.io
Description: Zenoh bridge for ROS1
Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-ros1
Package: zenoh-cpp
Version: 0.10.0.1
Architecture: x86_64
Maintainer: ZettaScale Zenoh Team,
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# DDS plugin and standalone `zenoh-bridge-dds`
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Docker image:** see [below](#Docker-image)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
## Background
The Data Distribution Service (DDS) is a standard for data-centric publish
subscribe. Whilst DDS has been around for quite some time and has a long
history of deployments in various industries, it has recently gained quite a
bit of attentions thanks to its adoption by the Robotic Operating System (ROS2)
-- where it is used for communication between ROS2 nodes.
.
## Robot Swarms and Edge Robotics
As mentioned above, ROS2 has adopted DDS as the mechanism to exchange data
between nodes within and potentially across a robot. That said, due to some of
the very core assumptions at the foundations of the DDS wire-protocol, beside
the fact that it leverages UDP/IP multicast for communication, it is not so
straightforward to scale DDS communication over a WAN or across multiple LANs.
Zenoh, on the other hand was designed since its inception to operate at
Internet Scale.
.
.
Thus, the main motivations to have a **DDS plugin** for **Eclipse zenoh** are:
.
- Facilitate the interconnection of robot swarms.
- Support use cases of edge robotics.
- Give the possibility to use **zenoh**'s geo-distributed storage and query
system to better manage robot's data.
.
As any plugin for Eclipse zenoh, it can be dynamically loaded by a zenoh
router, at startup or at runtime.
In addition, this project also provides a standalone version of this plugin as
an executable binary named `zenoh-bridge-dds`.
.
## How to install it
.
To install the latest release of either the DDS plugin for the Zenoh router,
either the `zenoh-bridge-dds` standalone executable, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-plugin-dds/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download:
- the `zenoh-plugin-dds-`/turtle1/cmd_vel`
`/turtle1/rotate_absolute` | | `/rosout\|/turtle1/` | `/rosout` and all `/turtle1` topics, services, parameters and actions | | `/turtle1/.*` | all topics and services with name containing `/turtle1/` | | `/turtle1/` | same: all topics, services, parameters and actions with name containing `/turtle1/` | | `rt/turtle1` | all topics with name containing `/turtle1` (no services, parameters or actions) | | `rq/turtle1\|/rr/turtle1` | all services and parameters with name containing `/turtle1` (no topics or actions) | | `rq/turtlesim/.*parameter\|/rr/turtlesim/.*parameter` | all parameters with name containing `/turtlesim` (no topics, services or actions) | | `rq/turtle1/.*/_action\|/rr/turtle1/.*/_action` | all actions with name containing `/turtle1` (no topics, services or parameters) | . ### _Running several robots without changing the ROS2 configuration_ If you run similar robots in the same network, they will by default all us the same DDS topics, leading to interferences in their operations. A simple way to address this issue using the zenoh bridge is to: - deploy 1 zenoh bridge per robot - have each bridge started with the `--scope "/
`rr/turtle1/set_penReply` | `rq/turtle1/set_penRequest`
`rr/turtle1/set_penReply` | `myscope/rq/turtle1/set_penRequest`
`myscope/rr/turtle1/set_penReply` | | action: `/turtle1/rotate_absolute` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `myscope/rq/turtle1/rotate_absolute/_action/send_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/send_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/get_resultRequest`
`myscope/rr/turtle1/rotate_absolute/_action/get_resultReply`
`myscope/rt/turtle1/rotate_absolute/_action/status`
`myscope/rt/turtle1/rotate_absolute/_action/feedback` | | all parameters for node `turtlesim`| `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `myscope/rq/turtlesim/list_parametersRequest`
`myscope/rr/turtlesim/list_parametersReply`
`myscope/rq/turtlesim/describe_parametersRequest`
`myscope/rr/turtlesim/describe_parametersReply`
`myscope/rq/turtlesim/get_parametersRequest`
`myscope/rr/turtlesim/get_parametersReply`
`myscope/rr/turtlesim/get_parameter_typesReply`
`myscope/rq/turtlesim/get_parameter_typesRequest`
`myscope/rq/turtlesim/set_parametersRequest`
`myscope/rr/turtlesim/set_parametersReply`
`myscope/rq/turtlesim/set_parameters_atomicallyRequest`
`myscope/rr/turtlesim/set_parameters_atomicallyReply` | | specific ROS discovery topic | `ros_discovery_info` | `ros_discovery_info` | `myscope/ros_discovery_info` Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds Package: zenoh-plugin-dds Version: 0.10.0-rc Architecture: arm64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 4005 Depends: zenohd (=0.10.0-rc) Filename: 0.10.0-rc/zenoh-plugin-dds_0.10.0-rc_arm64.deb Size: 1226436 MD5sum: bf73481c8f88b053eaaba2d598272212 SHA1: 75ae7d5fca6392db125eb14f11173c467cd10049 SHA256: efc316c241f0908999350f2a811c84c4ec04afa2fa5a6fa38c07e205b0ae2667 Section: net Priority: optional Homepage: http://zenoh.io Description: Zenoh plugin for ROS2 and DDS in general
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# DDS plugin and standalone `zenoh-bridge-dds`
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Docker image:** see [below](#Docker-image)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
## Background
The Data Distribution Service (DDS) is a standard for data-centric publish
subscribe. Whilst DDS has been around for quite some time and has a long
history of deployments in various industries, it has recently gained quite a
bit of attentions thanks to its adoption by the Robotic Operating System (ROS2)
-- where it is used for communication between ROS2 nodes.
.
## Robot Swarms and Edge Robotics
As mentioned above, ROS2 has adopted DDS as the mechanism to exchange data
between nodes within and potentially across a robot. That said, due to some of
the very core assumptions at the foundations of the DDS wire-protocol, beside
the fact that it leverages UDP/IP multicast for communication, it is not so
straightforward to scale DDS communication over a WAN or across multiple LANs.
Zenoh, on the other hand was designed since its inception to operate at
Internet Scale.
.
.
Thus, the main motivations to have a **DDS plugin** for **Eclipse zenoh** are:
.
- Facilitate the interconnection of robot swarms.
- Support use cases of edge robotics.
- Give the possibility to use **zenoh**'s geo-distributed storage and query
system to better manage robot's data.
.
As any plugin for Eclipse zenoh, it can be dynamically loaded by a zenoh
router, at startup or at runtime.
In addition, this project also provides a standalone version of this plugin as
an executable binary named `zenoh-bridge-dds`.
.
## How to install it
.
To install the latest release of either the DDS plugin for the Zenoh router,
either the `zenoh-bridge-dds` standalone executable, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-plugin-dds/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download:
- the `zenoh-plugin-dds-`/turtle1/cmd_vel`
`/turtle1/rotate_absolute` | | `/rosout\|/turtle1/` | `/rosout` and all `/turtle1` topics, services, parameters and actions | | `/turtle1/.*` | all topics and services with name containing `/turtle1/` | | `/turtle1/` | same: all topics, services, parameters and actions with name containing `/turtle1/` | | `rt/turtle1` | all topics with name containing `/turtle1` (no services, parameters or actions) | | `rq/turtle1\|/rr/turtle1` | all services and parameters with name containing `/turtle1` (no topics or actions) | | `rq/turtlesim/.*parameter\|/rr/turtlesim/.*parameter` | all parameters with name containing `/turtlesim` (no topics, services or actions) | | `rq/turtle1/.*/_action\|/rr/turtle1/.*/_action` | all actions with name containing `/turtle1` (no topics, services or parameters) | . ### _Running several robots without changing the ROS2 configuration_ If you run similar robots in the same network, they will by default all us the same DDS topics, leading to interferences in their operations. A simple way to address this issue using the zenoh bridge is to: - deploy 1 zenoh bridge per robot - have each bridge started with the `--scope "/
`rr/turtle1/set_penReply` | `rq/turtle1/set_penRequest`
`rr/turtle1/set_penReply` | `myscope/rq/turtle1/set_penRequest`
`myscope/rr/turtle1/set_penReply` | | action: `/turtle1/rotate_absolute` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `myscope/rq/turtle1/rotate_absolute/_action/send_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/send_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/get_resultRequest`
`myscope/rr/turtle1/rotate_absolute/_action/get_resultReply`
`myscope/rt/turtle1/rotate_absolute/_action/status`
`myscope/rt/turtle1/rotate_absolute/_action/feedback` | | all parameters for node `turtlesim`| `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `myscope/rq/turtlesim/list_parametersRequest`
`myscope/rr/turtlesim/list_parametersReply`
`myscope/rq/turtlesim/describe_parametersRequest`
`myscope/rr/turtlesim/describe_parametersReply`
`myscope/rq/turtlesim/get_parametersRequest`
`myscope/rr/turtlesim/get_parametersReply`
`myscope/rr/turtlesim/get_parameter_typesReply`
`myscope/rq/turtlesim/get_parameter_typesRequest`
`myscope/rq/turtlesim/set_parametersRequest`
`myscope/rr/turtlesim/set_parametersReply`
`myscope/rq/turtlesim/set_parameters_atomicallyRequest`
`myscope/rr/turtlesim/set_parameters_atomicallyReply` | | specific ROS discovery topic | `ros_discovery_info` | `ros_discovery_info` | `myscope/ros_discovery_info` Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds Package: zenoh-plugin-dds Version: 0.10.0-rc Architecture: armel Maintainer: zenoh-dev@eclipse.org Installed-Size: 3888 Depends: zenohd (=0.10.0-rc) Filename: 0.10.0-rc/zenoh-plugin-dds_0.10.0-rc_armel.deb Size: 1208656 MD5sum: 49e5d71d368745b6791548e65e151d66 SHA1: 1f5122443e032578fecd13864856ff8fb92e16eb SHA256: 6e1f714b2ecf9bfc1b333b3c074e19a76fa1b96d60f96ba6690a0ce97d3dc0e1 Section: net Priority: optional Homepage: http://zenoh.io Description: Zenoh plugin for ROS2 and DDS in general
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# DDS plugin and standalone `zenoh-bridge-dds`
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Docker image:** see [below](#Docker-image)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
## Background
The Data Distribution Service (DDS) is a standard for data-centric publish
subscribe. Whilst DDS has been around for quite some time and has a long
history of deployments in various industries, it has recently gained quite a
bit of attentions thanks to its adoption by the Robotic Operating System (ROS2)
-- where it is used for communication between ROS2 nodes.
.
## Robot Swarms and Edge Robotics
As mentioned above, ROS2 has adopted DDS as the mechanism to exchange data
between nodes within and potentially across a robot. That said, due to some of
the very core assumptions at the foundations of the DDS wire-protocol, beside
the fact that it leverages UDP/IP multicast for communication, it is not so
straightforward to scale DDS communication over a WAN or across multiple LANs.
Zenoh, on the other hand was designed since its inception to operate at
Internet Scale.
.
.
Thus, the main motivations to have a **DDS plugin** for **Eclipse zenoh** are:
.
- Facilitate the interconnection of robot swarms.
- Support use cases of edge robotics.
- Give the possibility to use **zenoh**'s geo-distributed storage and query
system to better manage robot's data.
.
As any plugin for Eclipse zenoh, it can be dynamically loaded by a zenoh
router, at startup or at runtime.
In addition, this project also provides a standalone version of this plugin as
an executable binary named `zenoh-bridge-dds`.
.
## How to install it
.
To install the latest release of either the DDS plugin for the Zenoh router,
either the `zenoh-bridge-dds` standalone executable, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-plugin-dds/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download:
- the `zenoh-plugin-dds-`/turtle1/cmd_vel`
`/turtle1/rotate_absolute` | | `/rosout\|/turtle1/` | `/rosout` and all `/turtle1` topics, services, parameters and actions | | `/turtle1/.*` | all topics and services with name containing `/turtle1/` | | `/turtle1/` | same: all topics, services, parameters and actions with name containing `/turtle1/` | | `rt/turtle1` | all topics with name containing `/turtle1` (no services, parameters or actions) | | `rq/turtle1\|/rr/turtle1` | all services and parameters with name containing `/turtle1` (no topics or actions) | | `rq/turtlesim/.*parameter\|/rr/turtlesim/.*parameter` | all parameters with name containing `/turtlesim` (no topics, services or actions) | | `rq/turtle1/.*/_action\|/rr/turtle1/.*/_action` | all actions with name containing `/turtle1` (no topics, services or parameters) | . ### _Running several robots without changing the ROS2 configuration_ If you run similar robots in the same network, they will by default all us the same DDS topics, leading to interferences in their operations. A simple way to address this issue using the zenoh bridge is to: - deploy 1 zenoh bridge per robot - have each bridge started with the `--scope "/
`rr/turtle1/set_penReply` | `rq/turtle1/set_penRequest`
`rr/turtle1/set_penReply` | `myscope/rq/turtle1/set_penRequest`
`myscope/rr/turtle1/set_penReply` | | action: `/turtle1/rotate_absolute` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `myscope/rq/turtle1/rotate_absolute/_action/send_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/send_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/get_resultRequest`
`myscope/rr/turtle1/rotate_absolute/_action/get_resultReply`
`myscope/rt/turtle1/rotate_absolute/_action/status`
`myscope/rt/turtle1/rotate_absolute/_action/feedback` | | all parameters for node `turtlesim`| `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `myscope/rq/turtlesim/list_parametersRequest`
`myscope/rr/turtlesim/list_parametersReply`
`myscope/rq/turtlesim/describe_parametersRequest`
`myscope/rr/turtlesim/describe_parametersReply`
`myscope/rq/turtlesim/get_parametersRequest`
`myscope/rr/turtlesim/get_parametersReply`
`myscope/rr/turtlesim/get_parameter_typesReply`
`myscope/rq/turtlesim/get_parameter_typesRequest`
`myscope/rq/turtlesim/set_parametersRequest`
`myscope/rr/turtlesim/set_parametersReply`
`myscope/rq/turtlesim/set_parameters_atomicallyRequest`
`myscope/rr/turtlesim/set_parameters_atomicallyReply` | | specific ROS discovery topic | `ros_discovery_info` | `ros_discovery_info` | `myscope/ros_discovery_info` Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds Package: zenoh-plugin-dds Version: 0.10.0-rc Architecture: amd64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 4493 Depends: zenohd (=0.10.0-rc) Filename: 0.10.0-rc/zenoh-plugin-dds_0.10.0-rc_amd64.deb Size: 1379700 MD5sum: 7f1426d7e145690366499e862b2df140 SHA1: 4db854f1b1a2f3d03a8caa2ed5abfd295337c622 SHA256: 10dba9e7d027d83a1593faceaeb401220499947ccdb5637bb8598f9aa796cc50 Section: net Priority: optional Homepage: http://zenoh.io Description: Zenoh plugin for ROS2 and DDS in general
.
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# DDS plugin and standalone `zenoh-bridge-dds`
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Docker image:** see [below](#Docker-image)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
## Background
The Data Distribution Service (DDS) is a standard for data-centric publish
subscribe. Whilst DDS has been around for quite some time and has a long
history of deployments in various industries, it has recently gained quite a
bit of attentions thanks to its adoption by the Robotic Operating System (ROS2)
-- where it is used for communication between ROS2 nodes.
.
## Robot Swarms and Edge Robotics
As mentioned above, ROS2 has adopted DDS as the mechanism to exchange data
between nodes within and potentially across a robot. That said, due to some of
the very core assumptions at the foundations of the DDS wire-protocol, beside
the fact that it leverages UDP/IP multicast for communication, it is not so
straightforward to scale DDS communication over a WAN or across multiple LANs.
Zenoh, on the other hand was designed since its inception to operate at
Internet Scale.
.
.
Thus, the main motivations to have a **DDS plugin** for **Eclipse zenoh** are:
.
- Facilitate the interconnection of robot swarms.
- Support use cases of edge robotics.
- Give the possibility to use **zenoh**'s geo-distributed storage and query
system to better manage robot's data.
.
As any plugin for Eclipse zenoh, it can be dynamically loaded by a zenoh
router, at startup or at runtime.
In addition, this project also provides a standalone version of this plugin as
an executable binary named `zenoh-bridge-dds`.
.
## How to install it
.
To install the latest release of either the DDS plugin for the Zenoh router,
either the `zenoh-bridge-dds` standalone executable, you can do as follows:
.
### Manual installation (all platforms)
.
All release packages can be downloaded from:
- https://download.eclipse.org/zenoh/zenoh-plugin-dds/latest/
.
Each subdirectory has the name of the Rust target. See the platforms each
target corresponds to on
https://doc.rust-lang.org/stable/rustc/platform-support.html
.
Choose your platform and download:
- the `zenoh-plugin-dds-`/turtle1/cmd_vel`
`/turtle1/rotate_absolute` | | `/rosout\|/turtle1/` | `/rosout` and all `/turtle1` topics, services, parameters and actions | | `/turtle1/.*` | all topics and services with name containing `/turtle1/` | | `/turtle1/` | same: all topics, services, parameters and actions with name containing `/turtle1/` | | `rt/turtle1` | all topics with name containing `/turtle1` (no services, parameters or actions) | | `rq/turtle1\|/rr/turtle1` | all services and parameters with name containing `/turtle1` (no topics or actions) | | `rq/turtlesim/.*parameter\|/rr/turtlesim/.*parameter` | all parameters with name containing `/turtlesim` (no topics, services or actions) | | `rq/turtle1/.*/_action\|/rr/turtle1/.*/_action` | all actions with name containing `/turtle1` (no topics, services or parameters) | . ### _Running several robots without changing the ROS2 configuration_ If you run similar robots in the same network, they will by default all us the same DDS topics, leading to interferences in their operations. A simple way to address this issue using the zenoh bridge is to: - deploy 1 zenoh bridge per robot - have each bridge started with the `--scope "/
`rr/turtle1/set_penReply` | `rq/turtle1/set_penRequest`
`rr/turtle1/set_penReply` | `myscope/rq/turtle1/set_penRequest`
`myscope/rr/turtle1/set_penReply` | | action: `/turtle1/rotate_absolute` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `rq/turtle1/rotate_absolute/_action/send_goalRequest`
`rr/turtle1/rotate_absolute/_action/send_goalReply`
`rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`rq/turtle1/rotate_absolute/_action/get_resultRequest`
`rr/turtle1/rotate_absolute/_action/get_resultReply`
`rt/turtle1/rotate_absolute/_action/status`
`rt/turtle1/rotate_absolute/_action/feedback` | `myscope/rq/turtle1/rotate_absolute/_action/send_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/send_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/cancel_goalRequest`
`myscope/rr/turtle1/rotate_absolute/_action/cancel_goalReply`
`myscope/rq/turtle1/rotate_absolute/_action/get_resultRequest`
`myscope/rr/turtle1/rotate_absolute/_action/get_resultReply`
`myscope/rt/turtle1/rotate_absolute/_action/status`
`myscope/rt/turtle1/rotate_absolute/_action/feedback` | | all parameters for node `turtlesim`| `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `rq/turtlesim/list_parametersRequest`
`rr/turtlesim/list_parametersReply`
`rq/turtlesim/describe_parametersRequest`
`rr/turtlesim/describe_parametersReply`
`rq/turtlesim/get_parametersRequest`
`rr/turtlesim/get_parametersReply`
`rr/turtlesim/get_parameter_typesReply`
`rq/turtlesim/get_parameter_typesRequest`
`rq/turtlesim/set_parametersRequest`
`rr/turtlesim/set_parametersReply`
`rq/turtlesim/set_parameters_atomicallyRequest`
`rr/turtlesim/set_parameters_atomicallyReply` | `myscope/rq/turtlesim/list_parametersRequest`
`myscope/rr/turtlesim/list_parametersReply`
`myscope/rq/turtlesim/describe_parametersRequest`
`myscope/rr/turtlesim/describe_parametersReply`
`myscope/rq/turtlesim/get_parametersRequest`
`myscope/rr/turtlesim/get_parametersReply`
`myscope/rr/turtlesim/get_parameter_typesReply`
`myscope/rq/turtlesim/get_parameter_typesRequest`
`myscope/rq/turtlesim/set_parametersRequest`
`myscope/rr/turtlesim/set_parametersReply`
`myscope/rq/turtlesim/set_parameters_atomicallyRequest`
`myscope/rr/turtlesim/set_parameters_atomicallyReply` | | specific ROS discovery topic | `ros_discovery_info` | `ros_discovery_info` | `myscope/ros_discovery_info` Vcs-Browser: https://github.com/eclipse-zenoh/zenoh-plugin-dds Vcs-Git: https://github.com/eclipse-zenoh/zenoh-plugin-dds Package: zenoh-plugin-mqtt Version: 0.10.0-rc Architecture: arm64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 3134 Depends: zenohd (=0.10.0-rc) Filename: 0.10.0-rc/zenoh-plugin-mqtt_0.10.0-rc_arm64.deb Size: 913732 MD5sum: 5ca7b918cac0a2589c1abb40ae291912 SHA1: d9ba6ef82b471137467b3b4c5457ebf54393217f SHA256: f58cdc7879aae4e56ec1aed61bbe88979c287cfa1747ed09d4cd283d23f9ffc6 Section: net Priority: optional Homepage: http://zenoh.io Description: Zenoh plugin for MQTT
.
[](https://github.com/eclipse-zenoh/zenoh-plugin-mqtt/actions?query=workflow%3ARust)
[](https://github.com/eclipse-zenoh/roadmap/discussions)
[](https://discord.gg/2GJ958VuHs)
[](https://choosealicense.com/licenses/epl-2.0/)
[](https://opensource.org/licenses/Apache-2.0)
.
# Eclipse Zenoh
The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.
.
Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and
computations. It carefully blends traditional pub/sub with geo-distributed
storages, queries and computations, while retaining a level of time and space
efficiency that is well beyond any of the mainstream stacks.
.
Check the website [zenoh.io](http://zenoh.io) and the
[roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed
information.
.
-------------------------------
# MQTT plugin and standalone `zenoh-bridge-mqtt`
.
:point_right: **Install latest release:** see [below](#How-to-install-it)
.
:point_right: **Docker image:** see [below](#Docker-image)
.
:point_right: **Build "master" branch:** see [below](#How-to-build-it)
.
## Background
.
[MQTT](https://mqtt.org/) is a pub/sub protocol leveraging a broker to route
the messages between the MQTT clients.
The MQTT plugin for Eclipse Zenoh acts as a MQTT broker, accepting connections
from MQTT clients (V3 and V5) and translating the MQTT pub/sub into a Zenoh
pub/sub.
I.e.:
- a MQTT publication on topic `device/123/temperature` is routed as a Zenoh
publication on key expression `device/123/temperature`
- a MQTT subscription on topic `device/#` is mapped to a Zenoh subscription on
key expression `device/**`
.
This allows a close intergration of any MQTT system with Zenoh, but also brings
to MQTT systems the benefits of a Zenoh routing infrastructure.
Some examples of use cases:
- Routing MQTT from the device to the Edge and to the Cloud
- Bridging 2 distinct MQTT systems across the Internet, with NAT traversal
- Pub/sub to MQTT via the Zenoh REST API
- MQTT-ROS2 (robot) communication
- Store MQTT publications in any Zenoh storage (RocksDB, InfluxDB, file
system...)
- MQTT record/replay with InfluxDB as a storage
.
The MQTT plugin for Eclipse Zenoh is available either as a dynamic library to
be loaded by the Zenoh router (`zenohd`), either as a standalone executable
(`zenoh-bridge-mqtt`) that can acts as a Zenoh client or peer.
.
## Configuration
.
`zenoh-bridge-mqtt` can be configured via a JSON5 file passed via the
`-c`argument. You can see a commented example of such configuration file:
[`DEFAULT_CONFIG.json5`](DEFAULT_CONFIG.json5).
.
The `"mqtt"` part of this same configuration file can also be used in the
configuration file for the zenoh router (within its `"plugins"` part). The
router will automatically try to load the plugin library (`zenoh_plugin_mqtt`)
at startup and apply its configuration.
.
`zenoh-bridge-mqtt` also accepts the following arguments. If set, each argument
will override the similar setting from the configuration file:
* zenoh-related arguments:
- **`-c, --config