.
[](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.
.
2. 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.
.
2. 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.
.
2. 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.
.
2. 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.
.
2. 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.
.
2. 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.
.
2. 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).
.
> :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.7.2-rc
Architecture: armhf
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 3796
Depends: zenoh-plugin-storage-manager (=0.7.2-rc)
Filename: 0.7.2-rc/zenoh-backend-influxdb_0.7.2-rc_armhf.deb
Size: 1170584
MD5sum: b653095addbd72d371118fd542fe3028
SHA1: 33f39c819e2f42311414f43ceec53f68e56cb0b4
SHA256: f134c229b181dc969ac4658828e01f8829818af28a57ff1f4d98b408d062adfd
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).
.
> :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.7.2-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 4913
Depends: zenoh-plugin-storage-manager (=0.7.2-rc)
Filename: 0.7.2-rc/zenoh-backend-influxdb_0.7.2-rc_amd64.deb
Size: 1543928
MD5sum: 64d681f05f7716ed9ecce3a4cdfd4baa
SHA1: 2e26758816ed369e3e307bc3641ee44978480ad8
SHA256: 5239a263dbd70c9495fd63d4d88e7bee56a54bb8890c0a51bb5a24d59631a571
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).
.
> :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.7.2-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 4417
Depends: zenoh-plugin-storage-manager (=0.7.2-rc)
Filename: 0.7.2-rc/zenoh-backend-influxdb_0.7.2-rc_arm64.deb
Size: 1381488
MD5sum: 685a9d106459f5a02938befe38b0db47
SHA1: 538c21b018526465aa5be04fc550b06826e35220
SHA256: bc5170f8c194dd5eb6d20baad698aa140e230ef8f2933f2bbdab78189ba6d15e
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).
.
> :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.7.2-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 8245
Depends: zenoh-plugin-storage-manager (=0.7.2-rc)
Filename: 0.7.2-rc/zenoh-backend-rocksdb_0.7.2-rc_arm64.deb
Size: 2512020
MD5sum: ce13ce19e0f94996a944df3f97a061ae
SHA1: 1388a11b4eadfd0306dd2b3d0fc601e37df2d1d0
SHA256: 6265d9986c95862a8fd7eb36fecc4caf1a0eca40e36dc56113b228b70763d668
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).
.
> :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.7.2-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 10297
Depends: zenoh-plugin-storage-manager (=0.7.2-rc)
Filename: 0.7.2-rc/zenoh-backend-s3_0.7.2-rc_arm64.deb
Size: 2630816
MD5sum: eaa73f62d44ce38911fad7c6aac478d6
SHA1: ab7759d926e06c9c462328c0408da769c7410006
SHA256: 46b6f934041b42b2837a8f9dd74a78808c3c99cfc36a6caf1f3ca9a52f9bfd4f
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).
.
> :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.7.2-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 11521
Depends: zenoh-plugin-storage-manager (=0.7.2-rc)
Filename: 0.7.2-rc/zenoh-backend-s3_0.7.2-rc_amd64.deb
Size: 2894992
MD5sum: 9964a688f9778da9b54f31df48cb11ef
SHA1: d97a8e2b35a3690df55f90971717cc291774f82e
SHA256: a5dc06ee8847adae2c0e1f01b212b269d8d241a7c4e4f1ae809c55871d3f67e6
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).
.
> :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.7.2-rc
Architecture: armel
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9234
Depends: zenoh-plugin-storage-manager (=0.7.2-rc)
Filename: 0.7.2-rc/zenoh-backend-s3_0.7.2-rc_armel.deb
Size: 2295824
MD5sum: a6757c8220910b4f64a3dae755cc8f03
SHA1: 52af4faa9117f105e60a2a33682fee97c337c9d2
SHA256: 0842623f30c3280dc07a27085f11e704c462d9362ae61f63f693d8694f75ac3d
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).
.
> :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.7.2-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9806
Depends: libc6 (>= 2.29)
Filename: 0.7.2-rc/zenoh-bridge-dds_0.7.2-rc_amd64.deb
Size: 3117836
MD5sum: 366eba74f6d950ef253c60ae73ae49b5
SHA1: b8d547328fc5fcfa16fd7d55e721e2c0b620a674
SHA256: dd9c830c980284737765b368b7411add45cf3d57a0c2f9ba016635e49f7880a3
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.7.2-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 8569
Depends: libc6:arm64 (>= 2.31)
Filename: 0.7.2-rc/zenoh-bridge-dds_0.7.2-rc_arm64.deb
Size: 2818956
MD5sum: c6b45d59a2f83acb48f453041a7a1721
SHA1: eee122768a34eb737f51c8b44cc4ae1e2bd078ab
SHA256: 90b7f088b482e83caec9e9a8ff9ec761c2293f2ba17cf2b57b98a7a8798a3d7c
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.7.2-rc
Architecture: armel
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 8591
Depends: libc6:armel (>= 2.31)
Filename: 0.7.2-rc/zenoh-bridge-dds_0.7.2-rc_armel.deb
Size: 2763840
MD5sum: f04342757da393c303c982aee696a3c4
SHA1: cab2fc4b95d4ebe01fbc9f259f6e0ac864a8c845
SHA256: e1ea01099c037356bf663f9e4095f0dd1047ac455deebe12443ecd0472f26450
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.7.2-rc
Architecture: armhf
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 8151
Depends: libc6:armhf (>= 2.31)
Filename: 0.7.2-rc/zenoh-bridge-dds_0.7.2-rc_armhf.deb
Size: 2772860
MD5sum: f1f5c64aad44b631ce421ae166656504
SHA1: de91e2b84d3bfa1df0d165612b6ceba3e7e7b1a6
SHA256: 57f357323b67bcb143aa567e9a04a901381a435ba2ea9351a9701ca259989eff
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.7.2-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 9052
Depends: libc6 (>= 2.29)
Filename: 0.7.2-rc/zenoh-bridge-mqtt_0.7.2-rc_amd64.deb
Size: 2842856
MD5sum: fc2ad30ca977af77222dd66f81744693
SHA1: bec0d2e9759a1fde7b1992379a912a62c059c167
SHA256: 9f13c602f9600090db5d533af6bbe105cf9904f7b7530cafc094f09c89ba217d
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.7.2-rc
Architecture: arm64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 7836
Depends: libc6:arm64 (>= 2.31)
Filename: 0.7.2-rc/zenoh-bridge-mqtt_0.7.2-rc_arm64.deb
Size: 2563844
MD5sum: 2cb80ea3c9a0f0f64a613b4df8f94e7c
SHA1: 4b3b3a0db42805ccad51386c7f6fa894c0e368e8
SHA256: b48cf4f24298f435f6f8973256ab7e57d101a6fbaa8bc776ef17f22d4a410c42
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.7.2-rc
Architecture: amd64
Maintainer: zenoh-dev@eclipse.org
Installed-Size: 10280
Depends: libc6 (>= 2.29)
Filename: 0.7.2-rc/zenoh-bridge-ros1_0.7.2-rc_amd64.deb
Size: 3104324
MD5sum: d64ec6cdb48b6ed57b104670b5c11a33
SHA1: 991880d888bb768ece271e31c1bf17f723844c76
SHA256: 3305164fce8abd2767a10ea960647dfa0c3d36866cc31e3302c2914a06226158
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.7.2.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.7.2-rc Architecture: amd64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 4022 Depends: zenohd (=0.7.2-rc) Filename: 0.7.2-rc/zenoh-plugin-dds_0.7.2-rc_amd64.deb Size: 1226128 MD5sum: eaa8ca73e78a48aa8038c040cb03d110 SHA1: 63ac598b53c4dd9ac51dd1adb6b32f7cd583e02e SHA256: d5a98fe2f1aa91d8a6dcd77136ca294001ca2d5854c1d1848111d627ad187e96 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.7.2-rc Architecture: armel Maintainer: zenoh-dev@eclipse.org Installed-Size: 3429 Depends: zenohd (=0.7.2-rc) Filename: 0.7.2-rc/zenoh-plugin-dds_0.7.2-rc_armel.deb Size: 1063248 MD5sum: 5bdcbbf092d53bf96348ae6bb70b8b27 SHA1: a16037515282466e6b7ed53fcefa1981d8d9acd2 SHA256: 1e463fc49e80555576d494c4758bd6c5fe8b55a6bc5f1919495f243c42e36322 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.7.2-rc Architecture: armhf Maintainer: zenoh-dev@eclipse.org Installed-Size: 3149 Depends: zenohd (=0.7.2-rc) Filename: 0.7.2-rc/zenoh-plugin-dds_0.7.2-rc_armhf.deb Size: 1069892 MD5sum: 5ef5d5167aabdef96aade74717382dd7 SHA1: ff4f2f043cdf8780115930aab22d34dafbecf8fe SHA256: aa2a5303bfed9df42a8f937a4e924dea61807347ee9b98abfa349a7dda633695 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.7.2-rc Architecture: arm64 Maintainer: zenoh-dev@eclipse.org Installed-Size: 2882 Depends: zenohd (=0.7.2-rc) Filename: 0.7.2-rc/zenoh-plugin-mqtt_0.7.2-rc_arm64.deb Size: 814064 MD5sum: 6887d5c74c844193c6e13ef9b7e2271d SHA1: 6681bab873e1c9bfef3e11254627707875b8959c SHA256: 4c7590d91d98f78f3eda5a01fc7e2ac46c73ec193ca3e1515d06535ed90daa83 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