From 5f0c3895f8cca9f5055ce2134c078dafe9638030 Mon Sep 17 00:00:00 2001 From: lxl66566 Date: Tue, 9 Jul 2024 21:23:07 +0800 Subject: [PATCH] docs: multiple markdown docs fixed Signed-off-by: lxl66566 --- USAGE.md | 26 +++--- crates/utils/README.md | 3 + crates/xline-client/README.md | 68 ++++++++-------- crates/xlinectl/README.md | 146 +++++++++++++++++++++++++--------- crates/xlineutl/README.md | 3 +- 5 files changed, 160 insertions(+), 86 deletions(-) diff --git a/USAGE.md b/USAGE.md index e2f76fcc0..44c208c32 100644 --- a/USAGE.md +++ b/USAGE.md @@ -2,12 +2,12 @@ ## Configurations -The Xline configuration file is written in toml format and the default path is /etc/xline_server.conf. If you need to change the path of the configuration file, you can set it via the environment variable XLINE_SERVER_CONFIG. +The Xline configuration file is written in toml format and the default path is `/etc/xline_server`.conf. If you need to change the path of the configuration file, you can set it via the environment variable `XLINE_SERVER_CONFIG`. The configuration file has four sections, as follows: 1. cluster section: contains information about curp cluster, including basic information, cluster member configuration, curp server timeout settings (optional), curp client timeout settings (optional). -2. log section: contains the Xline log-related configuration, where path is required, rotation (optional, default value is 'daily'), level (optional, default value is 'info') +2. log section: contains the Xline log-related configuration, where path is required, rotation (optional, default value is `daily`), level (optional, default value is `info`) 3. trace section: contains the jaeger's trace mode (online or offline), trace level and the log directory in offline mode 4. auth section: contains the address of the key pair required for authentication @@ -61,24 +61,24 @@ retry_timeout = '50ms' # the rpc retry interval, of which the default i ## Boot up an Xline cluster -1. Download binary from [release]() page. +1. Download binary from [release](https://github.com/xline-kv/Xline/releases) page. 2. Use the following command to start cluster: - ```bash - # Run in 3 terminals. If you want more logs, add `RUST_LOG=curp=debug,xline=debug` before the command. + ```bash + # Run in 3 terminals. If you want more logs, add `RUST_LOG=curp=debug,xline=debug` before the command. - ./xline --name node1 --members node1=127.0.0.1:2379,node2=127.0.0.1:2380,node3=127.0.0.1:2381 --is-leader + ./xline --name node1 --members node1=127.0.0.1:2379,node2=127.0.0.1:2380,node3=127.0.0.1:2381 --is-leader - ./xline --name node2 --members node1=127.0.0.1:2379,node2=127.0.0.1:2380,node3=127.0.0.1:2381 + ./xline --name node2 --members node1=127.0.0.1:2379,node2=127.0.0.1:2380,node3=127.0.0.1:2381 - ./xline --name node3 --members node1=127.0.0.1:2379,node2=127.0.0.1:2380,node3=127.0.0.1:2381 - ``` + ./xline --name node3 --members node1=127.0.0.1:2379,node2=127.0.0.1:2380,node3=127.0.0.1:2381 + ``` 3. Download or build `etcdctl` from [etcd](https://github.com/etcd-io/etcd) project. 4. Use `etcdctl` to operate the cluster: - ```bash - etcdctl --endpoints=http://127.0.0.1:2379 put foo bar + ```bash + etcdctl --endpoints=http://127.0.0.1:2379 put foo bar - etcdctl --endpoints=http://127.0.0.1:2379 get foo - ``` + etcdctl --endpoints=http://127.0.0.1:2379 get foo + ``` diff --git a/crates/utils/README.md b/crates/utils/README.md index 45468e2c1..3d55f1ebd 100644 --- a/crates/utils/README.md +++ b/crates/utils/README.md @@ -5,12 +5,14 @@ This crate provides a set of utilities for locks. ## Usage Add this to your Cargo.toml : + ```Toml [dependencies] utils = { path = "../utils", features = ["std"] } ``` Write your code like this: + ```Rust use utils::std_lock::{MutexMap, RwLockMap}; use std::sync::{Mutex, RwLock}; @@ -31,6 +33,7 @@ assert_eq!(val, 3); ``` ## Features + - `std`: utils for `std::sync::Mutex` and `std::sync::RwLock` - `parking_lot`: utils for` parking_lot::Mutex` and `parking_lot::RwLock` - `tokio`: utils for `tokio::sync::Mutex` and `tokio::sync::RwLock` diff --git a/crates/xline-client/README.md b/crates/xline-client/README.md index 930fd1268..279b213bd 100644 --- a/crates/xline-client/README.md +++ b/crates/xline-client/README.md @@ -3,7 +3,8 @@ Official Xline API client for Rust that supports the [CURP](https://github.com/xline-kv/Xline/tree/master/crates/curp) protocol # Pre-requisites -- Install `protobuf-compiler` as mentioned in [QuickStart](https://github.com/xline-kv/Xline/blob/master/doc/quick-start/README.md#install-dependencies) + +- Install `protobuf-compiler` as mentioned in [QuickStart](https://github.com/xline-kv/Xline/blob/master/doc/QUICK_START.md#build-from-source) ## Features @@ -77,40 +78,41 @@ Add `xline-client` to your `Cargo.toml`: [dependencies] xline-client = { git = "https://github.com/xline-kv/Xline.git", package = "xline-client" } ``` + To create a xline client: - ```rust, no_run - use xline_client::{ - types::kv::{PutOptions, RangeOptions}, - Client, ClientOptions, - }; - use anyhow::Result; - - #[tokio::main] - async fn main() -> Result<()> { - // the name and address of all curp members - let curp_members = ["10.0.0.1:2379", "10.0.0.2:2379", "10.0.0.3:2379"]; - - let mut client = Client::connect(curp_members, ClientOptions::default()) - .await? - .kv_client(); - - client.put("key", "value", None).await?; - - let resp = client.range("key", None).await?; - // let resp = client.range("key2", Some(RangeOptions::default().with_limit(6))).await?; - - if let Some(kv) = resp.kvs.first() { - println!( - "got key: {}, value: {}", - String::from_utf8_lossy(&kv.key), - String::from_utf8_lossy(&kv.value) - ); - } - - Ok(()) - } - ``` +```rust, no_run +use xline_client::{ + types::kv::{PutOptions, RangeOptions}, + Client, ClientOptions, +}; +use anyhow::Result; + +#[tokio::main] +async fn main() -> Result<()> { + // the name and address of all curp members + let curp_members = ["10.0.0.1:2379", "10.0.0.2:2379", "10.0.0.3:2379"]; + + let mut client = Client::connect(curp_members, ClientOptions::default()) + .await? + .kv_client(); + + client.put("key", "value", None).await?; + + let resp = client.range("key", None).await?; + // let resp = client.range("key2", Some(RangeOptions::default().with_limit(6))).await?; + + if let Some(kv) = resp.kvs.first() { + println!( + "got key: {}, value: {}", + String::from_utf8_lossy(&kv.key), + String::from_utf8_lossy(&kv.value) + ); + } + + Ok(()) +} +``` ## Examples diff --git a/crates/xlinectl/README.md b/crates/xlinectl/README.md index 5a53f744e..f1cd9241b 100644 --- a/crates/xlinectl/README.md +++ b/crates/xlinectl/README.md @@ -4,34 +4,34 @@ This crate provides a command line client for Xline. ## Global Options -- endpoints ... -- Set Xline endpoints, which are separated by ',' +- `--endpoints ...` -- Set Xline endpoints, which are separated by ',' ```bash # connect to servers with specific addresses ./xlinectl --endpoints "127.0.0.1:2379" ``` -- user -- The name of the user, this provide a shorthand to set password +- `--user ` -- The name of the user, this provide a shorthand to set password ```bash # connect to servers using user `foo` with password `bar` ./xlinectl --user foo:bar ``` -- password -- The password of the user, should exist if password not set in `--user` +- `--password ` -- The password of the user, should exist if password not set in `--user` ```bash # connect to servers using user `foo` with password `bar` ./xlinectl --user foo --password bar ``` -- wait_synced_timeout -- The timeout for Curp client waiting synced(in secs) [default: 2] +- `--wait_synced_timeout ` -- The timeout for Curp client waiting synced(in secs) [default: 2] -- propose_timeout -- The timeout for Curp client proposing request(in secs) [default: 1] +- `--propose_timeout ` -- The timeout for Curp client proposing request(in secs) [default: 1] -- retry_timeout -- The timeout for Curp client retry interval(in millis) [default: 50] +- `--retry_timeout ` -- The timeout for Curp client retry interval(in millis) [default: 50] -- printer_type -- The format of the result that will be printed [default: SIMPLE] [possible values: SIMPLE, FIELD] +- `--printer_type ` -- The format of the result that will be printed [default: SIMPLE] [possible values: SIMPLE, FIELD] ## Output Format @@ -52,10 +52,10 @@ put [options] #### Options -- lease -- lease ID to attach to the key [default: 0] -- prev_kv -- return the previous key-value pair before modification -- ignore_value -- updates the key using its current value -- ignore_lease -- updates the key using its current lease +- `--lease ` -- lease ID to attach to the key [default: 0] +- `--prev_kv` -- return the previous key-value pair before modification +- `--ignore_value` -- updates the key using its current value +- `--ignore_lease` -- updates the key using its current lease #### Output @@ -95,15 +95,15 @@ get [options] [range_end] #### Options -- consistency -- Linearizable(L) or Serializable(S) [default: L] -- order -- Order of results; ASCEND or DESCEND -- sort_by -- Sort target; CREATE, KEY, MODIFY, VALUE, or VERSION -- limit -- Maximum number of results [default: 0] -- prefix -- Get keys with matching prefix (conflicts with range_end) -- from_key -- Get keys that are greater than or equal to the given key using byte compare (conflicts with prefix and range_end) -- rev -- Specify the kv revision [default: 0] -- keys_only -- Get only the keys -- count_only -- Get only the count (conflicts with keys_only) +- `--consistency ` -- Linearizable(L) or Serializable(S) [default: L] +- `--order ` -- Order of results; `ASCEND` or `DESCEND` +- `--sort_by ` -- Sort target; `CREATE`, `KEY`, `MODIFY`, `VALUE`, or `VERSION` +- `--limit ` -- Maximum number of results [default: 0] +- `--prefix` -- Get keys with matching prefix (conflicts with range_end) +- `--from_key` -- Get keys that are greater than or equal to the given key using byte compare (conflicts with prefix and range_end) +- `--rev ` -- Specify the kv revision [default: 0] +- `--keys_only` -- Get only the keys +- `--count_only` -- Get only the count (conflicts with keys_only) #### Output @@ -157,6 +157,7 @@ bar2 ``` ### DELETE + Deletes the key or a range of keys #### Usage @@ -166,9 +167,10 @@ delete [options] [range_end] ``` #### Options -- prefix -- delete keys with matching prefix -- prev_kv -- return deleted key-value pairs -- from_key -- delete keys that are greater than or equal to the given key using byte compare + +- `--prefix` -- delete keys with matching prefix +- `--prev_kv` -- return deleted key-value pairs +- `--from_key` -- delete keys that are greater than or equal to the given key using byte compare #### Output @@ -197,6 +199,7 @@ delete [options] [range_end] ``` ### TXN + Txn processes all the requests in one transaction #### Usage @@ -206,11 +209,13 @@ txn [options] ``` #### Options -- interactive -- set interactive mode + +- `--interactive` -- set interactive mode #### Input Format The ebnf is the same as etcdctl + ```ebnf ::= * "\n" "\n" "\n" ::= (||||) "\n" @@ -237,11 +242,12 @@ The ebnf is the same as etcdctl [child requests] ``` -`` can be SUCCESS | FAILURE +`` can be `SUCCESS` | `FAILURE` #### Examples non-interactive mode + ```bash ./xlinectl txn <<<'mod("key1") > "0" @@ -254,6 +260,7 @@ put key2 "some-val" ``` interactive mode + ```bash ./xlinectl txn --interactive compares: @@ -266,7 +273,9 @@ failure request: put key1 "val1" put key2 "some-val" ``` + ### COMPACTION + COMPACTION discards all Xline event history prior to a given revision. Since Xline uses a multiversion concurrency control model, it preserves all key updates as event history. When the event history up to some revision is no longer needed, all superseded keys may be compacted away to reclaim storage space in the Xline backend database. #### Usage @@ -276,7 +285,8 @@ compaction [options] ``` #### Options -- physical -- To wait for compaction to physically remove all old revisions + +- `--physical` -- To wait for compaction to physically remove all old revisions #### Output @@ -297,19 +307,22 @@ Compacted ``` ### WATCH + Watches events stream on keys or prefixes #### Usage + ```bash watch [options] [key] [range_end] ``` #### Options -- prefix -- Watch a prefix -- rev -- Revision to start watching -- pre_kv -- Get the previous key-value pair before the event happens -- progress_notify -- Get periodic watch progress notification from server -- interactive -- Interactive mode + +- `--prefix` -- Watch a prefix +- `--rev ` -- Revision to start watching +- `--pre_kv` -- Get the previous key-value pair before the event happens +- `--progress_notify` -- Get periodic watch progress notification from server +- `--interactive` -- Interactive mode #### Output @@ -333,16 +346,19 @@ watch [options] [key] [range_end] #### Examples non-interactive mode, which will continuously get output from response stream + ```bash # Watch key `foo` ./xlinectl watch foo ``` + ```bash # Watch a range of keys from foo to foo3 ./xlinectl watch foo foo3 ``` interactive mode, which can start or cancel a watch + ```bash ./xlinectl watch --interactive @@ -352,13 +368,14 @@ watch foo foo3 cancel 100 ``` - ### LEASE ### LEASE GRANT + Create a lease with a given TTL #### Usage + ```bash grant ``` @@ -370,6 +387,7 @@ grant ``` #### Examples + ```bash # create a new lease with 100s TTL ./xlinectl lease grant 100 @@ -377,6 +395,7 @@ grant ``` ### LEASE REVOKE + Revoke a lease #### Usage @@ -384,6 +403,7 @@ Revoke a lease ```bash revoke ``` + #### Output ``` @@ -391,6 +411,7 @@ Revoked ``` #### Examples + ```bash ./xlinectl lease grant 100 8927807922788821579 @@ -400,6 +421,7 @@ Revoked ``` ### LEASE TIMETOLIVE + Get lease ttl information #### Usage @@ -425,6 +447,7 @@ timetolive ``` ### LEASE LIST + List all active leases #### Usage @@ -442,6 +465,7 @@ list ``` #### Examples + ```bash ./xlinectl lease grant 100 8927807922788821579 @@ -455,6 +479,7 @@ list ``` ### LEASE KEEP-ALIVE + lease keep alive periodically #### Usage @@ -464,7 +489,8 @@ keep_alive [options] ``` #### Options -- once -- keep alive once + +- `--once` -- keep alive once #### Output @@ -493,9 +519,11 @@ keep_alive [options] ## Cluster maintenance commands ### MEMBER + MEMBER provides commands for managing Xline cluster membership. ### MEMBER ADD + MEMBER ADD introduces a new member into the Xline cluster as a new peer. #### Usage @@ -505,8 +533,8 @@ member add [options] ``` #### Options -- is_learner -- Add as learner +- `--is_learner` -- Add as learner #### Output @@ -515,6 +543,7 @@ member add [options] ``` #### Examples + ```bash # Add a member whose addresses are [127.0.0.1:2379, 127.0.0.1:2380] ./xlinectl member add "10.0.0.1:2379,10.0.0.2:2379" @@ -522,6 +551,7 @@ member add [options] ``` ### MEMBER UPDATE + MEMBER UPDATE sets the peer URLs for an existing member in the Xline cluster. #### Usage @@ -537,6 +567,7 @@ Member updated ``` #### Examples + ```bash ./xlinectl member add "10.0.0.1:2379,10.0.0.2:2379" 16151281779493828828 @@ -545,6 +576,7 @@ Member updated ``` ### MEMBER LIST + MEMBER ADD introduces a new member into the Xline cluster as a new peer. #### Usage @@ -554,8 +586,8 @@ member list ``` #### Options -- linearizable -- to use linearizable fetch +- `--linearizable` -- to use linearizable fetch #### Output @@ -566,6 +598,7 @@ member list ``` #### Examples + ```bash # List all members ./xlinectl member list @@ -575,6 +608,7 @@ member list ``` ### MEMBER REMOVE + MEMBER REMOVE removes a member of an Xline cluster from participating in cluster consensus. #### Usage @@ -590,6 +624,7 @@ Member removed ``` #### Examples + ```bash # Remove a member ./xlinectl member remove 16151281779493828828 @@ -597,6 +632,7 @@ Member removed ``` ### MEMBER PROMOTE + MEMBER PROMOTE promotes a learner of an Xline cluster to member #### Usage @@ -612,6 +648,7 @@ Member promoted ``` #### Examples + ```bash # Remove a member ./xlinectl member promote 16151281779493828828 @@ -619,9 +656,11 @@ Member promoted ``` ### SNAPSHOT + Get snapshots of xline nodes ### SNAPSHOT SAVE + Save snapshot to file #### Usage @@ -647,6 +686,7 @@ snapshot saved to: /tmp/foo.snapshot ## Concurrency commands ### LOCK + Acquire a lock, which will return a unique key that exists so long as the lock is held. #### Usage @@ -670,12 +710,15 @@ lock acquired ./xlinectl lock foo ./xlinectl put foo bar OK ``` + ## Authentication commands ### AUTH + Manage authentication ### AUTH ENABLE + Enable authentication #### Usage @@ -691,6 +734,7 @@ Authentication enabled ``` #### Examples + ```bash ./xlinectl user add root rootpw ./xlienctl user grant-role root root @@ -700,6 +744,7 @@ Authentication enabled ``` ### AUTH DISABLE + Disable authentication #### Usage @@ -715,6 +760,7 @@ Authentication disabled ``` #### Examples + ```bash # Disable authentication ./xlinectl --user root:root auth disable @@ -722,6 +768,7 @@ Authentication disabled ``` ### AUTH STATUS + Status of authentication #### Usage @@ -731,15 +778,18 @@ auth status ``` #### Examples + ```bash # Check the status of authentication ./xlinectl auth status ``` ### ROLE + Role related commands ### ROLE ADD + Create a new role #### Usage @@ -763,6 +813,7 @@ Role added ``` ### ROLE GET + List role information #### Usage @@ -797,6 +848,7 @@ key1 ``` ### ROLE DELETE + Delete a role #### Usage @@ -812,6 +864,7 @@ Role deleted ``` #### Examples + ```bash ./xlinectl --user=root:root role add foo # delete the role named `foo` @@ -820,6 +873,7 @@ Role deleted ``` ### ROLE LIST + List all roles #### Usage @@ -848,6 +902,7 @@ foo1 ``` ### ROLE GRANT-PERMISSION + Grant permission to a role, including Read, Write or ReadWrite #### Usage @@ -857,8 +912,9 @@ grant_perm [options] [range_end] ``` #### Options -- prefix -- Get keys with matching prefix -- from_key -- Get keys that are greater than or equal to the given key using byte compare (conflicts with `range_end`) + +- `--prefix` -- Get keys with matching prefix +- `--from_key` -- Get keys that are greater than or equal to the given key using byte compare (conflicts with `range_end`) #### Output @@ -875,6 +931,7 @@ Permission granted ``` ### ROLE REVOKE-PERMISSION + Revoke permission from a role #### Usage @@ -900,6 +957,7 @@ Permission revoked ### USER ### USER ADD + Add a new user #### Usage @@ -909,7 +967,8 @@ add [options] [password] ``` #### Options -- no_password -- Create without password + +- `--no_password` -- Create without password #### Output @@ -918,6 +977,7 @@ User added ``` #### Examples + ```bash # Add a new user with a specified password ./xlinectl --user=root:root user add foo bar @@ -929,6 +989,7 @@ User added ``` ### USER GET + Get a new user #### Usage @@ -938,7 +999,8 @@ get [options] ``` #### Options -- detail -- Show permissions of roles granted to the user + +- `--detail` -- Show permissions of roles granted to the user #### Output @@ -949,6 +1011,7 @@ get [options] ``` #### Examples + ```bash ./xlinectl --user=root:root user grant_role foo role0 ./xlinectl --user=root:root user grant_role foo role1 @@ -959,6 +1022,7 @@ role1 ``` ### USER LIST + List all users #### Usage @@ -976,6 +1040,7 @@ list ``` #### Examples + ```bash ./xlinectl --user=root:root user add foo bar ./xlinectl --user=root:root user add foo1 bar1 @@ -986,6 +1051,7 @@ foo1 ``` ### USER PASSWD + Change the password of a user #### Usage @@ -1009,6 +1075,7 @@ Password updated ``` ### USER GRANT-ROLE + Grant role to a user #### Usage @@ -1034,6 +1101,7 @@ Role granted ``` ### USER REVOKE-ROLE + Revoke role from a user #### Usage diff --git a/crates/xlineutl/README.md b/crates/xlineutl/README.md index f204163fd..2d9e3a1a5 100644 --- a/crates/xlineutl/README.md +++ b/crates/xlineutl/README.md @@ -16,10 +16,11 @@ restore [options] #### Options -- data-dir -- path to the output data directory +- `--data-dir` -- path to the output data directory #### Examples ```bash # restore snapshot to data dir ./xlineutl snapshot restore /path/to/snapshot --data-dir /path/to/target/dir +```