From 7a4744576e21c85d31b1527b2c4bf2230e5152e8 Mon Sep 17 00:00:00 2001 From: Yuyuan Yuan Date: Fri, 3 May 2024 01:20:00 +0800 Subject: [PATCH] docs: format and add a link to ZRuntime config (#1000) * docs: format and add a link to ZRuntime config * docs: format and remove the tx thread option in DEFAULT_CONFIG --- DEFAULT_CONFIG.json5 | 45 +++++++++++++++++++++----------------------- README.md | 38 ++++++++++++++++++++----------------- 2 files changed, 42 insertions(+), 41 deletions(-) diff --git a/DEFAULT_CONFIG.json5 b/DEFAULT_CONFIG.json5 index ec9a827777..430268935a 100644 --- a/DEFAULT_CONFIG.json5 +++ b/DEFAULT_CONFIG.json5 @@ -19,8 +19,8 @@ /// Which endpoints to connect to. E.g. tcp/localhost:7447. /// By configuring the endpoints, it is possible to tell zenoh which router/peer to connect to at startup. - /// For TCP/UDP on Linux, it is possible additionally specify the interface to be connected to: - /// E.g. tcp/192.168.0.1:7447#iface=eth0, for connect only if the IP address is reachable via the interface eth0 + /// For TCP/UDP on Linux, it is possible additionally specify the interface to be connected to: + /// E.g. tcp/192.168.0.1:7447#iface=eth0, for connect only if the IP address is reachable via the interface eth0 connect: { /// timeout waiting for all endpoints connected (0: no retry, -1: infinite timeout) /// Accepts a single value or different values for router, peer and client. @@ -30,16 +30,16 @@ // "/
" ], - /// Global connect configuration, + /// Global connect configuration, /// Accepts a single value or different values for router, peer and client. /// The configuration can also be specified for the separate endpoint /// it will override the global one /// E.g. tcp/192.168.0.1:7447#retry_period_init_ms=20000;retry_period_max_ms=10000" - + /// exit from application, if timeout exceed exit_on_failure: { router: false, peer: false, client: true }, - /// connect establishing retry configuration - retry: { + /// connect establishing retry configuration + retry: { /// intial wait timeout until next connect try period_init_ms: 1000, /// maximum wait timeout until next connect try @@ -52,7 +52,7 @@ /// Which endpoints to listen on. E.g. tcp/localhost:7447. /// By configuring the endpoints, it is possible to tell zenoh which are the endpoints that other routers, /// peers, or client can use to establish a zenoh session. - /// For TCP/UDP on Linux, it is possible additionally specify the interface to be listened to: + /// For TCP/UDP on Linux, it is possible additionally specify the interface to be listened to: /// E.g. tcp/0.0.0.0:7447#iface=eth0, for listen connection only on eth0 listen: { /// timeout waiting for all listen endpoints (0: no retry, -1: infinite timeout) @@ -63,16 +63,16 @@ // "/
" ], - /// Global listen configuration, + /// Global listen configuration, /// Accepts a single value or different values for router, peer and client. /// The configuration can also be specified for the separate endpoint /// it will override the global one /// E.g. tcp/192.168.0.1:7447#exit_on_failure=false;retry_period_max_ms=1000" - + /// exit from application, if timeout exceed exit_on_failure: true, - /// listen retry configuration - retry: { + /// listen retry configuration + retry: { /// intial wait timeout until next try period_init_ms: 1000, /// maximum wait timeout until next try @@ -171,19 +171,19 @@ // flow: "egress", // /// A list of downsampling rules: key_expression and the maximum frequency in Hertz // rules: [ - // { key_expr: "demo/example/zenoh-rs-pub", freq: 0.1 }, + // { key_expr: "demo/example/zenoh-rs-pub", freq: 0.1 }, // ], // }, // ], - // /// configure access control (ACL) rules + // /// configure access control (ACL) rules // access_control: { // ///[true/false] acl will be activated only if this is set to true // "enabled": false, // ///[deny/allow] default permission is deny (even if this is left empty or not specified) // "default_permission": "deny", // ///rule set for permissions allowing or denying access to key-expressions - // "rules": + // "rules": // [ // { // "actions": [ @@ -216,7 +216,7 @@ /// This option does not make LowLatency transport mandatory, the actual implementation of transport /// used will depend on Establish procedure and other party's settings /// - /// NOTE: Currently, the LowLatency transport doesn't preserve QoS prioritization. + /// NOTE: Currently, the LowLatency transport doesn't preserve QoS prioritization. /// NOTE: Due to the note above, 'lowlatency' is incompatible with 'qos' option, so in order to /// enable 'lowlatency' you need to explicitly disable 'qos'. lowlatency: false, @@ -225,19 +225,19 @@ enabled: true, }, /// Enables compression on unicast communications. - /// Compression capabilities are negotiated during session establishment. + /// Compression capabilities are negotiated during session establishment. /// If both Zenoh nodes support compression, then compression is activated. compression: { enabled: false, }, - }, + }, multicast: { - /// Enables QoS on multicast communication. + /// Enables QoS on multicast communication. /// Default to false for Zenoh-to-Zenoh-Pico out-of-the-box compatibility. qos: { enabled: false, }, - /// Enables compression on multicast communication. + /// Enables compression on multicast communication. /// Default to false for Zenoh-to-Zenoh-Pico out-of-the-box compatibility. compression: { enabled: false, @@ -261,7 +261,7 @@ /// messages will be sent at the configured time interval. /// NOTE: In order to consider eventual packet loss and transmission latency and jitter, /// set the actual keep_alive interval to one fourth of the lease time: i.e. send - /// 4 keep_alive messages in a lease period. Changing the lease time will have the + /// 4 keep_alive messages in a lease period. Changing the lease time will have the /// keep_alive messages sent more or less often. /// This is in-line with the ITU-T G.8013/Y.1731 specification on continous connectivity /// check which considers a link as failed when no messages are received in 3.5 times the @@ -299,9 +299,6 @@ /// Higher values lead to a more aggressive batching but it will introduce additional latency. backoff: 100, }, - // Number of threads dedicated to transmission - // By default, the number of threads is calculated as follows: 1 + ((#cores - 1) / 4) - // threads: 4, }, /// Configure the zenoh RX parameters of a link rx: { @@ -378,7 +375,7 @@ /// /// Plugins configurations /// - // + // // plugins_loading: { // // Enable plugins loading. // enabled: false, diff --git a/README.md b/README.md index fb268141a5..b09ea73d86 100644 --- a/README.md +++ b/README.md @@ -26,12 +26,12 @@ To install the latest release of the Zenoh router (`zenohd`) and its default plu ### 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/ 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. +Choose your platform and download the `.zip` file. Unzip it where you want, and run the extracted `zenohd` binary. ### Linux Debian @@ -99,32 +99,32 @@ Zenoh's router is built as `target/release/zenohd`. All the examples are built i > **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: + - 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: + - 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: + - 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: + - 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: + - 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: + - 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): + - 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): + - 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/**`: + - 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: + - check it has been created: `curl 'http://localhost:8000/@/router/local/**/storages/*'` **Configuration options:** @@ -133,8 +133,12 @@ A Zenoh configuration file can be provided via CLI to all Zenoh examples and the * `-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) +> [!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: @@ -142,7 +146,7 @@ See other examples of Zenoh usage in [examples/](examples) * `--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. + * `-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/:` @@ -184,8 +188,8 @@ Otherwise, incompatibilities in memory mapping of shared types between `zenohd` By default the Zenoh router is delivered or built with 2 plugins. These may be configured through a configuration file, or through individual changes to the configuration via the `--cfg` CLI option or via zenoh puts on individual parts of the configuration. -> [!WARNING] -> Since `v0.6`, `zenohd` no longer loads every available plugin at startup. Instead, only configured plugins are loaded (after processing `--cfg` and `--plugin` options). Once `zenohd` is running, plugins can be hot-loaded and, if they support it, reconfigured at runtime by editing their configuration through the adminspace. +> [!WARNING] +> Since `v0.6`, `zenohd` no longer loads every available plugin at startup. Instead, only configured plugins are loaded (after processing `--cfg` and `--plugin` options). Once `zenohd` is running, plugins can be hot-loaded and, if they support it, reconfigured at runtime by editing their configuration through the adminspace. Note that the REST plugin is added to the configuration by the default value of the `--rest-http-port` CLI argument. @@ -198,5 +202,5 @@ This plugin allows you to easily define storages. These will store key-value pai ------------------------------- ## 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. +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. Otherwise, you can ask a question on the [zenoh Discord server](https://discord.gg/vSDSpqnbkm), or [create an issue](https://github.com/eclipse-zenoh/zenoh/issues).