Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix README format #1186

Merged
merged 2 commits into from
Jun 25, 2024
Merged

Fix README format #1186

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
79c8c82
Fix the README format.
evshary Jun 25, 2024
52f1971
Fix some out-dated contents.
evshary Jun 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 91 additions & 83 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,28 +8,30 @@
[![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.

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.
Expand All @@ -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
Expand All @@ -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]
Expand All @@ -67,118 +75,117 @@ 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.71.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 <FILE>`: 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 <FILE>`: 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)

> [!NOTE]
> **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 <FILE>`: 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 <KEY>:<VALUE>`: 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 <ENDPOINT>...`: 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/<host_name_or_IPv4_or_IPv6>:<port>`
- UDP: `udp/<host_name_or_IPv4_or_IPv6>:<port>`
- [TCP+TLS](https://zenoh.io/docs/manual/tls/): `tls/<host_name>:<port>`
- [QUIC](https://zenoh.io/docs/manual/quic/): `quic/<host_name>:<port>`
* `-e, --connect <ENDPOINT>...`: 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 <hex_string>`: 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 [<PLUGIN_NAME> | <PLUGIN_NAME>:<LIBRARY_PATH>]...`: 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_<name>.so` on Unix, `libzenoh_plugin_<PLUGIN_NAME>.dylib` on MacOS or `zenoh_plugin_<PLUGIN_NAME>.dll` on Windows.
- `"<PLUGIN_NAME>:<LIBRARY_PATH>"`; the plugin will be loaded from library file at `<LIBRARY_PATH>`.

Repeat this option to load several plugins.
* `--plugin-search-dir <DIRECTORY>...`: 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 <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 `<local_ip>:<port_number>` (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 <FILE>`: 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 <KEY>:<VALUE>`: 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 <ENDPOINT>...`: 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/<host_name_or_IPv4_or_IPv6>:<port>`
* UDP: `udp/<host_name_or_IPv4_or_IPv6>:<port>`
* [TCP+TLS](https://zenoh.io/docs/manual/tls/): `tls/<host_name>:<port>`
* [QUIC](https://zenoh.io/docs/manual/quic/): `quic/<host_name>:<port>`
* `-e, --connect <ENDPOINT>...`: 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 <hex_string>`: 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 [<PLUGIN_NAME> | <PLUGIN_NAME>:<LIBRARY_PATH>]...`: 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_<name>.so` on Unix, `libzenoh_plugin_<PLUGIN_NAME>.dylib` on MacOS or `zenoh_plugin_<PLUGIN_NAME>.dll` on Windows.
* `"<PLUGIN_NAME>:<LIBRARY_PATH>"`; the plugin will be loaded from library file at `<LIBRARY_PATH>`.

Repeat this option to load several plugins.
* `--plugin-search-dir <DIRECTORY>...`: 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 <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 `<local_ip>:<port_number>` (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]
Expand All @@ -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.
Expand Down
Loading