diff --git a/README.md b/README.md index 9a1a0dd35f..9a6216d3ef 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](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. @@ -15,21 +16,22 @@ Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and computations Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. ------------------------------- + ## Getting Started Zenoh is extremely easy to learn, the best place to master the fundamentals is our [getting started guide](https://zenoh.io/docs/getting-started/first-app/). ------------------------------- + ## How to install it To install the latest release of the Zenoh router (`zenohd`) and its default plugins (REST API plugin and Storages Manager plugin) you can do as follows: ### Manual installation (all platforms) -All release packages can be downloaded from: - - https://download.eclipse.org/zenoh/zenoh/latest/ +All release packages can be downloaded from [https://download.eclipse.org/zenoh/zenoh/latest/](https://download.eclipse.org/zenoh/zenoh/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 +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](https://doc.rust-lang.org/stable/rustc/platform-support.html). Choose your platform and download the `.zip` file. Unzip it where you want, and run the extracted `zenohd` binary. @@ -43,6 +45,7 @@ echo "deb [trusted=yes] https://download.eclipse.org/zenoh/debian-repo/ /" | sud sudo apt update sudo apt install zenoh ``` + Then you can start run `zenohd`. ### MacOS @@ -53,12 +56,17 @@ Tap our brew package repository and install the `zenoh` formula: brew tap eclipse-zenoh/homebrew-zenoh brew install zenoh ``` + Then you can start run `zenohd`. +------------------------------- + +## Rust API -### Rust API +* [Docs.rs for Zenoh](https://docs.rs/zenoh/latest/zenoh/) ------------------------------- + ## How to build it > [!WARNING] @@ -67,72 +75,72 @@ Then you can start run `zenohd`. Install [Cargo and Rust](https://doc.rust-lang.org/cargo/getting-started/installation.html). Zenoh can be successfully compiled with Rust stable (>= 1.75.0), so no special configuration is required from your side. If you already have the Rust toolchain installed, make sure it is up-to-date with: ```bash -$ rustup update +rustup update ``` To build Zenoh, just type the following command after having followed the previous instructions: ```bash -$ cargo build --release --all-targets +cargo build --release --all-targets ``` Zenoh's router is built as `target/release/zenohd`. All the examples are built into the `target/release/examples` directory. They can all work in peer-to-peer, or interconnected via the zenoh router. ------------------------------- -## Quick tests of your build: -**Peer-to-peer tests:** +## Quick tests of your build - - **pub/sub** - - run: `./target/release/examples/z_sub` - - in another shell run: `./target/release/examples/z_put` - - the subscriber should receive the publication. +### Peer-to-peer tests - - **get/queryable** - - run: `./target/release/examples/z_queryable` - - in another shell run: `./target/release/examples/z_get` - - the queryable should display the log in its listener, and the get should receive the queryable result. +* **pub/sub** + * run: `./target/release/examples/z_sub` + * in another shell run: `./target/release/examples/z_put` + * the subscriber should receive the publication. -**Routed tests:** +* **get/queryable** + * run: `./target/release/examples/z_queryable` + * in another shell run: `./target/release/examples/z_get` + * the queryable should display the log in its listener, and the get should receive the queryable result. + +### Routed tests > [!NOTE] > **Windows users**: to properly execute the commands below in PowerShell you need to escape `"` characters as `\"`. - - **put/store/get** - - run the Zenoh router with a memory storage: - `./target/release/zenohd --cfg='plugins/storage_manager/storages/demo:{key_expr:"demo/example/**",volume:"memory"}'` - - in another shell run: `./target/release/examples/z_put` - - then run `./target/release/examples/z_get` - - the get should receive the stored publication. - - - **REST API using `curl` tool** - - run the Zenoh router with a memory storage: - `./target/release/zenohd --cfg='plugins/storage_manager/storages/demo:{key_expr:"demo/example/**",volume:"memory"}'` - - in another shell, do a publication via the REST API: - `curl -X PUT -d '"Hello World!"' http://localhost:8000/demo/example/test` - - get it back via the REST API: - `curl http://localhost:8000/demo/example/test` - - - **router admin space via the REST API** - - run the Zenoh router with permission to perform config changes via the admin space, and with a memory storage: - `./target/release/zenohd --adminspace-permissions=rw --cfg='plugins/storage_manager/storages/demo:{key_expr:"demo/example/**",volume:"memory"}'` - - in another shell, get info of the zenoh router via the zenoh admin space: - `curl http://localhost:8000/@/router/local` - - get the volumes of the router (only memory by default): - `curl 'http://localhost:8000/@/router/local/**/volumes/*'` - - get the storages of the local router (the memory storage configured at startup on '/demo/example/**' should be present): - `curl 'http://localhost:8000/@/router/local/**/storages/*'` - - add another memory storage on `/demo/mystore/**`: - `curl -X PUT -H 'content-type:application/json' -d '{"key_expr":"demo/mystore/**","volume":"memory"}' http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/mystore` - - check it has been created: - `curl 'http://localhost:8000/@/router/local/**/storages/*'` - -**Configuration options:** +* **put/store/get** + * run the Zenoh router with a memory storage: + `./target/release/zenohd --cfg='plugins/storage_manager/storages/demo:{key_expr:"demo/example/**",volume:"memory"}'` + * in another shell run: `./target/release/examples/z_put` + * then run `./target/release/examples/z_get` + * the get should receive the stored publication. + +* **REST API using `curl` tool** + * run the Zenoh router with a memory storage: + `./target/release/zenohd --cfg='plugins/storage_manager/storages/demo:{key_expr:"demo/example/**",volume:"memory"}'` + * in another shell, do a publication via the REST API: + `curl -X PUT -d '"Hello World!"' http://localhost:8000/demo/example/test` + * get it back via the REST API: + `curl http://localhost:8000/demo/example/test` + +* **router admin space via the REST API** + * run the Zenoh router with permission to perform config changes via the admin space, and with a memory storage: + `./target/release/zenohd --adminspace-permissions=rw --cfg='plugins/storage_manager/storages/demo:{key_expr:"demo/example/**",volume:"memory"}'` + * in another shell, get info of the zenoh router via the zenoh admin space: + `curl http://localhost:8000/@/router/local` + * get the volumes of the router (only memory by default): + `curl 'http://localhost:8000/@/router/local/**/volumes/*'` + * get the storages of the local router (the memory storage configured at startup on '/demo/example/**' should be present): + `curl 'http://localhost:8000/@/router/local/**/storages/*'` + * add another memory storage on `/demo/mystore/**`: + `curl -X PUT -H 'content-type:application/json' -d '{"key_expr":"demo/mystore/**","volume":"memory"}' http://localhost:8000/@/router/local/config/plugins/storage_manager/storages/mystore` + * check it has been created: + `curl 'http://localhost:8000/@/router/local/**/storages/*'` + +### Configuration options A Zenoh configuration file can be provided via CLI to all Zenoh examples and the Zenoh router. - * `-c, --config `: a [JSON5](https://json5.org) configuration file. [DEFAULT_CONFIG.json5](DEFAULT_CONFIG.json5) shows the schema of this file and the available options. - +* `-c, --config `: a [JSON5](https://json5.org) configuration file. [DEFAULT_CONFIG.json5](DEFAULT_CONFIG.json5) shows the schema of this file and the available options. See other examples of Zenoh usage in [examples/](examples) @@ -140,45 +148,44 @@ See other examples of Zenoh usage in [examples/](examples) > **Zenoh Runtime Configuration**: Starting from version 0.11.0-rc, Zenoh allows for configuring the number of worker threads and other advanced options of the runtime. For guidance on utilizing it, please refer to the [doc](https://docs.rs/zenoh-runtime/latest/zenoh_runtime/enum.ZRuntime.html). ------------------------------- + ## Zenoh router command line arguments -`zenohd` accepts the following arguments: - * `--adminspace-permissions <[r|w|rw|none]>`: Configure the read and/or write permissions on the admin space. Default is read only. - * `-c, --config `: a [JSON5](https://json5.org) configuration file. [DEFAULT_CONFIG.json5](DEFAULT_CONFIG.json5) shows the schema of this file. All properties of this configuration are optional, so you may not need such a large configuration for your use-case. - * `--cfg :`: allows you to change specific parts of the configuration right after it has been constructed. VALUE must be a valid JSON5 value, and key must be a path through the configuration file, where each element is separated by a `/`. When inserting in parts of the config that are arrays, you may use indexes, or may use `+` to indicate that you want to append your value to the array. `--cfg` passed values will always override any previously existing value for their key in the configuration. - * `-l, --listen ...`: An endpoint on which this router will listen for incoming sessions. - Repeat this option to open several listeners. By default, `tcp/[::]:7447` is used. The following endpoints are currently supported: - - TCP: `tcp/:` - - UDP: `udp/:` - - [TCP+TLS](https://zenoh.io/docs/manual/tls/): `tls/:` - - [QUIC](https://zenoh.io/docs/manual/quic/): `quic/:` - * `-e, --connect ...`: An endpoint this router will try to connect to. Repeat this option to connect to several peers or routers. - * `--no-multicast-scouting`: By default zenohd replies to multicast scouting messages for being discovered by peers and clients. - This option disables this feature. - * `-i, --id `: The identifier (as an hexadecimal string - e.g.: A0B23...) that zenohd must use. - **WARNING**: this identifier must be unique in the system! If not set, a random unsigned 128bit integer will be used. - * `--no-timestamp`: By default zenohd adds a HLC-generated Timestamp to each routed Data if there isn't already one. - This option disables this feature. - * `-P, --plugin [ | :]...`: A [plugin](https://zenoh.io/docs/manual/plugins/) that must be loaded. Accepted values: - - a plugin name; zenohd will search for a library named `libzenoh_plugin_.so` on Unix, `libzenoh_plugin_.dylib` on MacOS or `zenoh_plugin_.dll` on Windows. - - `":"`; the plugin will be loaded from library file at ``. - - Repeat this option to load several plugins. - * `--plugin-search-dir ...`: A directory where to search for [plugins](https://zenoh.io/docs/manual/plugins/) libraries to load. - Repeat this option to specify several search directories'. By default, the plugins libraries will be searched in: - `'/usr/local/lib:/usr/lib:~/.zenoh/lib:.'` - * `--rest-http-port `: Configures the [REST plugin](https://zenoh.io/docs/manual/plugin-http/)'s HTTP port. Accepted values: - - a port number - - a string with format `:` (to bind the HTTP server to a specific interface) - - `"None"` to deactivate the REST plugin - - If not specified, the REST plugin will be active on any interface (`[::]`) and port `8000`. +`zenohd` accepts the following arguments: -> [!WARNING] -> The following documentation pertains to the v0.6+ API, which comes many changes to the behaviour and configuration of Zenoh. -To access the v0.5 version of the code and matching README, please go to the [0.5.0-beta.9](https://github.com/eclipse-zenoh/zenoh/tree/0.5.0-beta.9) tagged version. +* `--adminspace-permissions <[r|w|rw|none]>`: Configure the read and/or write permissions on the admin space. Default is read only. +* `-c, --config `: a [JSON5](https://json5.org) configuration file. [DEFAULT_CONFIG.json5](DEFAULT_CONFIG.json5) shows the schema of this file. All properties of this configuration are optional, so you may not need such a large configuration for your use-case. +* `--cfg :`: allows you to change specific parts of the configuration right after it has been constructed. VALUE must be a valid JSON5 value, and key must be a path through the configuration file, where each element is separated by a `/`. When inserting in parts of the config that are arrays, you may use indexes, or may use `+` to indicate that you want to append your value to the array. `--cfg` passed values will always override any previously existing value for their key in the configuration. +* `-l, --listen ...`: An endpoint on which this router will listen for incoming sessions. + Repeat this option to open several listeners. By default, `tcp/[::]:7447` is used. The following endpoints are currently supported: + * TCP: `tcp/:` + * UDP: `udp/:` + * [TCP+TLS](https://zenoh.io/docs/manual/tls/): `tls/:` + * [QUIC](https://zenoh.io/docs/manual/quic/): `quic/:` +* `-e, --connect ...`: An endpoint this router will try to connect to. Repeat this option to connect to several peers or routers. +* `--no-multicast-scouting`: By default zenohd replies to multicast scouting messages for being discovered by peers and clients. + This option disables this feature. +* `-i, --id `: The identifier (as an hexadecimal string - e.g.: A0B23...) that zenohd must use. + **WARNING**: this identifier must be unique in the system! If not set, a random unsigned 128bit integer will be used. +* `--no-timestamp`: By default zenohd adds a HLC-generated Timestamp to each routed Data if there isn't already one. + This option disables this feature. +* `-P, --plugin [ | :]...`: A [plugin](https://zenoh.io/docs/manual/plugins/) that must be loaded. Accepted values: + * a plugin name; zenohd will search for a library named `libzenoh_plugin_.so` on Unix, `libzenoh_plugin_.dylib` on MacOS or `zenoh_plugin_.dll` on Windows. + * `":"`; the plugin will be loaded from library file at ``. + + Repeat this option to load several plugins. +* `--plugin-search-dir ...`: A directory where to search for [plugins](https://zenoh.io/docs/manual/plugins/) libraries to load. + Repeat this option to specify several search directories'. By default, the plugins libraries will be searched in: + `'/usr/local/lib:/usr/lib:~/.zenoh/lib:.'` +* `--rest-http-port `: Configures the [REST plugin](https://zenoh.io/docs/manual/plugin-http/)'s HTTP port. Accepted values: + * a port number + * a string with format `:` (to bind the HTTP server to a specific interface) + * `"None"` to deactivate the REST plugin + + If not specified, the REST plugin will be active on any interface (`[::]`) and port `8000`. ------------------------------- + ## Plugins > [!WARNING] @@ -200,6 +207,7 @@ This plugin converts GET and PUT REST requests into Zenoh gets and puts respecti This plugin allows you to easily define storages. These will store key-value pairs they subscribed to, and send the most recent ones when queried. Check out [DEFAULT_CONFIG.json5](DEFAULT_CONFIG.json5) for info on how to configure them. ------------------------------- + ## Troubleshooting In case of troubles, please first check on [this page](https://zenoh.io/docs/getting-started/troubleshooting/) if the trouble and cause are already known.